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


2.3 Creating an Actor

A small or a large actor is referred to by an actor handle.

Data type: qsmm_actor_t

This is a type for an actor handle. It is a pointer, so variables of this type can have the NULL value. The function qsmm_actor_create allocates a new actor handle. The function qsmm_actor_destroy frees an existing actor handle. After allocating an actor handle, it can be passed to API functions that take an argument of type qsmm_actor_t until the handle is freed.

To create and destroy an actor, the following functions can be used.

Function: int qsmm_actor_create (const struct qsmm_actor_desc_s *desc_p, qsmm_actor_t *actor_p)

This function creates an actor using parameters specified in *desc_p and stores a newly allocated actor handle in *actor_p.

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

QSMM_ERR_INVAL

Either argument actor_p is NULL or parameters specified in *desc_p are invalid.

QSMM_ERR_NOMEM

There was not enough memory to create an actor.

QSMM_ERR_BIGMDL

A large actor is to be created, but a multinode model, which shall provide operation of the actor, is too complicated. See Creating the Model Instance, for a description of error QSMM_ERR_BIGMDL which can be raised by the function qsmm_engine_create when creating the multinode model instance and which causes the function qsmm_actor_create to return this error code.

Function: void qsmm_actor_destroy (qsmm_actor_t actor)

This function destroys an actor specified by handle actor. After actor destruction, the actor handle must not be used. If actor is NULL, then the function will have no effect.

A structure, a pointer to which is an argument of function qsmm_actor_create, along with an associated datatype, a union, and enclosed structures is described below.

Structure: qsmm_actor_desc_s

This structure describes parameters for creating an actor. It contains the following fields.

Field: char use_flat_storage

A flag that specifies whether the actor should use flat storage or map storage for collecting statistics on the event history. If the value of this field is non-zero and the value of field large_desc_p is zero, then flat storage will be used. If the value of this field is non-zero and the value of field large_desc_p is non-zero, then error QSMM_ERR_INVAL will be reported. If the value of this field is zero, then map storage will be used.

Flat storage is a preallocated storage presumably of big size, but with quick access to data elements. Map storage is a dynamically allocated storage presumably of lesser size, but with slower access to data elements; binary trees are used for backing storage. See Types of Storage, for additional information on statistics storage types.

Field: int nspur

The number of spur types used by the actor. Must be greater than 0. If the actor is the large one, then a small actor, which is 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.

Field: int ngram_sz

The length of a list of signal identifiers, which defines an action choice state. Must be greater than 0. The longer the list is the more events in the event history are typically needed to train the actor.

Field: int profile_pool_sz

A non-negative size of the pool of probabilities lists in normal form that could be prepared and then set for particular action choice state n-grams. For a small actor, it is the maximum number of unique sorted lists of output signal probabilities, which could be stored in the actor’s memory. For a large actor, it is the maximum number of Huffman trees of unique structure, which could be stored in the actor’s memory (not counting an automatically created default Huffman tree that corresponds to case when profile probabilities of all output signals are equal). To determine whether a Huffman tree has to be reused, a temporary Huffman tree could be created, which 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 sorted lists of output signal probabilities.

Field: int compat

The compatibility level of algorithms used by the actor. Must be 0 or 1. Value 0 means to use original algorithms that were implemented in QSMM before version 1.15. Value 1 means to use enhanced algorithms:

  • – use a simpler formula for automatic spur increment;
  • – in a formula, which gives a relative probability of output signal choice, additionally multiply the mean discrete cycle period by a value returned by the function qsmm_get_actor_naction_per_evt and possibly by 2.

Setting a value of this field to 1 is recommended for your new programs. This manual does not include outdated details specific to the original algorithms.

Field: double sparse_fill_max

The maximum fill ratio for vectors that hold relative probabilities of output signals choice, on the basis of which the actor decides when to use sparse vectors instead of ordinary vectors. Must be a number between 0 and 1 (inclusive). Value 0 indicates that the actor must always use ordinary vectors. Value 1 indicates that the actor must always use sparse vectors. Values between 0 and 1 indicate the maximum percentage (divided by 100) of non-zero elements in sparse vectors relative to the number of vector dimensions.

