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


5.9.4 Output Arrays

A location label assigned to a choice instruction block refers to an output probabilities array for this choice instruction block. The choice instruction block might look like this:

ARR:    choice
        case    0.15, L1
        case    0.05, L2
        case    0.10, L3
        case    0.20, L4
        end     choice

This example defines the output probabilities array ‘ARR’ with four elements corresponding to case instructions in the choice instruction block. The element with index 0 corresponds to the ‘case 0.15, L1’ instruction, and the element with index 3 corresponds to the ‘case 0.20, L4’ instruction.

An output probabilities array corresponds to either the state transition matrix or action emission matrix. Use the function described below to get a matrix type.

Function: int qsmm_get_node_array_prob_mat (qsmm_t model, const char *label, qsmm_sig_t node, enum qsmm_mat_e *mat_p)

This function retrieves the type of a matrix corresponding to an output probabilities array of a node of a multinode model. The argument node specifies the identifier of this node. A location label assigned to a choice instruction block in an assembler program loaded into the node identifies the array. If mat_p is not NULL, the function sets *mat_p to a retrieved type. See Output Variables, for the description of elements of qsmm_mat_e enumeration.

If the node uses a source probability profile provided by another node, the function retrieves the type of the matrix of the output probabilities array 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 probabilities array label 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.

Use the function described below to get a segment of an output probabilities array.

Function: int qsmm_get_node_array_prob_out (qsmm_t model, const char *label, qsmm_sig_t node, size_t from, size_t to, enum qsmm_prob_e prob_type, double *prob_p)

This function retrieves a segment of an output probabilities array of a node of a multinode model. The argument node specifies the identifier of this node. A location label assigned to a choice instruction block in an assembler program loaded into the node identifies the array. If prob_p is not NULL, the function copies output probabilities from the array to a buffer prob_p starting at offset 0.

The argument prob_type specifies the type of probabilities to retrieve. See Emitting an Output Signal, for the description of elements of qsmm_prob_e enumeration. If prob_type is QSMM_PROB_AGGR or QSMM_PROB_LEARNED, and each array element corresponds to multiple cells of state transition matrix, the function retrieves all array elements equal to -2.

The arguments from and to specify the index of first element and the index of last element (exclusive) for the retrieved array segment. If to is 0, the function uses array length as the index of last element. The number of elements copied to prob_p is equal to the index of last element minus from.

A special element of an output probabilities array at index equal to array length corresponds to a choice alternative beneath the choice instruction block. This choice alternative receives control if none of case instructions in the choice instruction block transferred control elsewhere. To retrieve this special element, specify to equal to array length plus 1.

If the node uses a source probability profile provided by another node, the function obtains information how to calculate the array elements from the latter node. See Memory Efficient Cloning the Probability Profile, for a detailed description of this mode.

On success, the function returns a positive number of elements to store in prob_p starting at offset 0 as if prob_p is never NULL. 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_INVAL

The argument prob_type is invalid, or from is greater than or equal to the index of last element, or to is greater than array length plus 1.

QSMM_ERR_NOTFOUND

A node with identifier node or an output probabilities array label 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_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.

When calculating a segment of an output probabilities array of a node, the function qsmm_get_node_array_prob_out stores in a cache within the node the calculated probabilities of all choice alternatives corresponding to the output probabilities array. The cache speeds up retrieving the elements of this output probabilities array later. Call the function qsmm_node_var_out_forget to manually clear the cache. See Output Variables, for more information on the cache and functions that clear it automatically.

Use the function described below to fetch aggregate statistics on cycle types associated with an element of an output probabilities array. See Output Variables, for the description of a counterpart function fetching aggregate statistics on cycle types associated with an output probability variable and for additional information on the concept of aggregate statistics.

Function: int qsmm_get_node_array_prob_cycle (qsmm_t model, const char *label, qsmm_sig_t node, size_t offs, struct qsmm_cycle_s *cycle_p, struct qsmm_cspur_s *cspur_p)

This function retrieves aggregate statistics on cycle types for an element of an output probabilities array of a node of a multinode model. The argument node specifies the identifier of this node. A location label assigned to a choice instruction block in an assembler program loaded into the node identifies the array.

The argument offs specifies the index of this array element. A special element of an output probabilities array at index equal to array length corresponds to a choice alternative beneath the choice instruction block. This choice alternative receives control if none of case instructions in the choice instruction block transferred control elsewhere.

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 probabilities array 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 probabilities array 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_array_prob_mat described earlier in this subsection retrieves the type of a matrix corresponding to an output probabilities array.

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 element of the output probabilities array. The field cycle_p->profile is equal to that field for last cycle type associated with the element of the output probabilities array, 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 element of the output probabilities array.

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_INVAL

The argument offs is greater than the length of the output probabilities array.

QSMM_ERR_NOTFOUND

A node with identifier node or an output probabilities array label 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.

To dump the contents of all output probabilities arrays defined in an assembler program, consider only instructions with the type QSMM_INSTR_CHOICE. Use the function qsmm_get_instr_type to obtain the type of an assembler instruction by its handle. If an instruction with the type QSMM_INSTR_CHOICE has at least one location label assigned, the instruction has an associated output probabilities array. The call qsmm_get_instr_label(instr,0), where instr is an instruction handle, returns the first location label identifying the output probabilities array. If that call returns NULL, the instruction does not have location labels assigned and, therefore, does not have an associated output probabilities array. The length of an associated output probabilities array is equal to the return value of qsmm_get_instr_nnested function minus 1, as the last nested instruction is the ‘end choice’ instruction.

Below there is an example function that dumps the contents of all output probabilities arrays of a node containing an assembler program prg. The function returns 0 on success or -1 on out of memory error.

#include <stdlib.h>
#include <qsmm/qsmm.h>

static int
dump_arr_prob_out(
    qsmm_t qsmm,
    qsmm_sig_t node,
    qsmm_prg_t prg,
    enum qsmm_prob_e prob_type
) {
    int result=-1;
    double *probp=0;
    size_t prob_allo=0;
    const size_t ninstr=qsmm_get_prg_ninstr(prg);
    for (size_t iinstr=0; iinstr<ninstr; iinstr++) {
        const qsmm_instr_t instr=qsmm_get_prg_instr(prg,iinstr);
        const char *const labelp=qsmm_get_instr_label(instr,0);
        if (!labelp) continue;
        if (qsmm_get_instr_type(instr)!=QSMM_INSTR_CHOICE) continue;
        const size_t nprob=qsmm_get_instr_nnested(instr)-1;
        if (prob_allo<nprob) {
            double *const newp=realloc(probp,nprob*sizeof(*newp));
            if (!newp) goto Exit;
            prob_allo=nprob;
            probp=newp;
        }
        qsmm_get_node_array_prob_out(qsmm, labelp, node, 0, nprob,
                                     prob_type, probp);
        for (size_t iprob=0; iprob<nprob; iprob++)
            printf("%s[%zu]=%.15E\n",labelp,iprob,probp[iprob]);
    }
    result=0;

Exit:
    if (probp) free(probp);
    return result;
}

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