Output Variables (QSMM Programmer Manual)

5.9.3 Output Variables

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.

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.

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.