Next: , Previous: , Up: Multinode Model   [Contents][Index]


4.2 Creating a Multinode Model

A multinode model is referred to by a model handle.

Data type: qsmm_t

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

To create and destroy a multinode model, the following functions can be used.

Function: int qsmm_create (const struct qsmm_desc_s *desc_p, qsmm_t *model_p)

This function creates a multinode model using parameters specified in *desc_p and stores a newly allocated model handle in *model_p.

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

QSMM_ERR_INVAL

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

QSMM_ERR_NOMEM

There was not enough memory to create a multinode model.

Function: void qsmm_destroy (qsmm_t model)

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

A structure, a pointer to which is an argument of function qsmm_create, is described below.

Structure: qsmm_desc_s

This structure describes parameters for creating a multinode model. It contains the following fields.

Field: char use_flat_storage

A flag, which specifies whether flat storage or map storage should be used by a pair of actors that correspond to the multinode model. Is assigned to the field use_flat_storage of structure qsmm_actor_desc_s passed to the function qsmm_actor_create when creating each actor of the pair. It is permissible to use flat storage when the fields is_large_env and is_large_opt of this structure have zero values. If the value of field use_flat_storage is non-zero and it is not permissible to use flat storage, then error QSMM_ERR_INVAL will be reported.

Field: char dont_use_instr_class_weights

A flag that specifies whether to not to set weights of output signals of the instruction emitting engine equal to weights of instruction classes specified by the functions qsmm_set_instr_class_weight, qsmm_set_instr_class_weight_by_name_f, and qsmm_set_instr_meta_class_weight. The absence of necessity to set the weights of output signals makes the multinode model execute faster, especially when a sparse probability profile is specified for the action emission matrix of a node, and the number of instruction classes in the instruction class set of the node is large. If the flag is not 0, then those functions will raise error QSMM_ERR_NOTSUP.

Field: char is_determ_opt

A flag that imposes the following restriction on action emission matrices of all nodes of the multinode model: for every node state an action emission matrix must define deterministic choice of an instruction class emitted in that node state. When loading assembler programs into nodes, states are assumed to begin just before user and mixed type instructions, and there is no need to mark unnamed states by stt instructions. It is permissible to set this field to a non-zero value only when the field dont_use_instr_class_weights has a non-zero value and the field is_large_opt has zero value. Otherwise, error QSMM_ERR_INVAL will be reported.

Field: char is_large_env

A flag, which specifies whether a large actor or a small actor should be created for the environment state identification engine. The large actor will use binary Huffman trees. It is permissible to set this field to a non-zero value only when the field use_flat_storage has zero value and the field compat has value 1. Otherwise, error QSMM_ERR_INVAL will be reported.

Field: char is_large_opt

A flag, which specifies whether a large actor or a small actor should be created for the instruction emitting engine. The large actor will use binary Huffman trees. It is permissible to set this field to a non-zero value only when the fields use_flat_storage and is_determ_opt have zero values, the field dont_use_instr_class_weights has a non-zero value, and the field compat has value 1. Otherwise, error QSMM_ERR_INVAL will be reported.

Field: int nspur

The number of spur types used in the multinode model. This number includes the automatic spur, though that spur might not be really used. If the value of field is_determ_opt is zero, then the value of field nspur must be greater than 1. If the value of field is_determ_opt is non-zero, then the value of field nspur must be greater than 0.

Field: int stack_sz_max

The maximum allowed number of frames in the node call stack. If the actual number of stack frames exceeds the maximum allowed number, then error QSMM_ERR_STACKOVR will be raised. If the maximum allowed number of stack frames is too big, then stack overflow may occur without raising the error. That kind of stack overflow typically causes a segmentation fault. The value of this field must be greater than 0.

Field: int ngram_env_la_sz

The length of a segment of extra signals in an action choice state of the environment state identification engine that take part in the identification of a new node state. If this number is positive, then assembler programs cannot be loaded into nodes of the model. The value of this field must be non-negative.

Field: int nsig_ngram_env_la

The number of signals that are allowed to be the elements of a segment of extra signals of action choice state, the length of which is specified in the field ngram_env_la_sz. If the length is positive, then the number of signals must also be positive. If the length is zero, then the number of signals must also be zero.

Field: int profile_pool_env_sz

A non-negative size of the pool of probabilities lists in normal form of the environment state identification engine. Is assigned to the field profile_pool_sz of structure qsmm_actor_desc_s passed to the function qsmm_actor_create when creating the engine.

Field: int profile_pool_opt_sz

