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

Output probability variables are used to retrieve probabilities learned during training a node.
Variables of this kind need not be registered in the instruction class set.
Information on output probability variables is automatically fetched from the memory representation of an assembler program when loading the assembler program into a node by the function `qsmm_node_asm`

, to which the `QSMM_ASM_VAR_OUT`

flag is passed.
An output probability variable can be a controlled probability variable.

Not every probability variable encountered in the memory representation of an assembler program will be registered as an output probability variable of the node.
The first restriction is that the variable must be used in only one `jprob`

or `case`

instruction.
The second restriction is that the variable must be used in unambiguous context.
If a probability variable violates at least one of these restrictions, but is registered in the instruction class set as a controlled probability variable, then it will be only a controlled probability variable.
If the `QSMM_ASM_VAR_AUX`

flag is passed to the function `qsmm_node_asm`

, a probability variable violates at least one of the above restrictions and is not registered in the instruction class set as a controlled probability variable, then it will be treated as an auxiliary variable.
If the `QSMM_ASM_VAR_AUX`

flag is not passed to the function `qsmm_node_asm`

, a probability variable violates at least one of the above restrictions and is not registered in the instruction class set as a controlled probability variable, then an error will be reported.

Every output probability variable corresponds either to the state transition matrix or the action emission matrix of a node. The enumeration described below defines a matrix type. This enumeration was introduced in QSMM version 1.16.

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

`QSMM_MAT_GOTO`

The state transition matrix.

`QSMM_MAT_ACTION`

The action emission matrix.

To get the type of a matrix that corresponds to an output probability variable, use the function described below. This function was introduced in QSMM version 1.16.

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

`var_name`of a node of a multinode model specified by handle`model`. Argument`node`specifies the identifier of the node. If`mat_p`is not`NULL`

, then the function will set *`mat_p`to the type of the matrix. If the node uses a source probability profile provided by another node, then this function will retrieve the type of the matrix of the output probability variable of the latter node.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_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 the look-ahead signal segment.

`QSMM_ERR_NOMEM`

There was not enough memory to perform the operation.

To calculate the value of an output probability variable, there are calculated relative probabilities of all choice alternatives that include an alternative to which the probability variable corresponds. After that, the relative probabilities are normalized to obtain values of output probability variables that correspond to the choice alternatives. Calculated values are cached.

An output probability variable might correspond to many cells of the state transition matrix of a node.
When a type of probability to retrieve for the variable is `QSMM_PROB_FQ`

, then for a relative probability, the sum of frequencies of transitions to target states stored in the cells will be taken.
When a type of probability to retrieve is not `QSMM_PROB_FQ`

, then for a relative probability, the weighted mean of output probabilities in those cells will be taken.
The weights are the frequencies of transitions to target states stored in the cells.
A situation when an output probability variable corresponds to several cells of the state transition matrix is illustrated by the following fragment of an assembler program.

stt "s0" test 3 ; user instruction with 3 outcomes jprob var0, L2 stt "s1" ... L2: stt "s2"

Instruction ‘`test 3`’ has three outcomes, but in the above fragment of an assembler program they all are processed in the same way.
The state transition matrix has rows for all outcomes of the instruction and columns for states ‘`s0`’, ‘`s1`’, and ‘`s2`’.
The fragment of the state transition matrix is represented in Figure 5.1.
There *p* denotes an output probability,
*ν*
denotes a frequency of transition, and `pp`

denotes a profile probability.

To calculate the value of output probability variable `var0`

of type `QSMM_PROB_FQ`

, relative probabilities
*ν _{0,1}+ν_{1,1}+ν_{2,1}*
and

`QSMM_PROB_FQ`

, relative probabilities
It should be noted that when an output probability variable corresponds to more than one cell of the state transition matrix, calculating output probabilities of types `QSMM_PROB_LEARNED`

and `QSMM_PROB_AGGR`

is performed by a rather bogus algorithm.
Therefore, it is recommended to avoid calculating output probabilities of those types or to use output probability variables that correspond to single cells of the state transition matrix.
In many cases, output probabilities `QSMM_PROB_LEARNED`

and `QSMM_PROB_AGGR`

can be approximated by output probabilities `QSMM_PROB_FQ`

.

As it was said before, a probability variable used in more than one `jprob`

or `case`

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

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

As it was mentioned above, a probability variable used once, but in an ambiguous context, cannot be an output probability variable too.
In the current implementation of the assembler, only `jprob`

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

