An actor handle refers to a small or large actor.
This is a type for an actor handle.
It is a pointer, so variables of this type can be NULL.
The function qsmm_actor_create creates a new actor and returns its handle.
The function qsmm_actor_destroy destroys an existing actor addressed by a handle.
You can pass an actor handle to API functions taking an argument of qsmm_actor_t type after the creation of an actor and until its destruction.
Use the following functions to create and destroy an actor.
int qsmm_actor_create (const struct qsmm_actor_desc_s *desc_p, qsmm_actor_t *actor_p) ¶This function creates an actor using parameters in *desc_p and stores an actor handle in *actor_p.
If actor_p is NULL, the function only validates parameters in *desc_p.
The function returns a non-negative value on success or a negative error code on failure in creating an actor. Currently, the function can return the following error codes.
QSMM_ERR_INVALParameters in *desc_p are invalid.
QSMM_ERR_NOMEMThere was not enough memory to create an actor.
void qsmm_actor_destroy (qsmm_actor_t actor) ¶This function destroys an actor specified by handle actor.
You must not use the actor handle after actor destruction.
If actor is NULL, the function has no effect.
Below there are the description of a structure passed in *desc_p to the function qsmm_actor_create and the description of enclosed structures.
This structure describes parameters for creating an actor by the function qsmm_actor_create.
The structure contains the following fields.
int nspur ¶A non-negative number of spur types the actor will use. If the actor is the large one, a small actor associated with it will use the same number of spur types.
int ntime ¶[New in QSMM 1.19] A non-negative number of continuous time types the actor will use.
If the actor is the large one, a small actor associated with it will use the same number of continuous time types.
The function qsmm_set_actor_spur_time sets up a correspondence between spur types and time types.
int ngram_sz ¶The length of a list of signal identifiers encoding an action choice state. That length must be greater than 0.
int compat ¶The compatibility of algorithms used by the actor: 0, 1, 2, or 3. Value 0 means to use original algorithms implemented before QSMM 1.15. Value 1 supported since QSMM 1.15 means to use enhanced algorithms:
QSMM_RELPROB_BUILTIN1, by 2.
[New in QSMM 1.17] Value 2 further improves the algorithms:
QSMM_PROB_FQ type by the function qsmm_actor_calc_action_prob based on exact (not sometimes decremented by 1) frequencies of output signals in the event history;
qsmm_get_actor_sig_action select a signal without using a random number generator (i.e. deterministically) if the signal is the only one signal with a positive relative probability.
[New in QSMM 1.19] Value 3 means:
ntime of qsmm_actor_desc_s structure specifies their number when creating the actor by the function qsmm_actor_create;
the actor does not use the field period_sum_c of qsmm_cycle_s structure and the field tmc0 of qsmm_state_s structure;
qsmm_actor_create called for a small actor initializes to 1 (instead of 0.5) the multiplier for converting discrete time to the number of output signals emitted.
Creating a large actor requires setting this field to 3.
The function qsmm_actor_create sets the field compat of qsmm_desc_s structure to 3 when creating a multinode model for a large actor.
Set this field to 3 in your new programs. This manual does not include outdated details about old algorithms.
qsmm_sig_t nsig_in ¶The number of input signals. Input signal identifiers are in the range 0 (inclusive) to that number (exclusive). This field must be greater than 0.
qsmm_sig_t nsig_out ¶Initial number of output signals. Output signal identifiers are in the range 0 (inclusive) to that number (exclusive). This field must be greater than 1. See Number of Output Signals, for how to obtain the current number of output signals of an actor or increase that number.
qsmm_rng_t rng ¶The handle of a random number generator the actor will use.
See Random Number Generators, for how to create and destroy random number generators and perform other operations on them.
If this field is NULL, the function qsmm_actor_create creates an instance of default random number generator for use by the actor until its destruction.
struct qsmm_pair_sig_s * range_sig_p ¶Ranges of signal identifiers in a list encoding an action choice state.
The field ngram_sz of this structure specifies the length of the list.
The actor uses the ranges to check the validity of a list of signal identifiers encoding a current action choice state in various API functions.
If the field range_sig_p is not NULL, then this field must be the pointer to an array of ngram_sz elements, where each element is a pair.
The elements correspond to positions of signal identifiers in a list encoding an action choice state.
The fields first and second of each pair define the minimum value and the maximum value of a corresponding signal identifier.
The value of first must be less than or equal to the value of second.
The value of second must be less than the number of input signals of the actor specified in the field nsig_in of this structure.
If range_sig_p is NULL, this condition means that every signal in the list lies in the range 0 (inclusive) to the number (exclusive) of input signals of the actor.
struct qsmm_actor_large_desc_s * large_desc_p ¶The parameters of a large actor.
A non-NULL value of this field means to create a large actor.
This mode requires setting the field compat to 3.
To improve compatibility with future versions of QSMM library, zero by the function memset an instance of qsmm_actor_desc_s structure before setting its fields.
This structure holds a pair of signals, for example, a signal range. The structure contains the following fields.
qsmm_sig_t first ¶The first element of the pair. If the pair represents a signal range, the minimum value of a signal identifier.
qsmm_sig_t second ¶The second element of the pair. If the pair represents a signal range, the maximum value of a signal identifier.
This structure specifies the parameters of a large actor.
int tree_arity ¶The maximum number of child nodes of every node of output signal choice trees for adaptive selection of output signals by the large actor. That number must be greater than 1. You can use value 2 in most cases. It is better to use the number of output signals of a large actor equal to a positive integer power of the value of this field.
double profile_tol ¶[New in QSMM 1.19] An upper bound on absolute value of difference between the profile probability of each output signal and its probability determined by the structure of an output signal choice tree.
The large actor rearranges a Huffman tree built for an action choice state by splitting leaf nodes and making multiple leaf nodes correspond to the same output signals until the absolute value becomes less than the upper bound.
The field must be 0 or lie in the range FLT_EPSILON to 1.
If the field is 0, the actor does not rearrange Huffman trees built for action choice states.
To improve compatibility with future versions of QSMM library, zero by the function memset an instance of qsmm_actor_large_desc_s structure before setting its fields.
Below there is sample source code for creating a small actor.
struct qsmm_actor_desc_s actor_desc; memset(&actor_desc,0,sizeof(actor_desc)); actor_desc.nspur=1; actor_desc.ntime=1; actor_desc.ngram_sz=3; actor_desc.compat=3; actor_desc.nsig_in=6; actor_desc.nsig_out=4; qsmm_actor_t actor=0; const int rc=qsmm_actor_create(&actor_desc,&actor); if (rc<0) fprintf(stderr,"qsmm_actor_create: %s\n",qsmm_err_str(rc));
Below there is sample source code for creating a large actor.
struct qsmm_actor_desc_s actor_desc; memset(&actor_desc,0,sizeof(actor_desc)); actor_desc.nspur=1; actor_desc.ntime=1; actor_desc.ngram_sz=3; actor_desc.compat=3; actor_desc.nsig_in=6; actor_desc.nsig_out=4096; struct qsmm_actor_large_desc_s large_desc; memset(&large_desc,0,sizeof(large_desc)); large_desc.tree_arity=2; large_desc.profile_tol=0.005; actor_desc.large_desc_p=&large_desc; qsmm_actor_t actor=0;
const int rc=qsmm_actor_create(&actor_desc,&actor); if (rc<0) fprintf(stderr,"qsmm_actor_create: %s\n",qsmm_err_str(rc));
You can obtain some parameters specified when creating an actor by the following functions.
int qsmm_get_actor_nspur (qsmm_actor_t actor) ¶This function returns a non-negative integer equal to the number of spur types used by actor.
The field nspur of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the actor specifies that number.
int qsmm_get_actor_ntime (qsmm_actor_t actor) ¶This function returns a non-negative integer equal to the number of continuous time types used by actor.
The field ntime of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the actor specifies that number.
int qsmm_get_actor_ngram_sz (qsmm_actor_t actor) ¶This function returns a positive integer number equal to the length of a list of signal identifiers encoding an action choice state of actor.
The field ngram_sz of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the actor specifies that length.
int qsmm_get_actor_compat (qsmm_actor_t actor) ¶This function returns a non-negative integer number indicating the compatibility of algorithms used by actor.
The field compat of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the actor specifies the number.
qsmm_sig_t qsmm_get_actor_nsig_in (qsmm_actor_t actor) ¶This function returns the number of input signals of actor.
The field nsig_in of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the actor specifies that number.
const struct qsmm_pair_sig_s * qsmm_get_actor_range_sig (qsmm_actor_t actor) ¶This function returns the pointer to an array in an internal structure of an actor describing allowed ranges of signal identifiers in lists encoding its action choice states.
The field range_sig_p of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the actor specifies the content of the array.
The number of elements in the array is equal to the length of a list of signal identifiers encoding an action choice state.
The function qsmm_get_actor_ngram_sz returns that length.
The function qsmm_get_actor_range_sig never returns NULL.
A datatype for the handle of statistics storage is qsmm_storage_t.
See Statistics Storage, for more information.
You can obtain the handle of statistics storage of an actor by the following function.
qsmm_storage_t qsmm_get_actor_storage (qsmm_actor_t actor) ¶This function returns the handle of storage used by actor for collecting statistics on the event history.
If the actor is the large one, the storage contains only part of the statistics.
Output signal choice trees within the multinode model of the large actor hold the other part of the statistics.
The function never returns NULL.
A datatype for the multinode model of a large actor is qsmm_t.
You can obtain the handle of the multinode model of an actor by the following function.
qsmm_t qsmm_get_actor_large_model (qsmm_actor_t actor) ¶This function returns the handle of a multinode model used by a large actor to adaptively emit output signals.
If actor is a large actor, the function returns a non-NULL handle.
If actor is a small actor, the function returns NULL.
You can use this function to determine whether an actor is large or small one.