Next: Auxiliary Variables, Previous: Output Variables, Up: Using Probability Variables [Contents][Index]

A location label assigned to a `choice`

instruction block refers to an output probabilities array for this `choice`

instruction block.
The `choice`

instruction block might look like this:

ARR: choice case 0.15, L1 case 0.05, L2 case 0.10, L3 case 0.20, L4 end choice

This example defines the output probabilities array ‘`ARR`’ with four elements corresponding to `case`

instructions in the `choice`

instruction block.
The element with index 0 corresponds to the ‘`case 0.15, L1`’ instruction, and the element with index 3 corresponds to the ‘`case 0.20, L4`’ instruction.

An output probabilities array corresponds to either the state transition matrix or action emission matrix. Use the function described below to get a matrix type.

- Function:
*int***qsmm_get_node_array_prob_mat***(qsmm_t*`model`, const char *`label`, qsmm_sig_t`node`, enum qsmm_mat_e *`mat_p`) This function retrieves the type of a matrix corresponding to an output probabilities array of a node of a multinode

`model`. The argument`node`specifies the identifier of this node. A location`label`assigned to a`choice`

instruction block in an assembler program loaded into the node identifies the array. If`mat_p`is not`NULL`

, the function sets *`mat_p`to a retrieved type. See Output Variables, for the description of elements of`qsmm_mat_e`

