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.
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.
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.
Figure 5.1: a state transition matrix fragment with multiple cells for a jprob
instruction
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
ν0,2+ν1,2+ν2,2
and takes the ratio
(ν0,2+ν1,2+ν2,2)/(ν0,1+ν1,1+ν2,1+ν0,2+ν1,2+ν2,2)
for that probability.
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.
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.
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.
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.
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
.
Next: Output Arrays, Previous: Controlled Variables, Up: Using Probability Variables [Contents][Index]