Next: Automatic Spur, Previous: Customizing the Relative Probability Function, Up: Adaptive Probabilistic Mapping [Contents][Index]

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.

- – the value of
`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.

- 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. - 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.
- 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.`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.