Next: Emitting an Output Signal, Previous: Incrementing Time, Up: Repeated Sequence of Operations [Contents][Index]
An actor has a buffer containing an n-gram of identifiers of signals from the event history or a list 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 signal identifiers in the buffer.
The function qsmm_get_actor_ngram_sz
returns that number for a created actor.
The function qsmm_actor_create
initializes the elements of that buffer to minimum allowed signal identifiers specified by the field range_sig_p
of qsmm_actor_desc_s
structure when creating the actor.
The function qsmm_get_actor_sig_ngram
provides direct access to the buffer as an array of signal identifiers.
The functions qsmm_actor_shl_sig
and qsmm_actor_reg_sig_in
shift the buffer one signal left and append a new signal to the buffer.
Shifting the buffer one signal left implies incrementing by 1 discrete time tracked by the actor.
Call the function qsmm_actor_shl_sig
to shift the buffer one signal left and append a new signal to the buffer without updating statistics on action choice states.
Call the function qsmm_actor_reg_sig_in
if after shifting the buffer one signal left and appending a new signal to the buffer, it encodes a current action choice state.
That function updates statistics on the current action choice state using information recorded when that action choice state occurred the previous time in the event history.
To set a current action choice state for an actor, use a series of calls to qsmm_actor_shl_sig
followed by a call to qsmm_actor_reg_sig_in
.
Alternatively, obtain a pointer to the buffer by qsmm_get_actor_sig_ngram
, set the content of that buffer shifted one signal right, and call qsmm_actor_reg_sig_in
to shift the buffer one signal left with setting the rightmost signal of the current action choice state.
Use the following function to shift the buffer containing an n-gram of signals from the event history one signal left, append a signal to the buffer, and increment by 1 discrete time without updating information on action choice states.
This function shifts one signal left the content of the buffer in actor containing an n-gram of signals from the event history and appends signal sig_last to the end of that buffer.
The function increments by 1 discrete time tracked by the actor.
If sig_first_p is not NULL
, the function returns in *sig_first_p the leftmost signal in the buffer before the shift.
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, the function returns negative error code QSMM_ERR_INVAL
.
For example, if the buffer contained signals <3, 6, 2>, then after executing the lines
qsmm_sig_t sig_first=QSMM_SIG_INVALID; qsmm_actor_shl_sig(actor,4,&sig_first);
the buffer would contain signals <6, 2, 4>, and sig_first
would be equal to 3.
Use the following function to perform the operation opposite to the operation performed by the function qsmm_actor_shl_sig
.
This function shifts one signal right the content of the buffer in actor containing an n-gram of signals from the event history and prepends signal sig_first to the beginning of that buffer.
The function decrements by 1 discrete time tracked by the actor.
If sig_last_p is not NULL
, the function returns in *sig_last_p the rightmost signal in the buffer before the shift.
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, the function returns negative error code QSMM_ERR_INVAL
.
Use the following function to shift the buffer containing an n-gram of signals from the event history one signal left, append a signal to the buffer, and increment by 1 discrete time with updating statistics on a current action choice state.
This function shifts one signal left the content of the buffer in actor containing an n-gram of signals from the event history and appends signal sig to the end of that buffer. The resulting content of the buffer shall encode an action choice state. The function increments by 1 discrete time tracked by the actor.
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 two occurrences of the same action choice state. A cycle type is the pair comprised of that action choice state and an output signal emitted when that 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 current 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:
If the actor uses automatic spur, the function increments it by the logarithm of observed probability of that 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_sig_in
increments by 1 the total number of cycles processed and increments the total sum of discrete cycle periods.
The function qsmm_actor_reg_sig_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_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 content of the buffer and appending signal sig to its end, the buffer would 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_INFIN
The operation of computing the increment of automatic spur or the operation of increasing the sum of spur 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 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.
Note: you should call the function
qsmm_actor_reg_sig_in
for increasing values of discrete time tracked by the actor. Otherwise, that function might finish execution just after making the buffer encode an action choice state.
Use the following function to obtain direct access to the buffer.
This function returns the pointer to the buffer in actor containing an n-gram of signals from the event history.
That buffer is an array of signal identifiers with the number of elements 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 function qsmm_get_actor_sig_ngram
to temporarily replace the content of the buffer to calculate the probabilities of output signals for another action choice state.
For that, save the content in another array, replace the content with a signal list encoding another action choice state, calculate the probabilities of output signals for the action choice state by the function qsmm_actor_calc_action_prob
, and restore original content.
To obtain the number of output signals emitted by an actor, it multiplies discrete time by a parameter in the range 0 to 1 set by the function qsmm_set_actor_naction_per_evt
and retrieved by the function qsmm_get_actor_naction_per_evt
.
The default value of that parameter is 0.5.
Let us suppose that the field ngram_sz
of qsmm_actor_desc_s
structure passed to the function qsmm_actor_create
when creating an actor was equal to NGRAM_SZ
.
There are three common modes of setting a current action choice state for the actor.
qsmm_sig_t sig_ngram[NGRAM_SZ]
is an array of signal identifiers encoding an action choice state.
qsmm_actor_shl_sig
and qsmm_actor_reg_sig_in
.
The call qsmm_set_actor_naction_per_evt(actor,1.0/(NGRAM_SZ+1))
is necessary at the beginning if the function for computing the relative probability of an output signal depends on the number of output signals emitted by the actor.
In the general case, use a block of source code like this to set the action choice state as the current one:
int rc; for (int ii=0; ii<NGRAM_SZ-1; ii++) if ((rc=qsmm_actor_shl_sig(actor,sig_ngram[ii],0))<0) REPORT_ERROR(rc); if ((rc=qsmm_actor_reg_sig_in(actor,sig_ngram[NGRAM_SZ-1]))<0) REPORT_ERROR(rc);
If NGRAM_SZ
is equal to 1, this block of source code reduces to:
const int rc=qsmm_actor_reg_sig_in(actor,sig_ngram[0]); if (rc<0) REPORT_ERROR(rc);
If NGRAM_SZ
is equal to 2, the block reduces to:
int rc; if ((rc=qsmm_actor_shl_sig(actor,sig_ngram[0],0))<0) REPORT_ERROR(rc); if ((rc=qsmm_actor_reg_sig_in(actor,sig_ngram[1]))<0) REPORT_ERROR(rc);
qsmm_get_actor_sig_ngram
and qsmm_actor_reg_sig_in
.
In the general case, use a block of source code like this to set the action choice state as the current one:
memmove(qsmm_get_actor_sig_ngram(actor)+1, sig_ngram, (NGRAM_SZ-1)*sizeof(*sig_ngram)); const int rc=qsmm_actor_reg_sig_in(actor,sig_ngram[NGRAM_SZ-1]); if (rc<0) REPORT_ERROR(rc);
If NGRAM_SZ
is equal to 1, this block of source code reduces to:
const int rc=qsmm_actor_reg_sig_in(actor,sig_ngram[0]); if (rc<0) REPORT_ERROR(rc);
If NGRAM_SZ
is equal to 2, the block reduces to:
qsmm_get_actor_sig_ngram(actor)[1]=sig_ngram[0]; const int rc=qsmm_actor_reg_sig_in(actor,sig_ngram[1]); if (rc<0) REPORT_ERROR(rc);
qsmm_sig_t sig_ngram[NGRAM_SZ-1]
is an array of input signals.
We are not completely replacing buffer content with input signals—last signal emitted stored in the rightmost buffer element should become the leftmost buffer element.
If state0 is an output signal denoting the initial state of a finite automaton, the call qsmm_actor_shl_sig(actor,state0,0)
is necessary at the beginning.
qsmm_actor_shl_sig
and qsmm_actor_reg_sig_in
.
The call qsmm_set_actor_naction_per_evt(actor,1.0/NGRAM_SZ)
is also necessary at the beginning if the function for computing the relative probability of an output signal depends on the number of output signals emitted by the actor.
In the general case, use a block of source code like this to set the current action choice state:
for (int ii=0; ii<NGRAM_SZ-2; ii++) if ((rc=qsmm_actor_shl_sig(actor,sig_ngram[ii],0))<0) REPORT_ERROR(rc); if ((rc=qsmm_actor_reg_sig_in(actor,sig_ngram[NGRAM_SZ-2]))<0) REPORT_ERROR(rc);
If NGRAM_SZ
is equal to 2, this block of source code reduces to:
const int rc=qsmm_actor_reg_sig_in(actor,sig_ngram[0]); if (rc<0) REPORT_ERROR(rc);
If NGRAM_SZ
is equal to 3, the block reduces to:
int rc; if ((rc=qsmm_actor_shl_sig(actor,sig_ngram[0],0))<0) REPORT_ERROR(rc); if ((rc=qsmm_actor_reg_sig_in(actor,sig_ngram[1]))<0) REPORT_ERROR(rc);
qsmm_get_actor_sig_ngram
and qsmm_actor_reg_sig_in
.
In the general case, use a block of source code like this to set the current action choice state:
qsmm_sig_t *const sig_ngram_p=qsmm_get_actor_sig_ngram(actor); sig_ngram_p[1]=sig_ngram_p[NGRAM_SZ-1]; memmove(sig_ngram_p+2,sig_ngram,(NGRAM_SZ-2)*sizeof(*sig_ngram)); const int rc=qsmm_actor_reg_sig_in(actor,sig_ngram[NGRAM_SZ-2]); if (rc<0) REPORT_ERROR(rc);
If NGRAM_SZ
is equal to 2, this block of source code reduces to:
const int rc=qsmm_actor_reg_sig_in(actor,sig_ngram[0]); if (rc<0) REPORT_ERROR(rc);
If NGRAM_SZ
is equal to 3, the block reduces to:
qsmm_sig_t *const sig_ngram_p=qsmm_get_actor_sig_ngram(actor); sig_ngram_p[1]=sig_ngram_p[2]; sig_ngram_p[2]=sig_ngram[0]; const int rc=qsmm_actor_reg_sig_in(actor,sig_ngram[1]); if (rc<0) REPORT_ERROR(rc);
qsmm_actor_reg_sig_in(actor,sig_in)
.
This mode of setting a current action choice state may be inefficient.
Using the following functions, you can obtain the discrete cycle period of last cycle registered by the function qsmm_actor_reg_sig_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.
This function returns the discrete cycle period of last cycle registered for actor by the function qsmm_actor_reg_sig_in
.
A returned value is always non-negative.
If there was no call to the function qsmm_actor_reg_sig_in
yet, or at the last call that function did not register a cycle, the function qsmm_get_actor_discrete_cycle_period_last
returns 0.
This function returns the mean discrete cycle period of all cycles registered for actor by the function qsmm_actor_reg_sig_in
since creating the actor.
If qsmm_actor_reg_sig_in
has not registered a cycle yet, the function qsmm_get_actor_discrete_cycle_period_mean
returns 0.
This function returns only finite and non-negative values.
Next: Emitting an Output Signal, Previous: Incrementing Time, Up: Repeated Sequence of Operations [Contents][Index]