Figure 5.1: A fragment of state transition matrix for calculating the value of a variable
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.
This enumeration specifies a type of matrix. It contains the following elements.
QSMM_MAT_GOTOThe state transition matrix.
QSMM_MAT_ACTIONThe 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.
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_NOTFOUNDA node with identifier node or an output probability variable named var_name does not exist.
QSMM_ERR_UNTIMELYThe model instance does not exist.
QSMM_ERR_UNSUPPLAThe multinode model has positive length of the look-ahead signal segment.
QSMM_ERR_NOMEMThere 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
ν0,2+ν1,2+ν2,2
are calculated, and ratio
(ν0,2+ν1,2+ν2,2)/(ν0,1+ν1,1+ν2,1+ν0,2+ν1,2+ν2,2)
is taken for the value.
To calculate the value of the variable of a type other than QSMM_PROB_FQ, relative probabilities
(p0,1ν0,1+p1,1ν1,1+p2,1ν2,1)/(ν0,1+ν1,1+ν2,1)
and
(p0,2ν0,2+p1,2ν1,2+p2,2ν2,2)/(ν0,2+ν1,2+ν2,2)
are calculated, and the second relative probability divided by the sum of both relative probabilities is taken for the value.
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.
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_NOTFOUNDA node with identifier node does not exist.
QSMM_ERR_CALLBACKThe callback function did return an error.
To retrieve the value of an output probability variable, use the function described below.
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_INVALThe value of prob_type is not a valid element of enumeration qsmm_prob_e.
QSMM_ERR_NOTFOUNDA 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_UNTIMELYThe model instance does not exist.
QSMM_ERR_UNSUPPLAThe multinode model has positive length of the look-ahead signal segment.
QSMM_ERR_STORAGEStatistics 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_NOMEMThere 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.
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_NOTFOUNDA node with identifier node or an output probability variable named var_name does not exist.
QSMM_ERR_UNTIMELYThe model instance does not exist.
QSMM_ERR_UNSUPPLAThe multinode model has positive length of the look-ahead signal segment.
QSMM_ERR_STORAGEStatistics 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_NOMEMThere 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.
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.
Next: Auxiliary Variables, Previous: Controlled Variables, Up: Using Probability Variables [Contents][Index]