Next: Repeated Sequence of Operations, Previous: Small and Large Actors, Up: Adaptive Probabilistic Mapping [Contents][Index]
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.
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 the 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.
QSMM_ERR_BIGMDLA non-NULL field large_desc_p in *desc_p specified to create a large actor, but its multinode model would be too complex.
See Creating the Model Instance, for a description of QSMM_ERR_BIGMDL error the function qsmm_engine_create can report on creating a multinode model instance thereby causing the function qsmm_actor_create to return this error code.
This function destroys an actor specified by handle actor.
You must not use the actor handle after the actor destruction.
If actor is NULL, the function has no effect.
Below there are a description of a structure passed in *desc_p to the function qsmm_actor_create and descriptions of a related datatype, a union, and enclosed structures.
This structure describes parameters for creating an actor by the function qsmm_actor_create.
The structure contains the following fields.
A flag specifying the type of storage the actor will use for collecting statistics on the event history.
If this field is non-zero, and the field large_desc_p is NULL, then the actor will use flat storage.
If this field is non-zero, and the field large_desc_p is non-NULL, then the function qsmm_actor_create will report QSMM_ERR_INVAL.
If this field is zero, then the actor will use map storage.
Flat storage is preallocated storage presumably of large size but with fast access to data elements. Map storage is dynamically allocated storage presumably of smaller size but with slower access to data elements; map storage uses sorted maps for backing storage. See Storage Types, for additional information on statistics storage types.
The number of spur types the actor will use.
That number must be greater than 0.
If the actor is the large one, then a small actor associated with the large actor will use 1+nspur spur types, where an implicitly added spur type with the lowest index corresponds to the automatic spur of the small actor.
See Automatic Spur, for more information on that spur.
The length of a list of signal identifiers encoding an action choice state. That length must be greater than 0. The longer the list is the more events in the event history the actor typically needs for training.
Non-negative size of the pool of probabilities lists in normal form.
The function qsmm_actor_profile_add adds a unique probabilities list in normal form to that pool.
The function qsmm_set_actor_ngram_profile sets the added probabilities list for a particular action choice state n-gram.
For a small actor, the size of the pool of probabilities lists in normal form is the maximum number of unique sorted lists of normalized output signal weights (profile probabilities) the actor can store in its memory.
For a large actor, that size is the maximum number of Huffman trees of unique structure the actor can store in its memory, not counting an automatically created default Huffman tree corresponding to the case when the weights of all output signals are equal. To determine whether or not a Huffman tree is unique, the actor creates a temporary Huffman tree to compare the probabilities of its leaves with the probabilities of leaves of previously stored Huffman trees. That is why the value of this field should generally be greater by 1 than the number of Huffman trees of unique structure required to represent the sorted lists of output signal weights.
The compatibility level of algorithms used by the actor. That level must be 0, 1, or 2. Value 0 means to use original algorithms implemented before QSMM 1.15. Value 1 means to use enhanced algorithms:
qsmm_get_actor_naction_per_evt and, if the relative probability function type is QSMM_RELPROB_BUILTIN1, by 2.
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.
Set this field to 2 in your new programs. This manual does not include outdated details specific to the original algorithms.
Maximum fill ratio for sparse vectors holding the relative probabilities of output signals. The actor chooses whether to use sparse vectors or ordinary vectors based on this ratio. It must be a number in the range 0 to 1 inclusive. Value 0 indicates that the actor must always use ordinary vectors. Value 1 indicates that the actor must always use sparse vectors. A value between 0 and 1 indicates the maximum percentage (divided by 100) of non-zero elements in sparse vectors relative to the numbers of vector dimensions.
Note: when creating a large actor (the field
large_desc_pis notNULLin this case), forgetting to set the fieldsparse_fill_maxto a positive value, for example, 0.2 or 1, will cause bad actor performance.
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.
The type of a specification of the number and directions of signals used by the actor. Here “signal direction” means whether a signal is input one, output one, or belongs to both types.
Value QSMM_ACTOR_SIG_SPEC_IN_OUT indicates that the field sig_spec of this structure specifies the number of input signals and the number of output signals.
Value QSMM_ACTOR_SIG_SPEC_MASK indicates that the field sig_spec of this structure specifies the total number of signals and a mask describing the directions of those signals.
A specification of the number and directions of signals used by the actor.
If the field sig_spec_type of this structure has value QSMM_ACTOR_SIG_SPEC_IN_OUT, then sig_spec.in_out must contain the specification.
If the field sig_spec_type of this structure has value QSMM_ACTOR_SIG_SPEC_MASK, then sig_spec.mask must contain the specification.
The ranges of signal identifiers in a list encoding an action choice state.
The field ngram_sz of this structure specifies the length of this list.
The actor uses those ranges to check the validity of a list of signal identifiers encoding a current action choice state in various API functions, to reduce the memory footprint of flat storage if a small actor uses this type of storage, and to reduce the number of nodes in the multinode model of a large actor.
There can be other uses for the ranges in future QSMM versions.
Specify the ranges as precisely as possible to reduce the memory footprint of the actor.
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.
Those elements correspond to the 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 total number of signals of the actor specified using the fields sig_spec_type and sig_spec 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 total number (exclusive) of signals of the actor.
The parameters of a large actor.
A non-NULL value of this field indicates to create a large actor.
To improve compatibility with future versions of QSMM library, zero by the function memset an instance of qsmm_actor_desc_s structure before setting the fields of this instance passed to the function qsmm_actor_create.
This enumeration defines a method of specification of the number and directions of signals of an actor in the field sig_spec of qsmm_actor_desc_s structure.
The enumeration contains the following elements.
QSMM_ACTOR_SIG_SPEC_IN_OUTThe actor has a specified number of input signals and a specified number of output signals.
A segment of output signal identifiers follows a segment of input signal identifiers.
For example, if the actor has 6 input signals and 4 output signals, then signals 0, 1, 2, 3, 4, 5 will be input ones, and signals 6, 7, 8, 9 will be output ones.
The field sig_spec.in_out of qsmm_actor_desc_s structure should contain the number of input and output signals.
QSMM_ACTOR_SIG_SPEC_MASKThe actor has a specified total number of signals.
Every signal can be input one.
A mask specifies a subset of output signals among those signals.
The field sig_spec.mask of qsmm_actor_desc_s structure should contain the total number of signals and the mask.
This union describes in two possible forms the number and directions of signals of an actor.
The field sig_spec of qsmm_actor_desc_s structure holds that information.
The union contains the following fields.
The number of input signals and the number of output signals.
The field sig_spec_type of qsmm_actor_desc_s structure should be equal to QSMM_ACTOR_SIG_SPEC_IN_OUT.
The total number of signals and a subset of output signals.
The field sig_spec_type of qsmm_actor_desc_s structure should be equal to QSMM_ACTOR_SIG_SPEC_MASK.
This structure specifies the number of input signals and the number of output signals of an actor. The structure contains the following fields.
The number of input signals of the actor. That number must be greater than 0.
The number of output signals of the actor. That number must be greater than 1.
The sum of values in the fields nsig_in and nsig_out must be less than or equal to QSMM_SIG_MAX+1.
This structure specifies the total number of signals and a subset of output signals of an actor. The structure contains the following fields.
If this field is NULL, then all actor signals will be output ones; some or all of those signals can be input ones.
If this field is not NULL, then the field must contain the pointer to an array of nsig (see the next field) elements.
A zero element indicates that a signal with the identifier equal to an element index is an input signal.
A non-zero element indicates that a signal with the identifier equal to an element index is an output signal and possibly input one.
The array must contain at least two non-zero elements.
The function qsmm_actor_create copies the array to an internal structure of the actor.
The total number of signals of the actor.
That number must be greater than 1 and less than or equal to QSMM_SIG_MAX+1.
This structure holds a pair of signals, for example, a signal range. The structure contains the following fields.
The first element of the pair. If the pair represents a signal range, then the minimum value of a signal identifier.
The second element of the pair. If the pair represents a signal range, then the maximum value of a signal identifier.
This structure specifies the parameters of a large actor. The structure contains only one field but is a structure to simplify adding new parameters in future QSMM versions.
The maximum number of child nodes of every node of Huffman 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.
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 the value of tree_arity field of this instance passed via the field large_desc_p of qsmm_actor_desc_s structure to the function qsmm_actor_create.
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.ngram_sz=3;
actor_desc.compat=2;
actor_desc.sig_spec_type=QSMM_ACTOR_SIG_SPEC_IN_OUT;
struct qsmm_actor_sig_spec_in_out_s *const io_p=
&actor_desc.sig_spec.in_out;
io_p->nsig_in=6;
io_p->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.ngram_sz=3;
actor_desc.compat=2;
actor_desc.sparse_fill_max=1;
actor_desc.sig_spec_type=QSMM_ACTOR_SIG_SPEC_IN_OUT;
struct qsmm_actor_sig_spec_in_out_s *const io_p=
&actor_desc.sig_spec.in_out;
io_p->nsig_in=6;
io_p->nsig_out=4096;
struct qsmm_pair_sig_s range_sig[3];
memset(&range_sig,0,sizeof(range_sig));
range_sig[0].second=5;
range_sig[1].second=5;
range_sig[2].second=5;
actor_desc.range_sig_p=range_sig;
// action choice state consists only of input signals of the actor
struct qsmm_actor_large_desc_s large_desc;
memset(&large_desc,0,sizeof(large_desc));
large_desc.tree_arity=2;
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 parameters specified when creating an actor later by the following functions.
This function returns a positive 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.
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.
This function returns a non-negative integer number equal to the size of the pool of probabilities lists in normal form of actor.
The field profile_pool_sz of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the actor specifies that size.
This function returns a non-negative integer number equal to the compatibility level 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 that level.
This function returns a positive integer equal to the total number of signals of actor.
If the field sig_spec_type of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the actor is equal to QSMM_ACTOR_SIG_SPEC_IN_OUT, the total number of signals is the sum of sig_spec.in_out.nsig_in and sig_spec.in_out.nsig_out fields of qsmm_actor_desc_s structure.
If the field sig_spec_type is equal to QSMM_ACTOR_SIG_SPEC_MASK, the total number of signals is the field sig_spec.mask.nsig of qsmm_actor_desc_s structure.
This function returns a positive integer equal to the number of output signals of actor.
If the field sig_spec_type of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the actor is equal to QSMM_ACTOR_SIG_SPEC_IN_OUT, the number of output signals is the field sig_spec.in_out.nsig_out of qsmm_actor_desc_s structure.
If the field sig_spec_type is equal to QSMM_ACTOR_SIG_SPEC_MASK, the number of output signals is the number of non-zero elements in the array sig_spec.mask.is_sig_out_p in the structure qsmm_actor_desc_s.
This function returns maximum fill ratio for sparse vectors holding the relative probabilities of output signals.
An actor chooses whether to use sparse vectors or ordinary vectors based on this ratio.
The field sparse_fill_max of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the actor specifies this ratio.
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 this 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.
You can obtain the handle of statistics storage of an actor by the following function.
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 that statistics.
Huffman trees within the multinode model of that large actor hold the other part of that statistics.
This 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.
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.
Next: Repeated Sequence of Operations, Previous: Small and Large Actors, Up: Adaptive Probabilistic Mapping [Contents][Index]