Next: Example of Using the Actor API, Previous: Controlling Random Behavior of an Actor, Up: Adaptive Probabilistic Mapping [Contents][Index]

When using a custom function, which returns a relative probability of output signal choice, or providing coherent operation of a stack of actors, it may be necessary to know a discrete time period of the last cycle processed by an actor or the mean discrete time period of all cycles processed by the actor since the beginning of its operation. This information can be obtained using the following functions.

- Function:
*long***qsmm_get_actor_discrete_cycle_period_last***(qsmm_actor_t*`actor`) This function returns a discrete time period of the last cycle registered by

`actor`in the function`qsmm_actor_reg_sig_in`

. The returned value is always non-negative.If the function

`qsmm_actor_reg_sig_in`

is not yet called, then zero will be returned. When the function`qsmm_actor_reg_sig_in`

is called at least once, zero will be returned if at the last call to`qsmm_actor_reg_sig_in`

a cycle is not encountered.

- Function:
*double***qsmm_get_actor_discrete_cycle_period_mean***(qsmm_actor_t*`actor`) This function returns the mean discrete time period of all cycles registered by

`actor`in the function`qsmm_actor_reg_sig_in`

since the beginning of actor operation. If there are no cycles registered yet, then zero will be returned. The function returns only finite and non-negative values.

A function, which calculates a relative probability of output signal choice, typically uses a parameter equal to the number of actor’s output signals to perform the calculation.
The function `qsmm_actor_create`

creates an actor with a particular number of output signals.
However, during operation of a small actor, its output signal weights can be changed using the function `qsmm_set_actor_sig_weight`

or by assigning preloaded probability profiles to action choice states using the function `qsmm_set_actor_ngram_profile`

, and those weights may correspond to a lesser number of output signals.
For example, if the actor had four output signals, and the weight of one of them were set to zero, then the actual number of output signals would be three.
The same applies to a probability profile that can be specified for an action choice state (in actor’s statistics storage for a small actor or using the function `qsmm_set_actor_ngram_profile`

for a large actor): if the profile probability of an output signal is equal to zero, then the actual number of output signals will be less than the number of output signals defined when creating the actor.

However, the concept of the actual number of output signals is somewhat weak. The weakness shows up when positive weights (or profile probabilities) of output signals are not equal. In this case, the actual number of output signals might not be simply the number of output signals that have positive weights (or profile probabilities). For example, if four signals have weights <0.33, 0.33, 0.33, 0.01>, then the actual number of output signals will rather be three than four.

When loading an assembler program into a node or changing values of controlled probability variables of a node, the QSMM package uses the following algorithm for the approximate calculation of the actual number of output signals, which corresponds to a list of weights.

- Zero
*c*, the resulting number of output signals. - Calculate
*a*, the arithmetic mean of all positive weights of output signals. - For every output signal weight
*b*, if*b>a*, then add 1 to*c*, otherwise add*b/a*to*c*.

During actor operation, when calculating relative probabilities of emitting output signals in action choice states, to different action choice states there may correspond different actual numbers of output signals. If a function, which returns a relative probability of output signal choice, uses only one parameter that denotes the number of output signals, there may arise a need to introduce the concept of the mean number of actor’s output signals, which is, in fact, weaker than the concept of the actual number of output signals. The mean number of output signals of an actor could be calculated on the basis of actual numbers of output signals from which the actor chooses a specific output signal each time it produces an action, i.e. on the basis of actual numbers of output signals for particular occurrences of action choice states in the event history, and might be the arithmetic or geometric mean of those actual numbers of output signals.

The mean number of output signals can be retrieved or set using the following functions.

- Function:
*double***qsmm_get_actor_nsig_ctrl***(qsmm_actor_t*`actor`) This function returns the mean number of output signals of

`actor`. It is either the number of output signals calculated from the contents of structure`qsmm_actor_desc_s`

, passed to the function`qsmm_actor_create`

when creating the actor, or the number of output signals previously set using the function`qsmm_set_actor_nsig_ctrl`

. The function`qsmm_get_actor_nsig_ctrl`

can be called from a custom function that returns a relative probability of output signal choice if the function uses a formula that involves the number of output signals. A value returned by the function`qsmm_get_actor_nsig_ctrl`

is always finite and is greater than or equal to 2.

- Function:
*int***qsmm_set_actor_nsig_ctrl***(qsmm_actor_t*`actor`, double`val`) This function sets the mean number of output signals of

`actor`to`val`. The mean number of output signals is used by built-in functions, which return a relative probability of output signal choice, and can be used by a custom relative probability function supplied by a developer.On success, the function returns a non-negative value. If

`val`is not a finite number or is a number less than 2, then negative error code`QSMM_ERR_INVAL`

