2.5.1 Incrementing Spur

An actor selects output signals adaptively according to spur increments supplied to it along with input signals. Those spur increments are indirect and probabilistic assessment of efficiency of output signal selection. An output signal selected does not have one-to-one correspondence with a spur increment followed—an arbitrary number of output signals selected can cause an arbitrary number of spur increments followed in arbitrary delays.

Each spur increment is an increment of spur of a specific type. See Spur-driven Behavior, for the definitions of spur and spur type.

The function qsmm_actor_create sets the number of spur types for an actor. Every spur type definition has the following parameters: a way of spur perception, spur weight, and a type of time for computing spur increment velocity. A list of spur type definitions along with the methods of performing spur increments specify the spur scheme of an actor.

Use the following function to increment the value of spur of a specific type.

Function: int qsmm_actor_spur_delta (qsmm_actor_t actor, int spur_type, double spur_delta)

This function increments by spur_delta the value of spur of spur_type type an actor has been accumulating. Spur types have zero-based indices. Special spur type -1 of a large actor corresponds to the automatic spur of a small actor associated with the large actor. The value of spur_delta can be negative.

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

One of the following conditions is true:

• – the actor is the small one, and spur_type is negative;
• – the actor is the large one, and spur_type is less than -1;
• – spur_type is greater than or equal to the number of spur types specified in the field nspur of qsmm_actor_desc_s structure when creating the actor;
• – spur_delta is non-finite.

QSMM_ERR_INFIN

The incremented spur value would be infinite.

Use the following function to get the current value of spur of a specific type.

Function: int qsmm_get_actor_spur (qsmm_actor_t actor, int spur_type, double *spur_p)

This function sets *spur_p equal to the current value of spur of spur_type type an actor has been accumulating. Spur types have zero-based indices. Special spur type -1 of a large actor corresponds to the automatic spur of a small actor associated with the large actor. If spur_p is NULL, the function does not set *spur_p. Otherwise, *spur_p is finite.

On success, the function returns a non-negative value. If the actor is the small one and spur_type is negative, or if the actor is the large one and spur_type is less than -1, or if spur_type is greater than or equal to the number of spur types specified in the field nspur of qsmm_actor_desc_s structure when creating the actor, the function returns negative error code QSMM_ERR_INVAL.