A non-negative size of the pool of probabilities lists in normal form of the instruction emitting engine. Is assigned to the field profile_pool_sz of structure qsmm_actor_desc_s passed to the function qsmm_actor_create when creating the engine.

Field: int compat

The compatibility level of algorithms used by the multinode model. Must be 0 or 1. Is assigned to the field compat of structure qsmm_actor_desc_s passed to the function qsmm_actor_create when creating a pair of actors that correspond to the multinode model. Setting a value of this field to 1 is recommended for your new programs. This manual does not include outdated details, specific to original algorithms, which will be used when this field has value 0.

Field: double sparse_fill_max

The maximum fill ratio for vectors that hold relative probabilities of output signals choice, on the basis of which engines of the multinode model decide when to use sparse vectors instead of ordinary vectors. Must be a number between 0 and 1 (inclusive). Is assigned to the field sparse_fill_max of structure qsmm_actor_desc_s passed to the function qsmm_actor_create when creating the engines.

Note: when the field is_large_env and/or the field is_large_opt have non-zero values or when loading large assembler programs, which specify sparse probability profiles, into model nodes, forgetting to set the field sparse_fill_max to a positive value, e.g. to 0.2, will cause bad model performance.

Field: qsmm_rng_t rng

The handle of a random number generator to be used by the multinode model. 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 multinode model and destroyed upon multinode model destruction.

Field: struct qsmm_pair_sig_s * range_sig_env_la_p

Ranges of signal identifiers in a segment of extra signals in an action choice state that take part in the identification of a new node state. Those ranges are used to check the validity of the segment, to reduce the memory footprint of flat storage if it is used by a small actor, which represents the environment state identification engine, and to reduce the number of nodes in the multinode model of a large actor, which represents the environment state identification engine. In future versions of the package, the ranges can be used for other purposes. To reduce the memory footprint of the environment state identification engine, it is recommended to specify the ranges as precisely as possible.

This field must be NULL or be the pointer to an array of ngram_env_la_sz elements. Each array element is a pair (see Creating an Actor, for a description of structure qsmm_pair_sig_s). 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 a value specified in the field nsig_ngram_env_la of this structure. If the field range_sig_env_la_p is NULL, then it will be assumed that every segment signal can be in the range 0 (inclusive) to the value (exclusive) of field nsig_ngram_env_la.

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

Some parameters specified when creating a multinode model can be obtained later using the following functions.

Function: int qsmm_get_use_instr_class_weights (qsmm_t model)

This function returns a positive value if weights of output signals of an instruction emitting engine that corresponds to multinode model are set equal to weights of instruction classes of a node being executed or returns 0 otherwise. The function returns a positive value if the field dont_use_instr_class_weights of structure qsmm_desc_s passed to the function qsmm_create has zero value when creating the multinode model. The function returns zero if that field has a non-zero value when creating the multinode model. The function never returns negative values.

Function: int qsmm_get_determ_opt (qsmm_t model)

This function returns a positive value if action emission matrices of all nodes of multinode model are restricted to defining deterministic choice of action for every node state. The function returns a positive value if the field is_determ_opt of structure qsmm_desc_s passed to the function qsmm_create has a non-zero value when creating the multinode model. Otherwise, zero value is returned. This function never returns negative values.

Function: int qsmm_get_nspur (qsmm_t model)

This function returns the number of spur types used in multinode model. It is a number specified in the field nspur of structure qsmm_desc_s when creating the multinode model by the function qsmm_create. The returned value is always positive.

Function: int qsmm_get_stack_sz_max (qsmm_t model)

This function returns the maximum allowed number of frames in the node call stack of a multinode model specified by handle model. It is a number specified in the field stack_sz_max of structure qsmm_desc_s when creating the multinode model by the function qsmm_create. The returned value is always positive.

Function: int qsmm_get_ngram_env_la_sz (qsmm_t model)

This function returns the length of a segment of extra signals in an action choice state of the environment state identification engine of multinode model, which take part in the identification of a new node state. It is a number specified in the field ngram_env_la_sz of structure qsmm_desc_s when creating the multinode model by the function qsmm_create. The returned value is always non-negative.

Function: int qsmm_get_nsig_ngram_env_la (qsmm_t model)

This function returns the number of signals, which are allowed to be placed into an action choice state of the environment state identification engine of multinode model at extra positions, and which take part in the identification of a new node state. It is a number specified in the field nsig_ngram_env_la of structure qsmm_desc_s when creating the multinode model by the function qsmm_create. The returned value is always non-negative.


Next: , Previous: , Up: Multinode Model   [Contents][Index]