The state transition matrix of a node contains transition probabilities of supported types along with other numeric information. The rows of that matrix biuniquely correspond to quadruples where each quadruple consists of a source transition state, a user or mixed-type instruction invoked in the source transition state, the outcome of this instruction, and the content of look-ahead signal segment. The columns of that matrix biuniquely correspond to target transition states. Use the following function to dump a state transition matrix to a stream.
This function dumps the state transition 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 state transition 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 environment state identification 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 model instance in inconsistent state.
The description of a structure specifying dumping parameters is below.
This structure specifies the parameters of dumping the state transition matrix of a node. The structure contains the following fields.
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_goto_dump_v2
dumps probabilities with a corresponding type.
The default is to dump probabilities of all types.
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.
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.
The minimum value of fq
field of an instance of qsmm_cycle_s
structure for a matrix cell.
The function qsmm_mat_goto_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_goto_desc_s
structure before setting the fields of this instance passed to the function qsmm_mat_goto_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_goto_desc_s
structure passed to qsmm_mat_goto_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 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 are descriptions of output pieces of information. See Structures for Accessing Storage, for details about referenced structure fields.
Ai
An instruction class invoked by the node in a source transition 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 Ai
.
Li
Look-ahead signal i that was in the look-ahead signal segment when the node was in a source transition state.
The number of Li
tokens is equal to look-ahead signal segment length.
The positions of Li
tokens are the positions of elements in the look-ahead signal segment.
Oi
Outcome i of an instruction class invoked by the node in a source transition state.
Si
The description of a transition to target state i.
If the state has a name assigned by the argument of stt
assembler instruction, the name enclosed in double quotes follows the token Si
.
RST
This keyword can replace the tokens ‘Ax |name| Oy’ for source transition state 0. The keyword indicates that specified transitions to target states are initial transitions performed just after transferring control to the node. In this situation, the node did not yet invoke instructions, so values x and y are unknown.
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].ds
The value of delta_sum
field of qsmm_cspur_s
structure for spur type i.
Spur type 0 is usually the automatic spur.
spur[i].val0
The value of val0
field of qsmm_sspur_s
structure for spur type i.
Spur type 0 is usually the automatic spur.
State
The index of a source transition state.
If the state has a name assigned by the argument of stt
assembler instruction, the name enclosed in double quotes follows that index.
state_next
The index of target state of last transition made from a source 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.
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_goto_dump_v2
dumps only the descriptions of state transitions that have some information in statistics storage.
This approach helps reduce the length of output when dumping a sparse state transition matrix.
When the descriptions of some state transitions are absent in the output because of a positive value of fq_min
field of qsmm_dump_mat_goto_desc_s
structure or because statistics storage does not contain information on some state transitions, the sum of state transition probabilities with a specific type may be less than 1 in a matrix row.
If the field fq_min
is zero, every not dumped transition has probability (1-p)/n, where p is the sum of probabilities of dumped transitions, and n is the number of not dumped transitions.