will be returned.

In the simplest case, when output signal weights are not changed during actor operation and profile probabilities are not used, there is no need to modify the mean number of output signals, which was initially set by the function `qsmm_actor_create`

.
Otherwise, a program, which uses a small actor, should calculate in some way the mean number of output signals and set that number for the actor by the function `qsmm_set_actor_nsig_ctrl`

.

If an array of signal weights or a probability profile specifies that only one signal can be chosen (i.e. if the array of signal weights contains a single positive element or if a probability profile for an action choice state contains a single positive probability of an output signal), then the best will be not to call the functions `qsmm_actor_shl_sig`

, `qsmm_actor_reg_sig_in`

, and `qsmm_actor_reg_sig_action`

at all.
In this case, action choice can be performed in a deterministic way (without using the actor), and discrete time shall not be incremented.
However, if the functions `qsmm_actor_shl_sig`

and `qsmm_actor_reg_sig_in`

were already called, then for proper accumulation of statistics for the action choice state, it would be appropriate to register that the only allowed output signal using a call to `qsmm_actor_reg_sig_action`

and then to backtrack discrete time (using several calls to `qsmm_actor_shr_sig`

) to the moment before feeding the action choice state n-gram to the actor.

The historical limitation for the minimum mean number of actor’s output signals, which can be set using the function `qsmm_set_actor_nsig_ctrl`

, is 2.
When computing the mean number of output signals on the basis of actual numbers of output signals for particular occurrences of action choice states in the event history, if there is no signal, which is only allowed to be emitted in an action choice state, and the actual number of output signals computed for an array of signal weights or a probability profile is less than 2, then you may either use 2 for the actual number of output signals for the particular occurrence of action choice state to calculate the mean number of output signals or change the array of signal weights or the probability profile in such a way that they will give more freedom for the actor to choose output signals.

To calculate the mean number of output signals, when an action choice state has a probability profile specified, the precomputed actual number of output signals can be fetched from the probability profile. You still need to store the actual number of output signals, computed in advance, in the profile. To fetch the precomputed actual number of output signals from a probability profile of an action choice state and to determine an output signal if the profile allows only one output signal to be emitted, the following function can be used.

- Function:
*int***qsmm_get_actor_profile_nsig_ctrl***(qsmm_actor_t*`actor`, int *`nsig_pos_p`, double *`nsig_ctrl_p`, qsmm_sig_t *`sig_action_p`) This function retrieves information associated with a probability profile for current action choice state of an

`actor`held in its statistics storage. The current action choice state is the one, which corresponds to the contents of a window that holds current n-gram from the event history.If

`nsig_pos_p`is not`NULL`

, then the function will set *`nsig_pos_p`to the number of output signals, which can be emitted by the actor in its current action choice state and which have positive profile probabilities assigned. If`nsig_pos_p`is not`NULL`

, and current action choice state does not have a probability profile specified, then *`nsig_pos_p`will be set to 0.If

`nsig_ctrl_p`is not`NULL`

, then the function will set *`nsig_ctrl_p`to the actual number of output signals that can be emitted by the actor in its current action choice state. If`nsig_ctrl_p`is not`NULL`

, and current action choice state does not have a probability profile specified, then *`nsig_ctrl_p`will be set to 0.If the probability profile allows only one output signal to be emitted, then *

`nsig_pos_p`will be set to 1 (if`nsig_pos_p`is not`NULL`

), *`nsig_ctrl_p`will be set to 1 (if`nsig_ctrl_p`is not`NULL`

), and *`sig_action_p`will be set to that output signal (if`sig_action_p`is not`NULL`

). If`sig_action_p`is not`NULL`

, and current action choice state does not have a probability profile specified or the probability profile does not allow a single output signal to be emitted, then *`sig_action_p`will be set to`QSMM_SIG_INVALID`

.See Structures for Accessing Storage, for information on how to pass the number of output signals, which have positive profile probabilities assigned, the actual number of output signals, and a single output signal, which can be emitted (if it exists), to storage access functions to write them to statistics storage, which handle can be obtained using the function

`qsmm_get_actor_storage`

, so these parameters can be retrieved later by the function`qsmm_get_actor_profile_nsig_ctrl`

.If current action choice state has a probability profile specified, then the function will return a positive value. If current action choice state does not have a probability profile specified, then the function will return 0.

On failure, the function returns a negative error code. Currently, the following error codes can be returned.

`QSMM_ERR_NGRAM`

The contents of an actor window, which holds current n-gram from the event history, correspond to an invalid action choice state. To determine the validity of an action choice state, 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_STORAGE`

Statistics storage failure.

`QSMM_ERR_NOMEM`

A statistics storage access function did return out of memory error.