Note: when a large actor is created (i.e. the field large_desc_p has a non-zero value), forgetting to set the field sparse_fill_max to a positive value, e.g. to 0.2, will cause bad actor performance.

Field: qsmm_rng_t rng

The handle of a random number generator to be used by the actor. See Random Number Generators, for information on how to create, destroy random number generators, and perform other operations on them. Can be 0, in which case an instance of default random number generator is automatically created for use by the actor and destroyed upon actor destruction.

Field: enum qsmm_actor_sig_spec_e sig_spec_type

The type of 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 means that the number of input signals and the number of output signals are specified in the field sig_spec of this structure.

Value QSMM_ACTOR_SIG_SPEC_MASK means that the total number of signals and a mask, which describes directions of those signals, are specified in the field sig_spec of this structure.

Field: union qsmm_actor_sig_spec_u sig_spec

A specification of the number and direction of signals used by the actor.

If the field sig_spec_type of this structure has value QSMM_ACTOR_SIG_SPEC_IN_OUT, then the specification of the number and direction of signals must be stored in sig_spec.in_out.

If the field sig_spec_type of this structure has value QSMM_ACTOR_SIG_SPEC_MASK, then the specification of the number and direction of signals must be stored in sig_spec.mask.

Field: struct qsmm_pair_sig_s * range_sig_p

Ranges of signal identifiers in a list that defines an action choice state. Those ranges are used to check the validity of a list of signal identifiers, which defines current action choice state, in various Actor API functions, to reduce the memory footprint of flat storage if a small actor uses such storage, and to reduce the number of nodes in a multinode model that corresponds to a large actor. In future versions of the package, the ranges can be used for other purposes. To reduce the memory footprint of the actor, it is recommended to specify the ranges as precisely as possible.

If this field is not NULL, then it must be the pointer to an array of ngram_sz elements, where each element is a pair. Those elements correspond to signal identifiers in a list that defines an action choice state. The fields first and second of each pair define the minimum value and the maximum value of the 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 the field range_sig_p is NULL, then it will be assumed that every signal in the list lies in the range 0 (inclusive) to the total number (exclusive) of signals of the actor.

Field: struct qsmm_actor_large_desc_s * large_desc_p

Parameters of large actor. A non-zero value of this field indicates to create a large actor.

To improve compatibility with future versions of the library, an instance of structure qsmm_actor_desc_s, a pointer to which is passed to the function qsmm_actor_create, should be zeroed using the function memset before setting values of structure fields.

Enumeration: qsmm_actor_sig_spec_e

This enumeration specifies how the number and direction of signals of an actor are stored in the field sig_spec of structure qsmm_actor_desc_s. The enumeration contains the following elements.

QSMM_ACTOR_SIG_SPEC_IN_OUT

The actor has specified number of input signals and 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 numbers of input and output signals should be stored in the field sig_spec.in_out of structure qsmm_actor_desc_s.

QSMM_ACTOR_SIG_SPEC_MASK

The actor has specified total number of signals. Every signal can be input one. A mask is given that describes which of those signals are also output ones. The total number of signals and the mask should be stored in the field sig_spec.mask of structure qsmm_actor_desc_s.

Union: qsmm_actor_sig_spec_u

This union describes in two possible forms the number and direction of signals of an actor. The field sig_spec of structure qsmm_actor_desc_s holds that information. The union contains the following fields.

Field: struct qsmm_actor_sig_spec_in_out_s in_out

The number of input signals and the number of output signals. This field is used when the field sig_spec_type of structure qsmm_actor_desc_s has the value QSMM_ACTOR_SIG_SPEC_IN_OUT.

Field: struct qsmm_actor_sig_spec_mask_s mask

The total number of signals and a subset of output signals. This field is used when the field sig_spec_type of structure qsmm_actor_desc_s has the value QSMM_ACTOR_SIG_SPEC_MASK.

Structure: qsmm_actor_sig_spec_in_out_s

This structure specifies the number of input signals and the number of output signals of an actor. It contains the following fields.

