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

The purpose of output probability variables is to retrieve probabilities learned while executing or training a node.
You do not register variables of this kind in an instruction class set.
The function `qsmm_node_asm`

called with the `QSMM_ASM_VAR_OUT`

flag automatically collects information on output probability variables in a memory representation of an assembler program while loading it into a node.
An output probability variable can be a controlled probability variable.

Not every probability variable in an assembler program becomes an output probability variable.
The first restriction is that the variable must occur in only one `jprob`

or `case`

instruction.
The second restriction is that the variable must have unambiguous context.
If a probability variable violates at least one of these restrictions, but the function `qsmm_reg_var_prob`

or macro `QSMM_REG_VAR_PROB`

has registered it as a controlled probability variable, it becomes only a controlled probability variable.
If `qsmm_node_asm`

receives the `QSMM_ASM_VAR_AUX`

flag, a probability variable violates at least one of these restrictions and is not a controlled probability variable, that function treats the probability variable as an auxiliary variable.
If `qsmm_node_asm`

does not receive `QSMM_ASM_VAR_AUX`

, a probability variable violates at least one of these restrictions and is not a controlled probability variable, that function reports an error.

Every output probability variable corresponds to either the state transition matrix or action emission matrix. The enumeration described below represents a matrix type.

- Enumeration:
**qsmm_mat_e** This enumeration specifies a matrix type. The enumeration contains the following elements.

`QSMM_MAT_GOTO`

The state transition matrix.

`QSMM_MAT_ACTION`

The action emission matrix.

`QSMM_MAT_COUNT`

The number of supported matrix types.

Use the function described below to get the type of a matrix corresponding to an output probability variable.

- Function:
*int***qsmm_get_node_var_prob_mat***(qsmm_t*`model`, const char *`var_name`, qsmm_sig_t`node`, enum qsmm_mat_e *`mat_p`) This function retrieves the type of a matrix corresponding to the output probability variable

`var_name`of a node of a multinode`model`. The argument`node`specifies the identifier of this node. If`mat_p`is not`NULL`

, the function sets *`mat_p`to a retrieved type.If the node uses a source probability profile provided by another node, the function retrieves the type of the matrix of the output probability variable 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 probability variable named`var_name`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.

Fetching the value of an output probability variable requires calculating the relative probabilities of all choice alternatives that include an alternative corresponding to the output probability variable.
The cache of calculated probabilities of choice alternatives speeds up fetching the values of output probability variables for other choice alternatives later.
Along with the cache of calculated probabilities of choice alternatives, a node keeps the cache of calculated values of output probability variables.
To free memory, you can clear both caches by the function `qsmm_node_var_out_forget`

described further on in this subsection.

An output probability variable can correspond to multiple cells of a state transition matrix. The following fragment of an assembler program illustrates this situation.

stt "s0" test ; user instruction with multiple ; outcomes (e.g. 3) jprob var0, L2 stt "s1" ... L2: stt "s2"

The above fragment of an assembler program does not condition on specific outcomes of ‘`test`’ instruction (i.e. handles them in the same way).
The state transition matrix has rows for all three outcomes of this instruction and columns for the states ‘`s0`’, ‘`s1`’, and ‘`s2`’.
The fragment of that state transition matrix is in Figure 5.1.
There
*ν*
denotes a frequency of state transition, and `pp`

denotes a profile probability.

The function `qsmm_get_node_var_prob_out`

described further on in this subsection supports calculating probabilities of `QSMM_PROB_PROFILE`

and `QSMM_PROB_FQ`

types for output probability variables corresponding to individual and multiple cells of state transition matrix and corresponding to individual cells of action emission matrix.
That function supports calculating probabilities of `QSMM_PROB_AGGR`

and `QSMM_PROB_LEARNED`

types for output probability variables corresponding to individual cells only.

If an output probability variable corresponds to multiple cells of state transition matrix, profile probabilities in those multiple cells are equal, and `qsmm_get_node_var_prob_out`

returns them as a `QSMM_PROB_PROFILE`

probability.
For the above example, `qsmm_get_node_var_prob_out`

returns value `var0`

as the probability `QSMM_PROB_PROFILE`

