Next: , Previous: , Up: Adaptive Probabilistic Mapping   [Contents][Index]


2.9 Specifying Weights of Output Signals

The weight of an output signal of actor is an additional coefficient, by which a relative probability of emitting the output signal is multiplied. To disable emitting an output signal, set its weight equal to 0.

It is essential to note that by reasons described in Other Parameters of an Actor, changing default weights of output signals of a small actor, in general, makes its behavior ill-defined and should be avoided. Changing the weights seems to be the correct procedure only for a large actor, because this procedure does not alter the number of choice alternatives at decision points along the pathways to output signals.

Every output signal of small actor can have weight assigned to it with or without binding to a specific action choice state. Output signals of large actor can only have weights bound to specific action choice states.

For a small actor, output signal weight bound to an action choice state can be specified using a preloaded probability profile for the action choice state or as a profile probability held in statistics storage of the small actor. See Structures for Accessing Storage, for information on how to pass profile probabilities to storage access functions to write them to storage. For a large actor, the only supported way to specify output signal weights is using preloaded probability profiles for action choice states.

If a small actor has a preloaded probability profile specified for current action choice state, then the function qsmm_actor_calc_action_prob will copy output signal weights from the preloaded probability profile to a working array of output signal weights that ordinarily holds weights assigned to output signals without binding to a particular action choice state. The contents of that working array can be inspected or modified using the functions qsmm_get_actor_sig_weight and qsmm_set_actor_sig_weight described below. The function qsmm_actor_create initializes weights of all output signals of a newly created small actor, which are stored in the working array, to 1. If an output signal of a small actor has a profile probability specified for an action choice state in statistics storage of the actor, then the overall weight of the output signal (which can be emitted in that action choice state) will be the product of a corresponding weight in the working array and that profile probability.

For a small actor, weights stored in the working array are always applied to relative probabilities computed within the function qsmm_actor_calc_action_prob, disregarding of a requested type of probabilities to calculate. For a large actor, the working array is not used. After multiplying computed relative probabilities by corresponding weights, the function qsmm_actor_calc_action_prob normalizes the resulting array to obtain probabilities that sum up to 1.

Function: int qsmm_get_actor_sig_weight (qsmm_actor_t actor, qsmm_sig_t sig, double *weight_p)

This function sets *weight_p to the weight of output signal sig of actor. If weight_p is NULL, then *weight_p will not be set, otherwise *weight_p will always be a finite and a non-negative number.

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_INVAL

Signal sig is not an output signal of the actor.

QSMM_ERR_NOTSUP

The actor is the large one.

Function: int qsmm_set_actor_sig_weight (qsmm_actor_t actor, qsmm_sig_t sig, double weight)

This function sets the weight of output signal sig of actor to weight.

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_INVAL

Signal sig is not an output signal of the actor, or weight is not a finite number or is a negative number.

QSMM_ERR_NOTSUP

The actor is the large one.

A preloaded probability profile for an action choice state of an actor is defined by a list of probabilities in normal form and a one-to-one correspondence between elements of that list and identifiers of output signals of the actor. In QSMM, that correspondence is called a permutation of output signals for short. Splitting a preloaded probability profile into a probabilities list in normal form and a permutation of output signals is done to reduce the memory footprint of an actor, especially of large one.

For a small actor, the normal form of a list of probabilities is simply a sorted form of that list. For a large actor, the normal form of a given list of probabilities is a resulting list of probabilities that correspond to leaves of a Huffman tree created for a sorted form of the given list of probabilities. Indices of probabilities in the resulting list are equal to indices of corresponding source probabilities in the sorted list. Note that actually used profile probabilities, which follow from the structure of a Huffman tree, may differ from source profile probabilities for which that Huffman tree was created.

There is a concept of a pool of probabilities lists in normal form, which corresponds to an actor. Probabilities lists in normal form added to the pool cannot be removed from the pool, except by destroying the actor using the function qsmm_actor_destroy. The size of the pool is specified in the field profile_pool_sz of structure qsmm_actor_desc_s when creating the actor using the function qsmm_actor_create and can be retrieved later by the function qsmm_get_actor_profile_pool_sz.

