Next: , Previous: , Up: Repeated Sequence of Operations   [Contents][Index]


2.5.3 Receiving Input Signals

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.

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 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.

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 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.

Function: int qsmm_actor_reg_sig_in (qsmm_actor_t actor, qsmm_sig_t sig)

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.

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 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.

  1. Action choice states solely consist of input signals of the actor. Let us suppose that qsmm_sig_t sig_ngram[NGRAM_SZ] is an array of signal identifiers encoding an action choice state.
    1. Using the functions 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);
      
    2. Using the functions 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);
      
  2. Action choice states consist of last output signal emitted and input signals. Let us suppose that 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.

    1. Using the functions 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);
      
    2. Using the functions 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);
      
  3. Action choice states are n-grams of events from the event history; input and output signals interleave. If sig_in is an input signal, append it to the current action choice state n-gram and shift it by the call 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.

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_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.

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 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: , Previous: , Up: Repeated Sequence of Operations   [Contents][Index]