Next: Controlling Random Behavior of a Multinode Model, Previous: Dumping a State Transition Matrix, Up: Multinode Model [Contents][Index]

The action emission matrix of a node contains probabilities of emitting each action of the node in each state of the node. The actions are instruction classes of instruction class set of the node. To dump an action emission matrix to a stream, the following function can be used.

- Function:
*int***qsmm_mat_action_dump***(qsmm_t*`model`, int`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 specified by handle

`model`to stream`filep`. Argument`node`specifies the identifier of the node. If`node`is equal to -1, then action emission matrices of all nodes of the multinode model will be dumped. Dumping is performed according to parameters specified in *`desc_p`. If`desc_p`is`NULL`

, then default parameters will be used.In the current implementation, if

`desc_p`is not`NULL`

, then *`desc_p`will not be modified as a result of the function call. However, in future versions of the package the contents of *`desc_p`could be modified by the function, e.g. statistics on the dumping process could be written there.The function returns a non-negative value on success or a negative error code on failure. Currently, the following error codes can be returned.

`QSMM_ERR_UNTIMELY`

The model instance does not exist.

`QSMM_ERR_INVAL`

The value of

`desc_p`is not`NULL`

, and parameters specified in *`desc_p`are invalid.`QSMM_ERR_NOTFOUND`

The value of

`node`is not -1, and a node with identifier`node`does not exist.`QSMM_ERR_STORAGE`

An Actor API function did return error

`QSMM_ERR_STORAGE`

. This could leave the model instance in indeterminate state.`QSMM_ERR_NOMEM`

There was not enough memory to perform the operation. This could leave the model instance in indeterminate state.

A structure, which specifies parameters of dumping, is described below.

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

- Field:
*char***do_print_prob[QSMM_PROB_COUNT]** An array that specifies probabilities of which types to dump. Indices of the array are the elements of enumeration

`qsmm_prob_e`

(except for the last element) described in Generating an Optimal Action. If an element of the array has a non-zero value, then probabilities of the corresponding type will be dumped. The default is to dump probabilities of all supported types.

- Field:
*int***indent** Left indent, i.e. 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 is a positive number, then use fixed-point notation. If is a negative number, then use exponential notation with the number of digits after the decimal point equal to the absolute value of the field. If is zero, then use exponential notation with 15 digits after the decimal point, which is the default mode.

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

`fq`

of an instance of structure`qsmm_cycle_s`

, which corresponds to the intersection of a row and a column of the matrix. Information on instances with lesser value of field`fq`

, i.e. which have lesser frequency, will not be included in the output. The default is to use value 0 for the minimum frequency.

- Field:

To improve compatibility with future versions of the library, an instance of structure `qsmm_dump_mat_action_desc_s`

, a pointer to which is passed to the function `qsmm_mat_action_dump`

, should be zeroed using the function `memset`

before setting values of structure fields.

Below there is shown a fragment of a dump.
When creating the dump, only element `QSMM_PROB_LEARNED`

of field `do_print_prob`

of structure `qsmm_dump_mat_action_desc_s`

was set to a non-zero value.
To make lines of the example shorter, some digits in fractional parts of numbers in exponential notation were replaced with ellipses.

* 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 is a key for the dump. For information on fields of structures referenced, see Structures for Accessing Storage.

`A`

`i`The description of an action with index

`i`for a state. Starting from QSMM version 1.15, the name of an instruction class that corresponds to the action is dumped after token`A`

between characters ‘`i``|`’.`action_next`

The index of the last action emitted in a state. Corresponds to the value of field

`sig_cycle_next`

of structure`qsmm_state_s`

. Special value ‘`N`’ corresponds to the value`QSMM_SIG_INVALID`

of that field.`fq`

The value of field

`fq`

of structure`qsmm_cycle_s`

.`pa`

The probability of type

`QSMM_PROB_AGGR`

.`pf`

The probability of type

`QSMM_PROB_FQ`

.`pl`

The probability of type

`QSMM_PROB_LEARNED`

.`pp`

The probability of type

`QSMM_PROB_PROFILE`

.`ps_c`

The value of field

`period_sum_c`

of structure`qsmm_cycle_s`

.`ps_d`

The value of field

`period_sum_d`

of structure`qsmm_cycle_s`

.`spur[`

`i`].dsThe value of field

`delta_sum`

of structure`qsmm_cspur_s`

for spur type`i`.`spur[`

`i`].val0The value of field

`val0`

of structure`qsmm_sspur_s`

for spur type`i`.`State`

The description of a state. Starting from QSMM version 1.15, if the state has a name assigned by an argument of

`stt`

assembler instruction, then that name will be dumped after the index of the state in quotes.`tmc0`

The value of field

`tmc0`

of structure`qsmm_state_s`

.`tmd0`

The value of field

`tmd0`

of structure`qsmm_state_s`

.

Starting from QSMM version 1.14, descriptions only of those actions for an action choice state are dumped, information on which is held in storage. Omitting actions, information on which is absent in storage, reduces the length of the output when dumping a sparse action emission matrix.

When not all descriptions of actions are dumped, either because of a positive value of field `fq_min`

of structure `qsmm_dump_mat_action_desc_s`

or because information on some actions is absent in storage, the sum of probabilities (of a specific type) of actions for an action choice state may be less than 1.
If the field `fq_min`

has zero value, then every action that was not dumped will have a probability equal to *(1-p)/n*, where *p* is the sum of probabilities of actions, which were dumped, and *n* is the number of actions that were not dumped.