---

2.6.5 Number of Output Signals ¶

Use the following function to get the number of output signals of an actor.

Function: qsmm_sig_t qsmm_get_actor_nsig_out (qsmm_actor_t actor) ¶

This function returns the number of output signals of an actor. That number is either the number of output signals specified in the field nsig_out of qsmm_actor_desc_s structure 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_out.

Since QSMM 1.19, actors support increasing the number of output signals. Use the following function to increase the number of output signals of an actor after creating it.

Function: int qsmm_set_actor_nsig_out (qsmm_actor_t actor, qsmm_sig_t nsig_out) ¶

This function increases the number of output signals of an actor and makes that number equal to nsig_out. For a large actor, this operation is possible when the actor has not created a default output signal choice tree yet. A large actor creates a default output signal choice tree when:

• generating an output signal for an action choice state with unset probability profile by the function qsmm_get_actor_sig_action;
• calculating probabilities of output signals for an action choice state with unset probability profile by the function qsmm_actor_calc_action_prob;
• obtaining the node of a default output signal choice tree by calling the function qsmm_get_actor_large_osct_node for probabilities list index (size_t) -1.

For a small actor, qsmm_set_actor_nsig_out sets weights of added output signals to 1.

The function returns a non-negative value on success or a negative error code on failure. Currently, the function can return the following error codes.

QSMM_ERR_INVAL

The argument nsig_out is less than the current number of output signals returned by the function qsmm_get_actor_nsig_out or greater than QSMM_SIG_MAX+1.

QSMM_ERR_UNTIMELY

The actor is the large one, and it has created a default output signal choice tree.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

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 increasable by the function qsmm_set_actor_nsig_out. 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 has 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.

Large actors can avoid the weak concept of the nominal number of output signals if large actors use output signal choice trees with arity 2. In this case, small actors associated with the large actors use equal profile probabilities of output signals. In QSMM 1.19, the developer can create a large actor with setting the new field profile_tol of qsmm_actor_large_desc_s structure to a positive value for rearranging a Huffman tree generated for a list of output signal weights (e.g. specified for an action choice state by qsmm_set_actor_ngram_profile) to achieve a desired precision of output signal weights following from tree structure.

Tip: when specifying custom output signal weights, use a large actor with tree arity 2 instead of a small actor to make actor’s behavior well defined.

When using a small actor and loading an assembler program into a node or changing values of controlled probability variables of a node, QSMM uses the following algorithm for 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 nominal numbers of output signals calculated for profile probabilities of output signals of action choice states occurring in the event history. The mean nominal number of output signals might be the arithmetic or geometric mean of 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 specified in the field nsig_out of qsmm_actor_desc_s structure 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 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 the 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.