4.4.2 Dumping the Action Emission Matrix ¶

The action emission matrix of a node contains the probabilities of emitting all instruction classes belonging to the instruction class set of the node in all its states. 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 the node. If node is equal to QSMM_SIG_INVALID, the function dumps action emission matrices of all nodes of the 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

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

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 types of probabilities to dump. Array indices are the elements of qsmm_prob_e enumeration (except for its last element QSMM_PROB_COUNT) described in Emitting an Output Signal. If an array element 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.

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 its fields.

Below there is an example dump fragment. When generating the dump, the element QSMM_PROB_LEARNED of do_print_prob field of qsmm_dump_mat_action_desc_s structure passed to the function qsmm_mat_action_dump_v2 was non-zero, and all other elements of this array were zero. The fragment contains truncated fractional parts of numbers in exponential notation to make lines shorter.

* State 1 : tmd0=2711, action_next=0, spur[0].val0=4.00...E+00, time[0].val0=1.20...E+03

  A0 |me| : pl=9.9...E-01, spur[0].ds=4.0...E+00, time[0].ds=8.2...E+02, fq=43, ps_d=1965
  A1 |ms| : pl=3.4...E-03, spur[0].ds=0.0...E+00, time[0].ds=9.8...E+01, fq=49, ps_d=147
  A2 |mw| : pl=3.4...E-03, spur[0].ds=0.0...E+00, time[0].ds=7.2...E+01, fq=36, ps_d=108

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

Ai

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. For an individual instruction class, its name enclosed between the characters ‘|’ follows the token Ai. For an instruction class sequence, a column of names of individual instruction classes comprising the sequence enclosed between two columns of ‘|’ characters follows the token Ai.

action_next

The index of the last instruction class emitted in a node state. The field sig_cycle_next of qsmm_state_s structure contains that index. The special value ‘N’ corresponds to the value QSMM_SIG_INVALID of that 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_d

The value of period_sum_d field of qsmm_cycle_s structure.

spur[i].ds

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

spur[i].val0

The value of val0 field of qsmm_sspval_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 the index.

time[i].ds

The value of delta_sum field of qsmm_cspval_s structure for continuous time type i.

time[i].val0

The value of val0 field of qsmm_sspval_s structure for continuous time type i.

tmd0

The value of tmd0 field of qsmm_state_s structure.

The function qsmm_mat_action_dump_v2 lists only instruction classes that have some information 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 emission probabilities of instruction classes dumped for a node state, and n is the number of instruction classes not dumped for the node state.