A data label assigned to a choice instruction block refers to an output probabilities array for the block.
A 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.
An element at index 0 is for the ‘case 0.15, L1’ instruction, and an element at index 3 is for 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.
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 for an output probabilities array of a node of a multinode model.
The argument node specifies the identifier of the node.
A data 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 matrix type 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_NOTFOUNDA node with identifier node or an output probabilities array label does not exist.
QSMM_ERR_UNTIMELYA model instance does not exist.
QSMM_ERR_NOPROFA node with identifier node does not have a probability profile specified.
QSMM_ERR_NOTSUPThe multinode model has positive length of look-ahead signal segment.
QSMM_ERR_NOMEMThere was not enough memory to perform the operation.
Use the function described below to get a segment of an output probabilities array.
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 in a multinode model.
The argument node specifies the identifier of the node.
A data 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.
The arguments from and to specify the index of the first element and the index of the last element (exclusive) for an array segment to retrieve. If to is 0, the function uses array length as the index of the last element. The number of elements copied to prob_p is equal to the index of the last element (exclusive) 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.
The choice alternative receives control if none of case instructions in the choice instruction block transferred control elsewhere.
To retrieve the 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.
If this function is able to retrieve an array segment, the function returns 2.
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 −2 as the value of each array element and returns 1.
If an output probabilities array corresponds to both the state transition matrix and action emission matrix, the function retrieves −1 as the value of each array element and returns 0.
On failure, the function returns a negative error code. Currently, the function can return the following error codes.
QSMM_ERR_INVALThe argument prob_type is invalid, or from is greater than or equal to the index of the last element, or to is greater than array length plus 1.
QSMM_ERR_NOTFOUNDA node with identifier node or an output probabilities array label does not exist.
QSMM_ERR_UNTIMELYA model instance does not exist.
QSMM_ERR_NOPROFA node with identifier node does not have a probability profile specified.
QSMM_ERR_NOTSUPThe multinode model has positive length of look-ahead signal segment.
QSMM_ERR_CALLBACKA 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_STORAGEA Storage API function reported storage failure.
QSMM_ERR_STATSInconsistent statistics on an action choice state or cycle type detected.
QSMM_ERR_ILSEQUnable to convert a multibyte string to a wide string or vice versa according to a current locale.
QSMM_ERR_NOMEMThere 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.
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 calculated probabilities of all choice alternatives for the output probabilities array.
The cache speeds up retrieving the elements of the output probabilities array later.
Call the function qsmm_node_var_out_forget to forcibly 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.
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_cspval_s *cspval_p) ¶This function retrieves aggregate statistics on cycle types for an element of an output probabilities array of a node in a multinode model.
The argument node specifies the identifier of the 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 the 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.
The 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 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 probabilities array 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 probabilities array 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_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 and period_sum_d of *cycle_p are equal to their sums for all cycle types associated with the element of the output probabilities array.
The field cycle_p->profile is equal to that field for the last cycle type associated with the element of the output probabilities array, 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 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 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_INVALThe argument offs is greater than the length of the output probabilities array.
QSMM_ERR_NOTFOUNDA node with identifier node or an output probabilities array label does not exist.
QSMM_ERR_UNTIMELYA model instance does not exist.
QSMM_ERR_NOPROFA node with identifier node does not have a probability profile specified.
QSMM_ERR_NOTSUPThe multinode model has positive length of look-ahead signal segment.
QSMM_ERR_STORAGEA Storage API function reported storage failure.
QSMM_ERR_STATSInconsistent statistics on an action choice state or cycle type detected.
QSMM_ERR_ILSEQUnable to convert a multibyte string to a wide string or vice versa according to a current locale.
QSMM_ERR_NOMEMThere was not enough memory to perform the operation.
To dump 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 a data label assigned, the instruction has an associated output probabilities array.
The call qsmm_get_instr_label(instr,-1), where instr is an instruction handle, returns a data label identifying the output probabilities array.
If that call returns NULL, the instruction does not have a data label 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 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 array_name_p=qsmm_get_instr_label(instr,-1);
if (!array_name_p) 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, array_name_p, node, 0, nprob,
prob_type, probp);
for (size_t iprob=0; iprob<nprob; iprob++)
printf("%s[%zu]=%.15E\n",array_name_p,iprob,probp[iprob]);
}
result=0;
Exit:
free(probp);
return result;
}