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 non-deterministic 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]