Next: , Previous: , Up: Adaptive Probabilistic Mapping   [Contents][Index]


2.6 Event History N-gram

An action choice state is a list of signal identifiers of fixed length, on the basis of which an actor can generate an output signal. That length has to be specified in the field ngram_sz of structure qsmm_actor_desc_s when creating the actor using the function qsmm_actor_create and can be retrieved later by the function qsmm_get_actor_ngram_sz.

There is a window associated with an actor, the contents of which are n-grams of length ngram_sz from the event history. When creating an actor, elements of the window are initialized to 0. For example, when ngram_sz is equal to 3, the contents of the window just after creating the actor are <0, 0, 0>.

The contents of the window shift one signal left and a new signal from the event history becomes the last signal of the window after a call to the function qsmm_actor_shl_sig, qsmm_actor_reg_sig_in, or qsmm_actor_reg_sig_action. Shifting the contents of the window one signal left also implies incrementing by 1 discrete time tracked by the actor.

To shift the contents of the window one signal left and append a new signal from the event history, so that the window would contain an n-gram that represents an action choice state, the function qsmm_actor_reg_sig_in should be used. This function updates statistics, collected on the event history, using information recorded when the same action choice state has occurred the previous time in the event history.

To shift the contents of the window one signal left and append a new signal, which is an output signal generated by the actor (or another output signal the application program has chosen to emit), the function qsmm_actor_reg_sig_action should be used. You should usually call this function after a call to qsmm_actor_reg_sig_in. It records for an action choice state discrete and continuous time of the last occurrence of the action choice state in the event history, an output signal emitted in that action choice state, and current value of the spur of every type the actor has been accumulating.

Note: because the function qsmm_actor_reg_sig_action records time and values of spur for an action choice state, which has just occurred in the event history, the functions qsmm_actor_time_delta and qsmm_actor_spur_delta usually should not be called between a call to qsmm_actor_reg_sig_in and a subsequent call to qsmm_actor_reg_sig_action.

In all other cases, to shift the contents of the window one signal left and append a new signal from the event history, the function qsmm_actor_shl_sig should be used. This function does not update statistics collected on the event history.

In Figure 2.4, there is shown an example of changing a window, which holds current n-gram from the event history, caused by calls to Actor API functions. This example corresponds to first eight events from event history shown in Figure 2.1. N-grams, which represent action choice states, are marked by thick lines.

Example of changing current n-gram of event history

Figure 2.4: Example of changing current n-gram of event history

Functions, which shift the contents of the window one signal left and increment by 1 discrete time tracked by an actor, are described in detail below.

Function: int qsmm_actor_shl_sig (qsmm_actor_t actor, qsmm_sig_t sig_last, qsmm_sig_t *sig_first_p)

This function shifts one signal left the contents of a window of actor, which holds current n-gram from the event history, and appends signal sig_last to the end of the window. Discrete time tracked by the actor is incremented by 1. A signal, which was at the beginning of the window before the shift, is returned in *sig_first_p if sig_first_p is not NULL.

For example, if the window contained signals <3, 6, 2>, then after executing lines of code

qsmm_sig_t sig_first=QSMM_SIG_INVALID;
qsmm_actor_shl_sig(actor,4,&sig_first);

the window would contain signals <6, 2, 4>, and sig_first would be equal to 3.

On success, the function returns a non-negative value. If sig_last is greater than or equal to the number of signals of the actor, then negative error code QSMM_ERR_INVAL will be returned.

Function: int qsmm_actor_reg_sig_in (qsmm_actor_t actor, qsmm_sig_t sig)

This function shifts one signal left the contents of a window of actor, which holds current n-gram from the event history, and appends signal sig to the end of the window. Discrete time tracked by the actor is incremented by 1. The resulting contents of the window are considered to be an n-gram that represents an action choice state. If that action choice state did not occur earlier in the event history, then the function finishes execution.

If that action choice state did occur earlier in the event history, then for a pair, which consists of the action choice state and an output signal emitted when the action choice state has occurred the previous time in the event history (that moment is referred to below as the time of the last occurrence of the pair), statistics is updated in the following way:

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

QSMM_ERR_INVAL

The value of sig is greater than or equal to the number of signals of the actor.

QSMM_ERR_NGRAM