enumeration.If the node uses a source probability profile provided by another node, the function retrieves the type of the matrix of the output probabilities array of the latter node. See Memory Efficient Cloning the Probability Profile, for a detailed description of this mode.

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`

A node with identifier

`node`or an output probabilities array`label`does not exist.`QSMM_ERR_UNTIMELY`

The model instance does not exist.

`QSMM_ERR_UNSUPPLA`

The multinode model has positive length of look-ahead signal segment.

`QSMM_ERR_NOMEM`

There was not enough memory to perform the operation.

Use the function described below to get a segment of an output probabilities array.

- Function:
*int***qsmm_get_node_array_prob_out***(qsmm_t*`model`, const char *`label`, qsmm_sig_t`node`, size_t`from`, size_t`to`, enum qsmm_prob_e`prob_type`, double *`prob_p`) This function retrieves a segment of an output probabilities array of a node of a multinode

`model`. The argument`node`specifies the identifier of this node. A location`label`assigned to a`choice`

instruction block in an assembler program loaded into the node identifies the array. If`prob_p`is not`NULL`

, the function copies output probabilities from the array to a buffer`prob_p`starting at offset 0.The argument

`prob_type`specifies the type of probabilities to retrieve. See Emitting an Output Signal, for the description of elements of`qsmm_prob_e`

enumeration. If`prob_type`is`QSMM_PROB_AGGR`

or`QSMM_PROB_LEARNED`

, and each array element corresponds to multiple cells of state transition matrix, the function retrieves all array elements equal to -2.The arguments

`from`and`to`specify the index of first element and the index of last element (exclusive) for the retrieved array segment. If`to`is 0, the function uses array length as the index of last element. The number of elements copied to`prob_p`is equal to the index of last element minus`from`.A special element of an output probabilities array at index equal to array length corresponds to a choice alternative beneath the

`choice`

instruction block. This choice alternative receives control if none of`case`

instructions in the`choice`

instruction block transferred control elsewhere. To retrieve this special element, specify`to`equal to array length plus 1.If the node uses a source probability profile provided by another node, the function obtains information how to calculate the array elements from the latter node. See Memory Efficient Cloning the Probability Profile, for a detailed description of this mode.

On success, the function returns a positive number of elements to store in

`prob_p`starting at offset 0 as if`prob_p`is never`NULL`

. If this number is greater than`INT_MAX`

, the function returns`INT_MAX`

. On failure, the function returns a negative error code. Currently, the function can return the following error codes.`QSMM_ERR_INVAL`

The argument

`prob_type`is invalid, or`from`is greater than or equal to the index of last element, or`to`is greater than array length plus 1.`QSMM_ERR_NOTFOUND`

A node with identifier

`node`or an output probabilities array`label`does not exist.`QSMM_ERR_UNTIMELY`

The model instance does not exist.

`QSMM_ERR_UNSUPPLA`

The multinode model has positive length of look-ahead signal segment.

`QSMM_ERR_CALLBACK`

A helper function for computing the relative probability of an output signal 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.

When calculating a segment of an output probabilities array of a node, the function `qsmm_get_node_array_prob_out`

stores in a cache within the node the calculated probabilities of all choice alternatives corresponding to the output probabilities array.
The cache speeds up retrieving the elements of this output probabilities array later.
Call the function `qsmm_node_var_out_forget`

to manually clear the cache.
See Output Variables, for more information on the cache and functions that clear it automatically.

Use the function described below to fetch aggregate statistics on cycle types associated with an element of an output probabilities array. See Output Variables, for the description of a counterpart function fetching aggregate statistics on cycle types associated with an output probability variable and for additional information on the concept of aggregate statistics.

- Function:
*int***qsmm_get_node_array_prob_cycle***(qsmm_t*`model`, const char *`label`, qsmm_sig_t`node`, size_t`offs`, struct qsmm_cycle_s *`cycle_p`, struct qsmm_cspur_s *`cspur_p`) This function retrieves aggregate statistics on cycle types for an element of an output probabilities array of a node of a multinode

`model`. The argument`node`specifies the identifier of this node. A location`label`assigned to a`choice`

instruction block in an assembler program loaded into the node identifies the array.The argument

`offs`specifies the index of this array element. A special element of an output probabilities array at index equal to array length corresponds to a choice alternative beneath the`choice`

instruction block. This choice alternative receives control if none of`case`

instructions in the`choice`

instruction block transferred control elsewhere.If

`cycle_p`is not`NULL`

, the function sets *`cycle_p`to aggregate statistics on the cycle types. If`cspur_p`is not`NULL`

, the function sets *`cspur_p`to aggregate statistics on spur types for the cycle types. See Structures for Accessing Storage, for the descriptions of`qsmm_cycle_s`

and`qsmm_cspur_s`

structures.If

`cspur_p`is not`NULL`

, and the output probabilities array corresponds to the state transition matrix, the array`cspur_p`must be capable of holding the number of elements returned by the function`qsmm_get_nspur`

. If`cspur_p`is not`NULL`

, and the output probabilities array corresponds to the action emission matrix, the array`cspur_p`must be capable of holding the number of elements returned by`qsmm_get_nspur`

minus 1. The function`qsmm_get_node_array_prob_mat`

described earlier in this subsection retrieves the type of a matrix corresponding to an output probabilities array.The aggregate statistics composes from statistics on individual cycle types in the following way. The fields

`fq`

,`period_sum_d`

, and`period_sum_c`

of *`cycle_p`are the sums of those fields for all cycle types associated with the element of the output probabilities array. The field`cycle_p``->profile`

is equal to that field for last cycle type associated with the element of the output probabilities array, as all such cycle types have the same value of`profile`

field. The fields`delta_sum`

in the elements of`cspur_p`array are the sums of corresponding fields for all cycle types associated with the element of the output probabilities array.If the node uses a source probability profile provided by another node, the function obtains information how to calculate aggregate statistics from the latter node. See Memory Efficient Cloning the Probability Profile, for a detailed description of this mode.

On success, the function returns a non-negative number of cycle types making up the aggregate statistics. If this number is greater than

`INT_MAX`

, the function returns`INT_MAX`

. On failure, the function returns a negative error code. Currently, the function can return the following error codes.`QSMM_ERR_INVAL`

The argument

`offs`is greater than the length of the output probabilities array.`QSMM_ERR_NOTFOUND`

A node with identifier

`node`or an output probabilities array`label`does not exist.`QSMM_ERR_UNTIMELY`

The model instance does not exist.

`QSMM_ERR_UNSUPPLA`

The multinode model has positive length of look-ahead signal segment.

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

To dump the contents of all output probabilities arrays defined in an assembler program, consider only instructions with the type `QSMM_INSTR_CHOICE`

.
Use the function `qsmm_get_instr_type`

to obtain the type of an assembler instruction by its handle.
If an instruction with the type `QSMM_INSTR_CHOICE`

has at least one location label assigned, the instruction has an associated output probabilities array.
The call `qsmm_get_instr_label(`

, where `instr`,0)

is an instruction handle, returns the first location label identifying the output probabilities array.
If that call returns `instr``NULL`

, the instruction does not have location labels assigned and, therefore, does not have an associated output probabilities array.
The length of an associated output probabilities array is equal to the return value of `qsmm_get_instr_nnested`

function minus 1, as the last nested instruction is the ‘`end choice`’ instruction.

Below there is an example function that dumps the contents of all output probabilities arrays of a

containing an assembler program `node`

.
The function returns 0 on success or -1 on out of memory error.
`prg`

#include <stdlib.h> #include <qsmm/qsmm.h> static int dump_arr_prob_out( qsmm_t qsmm, qsmm_sig_tnode, qsmm_prg_tprg, enum qsmm_prob_e prob_type ) { int result=-1; double *probp=0; size_t prob_allo=0; const size_t ninstr=qsmm_get_prg_ninstr(prg); for (size_t iinstr=0; iinstr<ninstr; iinstr++) { const qsmm_instr_t instr=qsmm_get_prg_instr(prg,iinstr); const char *const labelp=qsmm_get_instr_label(instr,0); if (!labelp) continue; if (qsmm_get_instr_type(instr)!=QSMM_INSTR_CHOICE) continue; const size_t nprob=qsmm_get_instr_nnested(instr)-1;

if (prob_allo<nprob) { double *const newp=realloc(probp,nprob*sizeof(*newp)); if (!newp) goto Exit; prob_allo=nprob; probp=newp; }

qsmm_get_node_array_prob_out(qsmm, labelp, node, 0, nprob, prob_type, probp); for (size_t iprob=0; iprob<nprob; iprob++) printf("%s[%zu]=%.15E\n",labelp,iprob,probp[iprob]); } result=0; Exit: if (probp) free(probp); return result; }