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]