Output Variables (QSMM Programmer Manual)

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

5.8.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 the two 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, and a probability variable violates at least one of the two restrictions and is not a controlled probability variable, qsmm_node_asm treats the probability variable as an auxiliary variable. If qsmm_node_asm does not receive QSMM_ASM_VAR_AUX, and a probability variable violates at least one of the two restrictions and is not a controlled probability variable, qsmm_node_asm 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 output probability variable var_name of a node of a multinode model. The argument node specifies the identifier of the 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 matrix type 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: A model instance does not exist.
QSMM_ERR_NOPROF: A node with identifier node does not have a probability profile specified.
QSMM_ERR_NOTSUP: The multinode model has positive length of look-ahead signal segment.
QSMM_ERR_NOMEM: There was not enough memory to perform the operation.

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 assembler program fragment 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 the instruction and columns for the states ‘s0’, ‘s1’, and ‘s2’. This state transition matrix fragment is in Figure 5.1. There ν denotes state transition frequency, and pp denotes profile probability.

Figure 5.1: 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 or 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 the 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 probability QSMM_PROB_PROFILE of the output probability variable ‘var0’. That function does not support calculating probabilities of QSMM_PROB_AGGR and QSMM_PROB_LEARNED types for the output probability variable ‘var0’.

To calculate a QSMM_PROB_FQ probability, qsmm_get_node_var_prob_out takes sums of frequencies of transitions to target states for relative probabilities. For example, to calculate probability QSMM_PROB_FQ of the output probability variable ‘var0’, 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 the probability.

As already mentioned, a probability variable used in multiple jprob and case instructions cannot be an output probability variable. The following assembler program fragment 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. An output probability variable can have ambiguous context due to the following reasons:

it belongs to different contiguous blocks of jprob instructions;
it specifies a profile probability for both the state transition matrix and action emission matrix;
it is another output probability variable for the same cell of the state transition matrix.

A probability variable belongs to different contiguous blocks of jprob instructions if the blocks have different start addresses. The following assembler program fragment illustrates this situation.

L1:     user    0               ; user instruction
        jprob   0.5, L3         ; beginning of the first block of
                                ; `jprob' instructions

L2:     jprob   var0, L1        ; beginning of the second (singleton)
                                ; block of `jprob' instructions and
                                ; also the second `jprob' instruction
                                ; in the first block

        user    1               ; user instruction


L3:     user    2               ; user instruction
        jmp     L2              ; jump to the second (singleton) block
                                ; of `jprob' instructions

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. In the second case, the block begins with the ‘jprob var0, L1’ instruction and contains only this instruction. That is, the blocks containing the ‘jprob var0, L1’ instruction have different start addresses, and, therefore, the variable ‘var0’ cannot be an output probability variable.

The following assembler program fragment illustrates the situation when a variable specifies a profile probability for both the state transition matrix and action emission matrix.

        stt

        ; This `choice' instruction block specifies profile
        ; probabilities for the action emission matrix because the
        ; block follows the `stt' instruction.
        ;
        ; This block also specifies profile probabilities for the
        ; state transition matrix because the block is the next
        ; instruction to execute after a user instruction.

L0:     choice
        case    var0, L1
        case    0.2, L2
        end     choice

        user    0               ; user instruction

L1:     user    1               ; user instruction

