Previous: , Up: Using Probabilities Lists   [Contents][Index]


5.10.3 Getting Output Probabilities Arrays

An output probabilities array, which corresponds to a casels instruction or a choice instruction block, is referenced using one of location labels assigned to the instruction or the instruction block. A casels instruction and a choice instruction block with such location labels assigned might look like these:

LS1:    casels  ls1, L1, L2, L3, L4, L5, L6, L7, L8
LS2:    choice
        case    0.15, L1
        case    0.05, L2
        case    0.10, L3
        case    0.20, L4
        end     choice

In these examples there are defined two output probabilities arrays: LS1 and LS2. Array elements correspond to jump labels specified in arguments of the casels instruction and to case instructions within the choice instruction block.

Every output probabilities array corresponds either to the state transition matrix or to the action emission matrix of a node. To get the type of a matrix, to which an output probabilities array corresponds, a function described below can be used. The function was introduced in QSMM version 1.16.

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

This function retrieves the type of a matrix that corresponds to an output probabilities array of a node of a multinode model specified by handle model. A location label named label assigned to a casels instruction or a choice instruction block in an assembler program loaded into the node specifies the array. Argument node specifies the identifier of this node. If mat_p is not NULL, then the function will set *mat_p to the type of the matrix. See Output Variables, for a description of elements of enumeration qsmm_mat_e. 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 probabilities array 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_NOTFOUND

A node with identifier node or 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 the look-ahead signal segment.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

To get the content of a segment of an output probabilities array, use the function described below.

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

This function fetches the content of an output probabilities array of a node of a multinode model specified by handle model. A location label named label assigned to a casels instruction or a choice instruction block in an assembler program loaded into the node specifies the array. Argument node specifies the identifier of this node. If prob_p is not NULL, then the function will copy output probabilities of type prob_type from that array to a buffer addressed by prob_p. See Generating an Optimal Action, for a description of elements of enumeration qsmm_prob_e.

Arguments from and to can be both zero (which is not recommended) or may specify indices of the first element (inclusive) and of the last element (exclusive) of a segment of output probabilities array, the contents of which should be fetched to buffer prob_p. If to is 0, then the length of the output probabilities array will be used as an index (incremented by 1) of the last element of the segment. A special element of the output probabilities array at index equal to the length of the array corresponds to a choice alternative just after the casels instruction or the choice instruction block, to which control is transferred when no jump to one of location labels specified in the casels instruction or case instructions within the choice instruction block is made.

If node uses a source probability profile provided by another node, then information on how to fetch the contents of output probabilities array label 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 elements written to buffer prob_p. On failure, a negative error code is returned. Currently, the following error codes can be returned.

QSMM_ERR_INVAL

The value of prob_type is not a valid element of enumeration qsmm_prob_e, or the value of from is negative or is greater than or equal to an index (incremented by 1) of the last element of the segment of the output probabilities array, or the value of to is negative or is greater than the length of the output probabilities array plus 1.

QSMM_ERR_NOTFOUND

A node with identifier node or 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 the look-ahead signal segment.

QSMM_ERR_STORAGE

Statistics 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_NOMEM

There 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.

In QSMM version 1.16 there is introduced a function for fetching aggregate statistics on cycle types associated with an element of output probabilities array. A description of the function is given below. See Output Variables, for a description of the corresponding function for 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, int node, int offs, struct qsmm_cycle_s *cycle_p, struct qsmm_cspur_s *cspur_p)

This function fetches aggregate statistics on cycle types that correspond to an element of an output probabilities array of a node of a multinode model specified by handle model. A location label named label assigned to a casels instruction or a choice instruction block in an assembler program loaded into the node specifies the array. Argument node specifies the identifier of this node.

The index of the element of the array is specified by offs. A special element of the array at index equal to the length of the array corresponds to a choice alternative just after the casels instruction or the choice instruction block, to which control is transferred when no jump to one of location labels specified in the casels instruction or case instructions within the choice instruction block is made.