The pool contains unique probabilities lists in normal form. That is, for a large actor, to elements of the pool there correspond Huffman trees with unique positional arrangements of nodes. For that type of actor, even when preloading a probability profile, to which there does correspond a probabilities list in normal form already contained in the pool, the actor creates a temporary Huffman tree to obtain the normal form of the list. The temporary Huffman tree takes up one element in the pool, which is why the size of the pool should generally be greater by 1 than the number of unique probabilities lists in normal form one needs to load into the pool.

There is also a concept of a pool of permutations of output signals, which corresponds to an actor. The pool contains unique permutations. As opposed to the pool of probabilities lists in normal form, the size of which has to be specified when creating the actor, the pool of permutations of output signals grows dynamically and its size does not need to be specified in advance. Permutations of output signals added to the pool cannot be removed from the pool, except by destroying the actor using the function qsmm_actor_destroy.

To split a list of weights of output signals of an actor into a unique probabilities list in normal form and a unique permutation of output signals, the following function can be used.

Function: int qsmm_actor_profile_add (qsmm_actor_t actor, qsmm_sig_t sig_beg, qsmm_sig_t sig_end, const double *weight_p, int *profile_p, int *permut_p)

This function preloads a list of weights of output signals into actor. The weights are passed via array weight_p. If weight_p is NULL, then this will be interpreted as if array weight_p contains all weights equal to 1.

Arguments sig_beg and sig_end can be both zero or may specify identifiers of the first signal (inclusive) and the last signal (exclusive) for the list of weights. In array weight_p, the weight of the first signal of that list has offset sig_beg. If sig_end is 0, then the total number of actor signals will be used for the value of the last signal of the list. Values of elements of array weight_p, which do not correspond to output signals of the actor, are ignored.

If profile_p is not NULL, then the function will set *profile_p to a non-negative index of a unique probabilities list in normal form that corresponds to the list of weights. That index will identify either a unique probabilities list in normal form just added to the pool of these lists or such a list which already contained in the pool. The length of the unique probabilities list in normal form is equal to the number of positive elements in array weight_p, which correspond to output signals of the actor within a range specified using sig_beg and sig_end.

If permut_p is not NULL, then the function will set *permut_p to a non-negative index of a unique permutation of output signals, which corresponds to the list of weights. That index will identify either a unique permutation of output signals just added to the pool of these permutations or such a permutation which 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 following error codes can be returned.

QSMM_ERR_INVAL

One of the following conditions is met:

  • – the value of sig_beg is greater than or equal to a value (incremented by 1) of the last signal of the list of weights;
  • – the value of sig_end is greater than the total number of signals of the actor;
  • – the sum of elements in array weight_p, which correspond to output signals of the actor within a range specified using sig_beg and sig_end, is not finite.
QSMM_ERR_WEIGHT

A negative or a non-finite element, which corresponds to an output signal of the actor, was encountered in array weight_p within a range specified using sig_beg and sig_end.

QSMM_ERR_NOCHOICE

Array weight_p does not contain at least one positive element that corresponds to an output signal of the actor within a range specified using sig_beg and sig_end.

QSMM_ERR_MPROF

No room in the pool of probabilities lists in normal form, the size of which was specified when creating the actor.

QSMM_ERR_STORAGE

Failure of statistics storage of a large actor. This could leave the actor in indeterminate state. If the actor is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds, then the actor’s state will become determinate.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation. This could leave the actor’s memory in indeterminate state. If the actor’s memory is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds, then the actor’s memory state will become determinate.

The function qsmm_actor_profile_add may operate slowly, which is especially true for a large actor when a Huffman tree is created. To speed up preloading a number of probability profiles, to which the same sorted list of weights of output signals corresponds, one can perform the following procedure.

  1. Preload the first probability profile using the function qsmm_actor_profile_add, which returns an index of probabilities list in normal form and an index of the permutation of output signals that identify the preloaded profile.
  2. For every other probability profile, sort a list of weights of output signals, which corresponds to the profile (all profiles have the same sorted form of that list), to obtain a permutation of output signals. Actually, it is necessary to sort a list of pairs, each consisting of weight and output signal identifier, in ascending order of weights.
  3. Register every such permutation of output signals using the function qsmm_actor_permut_add (described below) to obtain an index of unique permutation of output signals, which can be used along with an index of probabilities list in normal form, obtained at step 1, to identify a preloaded probability profile other than the first one.
