Next: , Previous: , Up: Multinode Model   [Contents][Index]


4.14 Dumping an Action Emission Matrix

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.

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.

Ai

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 Ai between characters ‘|’.

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].ds

The value of field delta_sum of structure qsmm_cspur_s for spur type i.

spur[i].val0

The 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.


Next: , Previous: , Up: Multinode Model   [Contents][Index]