Next: Entity References, Previous: Dumping the State Transition Matrix, Up: Listing a Multinode Model [Contents][Index]

The action emission matrix of a node contains the probabilities of emitting all instruction classes belonging to the instruction class set of this node in all states of this node. The rows of that matrix biuniquely correspond to node states. The columns of that matrix biuniquely correspond to instruction classes in the instruction class set. Use the following function to dump an action emission matrix to a stream.

- Function:
*int***qsmm_mat_action_dump_v2***(qsmm_t*`model`, int`rez1`, qsmm_sig_t`node`, struct qsmm_dump_mat_action_desc_s *`desc_p`, FILE *`filep`) This function dumps the action emission matrix of a node of a multinode

`model`to a stream`filep`according to parameters specified in *`desc_p`. The argument`node`specifies the identifier of this node. If`node`is equal to`QSMM_SIG_INVALID`

, the function dumps the action emission matrices of all nodes of this multinode model. If`desc_p`is`NULL`

, the function uses default dumping parameters. The argument`rez1`is for future use and must be equal to 0.In the current implementation, the function does not modify *

`desc_p`if`desc_p`is not`NULL`

. However, in a future implementation, the function may modify *`desc_p`, for example, to store there statistics on the dumping process.The function returns a non-negative value on success or a negative error code on failure. Currently, the function can return the following error codes.

`QSMM_ERR_NOTFOUND`

The argument

`node`is not`QSMM_SIG_INVALID`

, and a node with identifier`node`does not exist.`QSMM_ERR_INVAL`

The argument

`desc_p`is not`NULL`

, and parameters in *`desc_p`are invalid.`QSMM_ERR_UNTIMELY`

The model instance does not exist.

`QSMM_ERR_CALLBACK`

A helper function for computing the relative probability of an output signal assigned to the instruction emitting engine reported an error by returning

`NaN`

. The function`qsmm_actor_calc_action_prob`

calls the helper function.`QSMM_ERR_STORAGE`

A Storage API function reported storage failure.

`QSMM_ERR_STATS`

Inconsistent statistics on an action choice state or cycle type detected.

`QSMM_ERR_ILSEQ`

Unable to convert a multibyte string to a wide string or vice versa according to a current locale.

`QSMM_ERR_NOMEM`

There was not enough memory to perform the operation.

Errors

`QSMM_ERR_STORAGE`

,`QSMM_ERR_STATS`

,`QSMM_ERR_ILSEQ`

, and`QSMM_ERR_NOMEM`

can leave the multinode model in inconsistent state.

The description of a structure specifying dumping parameters is below.

- Structure:
**qsmm_dump_mat_action_desc_s** This structure specifies the parameters of dumping the action emission matrix of a node. The structure contains the following fields.

- Field:
*char***do_print_prob[QSMM_PROB_COUNT]** An array specifying the types of probabilities to dump. The indices of this array are the elements of

`qsmm_prob_e`

enumeration (except for its last element`QSMM_PROB_COUNT`

) described in Emitting an Output Signal. If an element of this array is non-zero, the function`qsmm_mat_action_dump_v2`

dumps probabilities with a corresponding type. The default is to dump probabilities of all types.

- Field:
*int***indent** Left indent—the number of spaces to print at the beginning of each line of output. Must be a non-negative value. The default is to use indent 0.

- Field:
*int***prob_prec** The number of digits after the decimal point to print for probabilities. If that number is positive, use fixed-point notation. If that number is negative, use exponential notation with the number of digits after the decimal point equal to the absolute value of this field. If that number is zero, use exponential notation with 15 digits after the decimal point; this is the default mode.

- Field:
*long***fq_min** The minimum value of

`fq`

field of an instance of`qsmm_cycle_s`

structure for a matrix cell. The function`qsmm_mat_action_dump_v2`

does not output information on instances with lesser values of`fq`

field (i.e. with lesser frequency). The default is to use minimum frequency 0.

- Field:

To improve compatibility with future versions of QSMM library, zero by the function `memset`

an instance of `qsmm_dump_mat_action_desc_s`

structure before setting the fields of this instance passed to the function `qsmm_mat_action_dump_v2`

.

Below there is an example fragment of a dump.
When generating it, the element `QSMM_PROB_LEARNED`

of `do_print_prob`

field of `qsmm_dump_mat_action_desc_s`

structure passed to `qsmm_mat_action_dump_v2`

was non-zero, and all other elements of this field were zero.
The example contains truncated fractional parts of numbers in exponential notation to make lines shorter.

* State 1 : tmd0=2711, tmc0=1.205...E+03, action_next=0, spur[0].val0=4.000...E+00 A0 |me| : pl=9.9306...E-01, spur[0].ds=4.0...E+00, fq=43, ps_d=1965, ps_c=8.22...E+02 A1 |ms| : pl=3.4713...E-03, spur[0].ds=0.0...E+00, fq=49, ps_d=147, ps_c=9.80...E+01 A2 |mw| : pl=3.4713...E-03, spur[0].ds=0.0...E+00, fq=36, ps_d=108, ps_c=7.20...E+01

Below there are descriptions of output pieces of information. See Structures for Accessing Storage, for details about referenced structure fields.

`A`

`i`Information on an instruction class emitted in a node state. Index

`i`uniquely identifies the instruction class in the instruction class set of the node. The name of the instruction class enclosed between the characters ‘`|`’ follows the token`A`

.`i``action_next`

The index of last instruction class emitted in a node state. That index corresponds to the value of

`sig_cycle_next`

field of`qsmm_state_s`

structure. The special value ‘`N`’ corresponds to the value`QSMM_SIG_INVALID`

of this field.`fq`

The value of

`fq`

field of`qsmm_cycle_s`

structure.`pa`

Probability of

`QSMM_PROB_AGGR`

type.`pf`

Probability of

`QSMM_PROB_FQ`

type.`pl`

Probability of

`QSMM_PROB_LEARNED`

type.`pp`

Probability of

`QSMM_PROB_PROFILE`

type.`ps_c`

The value of

`period_sum_c`

field of`qsmm_cycle_s`

structure.`ps_d`

The value of

`period_sum_d`

field of`qsmm_cycle_s`

structure.`spur[`

`i`].dsThe value of

`delta_sum`

field of`qsmm_cspur_s`

structure for spur type`i`.`spur[`

`i`].val0The value of

`val0`

field of`qsmm_sspur_s`

structure for spur type`i`.`State`

The description of a state with a specific index. If the state has a name assigned by the argument of

`stt`

assembler instruction, the name enclosed in double quotes follows this index.`tmc0`

The value of

`tmc0`

field of`qsmm_state_s`

structure.`tmd0`

The value of

`tmd0`

field of`qsmm_state_s`

structure.

The function `qsmm_mat_action_dump_v2`

only dumps information on instruction classes contained in statistics storage.
This approach helps reduce the length of output when dumping a sparse action emission matrix.

When information on some instruction classes is absent in the output because of a positive value of `fq_min`

field of `qsmm_dump_mat_action_desc_s`

structure or because statistics storage does not contain information on some instruction classes for some node states, the sum of action emission probabilities with a specific type may be less than 1 in a matrix row.
If the field `fq_min`

is zero, every not dumped instruction class has emission probability *(1-p)/n*, where *p* is the sum of probabilities of instruction classes dumped for a node state, and *n* is the number of instruction classes not dumped for the node state.