Field: int nsig_in

The number of input signals of the actor. Must be greater than 0.

Field: int nsig_out

The number of output signals of the actor. 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.

Structure: qsmm_actor_sig_spec_mask_s

This structure specifies the total number of signals and a subset of output signals of an actor. It contains the following fields.

Field: char * is_sig_ctrl_p

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 it must contain the pointer to an array that holds nsig (see the next field) elements. A zero element indicates that a signal with a corresponding identifier is an input signal. A non-zero element indicates that a signal with a corresponding identifier is an output signal and possibly input one. The array must contain at least two non-zero elements. When creating an actor, the array is copied to an internal structure of the actor.

Field: int nsig

The total number of signals of the actor. Must be greater than 1 and less than or equal to QSMM_SIG_MAX+1.

Structure: qsmm_pair_sig_s

This structure represents a pair of signals, e.g. a signal range. It contains the following fields.

Field: qsmm_sig_t first

The first element of the pair. If the pair represents a range of signals, then the minimum value of signal identifier.

Field: qsmm_sig_t second

The second element of the pair. If the pair represents a range of signals, then the maximum value of signal identifier.

Structure: qsmm_actor_large_desc_s

This structure specifies parameters of large actor. It contains only one field, but is designed as a structure to simplify adding new parameters of large actor in future versions of the package.

Field: int tree_arity

The maximum number of child nodes of every node of Huffman trees used for stochastic selection of optimal output signals by the large actor. Must be greater than 1. You can use value 2 in most cases. It is better to use the number of output signals of large actor equal to positive integer powers of the value of this field.

To improve compatibility with future versions of the library, an instance of structure qsmm_actor_large_desc_s (a pointer to which is assigned to the field large_desc_p of structure qsmm_actor_desc_s) should be zeroed using the function memset before setting the value of field tree_arity.

Below is sample code for creating a small actor.

int rc;
qsmm_actor_t actor=0;
struct qsmm_actor_desc_s actor_desc;
struct qsmm_actor_sig_spec_in_out_s *spec_in_out_p;
memset(&actor_desc,0,sizeof(actor_desc));
actor_desc.nspur=1;
actor_desc.ngram_sz=3;
actor_desc.compat=1;
actor_desc.sig_spec_type=QSMM_ACTOR_SIG_SPEC_IN_OUT;
spec_in_out_p=&actor_desc.sig_spec.in_out;
spec_in_out_p->nsig_in=6;
spec_in_out_p->nsig_out=4;
if ((rc=qsmm_actor_create(&actor_desc,&actor))<0)
    fprintf(stderr,"qsmm_actor_create: %s\n",qsmm_err_str(rc));

Below is sample code for creating a large actor.

int rc;
qsmm_actor_t actor=0;
struct qsmm_pair_sig_s range_sig[3];
struct qsmm_actor_desc_s actor_desc;
struct qsmm_actor_large_desc_s large_desc;
struct qsmm_actor_sig_spec_in_out_s *spec_in_out_p;
memset(&range_sig,0,sizeof(range_sig));
range_sig[0].second=5;
range_sig[1].second=5;
range_sig[2].second=5;
memset(&large_desc,0,sizeof(large_desc));
large_desc.tree_arity=2;
memset(&actor_desc,0,sizeof(actor_desc));
actor_desc.nspur=1;
actor_desc.ngram_sz=3;
actor_desc.compat=1;
actor_desc.sparse_fill_max=0.2;
actor_desc.sig_spec_type=QSMM_ACTOR_SIG_SPEC_IN_OUT;
spec_in_out_p=&actor_desc.sig_spec.in_out;
spec_in_out_p->nsig_in=6;
spec_in_out_p->nsig_out=4096;
actor_desc.range_sig_p=range_sig;
    // signal list, which defines an action choice state, is assumed to
    // consist only of input signals of the actor
actor_desc.large_desc_p=&large_desc;
if ((rc=qsmm_actor_create(&actor_desc,&actor))<0)
    fprintf(stderr,"qsmm_actor_create: %s\n",qsmm_err_str(rc));

