Previous: , Up: Specifying Output Signal Weights   [Contents][Index]


2.7.3 Assigning a Preloaded Probability Profile

You can assign a preloaded probability profile to a number of action choice states. Output signals emittable in those action choice states will have weights defined by the preloaded probability profile.

If the current action choice state is an action choice state with that preloaded probability profile assigned, the function qsmm_actor_calc_action_prob called for a small actor applies the weights by copying them from the preloaded probability profile to the array of output signal weights accessible by the functions qsmm_get_actor_sig_weight and qsmm_set_actor_sig_weight.

For a large actor, the function qsmm_get_actor_sig_action uses a Huffman tree defined by the preloaded probability profile to select an output signal in an action choice state with that preloaded probability profile assigned.

The purpose of the following functions is to retrieve or set up a correspondence between an action choice state and a preloaded probability profile.

Function: int qsmm_get_actor_ngram_profile (qsmm_actor_t actor, int rez1, int *profile_p, int *permut_p, const qsmm_sig_t *sig_ngram_p)

This function retrieves a correspondence between an action choice state of an actor and a preloaded probability profile. A probabilities list in normal form and a permutation of output signals define the preloaded probability profile. The array sig_ngram_p with length specified in the field ngram_sz of qsmm_actor_desc_s structure when creating the actor encodes the action choice state. The argument rez1 is for future use and must be equal to 0.

If profile_p is not NULL, the function sets *profile_p equal to the index of a probabilities list in normal form for the preloaded probability profile. If permut_p is not NULL, the function sets *permut_p equal to the index of a permutation of output signals for the preloaded probability profile. If the function sets *profile_p and *permut_p to -1, this is an indication that the action choice state has default output signal weights. For a small actor, default output signal weights are all equal. For a large actor, default output signal weights following from the structure of a default Huffman tree are equal only if the number of output signals is a positive integer power of tree arity.

On success, the function returns a non-negative value. If the array sig_ngram_p does not encode a valid action choice state, the function returns negative error code QSMM_ERR_NGRAM.

Function: int qsmm_set_actor_ngram_profile (qsmm_actor_t actor, int rez1, int profile, int permut, const qsmm_sig_t *sig_ngram_p)

This function sets up a correspondence between an action choice state of an actor and a preloaded probability profile. A probabilities list in normal form and a permutation of output signals define the preloaded probability profile. The argument profile specifies the index of this probabilities list in normal form. The argument permut specifies the index of this permutation of output signals. The array sig_ngram_p with length specified in the field ngram_sz of qsmm_actor_desc_s structure when creating the actor encodes the action choice state. The argument rez1 is for future use and must be equal to 0.

A special combination of profile and permut both equal to -1 is an indication to assign default output signal weights to the action choice state. For a small actor, default output signal weights are all equal. For a large actor, default output signal weights following from the structure of a default Huffman tree are equal only if the number of output signals is a positive integer power of tree arity.

The function keeps intact statistics collected for the action choice state and held in statistics storage with a handle retrievable by the function qsmm_get_actor_storage for the actor. However, for a large actor, the function qsmm_set_actor_ngram_profile destroys the Huffman tree of the action choice state encoded by sig_ngram_p. That Huffman tree holds the other part of statistics collected for the action choice state.

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_INVAL

The argument profile is not a valid index of a probabilities list in normal form, or the argument permut is not a valid index of a permutation of output signals, and, at the same time, profile and permut are not both equal to -1, or the length of a probabilities list in normal form specified by profile is not equal to the length of a permutation of output signals specified by permut.

QSMM_ERR_NGRAM

The array sig_ngram_p does not encode a valid action choice state. To determine the validity of an action choice state, the function checks that array for accordance with allowed ranges of signal identifiers specified by the field range_sig_p of qsmm_actor_desc_s structure when creating the actor.

QSMM_ERR_NOTSUP

For a small actor, the number of possible action choice states calculated on the basis of allowed ranges of signal identifiers specified by the field range_sig_p of qsmm_actor_desc_s structure when creating the actor is too large.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation. This error can leave the actor in inconsistent state. If after removing a reason of this error a repeated call to this function succeeds, the actor’s state becomes consistent.


Previous: , Up: Specifying Output Signal Weights   [Contents][Index]