A list of probabilities in normal form and a one-to-one correspondence between the elements of the list and identifiers of output signals define a preloaded probability profile for an action choice state. The one-to-one correspondence is a permutation of output signals. Output signals that do not take part in the permutation have profile probability 0. The purpose of splitting a preloaded probability profile into a probabilities list in normal form and a permutation of output signals is to reduce memory footprint of an actor, especially of large one.
For a small actor, the normal form of a list of probabilities is a sorted list of positive probabilities. For a large actor, the normal form of a source list of probabilities is a resulting list of probabilities following from the structure of an output signal choice tree created for a sorted source list. Resulting probabilities following from the structure of an output signal choice tree may differ from source probabilities for creating the output signal choice tree.
If the field profile_tol of qsmm_actor_large_desc_s structure specified when creating a large actor is positive, an extra normal form of a list of probabilities is a sorted list of positive probabilities.
Using the extra normal form makes it possible to skip building and restructuring a Huffman tree for the same sorted list of positive probabilities, as this operation can be slow.
An actor has a pool of unique probabilities lists in normal form.
The actor does not support removing elements from the pool, except by destroying the actor using the function qsmm_actor_destroy.
The following function returns current pool size.
size_t qsmm_get_actor_profile_pool_sz (qsmm_actor_t actor) ¶This function returns the number of elements in the pool of probabilities lists in normal form of actor. Every element is a unique list of probabilities in normal form.
An actor has also a pool of permutations of output signals.
The pool contains unique permutations.
The actor does not support removing permutations of output signals from the pool, except by destroying the actor using qsmm_actor_destroy.
Use the following function to split a list of weights of output signals of an actor into a probabilities list in normal form and a permutation of output signals.
int qsmm_actor_profile_add_v2 (qsmm_actor_t actor, int rez1, qsmm_sig_t sig_beg, qsmm_sig_t sig_end, const double *weight_p, size_t *profile_p, size_t *permut_p) ¶This function preloads a list of weights of output signals into an actor.
The array weight_p contains the weights.
If weight_p is NULL, the function interprets this condition as if the array weight_p contains all weights equal to 1.
The arguments sig_beg and sig_end specify the identifiers of the first output signal (inclusive) and last output signal (exclusive) for the list of weights. The array weight_p begins with the weight of the first output signal and has length sig_end-sig_beg.
For a large actor, if the field profile_tol of qsmm_actor_large_desc_s structure passed when creating the large actor was positive, the function first looks for an extra probabilities list in normal form containing normalized and sorted positive weights to speed up processing the same normalized and sorted list of positive weights.
If the extra probabilities list in normal form exists, the function returns its index in *profile_p if it is not NULL.
If the extra probabilities list does not exist, the function adds it to the pool and continues working with a main probabilities list in normal form following from the structure of a rearranged Huffman tree.
If profile_p is not NULL, the function sets *profile_p equal to the index of a unique probabilities list in normal form for the list of weights.
The index identifies either a unique probabilities list in normal form just added to the pool of probabilities lists in normal form or such a list already contained in the pool.
The length of the unique probabilities list in normal form is equal to the number of positive elements in the array weight_p.
If permut_p is not NULL, the function sets *permut_p equal to the index of a unique permutation of output signals for the list of weights.
The index identifies either a unique permutation of output signals just added to the pool of permutations of output signals or such a permutation already contained in the pool.
The length of the unique permutation of output signals is equal to the length of the unique probabilities list in normal form.
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_INVALThe argument sig_beg is greater than or equal to the argument sig_end, or sig_end is greater than the number of input signals and greater than the number of output signals.
QSMM_ERR_WEIGHTThe array weight_p contains a negative or non-finite element.
QSMM_ERR_INFINThe array weight_p contains only finite elements, but the sum of elements is infinite.
QSMM_ERR_NOCHOICEThe array weight_p does not contain at least one positive element.
QSMM_ERR_STORAGEFailure of statistics storage of a large actor. See Getting the Reason of a Storage Failure, for how to get an error message describing the failure.
QSMM_ERR_STATSInconsistent statistics on an action choice state or cycle type detected for a large actor.
QSMM_ERR_ILSEQFor a large actor, a generated error message is not convertible to a wide string according to a current locale, or a storage redirection function reported QSMM_ERR_ILSEQ.
QSMM_ERR_NOMEMThere was not enough memory to perform the operation.
Since QSMM 1.19, large actors support the following function for obtaining a model node containing an output signal choice tree for a probabilities list in normal form.
See the program tools/osct.c (see osct) for an example on how to print an output signal choice tree created for a supplied list of weights.
int qsmm_get_actor_large_osct_node (qsmm_actor_t actor, size_t profile, qsmm_sig_t *node_p) ¶This function sets *node_p equal to the index of a node in a multinode model of a large actor containing an output signal choice tree for a probabilities list in normal form identified by profile.
If node_p is NULL, the function does not set the node index.
The function qsmm_get_actor_large_model returns the handle of the multinode model.
The argument profile can be equal to the index of a probabilities list in normal form returned by the function qsmm_actor_profile_add_v2.
If profile is equal to special value (size_t) -1, it identifies a default probabilities list in normal form containing equal probabilities for all output signals of the large actor.
In this case, qsmm_get_actor_large_osct_node returns the index of a node containing a default output signal choice tree.
If the default tree does not yet exist, the function creates it.
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_INVALThe argument profile is not (size_t) -1 but greater than or equal to the number of unique probabilities lists in normal form returnable by the function qsmm_get_actor_profile_pool_sz.
QSMM_ERR_NOTSUPThe actor is the small one.
QSMM_ERR_STORAGEStatistics storage failure. See Getting the Reason of a Storage Failure, for how to get an error message describing the failure.
QSMM_ERR_STATSInconsistent statistics on an action choice state or cycle type detected.
QSMM_ERR_ILSEQA generated error message is not convertible to a wide string according to a current locale, or a storage redirection function reported QSMM_ERR_ILSEQ.
QSMM_ERR_NOMEMThere was not enough memory to perform the operation.
The function qsmm_actor_profile_add_v2 may operate slowly, especially when building an output signal choice tree for a large actor.
To speed up preloading a number of probability profiles for the same sorted list of output signal weights, you can perform the following procedure.
qsmm_actor_profile_add_v2 returning the index of a probabilities list in normal form and the index of a permutation of output signals identifying the preloaded profile.
qsmm_actor_permut_add_v2 described below to obtain the index of a unique permutation of output signals.
You can use that index along with the index of a probabilities list in normal form obtained in step 1 to identify a preloaded probability profile other than the first one.
int qsmm_actor_permut_add_v2 (qsmm_actor_t actor, int rez1, qsmm_sig_t sz, const qsmm_sig_t *sig_p, size_t *permut_p) ¶This function adds a permutation of output signals of an actor to its pool of permutations of output signals if the pool does not contain the permutation.
The array sig_p containing sz elements specifies the permutation.
If permut_p is not NULL, the function returns in *permut_p the index of an added permutation or a permutation already existing in the pool.
On success, the function returns a non-negative value. If the pool did not contain the permutation, the function returns a positive value. If the pool already contained the permutation, the function returns 0. On failure, the function returns a negative error code. Currently, the function can return the following error codes.
QSMM_ERR_INVALThe argument sz is 0, or the array sig_p contains duplicate elements or an element greater than or equal to the number of output signals of the actor.
QSMM_ERR_NOMEMThere was not enough memory to add the permutation of output signals to the pool.