instruction is ambiguous when the instruction is included in blocks of `jprob`

instructions that have different start addresses.
Such situation is illustrated by the following fragment of an assembler program.

L1: user 0 jprob 0.5, L3 L2: jprob var0, L1 user 1 L3: user 2 jmp L2

After invoking instruction ‘`user 0`’, the selection of the next instruction to execute is performed by a block that contains two instructions: ‘`jprob 0.5, L3`’ and ‘`jprob var0, L1`’.
However, after invoking instruction ‘`user 2`’, the selection of the next instruction to execute is performed only by the last instruction of that block.
In the first case, the block begins with instruction ‘`jprob 0.5, L3`’, and in the second case the block begins with instruction ‘`jprob var0, L1`’ (it contains only this instruction).
That is, the blocks have different start addresses, a ‘`jprob var0, L1`’ instruction they contain occurs in the ambiguous context, and, therefore, the variable `var0`

cannot be an output probability variable.

It is recommended to replace fixed profile probability values with output probability variables only in assembler programs for which no warnings are generated when loading them into nodes.
Such assembler programs do not contain instructions used in ambiguous contexts.
When the `QSMM_ASM_VAR_OUT`

flag is passed to the function `qsmm_node_asm`

, all probability variables used only once in such assembler programs become output probability variables.

To get names of output probability variables of a node, the following function can be used.