If cycle_p is not NULL, then *cycle_p will be set to aggregate statistics on the cycle types. If cspur_p is not NULL, then *cspur_p will be set to aggregate statistics on spur types for the cycle types. The structures qsmm_cycle_s and qsmm_cspur_s are described in Structures for Accessing Storage.

If cspur_p is not NULL and the output probabilities array 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 probabilities array 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 probabilities array corresponds, can be obtained using the function qsmm_get_node_array_prob_mat described earlier in this subsection.

Aggregate statistics on the cycle types is 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 element of output probabilities array. The value of cycle_p->profile is computed by calling the function qsmm_get_node_array_prob_out for the element of output probabilities array 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 element of output probabilities array.

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_INVAL

The value of offs is negative or is greater than the length of the output probabilities array.

QSMM_ERR_NOTFOUND

A node with identifier node or 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 the look-ahead signal segment.

QSMM_ERR_STORAGE

Statistics 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_NOMEM

There 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 the contents of a segment of output probabilities array of a node, explicitly and implicitly calculated probability values are stored in the values cache created within the node. In certain situations, the cache is destroyed automatically, but it can also be destroyed manually by the function qsmm_node_var_out_forget. See Output Variables, for more information on the cache of values of output probability variables and arrays of node.

If there is a need to dump the contents of all output probabilities arrays defined in an assembler program, then only instructions of types QSMM_INSTR_CHOICE and QSMM_INSTR_CASELS must be considered. The type of an instruction specified by its handle can be obtained by the function qsmm_get_instr_type. If the instruction has at least one location label assigned, then there will be an output probabilities array associated with that instruction. The first location label, which identifies the output probabilities array, can be retrieved by call qsmm_get_instr_label(instr,0), where instr is an instruction handle. When 0 is returned, the instruction does not have location labels assigned.

For an instruction of type QSMM_INSTR_CHOICE, the length of an output probabilities array associated with the instruction is equal to a value returned by the function qsmm_get_instr_nnested for that instruction minus 1 (the last nested instruction is the ‘end choice’ instruction). For an instruction of type QSMM_INSTR_CASELS, the length of the output probabilities array is equal to the length of probabilities list returned by the function qsmm_get_prg_ls_nprob. The name of probabilities list, which should be passed to that function, can be retrieved by the function qsmm_get_instr_ls_name for the instruction handle.

An example function that dumps the contents of all output probabilities arrays of a node into which assembler program prg was loaded is given below. The function returns 0 on success or -1 on out of memory error.

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

static int dump_prob_out_arrays(qsmm_t qsmm,
                                int node,
                                qsmm_prg_t prg,
                                enum qsmm_prob_e prob_type) {
    int ii, jj, ninstr, prob_allo=1, result=-1;
    double *probp=calloc(prob_allo,sizeof(*probp));
    if (!probp) goto Exit;
    ninstr=qsmm_get_prg_ninstr(prg);
    for (ii=0; ii<ninstr; ii++) {
        const char *label;
        int nprob;
        qsmm_instr_t instr=qsmm_get_prg_instr(prg,ii);
        if (!(label=qsmm_get_instr_label(instr,0))) continue;
        switch (qsmm_get_instr_type(instr)) {
            case QSMM_INSTR_CHOICE:
                nprob=qsmm_get_instr_nnested(instr)-1;
                break;
            case QSMM_INSTR_CASELS:
                nprob=qsmm_get_prg_ls_nprob(
                          prg, qsmm_get_instr_ls_name(instr));
                break;
            default:
                continue;
        }
        if (prob_allo<nprob) {
            double *newp;
            if (!(newp=realloc(probp,nprob*sizeof(*newp)))) goto Exit;
            prob_allo=nprob;
            probp=newp;
        }
        qsmm_get_node_array_prob_out(qsmm, label, node, 0, nprob,
                                     prob_type, probp);
        for (jj=0; jj<nprob; jj++)
            printf("%s[%d]=%.15E\n",label,jj,probp[jj]);
    }
    result=0;

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

Previous: , Up: Using Probabilities Lists   [Contents][Index]