Parameters specified when creating an actor can be obtained later using the following functions.

Function: int qsmm_get_actor_nspur (qsmm_actor_t actor)

This function returns a positive integer equal to the number of spur types used by actor, which is specified in the field nspur of structure qsmm_actor_desc_s when creating the actor by the function qsmm_actor_create.

Function: 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, which defines an action choice state of an actor. It is the length, which is specified in the field ngram_sz of structure qsmm_actor_desc_s when creating the actor using the function qsmm_actor_create.

Function: int qsmm_get_actor_profile_pool_sz (qsmm_actor_t actor)

This function returns a non-negative integer number equal to the size of the pool of probabilities lists in normal form of actor. It is the size, which is specified in the field profile_pool_sz of structure qsmm_actor_desc_s when creating the actor using the function qsmm_actor_create.

Function: int qsmm_get_actor_compat (qsmm_actor_t actor)

This function returns a non-negative integer number equal to a compatibility level of algorithms used by actor, which is specified in the field compat of structure qsmm_actor_desc_s when creating the actor by the function qsmm_actor_create.

Function: int qsmm_get_actor_nsig (qsmm_actor_t actor)

This function returns a positive integer equal to the total number of signals of actor.

If the value of field sig_spec_type of structure qsmm_actor_desc_s passed to the function qsmm_actor_create when creating the actor is equal to QSMM_ACTOR_SIG_SPEC_IN_OUT, then the total number of signals will be the sum of values of fields nsig_in and nsig_out of structure qsmm_actor_sig_spec_in_out_s specified in the field sig_spec.in_out of structure qsmm_actor_desc_s.

If the value of field sig_spec_type is equal to QSMM_ACTOR_SIG_SPEC_MASK, then the total number of signals will be the value of field sig_spec.mask.nsig of structure qsmm_actor_desc_s.

Function: int qsmm_get_actor_nsig_out (qsmm_actor_t actor)

This function returns a positive integer equal to the number of output signals of actor.

If the value of field sig_spec_type of structure qsmm_actor_desc_s passed to the function qsmm_actor_create when creating the actor is equal to QSMM_ACTOR_SIG_SPEC_IN_OUT, then the number of output signals will be the value of field sig_spec.in_out.nsig_out of structure qsmm_actor_desc_s.

If the value of field sig_spec_type is equal to QSMM_ACTOR_SIG_SPEC_MASK, then the number of output signals will be the number of non-zero elements in an array addressed by the field sig_spec.mask.is_sig_ctrl_p of structure qsmm_actor_desc_s.

Function: double qsmm_get_actor_sparse_fill_max (qsmm_actor_t actor)

This function returns the maximum fill ratio for vectors that hold relative probabilities of output signals choice, on the basis of which actor decides when to use sparse vectors instead of ordinary vectors. It is a value, which is specified in the field sparse_fill_max of structure qsmm_actor_desc_s when creating the actor using the function qsmm_actor_create.

Function: const struct qsmm_pair_sig_s * qsmm_get_actor_range_sig (qsmm_actor_t actor)

This function returns the pointer to an array (stored in an internal structure of an actor) that describes allowed ranges of signal identifiers in action choice states. The content of the array is specified using the field range_sig_p of structure qsmm_actor_desc_s when creating the actor by the function qsmm_actor_create. The number of elements in the array is equal to the length of a signal list that defines an action choice state. That length can be retrieved by the function qsmm_get_actor_ngram_sz.

A datatype, which represents a statistics storage handle, is qsmm_storage_t. The handle of statistics storage of an actor can be obtained using the following function.

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, then the storage will hold only part of the statistics. Other part of the statistics will be stored in Huffman trees created within a multinode model that corresponds to the large actor. This function never returns NULL.

A datatype, which represents a multinode model that corresponds to a large actor, is qsmm_t. The handle of a multinode model of an actor can be obtained using the following function.

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 stochastically generate optimal output signals. If an actor is not large one, then 0 will be returned. This function can be used to determine whether an actor is large one, in which case the function always returns a non-zero value.


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