- Function:
*int***qsmm_enum_var_prob_out***(qsmm_t*`model`, int`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 specified by handle`model`. If`node`uses a source probability profile provided by another node, then there will be enumerated output probability variables of the latter node.The process of enumeration is a repeated calling callback function

`callback_func`, to which the entity type`QSMM_ENT_VAR_PROB`

, the name of an output probability variable, and user parameter`paramp`are passed. See Enumerating Entities, for a description of the type of the callback function.If the callback function returns a positive value, then the process of enumeration will be continued. If the callback function returns zero, then the process of enumeration will be terminated, and the function

`qsmm_enum_var_prob_out`

will report success. If the callback function returns a negative value, then the process of enumeration will be terminated, and the function`qsmm_enum_var_prob_out`

will report failure.The function

`qsmm_enum_var_prob_out`

does not enumerate output probabilities arrays of the node. An example program that enumerates those arrays for the memory representation of an assembler program is given in Getting Output Probabilities Arrays.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_NOTFOUND`

A node with identifier

`node`does not exist.`QSMM_ERR_CALLBACK`

The callback function did return an error.

To retrieve the value of an output probability variable, use the function described below.

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

`model`. Argument`node`specifies the identifier of the node. If`valp`is not`NULL`

, then the function will set *`valp`to the value of output probability variable`var_name`. The value retrieved will be a probability of type`prob_type`. See Generating an Optimal Action, for a description of elements of enumeration`qsmm_prob_e`

.If

`node`uses a source probability profile provided by another node, then information on how to calculate the value of probability variable`var_name`will be obtained from the latter node. See Memory Efficient Cloning the Probability Profile, for a detailed description of this mode.If

`valp`is not`NULL`

, and variable`var_name`is a controlled or auxiliary probability variable used more than once in an assembler program loaded into`node`or into a node, which acts as a source of probability profile for`node`, or used in an ambiguous context in that assembler program, then *`valp`will be set to -1.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_INVAL`

The value of

`prob_type`is not a valid element of enumeration`qsmm_prob_e`

.`QSMM_ERR_NOTFOUND`

A node with identifier

`node`does not exist, or probability variable named`var_name`is not defined in an assembler program loaded into`node`or into a node that acts as a source of probability profile for`node`.`QSMM_ERR_UNTIMELY`

The model instance does not exist.

`QSMM_ERR_UNSUPPLA`

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

`QSMM_ERR_STORAGE`

Statistics storage failure. This could leave the model instance in indeterminate state. If the model instance is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds, then the model instance state will become determinate.

`QSMM_ERR_NOMEM`

There was not enough memory to perform the operation. This could leave the model instance in indeterminate state. If the model instance is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds, then the model instance state will become determinate.

Output probabilities, which correspond to `case`

instructions in `choice`

instruction blocks, can be retrieved via output probability variables used in `case`

instructions or as output probabilities arrays referenced by location labels assigned to `choice`

instruction blocks.
The contents of output probabilities arrays, which correspond to `casels`

instructions and `choice`

instruction blocks, are fetched by the function `qsmm_get_node_array_prob_out`

described in Getting Output Probabilities Arrays.

In QSMM version 1.16, there are introduced functions for fetching aggregate statistics for cycle types that correspond to output probability variables and elements of output probabilities arrays. The statistics are aggregate in the sense that when an output probability variable or an element of output probabilities array correspond to the state transition matrix of a node, the statistics are composed of statistics for cycle types in all matrix cells, which are associated with the variable or the array element. When an output probability variable or an element of output probabilities array correspond to the action emission matrix of a node, aggregate statistics are simply the statistics for a cycle type in a matrix cell associated with the variable or the array element.

To fetch aggregate statistics for cycle types associated with an output probability variable, a function described below can be used. For a description of a function for fetching aggregate statistics for cycle types associated with an element of output probabilities array, see Getting Output Probabilities Arrays.

- Function:
*int***qsmm_get_node_var_prob_cycle***(qsmm_t*`model`, const char *`var_name`, int`node`, struct qsmm_cycle_s *`cycle_p`, struct qsmm_cspur_s *`cspur_p`) This function fetches aggregate statistics on cycle types that correspond to output probability variable

`var_name`of a node of a multinode model specified by handle`model`. Argument`node`specifies the identifier of the node. If`cycle_p`is not`NULL`

, then *`cycle_p`will be set to aggregate statistics on those cycle types. If`cspur_p`is not`NULL`

, then *`cspur_p`will be set to aggregate statistics on spur types for those cycle types. See Structures for Accessing Storage, for a description of structures`qsmm_cycle_s`

and`qsmm_cspur_s`

.If

`cspur_p`is not`NULL`

and the output probability variable corresponds to the state transition matrix of the node, then array`cspur_p`must be capable of holding the number of elements returned for the multinode model by the function`qsmm_get_nspur`

. If`cspur_p`is not`NULL`

and the output probability variable corresponds to the action emission matrix of the node, then array`cspur_p`must be capable of holding the number of elements returned by the function`qsmm_get_nspur`

minus 1. The type of a matrix, to which the output probability variable corresponds, can be obtained using the function`qsmm_get_node_var_prob_mat`

described earlier in this subsection.Aggregate statistics on the cycle types are computed in the following way. Values of fields

`fq`

,`period_sum_d`

, and`period_sum_c`

of *`cycle_p`are the sums of values of those fields in instances of structure`qsmm_cycle_s`

, which correspond to cycle types associated with the output probability variable. The value of`cycle_p``->profile`

is computed by calling the function`qsmm_get_node_var_prob_out`

and passing`QSMM_PROB_PROFILE`

for a type of probability to retrieve. Values of field`delta_sum`

of elements of array`cspur_p`are the sums of values of that field of corresponding elements, which contain statistics on spur types for cycle types associated with the output probability variable.If

`node`uses a source probability profile provided by another node, then information on how to calculate the aggregate statistics will be obtained 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 that were used to make up the aggregate statistics. On failure, the function returns a negative error code. Currently, the following error codes can be returned.

`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 the look-ahead signal segment.

`QSMM_ERR_STORAGE`

Statistics storage failure. This could leave the model instance in indeterminate state. If the model instance is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds, then the model instance state will become determinate.

`QSMM_ERR_NOMEM`

There was not enough memory to perform the operation. This could leave the model instance in indeterminate state. If the model instance is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds, then the model instance state will become determinate.

When retrieving values of particular output probability variables, values of associated output probability variables can be implicitly calculated.
All values of output probability variables calculated for a node are stored in a values cache created within the node.
The cache is destroyed automatically by the functions `qsmm_node_call_default`

(see Transferring Control Between Nodes) and `qsmm_node_unload`

(see Unloading the Probability Profile) invoked for the node, after disassembling the node if it is assembled with the `QSMM_ASM_TEMPLATE`

flag, and when destroying the model instance.
For conserving memory, the cache can be destroyed manually by the following function.

- Function:
*int***qsmm_node_var_out_forget***(qsmm_t*`model`, int`node`) This function destroys the cache of values of output probability variables and arrays of a node of a multinode model specified by handle

`model`. Argument`node`specifies the identifier of the node. The functions`qsmm_get_node_var_prob_out`

and`qsmm_get_node_array_prob_out`

use the cache to speed up fetching output probability variables and arrays of this node.On success, a non-negative value is returned. If a node with identifier

`node`does not exist, then negative error code`QSMM_ERR_NOTFOUND`

will be returned.