of ‘`var0`’ output probability variable.
That function does not support calculating probabilities of `QSMM_PROB_AGGR`

and `QSMM_PROB_LEARNED`

types for this output probability variable.

To calculate a `QSMM_PROB_FQ`

probability, `qsmm_get_node_var_prob_out`

takes the sums of frequencies of transitions to target states for relative probabilities.
For example, to calculate the probability `QSMM_PROB_FQ`

of ‘`var0`’ output probability variable, `qsmm_get_node_var_prob_out`

calculates the sums
*ν _{0,1}+ν_{1,1}+ν_{2,1}*
and

As already mentioned, a probability variable used in multiple `jprob`

and `case`

instructions cannot be an output probability variable.
The following fragment of an assembler program illustrates this situation.

L1: user 0 ; user instruction jprob var0, L1 ; first occurrence of `var0' variable L2: user 1 ; user instruction jprob var0, L2 ; second occurrence of `var0' variable; ; encountering this occurrence means that ; `var0' cannot be an output ; probability variable jmp L1

A probability variable used once but in ambiguous context cannot be an output probability variable too.
At present, only `jprob`

instructions can have ambiguous context.
The context of a `jprob`

instruction is ambiguous if the blocks of `jprob`

instructions with different start addresses include this `jprob`

instruction.
The following fragment of an assembler program illustrates this situation.

L1: user 0 jprob 0.5, L3

L2: jprob var0, L1 user 1

L3: user 2 jmp L2

After invoking the ‘`user 0`’ instruction, the block consisting of ‘`jprob 0.5, L3`’ and ‘`jprob var0, L1`’ instructions selects the next instruction to execute.
However, after invoking the ‘`user 2`’ instruction, only the last instruction of that block selects the next instruction to execute.
In the first case, the block begins with the ‘`jprob 0.5, L3`’ instruction, and, in the second case, the block begins with the ‘`jprob var0, L1`’ instruction and contains only this instruction.
That is, the blocks have different start addresses, the ‘`jprob var0, L1`’ instruction those blocks contain has ambiguous context, and, therefore, the variable ‘`var0`’ cannot be an output probability variable.

If the function `qsmm_node_asm`

has not generated any warnings for an assembler program it loaded into a node, the assembler program does not contain instructions in ambiguous context.
If `qsmm_node_asm`

received the `QSMM_ASM_VAR_OUT`

flag, all probability variables that occurred only once in this assembler program became output probability variables.

Use the following function to get the names of output probability variables of a node.

- Function:
*int***qsmm_enum_var_prob_out***(qsmm_t*`model`, qsmm_sig_t`node`, qsmm_enum_ent_callback_func_t`callback_func`, void *`paramp`) This function enumerates output probability variables defined in an assembler program loaded into a node of a multinode

`model`. The argument`node`specifies the identifier of this node.The process of enumeration is repeated calling a callback function

`callback_func`receiving`QSMM_LREF_PROB_VAR_OUT`

as the type of a local entity reference, the name of an output probability variable in a local entity identifier, and a user parameter`paramp`. See Enumerating Entities, for the description of callback function type.If the callback function returns a positive value, the function

`qsmm_enum_var_prob_out`

continues the enumeration. If the callback function returns zero,`qsmm_enum_var_prob_out`

terminates the enumeration and reports success. If the callback function returns a negative value,`qsmm_enum_var_prob_out`

terminates the enumeration and reports failure.If the node uses a source probability profile provided by another node, the function enumerates the output probability variables of the latter node. See Memory Efficient Cloning the Probability Profile, for a detailed description of this mode.

The function

`qsmm_enum_var_prob_out`

