Next: , Previous: , Up: Customizing the Relative Probability Function   [Contents][Index]

#### 2.6.5 Number of Output Signals

A function returning the relative probability of an output signal typically uses a parameter equal to the number of output signals of an actor to perform the calculation. The function `qsmm_actor_create` creates an actor with a particular number of output signals. However, the function `qsmm_set_actor_sig_weight` can change output signal weights for a small actor, or the function `qsmm_set_actor_ngram_profile` can assign preloaded probability profiles to action choice states, and output signal weights may define a lesser number of output signals. For example, if the actor had four output signals, and `qsmm_set_actor_sig_weight` set the weight of one of them to zero, the nominal number of output signals is three. The same applies to a probability profile for an action choice state (set in the statistics storage of a small actor or by `qsmm_set_actor_ngram_profile` for a large actor): if the profile probability of an output signal is zero, the nominal number of output signals is less than the number of output signals defined when creating the actor.

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

When loading an assembler program into a node or changing the values of controlled probability variables of a node, QSMM uses the following algorithm for the approximate calculation of the nominal number of output signals for a list of weights:

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

Different action choice states in the event history can have different nominal numbers of output signals. If a function returning the relative probability of an output signal depends on the number of output signals, the function can use the mean nominal number of output signals for this parameter. An actor can compute the mean nominal number of output signals based on the nominal numbers of output signals calculated for the weights of the output signals of action choice states occurred in the event history. The mean nominal number of output signals might be the arithmetic or geometric mean of those nominal numbers of output signals. The concept of the mean nominal number of output signals is weaker than the concept of the nominal number of output signals.

You can retrieve or set the mean nominal number of output signals by the following functions.

Function: double qsmm_get_actor_nsig_ctrl (qsmm_actor_t actor)

This function returns the mean nominal number of output signals of an actor. That number is either the number of output signals calculated from the structure `qsmm_actor_desc_s` passed to the function `qsmm_actor_create` when creating the actor, or the number of output signals previously set by the function `qsmm_set_actor_nsig_ctrl`. You can call the function `qsmm_get_actor_nsig_ctrl` from a helper function for computing the relative probability of an output signal if the helper function depends on the number of output signals. A value returned by `qsmm_get_actor_nsig_ctrl` is always finite and greater than or equal to 2.

Function: int qsmm_set_actor_nsig_ctrl (qsmm_actor_t actor, double val)

This function sets the mean nominal number of output signals of an actor to val. Built-in functions returning the relative probability of an output signal use that number. A helper function for computing the relative probability of an output signal provided by a developer can also use that number.

On success, the function returns a non-negative value. If val is not a finite number or is a number less than 2, the function returns negative error code `QSMM_ERR_INVAL`.

In the simplest case, if you do not change output signal weights and do not use profile probabilities, there is no need to modify the mean nominal number of output signals initially set by the function `qsmm_actor_create` for a small actor. Otherwise, if a function returning the relative probability of an output signal depends on the number of output signals, you need to calculate in some way the mean nominal number of output signals and set that number for the small actor by the function `qsmm_set_actor_nsig_ctrl`. Because a large actor typically uses Huffman trees with a fixed number of child nodes of every tree node, and `qsmm_actor_create` sets this number as the mean nominal number of output signals of a small actor associated with the large actor, you might not need to modify the mean nominal number of output signals for the large actor.

If an array of output signal weights or a probability profile allows an actor to select only one output signal, that is, if the array contains a single positive element, or 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, you can perform the selection of an output signal in a deterministic way (without using the actor) and shall not increment discrete time.

To calculate the mean nominal number of output signals, you can fetch the precomputed nominal number of output signals for an action choice state from a probability profile if the action choice state has the probability profile specified. You still need to store the nominal number of output signals computed in advance in the profile. Use the following function to fetch the precomputed nominal number of output signals from the probability profile of an action choice state and to obtain an output signal if the profile specifies the deterministic selection of this output signal.

Function: int qsmm_get_actor_profile_nsig_ctrl (qsmm_actor_t actor, int *nsig_pos_p, double *nsig_ctrl_p, qsmm_sig_t *sig_out_p)

This function retrieves information from the statistics storage of an actor about a probability profile for a current action choice state encoded by the buffer for an n-gram of signals from the event history.

If nsig_pos_p is not `NULL`, the function sets *nsig_pos_p to the number of output signals with positive profile probabilities; the actor can emit one of those output signals in its current action choice state. If nsig_pos_p is not `NULL`, and the current action choice state does not have a probability profile specified, the function sets *nsig_pos_p to 0.

If nsig_ctrl_p is not `NULL`, the function sets *nsig_ctrl_p to the nominal number of output signals the actor can emit in its current action choice state. If nsig_ctrl_p is not `NULL`, and the current action choice state does not have a probability profile specified, the function sets *nsig_ctrl_p to 0.

If the probability profile allows an actor to emit only one output signal, the function sets *nsig_pos_p to 1 (if nsig_pos_p is not `NULL`), *nsig_ctrl_p to 1 (if nsig_ctrl_p is not `NULL`), and *sig_out_p to this output signal (if sig_out_p is not `NULL`). If sig_out_p is not `NULL`, and the current action choice state does not have a probability profile specified, or the probability profile defines nondeterministic selection of an output signal, the function sets *sig_out_p to `QSMM_SIG_INVALID`.

See Structures for Accessing Storage, for how to pass the number of output signals with positive profile probabilities, the nominal number of output signals, and an output signal to emit deterministically (if it exists) to storage access functions to write them to statistics storage with a handle obtained by the function `qsmm_get_actor_storage` to be able to retrieve those parameters later by the function `qsmm_get_actor_profile_nsig_ctrl`.

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

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

`QSMM_ERR_NGRAM`

The buffer does not encode a valid action choice state. To determine the validity of an action choice state, the function checks the content of the buffer 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_STORAGE`

Statistics storage failure. See Getting the Reason of a Storage Failure, for how to get an error message describing the failure.

`QSMM_ERR_STATS`

Inconsistent statistics on an action choice state detected.

`QSMM_ERR_ILSEQ`

A statistics storage access function generated an error message but cannot convert it to a wide string according to a current locale, or a storage redirection function reported `QSMM_ERR_ILSEQ`.

`QSMM_ERR_NOMEM`

A statistics storage access function reported out of memory error.

Next: , Previous: , Up: Customizing the Relative Probability Function   [Contents][Index]