Next: Dumping an Action Emission Matrix, Previous: Working with System and User Stacks, Up: Multinode Model [Contents][Index]

The state transition matrix of a node contains transition probabilities of supported types along with other numeric information. Rows of the matrix correspond to quadruples, each consisting of a source state, a user or mixed type instruction invoked in that state, the outcome of that instruction, and the contents of the look-ahead signal segment. Columns of the matrix correspond to target transition states. To dump a state transition matrix to a stream, the following function can be used.

- Function:
*int***qsmm_mat_goto_dump***(qsmm_t*`model`, int`node`, struct qsmm_dump_mat_goto_desc_s *`desc_p`, FILE *`filep`) This function dumps the state transition 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 state transition 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_goto_desc_s** This structure specifies parameters of dumping the state transition 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 Emitting an Output Signal. 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 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_goto_desc_s`

, a pointer to which is passed to the function `qsmm_mat_goto_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_goto_desc_s`

was set to a non-zero value.
To make lines of the example shorter, fractional parts of numbers in exponential notation were truncated, and the numbers were rounded.

* State 83 A0 |mn| O7 L0 : tmd0=183117, tmc0=6E+4, state_next=45, spur[0].val0=-4E+5, spur[1].val0=4E+2 S45 : pl=1.0E+00, spur[0].ds=-3E+05, spur[1].ds=4E+02, fq=376, ps_d=148416, ps_c=5E+04 S79 : pl=4.2E-267, spur[0].ds=-4E+04, spur[1].ds=1E+01, fq=3, ps_d=23976, ps_c=8E+03 S92 : pl=9.1E-283, spur[0].ds=-2E+04, spur[1].ds=4E+00, fq=2, ps_d=9516, ps_c=3E+03 A0 |mn| O7 L1 : tmd0=183219, tmc0=6E+4, state_next=120, spur[0].val0=-4E+5, spur[1].val0=4E+2 S63 : pl=2.2E-245, spur[0].ds=-4E+04, spur[1].ds=1E+01, fq=5, ps_d=22740, ps_c=8E+03 S87 : pl=2.0E-292, spur[0].ds=-3E+02, spur[1].ds=0E+00, fq=1, ps_d=156, ps_c=5E+01 S120 : pl=1.0E+00, spur[0].ds=-3E+05, spur[1].ds=4E+02, fq=119, ps_d=160185, ps_c=5E+04

Below there is a key for the dump. For information on fields of structures referenced, see Structures for Accessing Storage.

`A`

`i`An instruction invoked by the node in a source transition state. Index

`i`is a number that uniquely identifies the instruction, i.e. the instruction class, in an instruction class set which is a node class of the node. Starting from QSMM version 1.15, the name of the instruction class is dumped after token`A`

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

`i`Look-ahead signal

`i`that was in the look-ahead signal segment of multinode model when the node was in a source transition state. The number of tokens`L`

is equal to the length of the look-ahead signal segment of multinode model. Positions of tokens`i``L`

are equal to positions of look-ahead signals in the look-ahead signal segment.`i``O`

`i`Outcome

`i`of an instruction invoked by the node in a source transition state.`S`

`i`The description of a transition to target state

`i`. 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 token`S`

in quotes.`i``RST`

This keyword can replace tokens ‘

`A`’ for source transition state 0. The keyword indicates that one of specified transitions to target states will be made when control is just transferred to the node. In such situation the node did not invoke instructions yet, so values`x`|`name`| O`y``x`and`y`are unknown.`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 type 0 usually corresponds to the automatic spur.`spur[`

`i`].val0The value of field

`val0`

of structure`qsmm_sspur_s`

for spur type`i`. Spur type 0 usually corresponds to the automatic spur.`State`

The index of a source transition 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.`state_next`

The index of target state of the last transition made from a source 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.`tmc0`

The value of field

`tmc0`

of structure`qsmm_state_s`

.`tmd0`

The value of field

`tmd0`

of structure`qsmm_state_s`

.

Descriptions only of those transitions to target states are dumped, information on which is held in storage. Omitting transitions, information on which is absent in storage, reduces the length of the output when dumping a sparse state transition matrix.

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

of structure `qsmm_dump_mat_goto_desc_s`

or because information on some transitions is absent in storage, the sum of probabilities (of a specific type) of transitions to target states in a row of the matrix may be less than 1.
If the field `fq_min`

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