does not enumerate the output probabilities arrays of a node. See Output Arrays, for an example program that enumerates those arrays and prints their content.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`does not exist.`QSMM_ERR_CALLBACK`

The callback function reported an error.

Use the function described below to retrieve the value of an output probability variable.

- Function:
*int***qsmm_get_node_var_prob_out***(qsmm_t*`model`, const char *`var_name`, qsmm_sig_t`node`, enum qsmm_prob_e`prob_type`, double *`valp`) This function retrieves the value of the output probability variable

`var_name`of a node of a multinode`model`. The argument`node`specifies the identifier of this node.The argument

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

enumeration. If`valp`is not`NULL`

, the function sets *`valp`to a retrieved probability.If the node uses a source probability profile provided by another node, the function obtains information how to calculate the output probability variable from the latter node. See Memory Efficient Cloning the Probability Profile, for a detailed description of this mode.

If the function is able to retrieve the value of that output probability variable, the function sets *

`valp`to that value (if`valp`is not`NULL`

) and returns 2. If`prob_type`is`QSMM_PROB_AGGR`

or`QSMM_PROB_LEARNED`

, and the output probability variable corresponds to multiple cells of state transition matrix, the function sets *`valp`to -2 (if`valp`is not`NULL`

) and returns 1. If`var_name`is a controlled or auxiliary probability variable that occurs more than once in an assembler program loaded into the node or has ambiguous context in the assembler program, the function sets *`valp`to -1 (if`valp`is not`NULL`

) and returns 0.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.`QSMM_ERR_NOTFOUND`

A node with identifier

`node`does not exist, or the node does not have an assembler program loaded, or the assembler program does not define a probability variable named`var_name`.`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.

You can retrieve output probabilities for `case`

instructions in `choice`

instruction blocks via output probability variables in the `case`

instructions or via output probabilities arrays referred to by location labels assigned to the `choice`

instruction blocks.
Use the function `qsmm_get_node_array_prob_out`

described in Output Arrays to retrieve an output probabilities array for a `choice`

instruction block.

QSMM supports fetching aggregate statistics on cycle types for output probability variables and the elements of output probabilities arrays. The statistics are aggregate in the sense that if an output probability variable or an element of an output probabilities array corresponds to multiple cells of state transition matrix, the statistics includes statistics on cycle types in all those cells. If an output probability variable or an element of an output probabilities array corresponds to the action emission matrix, aggregate statistics are simply statistics on a cycle type in an individual cell.

Use the function described below to fetch aggregate statistics on cycle types associated with an output probability variable.
Use the function `qsmm_get_node_array_prob_cycle`

described in Output Arrays to fetch aggregate statistics on cycle types associated with an element of an output probabilities array.

- Function:
*int***qsmm_get_node_var_prob_cycle***(qsmm_t*`model`, const char *`var_name`, qsmm_sig_t`node`, struct qsmm_cycle_s *`cycle_p`, struct qsmm_cspur_s *`cspur_p`) This function retrieves aggregate statistics on cycle types for the output probability variable

`var_name`of a node of a multinode`model`. The argument`node`specifies the identifier of this node. 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 probability variable 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 probability variable 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_var_prob_mat`

described earlier in this subsection retrieves the type of a matrix corresponding to an output probability variable.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 output probability variable. The field`cycle_p``->profile`

is equal to that field for last cycle type associated with the output probability variable, 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 output probability variable.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_NOTFOUND`

A node with identifier

`node`or an output probability variable named`var_name`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.

The function `qsmm_get_node_var_prob_out`

stores all values of output probability variables calculated for a node in a cache within the node.
The functions `qsmm_node_call_default`

(see Calling a Node), `qsmm_node_unload`

(see Unloading the Probability Profile), and `qsmm_engine_destroy`

(see Creating the Model Instance) and the function `qsmm_node_disasm`

called to disassemble a node assembled with the `QSMM_ASM_TEMPLATE`

flag automatically clear this cache along with the cache of calculated probabilities of choice alternatives mentioned earlier.
To free memory, you can manually clear both caches by the following function.

- Function:
*int***qsmm_node_var_out_forget***(qsmm_t*`model`, qsmm_sig_t`node`) This function clears a cache of calculated probabilities of output probability variables and a cache of calculated probabilities of choice alternatives both stored in a node of a multinode

`model`. The argument`node`specifies the identifier of this node. The function`qsmm_get_node_var_prob_out`

uses both caches to speed up retrieving the output probability variables of this node. The function`qsmm_get_node_array_prob_out`

uses the second cache to speed up retrieving the output probabilities arrays of this node.On success, the function returns a non-negative value. If a node with identifier

`node`does not exist, the function returns negative error code`QSMM_ERR_NOTFOUND`

.