Function: int qsmm_actor_permut_add (qsmm_actor_t actor, int sz, const qsmm_sig_t *sig_p)

This function adds a permutation of output signals of actor to a pool for these permutations, which corresponds to the actor, if the pool does not already contain this permutation. The permutation is specified by array sig_p of length sz and must be a subset of identifiers of output signals of the actor.

On success, the function returns a non-negative index of a permutation of output signals just added to the pool or which already contained in the pool. That index uniquely identifies the permutation in the pool. On failure, the function returns a negative error code. Currently, the following error codes can be returned.

QSMM_ERR_INVAL

The value of sz is less than 1, or array sig_p contains duplicate elements or an element, which is not an identifier of output signal of the actor.

QSMM_ERR_NOMEM

There was not enough memory to add the permutation of output signals to the pool.

The purpose of the following functions is to retrieve or set up a correspondence between an action choice state and a list of weights of output signals, which can be emitted in that action choice state.

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 list of weights of output signals, which can be emitted in that action choice state. The list of weights is specified by an index of probabilities list in normal form and an index of the permutation of output signals. The action choice state is defined by list of signal identifiers sig_ngram_p of length specified in the field ngram_sz of structure qsmm_actor_desc_s when creating the actor. Argument rez1 is reserved for future use and must be equal to 0.

If profile_p is not NULL, then the function will set *profile_p to an index of probabilities list in normal form that corresponds to the list of weights of output signals. If permut_p is not NULL, then the function will set *permut_p to an index of the permutation of output signals, which corresponds to the list of weights of output signals. If the function sets *profile_p and *permut_p to -1, then this will be an indication that the default list of weights of output signals has been assigned to the action choice state. In such a list, all output signals of the actor have equal weights, with the exception that for a large actor actual weights that follow from the structure of a Huffman tree are all equal only if the length of the list is a positive integer power of arity of the tree.

On success, the function returns a non-negative value. If array sig_ngram_p specifies an invalid action choice state n-gram, then negative error code QSMM_ERR_NGRAM will be returned.

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 list of weights of output signals, which can be emitted in that action choice state. The list of weights is specified by profile, which is an index of probabilities list in normal form, and by permut, which is an index of the permutation of output signals. The action choice state is defined by list of signal identifiers sig_ngram_p of length specified in the field ngram_sz of structure qsmm_actor_desc_s when creating the actor. Argument rez1 is reserved 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 a default list of weights of output signals to the action choice state. The default list specifies equal weights for all output signals of the actor, with the exception that, for a large actor, actual weights that follow from the structure of a Huffman tree are all equal only if the length of the default list is a positive integer power of arity of the tree.

If the actor is the small one, the function keeps intact statistics collected for the action choice state during actor operation, which is held in storage of the actor. If the actor is the large one, the function also keeps intact statistics held in storage, a handle to which can be retrieved by the function qsmm_get_actor_storage. However, the function destroys a Huffman tree that may have been created for the action choice state, in which the other part of statistics collected for that state during actor operation is stored.

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_INVAL

Argument profile is not a valid index of probabilities list in normal form or argument permut is not a valid index of the 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

Argument sig_ngram_p specifies an invalid action choice state n-gram. To determine the validity of an action choice state n-gram, it is checked for accordance with allowed ranges of signal identifiers specified using the field range_sig_p of structure qsmm_actor_desc_s when creating the actor.

QSMM_ERR_NOTSUP

The actor is the small one, and the total number of possible action choice state n-grams, calculated on the basis of allowed ranges of signal identifiers specified using the field range_sig_p of structure qsmm_actor_desc_s when creating the actor, exceeds INT_MAX.

QSMM_ERR_STORAGE

Failure of statistics storage of a large actor. This could leave the actor in indeterminate state. If the actor is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds, then the actor’s state will become determinate.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation. This could leave the actor’s memory in indeterminate state. If the actor’s memory is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds, then the actor’s memory state will become determinate.


Next: , Previous: , Up: Adaptive Probabilistic Mapping   [Contents][Index]