After shifting one signal left the contents of an actor window, which holds current n-gram from the event history, and appending signal sig to the end of the window, that window would correspond to an invalid action choice state. To determine the validity of an action choice state, it is checked for accordance with allowed ranges of signal identifiers specified using the field range_sig_p of structure qsmm_actor_desc_s when creating the actor.

QSMM_ERR_STORAGE

Statistics storage failure. This could leave the actor in indeterminate state.

QSMM_ERR_NOMEM

A statistics storage access function did return out of memory error. This could leave the actor in indeterminate state.

When you want to store an action choice state n-gram of length greater than 1 in an actor window that holds current n-gram from the event history, you normally use a series of calls to qsmm_actor_shl_sig followed by a call to qsmm_actor_reg_sig_in:

int ii;
for (ii=0; ii<NGRAM_SZ-1; ii++)
    if (qsmm_actor_shl_sig(actor,sig_ngram[ii],0)<0) goto Error;
if (qsmm_actor_reg_sig_in(actor,sig_ngram[NGRAM_SZ-1])<0) goto Error;

Note that, in some cases, it is necessary not to completely replace the contents of the window, so NGRAM_SZ should be changed to a value less than the length of a list of signal identifiers, which represents an action choice state.

Function: int qsmm_actor_reg_sig_action (qsmm_actor_t actor, qsmm_sig_t sig)

This function registers signal sig as an output signal of actor emitted in an action choice state, which corresponds to the contents of a window that holds current n-gram from the event history.

The function records the following information for that action choice state:

Finally, the function shifts one signal left the contents of the window, which holds current n-gram from the event history, and appends signal sig to the end of the window. Discrete time tracked by the actor is incremented by 1.

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

QSMM_ERR_INVAL

Signal sig is not an output signal of the actor.

QSMM_ERR_NGRAM

The contents of an actor window, which holds current n-gram from the event history, correspond to an invalid action choice state. To determine the validity of an action choice state, it is checked for accordance with allowed ranges of signal identifiers specified using the field range_sig_p of structure qsmm_actor_desc_s when creating the actor.

QSMM_ERR_STORAGE

Statistics storage failure. This could leave the actor’s memory in indeterminate state. If the actor’s memory is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds, then the actor’s memory state will become determinate.

QSMM_ERR_NOMEM

A statistics storage access function did return out of memory error. This could leave the actor’s memory in indeterminate state. If the actor’s memory is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds, then the actor’s memory state will become determinate.

To shift the contents of the window one signal right and decrement by 1 discrete time tracked by the actor, the following function can be used.

Function: int qsmm_actor_shr_sig (qsmm_actor_t actor, qsmm_sig_t sig_first, qsmm_sig_t *sig_last_p)

This function shifts one signal right the contents of an actor window, which holds current n-gram from the event history, and prepends signal sig_first to the beginning of the window. Discrete time tracked by the actor is decremented by 1. A signal, which was at the end of the window before the shift, is returned in *sig_last_p if sig_last_p is not NULL.

On success, the function returns a non-negative value. If sig_first is greater than or equal to the number of signals of the actor, then negative error code QSMM_ERR_INVAL will be returned.

When using the function qsmm_actor_shr_sig, remember that the functions qsmm_actor_reg_sig_in and qsmm_actor_reg_sig_action should normally be called for increasing (or at least for equal) values of discrete time tracked by the actor. That is, after calling the function qsmm_actor_shr_sig certain number of times, the function qsmm_actor_shl_sig usually should be called the corresponding number of times to restore discrete time to the original value.

In some cases, it is necessary to analyze actor’s behavior when current action choice state is another state. To do that, it is required to save the contents of the window, which holds current n-gram from the event history, replace the contents with another n-gram, call an Actor API function that calculates probabilities of emitting output signals, and finally restore the original contents of the window. An internal buffer, which holds the contents of the window, can be obtained using the following function.

Function: qsmm_sig_t * qsmm_get_actor_sig_ngram (qsmm_actor_t actor)

This function returns the pointer to an internal array of an actor specified by handle actor. The internal array represents the window that holds current n-gram from the event history. This function never returns NULL. The number of elements in the array is equal to a value specified in the field ngram_sz of structure qsmm_actor_desc_s when creating the actor by the function qsmm_actor_create. The same value is returned by the function qsmm_get_actor_ngram_sz.