L2:     user    2               ; user instruction
        jmp     L0              ; jump to the `choice' instruction
                                ; block for selecting a
                                ; state transition

The choice instruction block specifies profile probabilities for the action emission matrix because the stt instruction precedes that block. The block also specifies profile probabilities for the state transition matrix because there is an unconditional jump to that block after the ‘user 2’ instruction. That is, the variable ‘var0’ specifies a profile probability for both matrices and, therefore, cannot be an output probability variable.

The following assembler program fragment illustrates the situation when another probability variable corresponds to the same cell of the state transition matrix.

L0:     user    0               ; user instruction

        choice
        case    var0, L1        ; variable `var0' specifies a
                                ; probability of transition to
                                ; label `L1'

        case    var1, L1        ; variable `var1' specifies another
                                ; probability of transition to
                                ; label `L1'
        end     choice


        user    2               ; user instruction

L1:     user    1               ; user instruction
        jmp     L0

The variables ‘var0’ and ‘var1’ specify profile probabilities of the transition to a state beginning at the location label ‘L1’. That is, ‘var1’ is another variable for a matrix cell holding a profile probability of that transition. Therefore, ‘var1’ cannot be an output probability variable.

Use the following function to get 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 the 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 as 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, qsmm_enum_var_prob_out continues enumeration. If the callback function returns zero, qsmm_enum_var_prob_out terminates enumeration and reports success. If the callback function returns a negative value, qsmm_enum_var_prob_out terminates enumeration and reports failure.

If the node uses a source probability profile provided by another node, the function enumerates 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 output probabilities arrays of a node. See Output Arrays, for an example program that enumerates the 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 output probability variable var_name of a node in a multinode model. The argument node specifies the identifier of the 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 the node uses a source probability profile provided by another node, the function obtains information how to calculate an output probability variable value 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 the 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 assembler program does not define a probability variable named var_name.
QSMM_ERR_UNTIMELY: A model instance does not exist.
QSMM_ERR_NOPROF: A node with identifier node does not have a probability profile specified.
QSMM_ERR_NOTSUP: 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 if the environment state identification engine or instruction emitting engine is a large actor. If after removing a reason of an error a repeated call to this function succeeds, the model instance state becomes consistent.

You can retrieve output probabilities for jprob instructions via output probability variables declared as data labels of jprob instructions or via output probability variables specified in the first argument of jprob instructions. You can retrieve output probabilities for case instructions in choice instruction blocks via output probability variables declared as data labels of case instructions, via output probability variables specified in the first argument of case instructions, or via output probabilities arrays referred to by data labels assigned to 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.

Fetching the value of an output probability variable requires calculating relative probabilities of all choice alternatives that include an alternative for the output probability variable. Putting calculated probabilities of all choice alternatives in a cache speeds up fetching values of output probability variables for other choice alternatives later. Along with the cache of calculated probabilities of choice alternatives, a node keeps a 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.

QSMM supports fetching aggregate statistics on cycle types for output probability variables and 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 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_cspval_s *cspval_p) ¶

This function retrieves aggregate statistics on cycle types for output probability variable var_name of a node of a multinode model. The argument node specifies the identifier of the node. If cycle_p is not NULL, the function sets *cycle_p to aggregate statistics on the cycle types. If cspval_p is not NULL, the function sets the elements of cspval_p array to aggregate statistics on cycle-summed value types for the cycle types. See Structures for Accessing Storage, for descriptions of qsmm_cycle_s and qsmm_cspval_s structures.

If cspval_p is not NULL, and the output probability variable corresponds to the state transition matrix, the array cspval_p must be capable of holding the number of elements equal to the sum of values returned by the functions qsmm_get_actor_nspur and qsmm_get_actor_ntime for the environment state identification engine. If cspval_p is not NULL, and the output probability variable corresponds to the action emission matrix, the array cspval_p must be capable of holding the number of elements equal to the sum of values returned by qsmm_get_actor_nspur and qsmm_get_actor_ntime for the instruction emitting engine. 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 and period_sum_d of *cycle_p are equal to their sums for all cycle types associated with the output probability variable. The field cycle_p->profile is equal to that field for the last cycle type associated with the output probability variable, as all cycle types have the same value of profile field. The fields delta_sum in the elements of cspval_p array are 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 the 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: A model instance does not exist.
QSMM_ERR_NOPROF: A node with identifier node does not have a probability profile specified.
QSMM_ERR_NOTSUP: 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 clear both caches by calling 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 the node. The function qsmm_get_node_var_prob_out uses both caches to speed up retrieving output probability variables of the node. The function qsmm_get_node_array_prob_out uses the second cache to speed up retrieving output probabilities arrays of the 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.