---

2.5.1 Receiving Input Signals ¶

An actor has a buffer containing an array of signal identifiers encoding a current action choice state. The field ngram_sz of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the actor specifies the number of elements in the array. The function qsmm_get_actor_ngram_sz returns that number for a created actor.

The function qsmm_actor_create initializes the array elements to minimum allowed signal identifiers specified by the field range_sig_p of qsmm_actor_desc_s structure passed to that function.

Use the following function to obtain direct access to the buffer.

Function: qsmm_sig_t * qsmm_get_actor_sig_ngram (qsmm_actor_t actor) ¶

This function returns the pointer to the buffer in actor containing an array of signal identifiers encoding a current action choice state. The number of elements in the array is equal to the field ngram_sz of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the actor; the function qsmm_get_actor_ngram_sz returns that number for an actor. The function qsmm_get_actor_sig_ngram never returns NULL.

Use the following function to register a current action choice state encoded by an array of signal identifiers contained in the buffer and update statistics on the current action choice state using information recorded when the action choice state occurred the previous time in the event history.

Function: int qsmm_actor_reg_ngram_in (qsmm_actor_t actor) ¶

This function increments by 1 discrete time tracked by an actor and processes an array of signal identifiers encoding a current action choice state contained in a buffer returned by the function qsmm_get_actor_sig_ngram.

If the action choice state did not occur earlier in the event history, the function finishes execution and reports success. If the action choice state occurred earlier in the event history, the function processes a cycle between the previous and current occurrence of the action choice state by updating statistics on its cycle type. A cycle type is the pair comprised of an action choice state and an output signal emitted when the action choice state occurred the previous time in the event history (we refer to that time as the time of cycle start). The output signal emitted is the cycle direction.

If the incremented discrete time is less than or equal to the discrete time of cycle start, the function finishes execution and reports success. Otherwise, the function updates statistics on the cycle type in the following way:

• increments by 1 the number of occurrences of the cycle type;
• increments the sum of discrete time periods for the cycle type by the difference between current discrete time and the discrete time of cycle start (we refer to that difference as discrete cycle period);
• for every continuous time type, the function increments the sum of continuous time periods for the cycle type by the difference between current continuous time and the continuous time of cycle start (we refer to that difference as continuous cycle period);
• for every spur type, the function increases the sum of spur increments for the cycle type by the difference between a current spur value and a spur value at the cycle start.

If the actor uses automatic spur, the function increments it by the logarithm of observed probability of the cycle type in the event history (see Automatic Spur, for additional information).

To be able to query mean discrete cycle period by the function qsmm_get_actor_discrete_cycle_period_mean, the function qsmm_actor_reg_ngram_in increments by 1 the total number of cycles processed and increments the total sum of discrete cycle periods.

The function qsmm_actor_reg_ngram_in 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_NGRAM

A buffer returnable by the function qsmm_get_actor_sig_ngram does not contain a valid array of signal identifiers encoding an action choice state. To determine array validity, the function qsmm_actor_reg_ngram_in checks it 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_INFIN

The operation of computing the increment of automatic spur or the operation of increasing the sum of spur or continuous time increments for the cycle type returned an infinite result.

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 or cycle type detected.

QSMM_ERR_ILSEQ

A statistics storage access function generated an error message but could not 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.

Using the following functions, you can obtain the discrete cycle period of last cycle registered by the function qsmm_actor_reg_ngram_in and the mean discrete cycle period of all cycles registered by that function since creating an actor. You can use this information in a custom function for computing the relative probability of an output signal.

Function: long qsmm_get_actor_discrete_cycle_period_last (qsmm_actor_t actor) ¶

This function returns the discrete cycle period of last cycle registered for actor by the function qsmm_actor_reg_ngram_in. A returned value is always non-negative.

If there was no call to qsmm_actor_reg_ngram_in yet, or at the last call that function did not register a cycle, qsmm_get_actor_discrete_cycle_period_last returns 0.

Function: double qsmm_get_actor_discrete_cycle_period_mean (qsmm_actor_t actor) ¶

This function returns the mean discrete cycle period of all cycles registered for an actor by the function qsmm_actor_reg_ngram_in since creating the actor.

If qsmm_actor_reg_ngram_in did not register any cycle yet, qsmm_get_actor_discrete_cycle_period_mean returns 0. This function returns only finite and non-negative values.