To enumerate n-grams of action choice states, information on which is stored in the actor’s memory, the following function can be used.

Function: int qsmm_actor_enum_ngrams (qsmm_actor_t actor, int ngram_prefix_sz, const qsmm_sig_t *sig_ngram_prefix_p, qsmm_enum_ngrams_callback_func_t callback_func, void *paramp)

This function enumerates n-grams of action choice states, information on which is stored in the memory of actor. For a small actor, these are states, information on which is held in statistics storage of the actor, a handle to which can be obtained using the function qsmm_get_actor_storage. For a large actor, these are states from the union of the following state sets:

The function enumerates the above action choice states that have prefix sig_ngram_prefix_p of length ngram_prefix_sz. If ngram_prefix_sz is 0, then sig_ngram_prefix_p can be NULL.

The process of enumeration is a repeated calling callback function callback_func, to which an action choice state n-gram and user parameter paramp are passed. If the callback function returns a positive value, then the process of enumeration will be continued. If the callback function returns zero, then the process of enumeration will be terminated, and the function qsmm_actor_enum_ngrams will report success. If the callback function returns a negative value, then the process of enumeration will be terminated, and the function qsmm_actor_enum_ngrams will report failure.

In the current implementation, the function qsmm_actor_enum_ngrams does not support recursive calling from the callback function for the same actor.

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

QSMM_ERR_INVAL

The value of ngram_prefix_sz is less than 0 or is greater than the length of a list of signal identifiers, which defines an action choice state.

QSMM_ERR_CALLBACK

The callback function did return an error.

QSMM_ERR_STORAGE

Statistics storage failure.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

The type of a pointer to the callback function called for every enumerated action choice state is described below.

Data type: qsmm_enum_ngrams_callback_func_t

This is a type of callback function pointer with the following declaration:

typedef int (*qsmm_enum_ngrams_callback_func_t)(
    qsmm_actor_t actor,
    const qsmm_sig_t *sig_ngram_p,
    void *paramp);

The callback function is called for every enumerated action choice state of an actor. The list of signal identifiers of an action choice state is passed via argument sig_ngram_p. The length of that list is equal to a value, which has to be specified in the field ngram_sz of structure qsmm_actor_desc_s when creating the actor using the function qsmm_actor_create and which can be retrieved later by the function qsmm_get_actor_ngram_sz. A user parameter is passed via argument paramp.

The callback function might return a positive value if the process of enumeration should be continued, zero if the process of enumeration should be terminated, or a negative value on error.

To remove information on an action choice state from the actor’s memory, the following function can be used.

Function: int qsmm_actor_remove_ngram (qsmm_actor_t actor, const qsmm_sig_t *sig_ngram_p)

This function removes information on an action choice state, specified by list of signal identifiers sig_ngram_p, from the memory of actor. The length of the list is equal to a value, which has to be specified in the field ngram_sz of structure qsmm_actor_desc_s when creating the actor using the function qsmm_actor_create and which can be retrieved later by the function qsmm_get_actor_ngram_sz.

For a small actor, the function removes information on the action choice state held in statistics storage of the actor, a handle to which can be obtained using the function qsmm_get_actor_storage. For a large actor, the function removes the following pieces of information if they exist in the actor’s memory:

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

QSMM_ERR_NGRAM

Argument sig_ngram_p specifies an invalid action choice state n-gram. To determine the validity of an action choice state n-gram, it is checked for accordance with allowed ranges of signal identifiers specified using the field range_sig_p of structure qsmm_actor_desc_s when creating the actor.

QSMM_ERR_NOTFOUND

The actor’s memory does not contain information on the action choice state, nothing to remove.

QSMM_ERR_STORAGE

Statistics storage failure. This could leave the actor’s memory in indeterminate state. If the actor’s memory is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds or returns QSMM_ERR_NOTFOUND, then the actor’s memory state will become determinate.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation. This could leave the actor’s memory in indeterminate state. If the actor’s memory is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds or returns QSMM_ERR_NOTFOUND, then the actor’s memory state will become determinate.


Next: , Previous: , Up: Adaptive Probabilistic Mapping   [Contents][Index]