Next: , Up: Creating a Multinode Model   [Contents][Index]


4.2.1 Creating a Handle

A model handle refers to a multinode model.

Data type: qsmm_t

This is a type for a model handle. It is a pointer, so variables of this type can be NULL. The function qsmm_create creates a new model and returns its handle. The function qsmm_destroy destroys an existing model addressed by a handle. You can pass a model handle to API functions taking an argument of qsmm_t type after the creation of a model and until its destruction.

Use the following functions to create and destroy a multinode model.

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

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

If model_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 a multinode model. Currently, the function can return the following error codes.

QSMM_ERR_INVAL

Parameters 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. You must not use the model handle after the model destruction. If model is NULL, the function has no effect.

Below there is a description of a structure passed in *desc_p to the function qsmm_create.

Structure: qsmm_desc_s

This structure describes parameters for creating a multinode model by the function qsmm_create. The structure contains the following fields.

Field: char use_flat_storage

A flag specifying the type of storage the environment state identification engine and instruction emitting engine will use: flat storage if the flag is non-zero, or map storage if the flag is zero. The function qsmm_engine_create assigns this flag to the field use_flat_storage of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating both engines. It is permissible to use flat storage if the fields is_large_env and is_large_opt of this structure are zero.

Field: char dont_use_instr_class_weights

A flag defining whether to set the weights of output signals of the instruction emitting engine equal to the 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 (see Setting Instruction Classes Weights, for the descriptions of those functions). A zero flag means to set the weights, and a non-zero flag means to not set them. If the flag is non-zero, those functions will report QSMM_ERR_NOTSUP. If the field is_determ_opt or is_large_opt of this structure is non-zero, the function qsmm_create implicitly sets this flag to a non-zero value. Eliminating the need to set the weights speeds up model execution, especially when the action emission matrix has a sparse probability profile, and the number of instruction classes in the instruction class set is large.

Field: char is_determ_opt

A flag imposing the following restriction on the probability profile of action emission matrix of every model node: for every node state, that probability profile must define a deterministic choice of an instruction class emitted in the node state. If this flag is non-zero, the node assembler considers that node states begin just before user and mixed-type instructions—marking unnamed node states by stt instructions becomes unnecessary. It is permissible to set this flag to a non-zero value only if the field is_large_opt of this structure is zero.

Field: char is_large_env

A flag specifying whether to create a small or large actor for the environment state identification engine: a small actor if this flag is zero, or a large actor if this flag is non-zero. The large actor uses binary Huffman trees. It is permissible to set this flag to a non-zero value only if the field use_flat_storage of this structure is zero, and the field compat is positive.

Field: char is_large_opt

A flag specifying whether to create a small or large actor for the instruction emitting engine: a small actor if this flag is zero, or a large actor if this flag is non-zero. The large actor uses binary Huffman trees. It is permissible to set this flag to a non-zero value only if the fields use_flat_storage and is_determ_opt of this structure are zero, and the field compat is positive.

Field: int nspur

The number of spur types. This number includes the automatic spur, although the model might not really use that spur. If the field is_determ_opt of this structure is zero, the field nspur must be greater than 1. If is_determ_opt is non-zero, 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, the function qsmm_node_call_default reports QSMM_ERR_STACKOVR. If the maximum allowed number of stack frames is too large, a stack overflow may occur without reporting this error. This kind of stack overflow typically causes a segmentation fault. The value of this field must be positive.

Field: int ngram_env_la_sz

The length of a segment of extra signals in a signal list encoding an action choice state of the environment state identification engine. Those extra signals take part in the identification of a current node state. See Setting Look-ahead Signals, for more information on them. The node assembler does not support loading assembler programs into the nodes of a model with positive length of look-ahead signal segment. The value of this field must be non-negative.

Field: int nsig_ngram_env_la

An upper bound on the identifier of every signal in the look-ahead signal segment with length specified in the field ngram_env_la_sz of this structure. Every identifier must be less than the upper bound. If the length is positive, then the upper bound must also be positive. If the length is zero, then the upper bound must also be zero.

Field: int profile_pool_env_sz

Non-negative size of the pool of probabilities lists in normal form for the environment state identification engine. The function qsmm_engine_create assigns this size to the field profile_pool_sz of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the engine.

Field: int profile_pool_opt_sz

Non-negative size of the pool of probabilities lists in normal form for the instruction emitting engine. The function qsmm_engine_create assigns this size to the field profile_pool_sz of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the engine.

Field: int compat

The compatibility level of algorithms. Must be 0, 1, or 2. The function qsmm_engine_create assigns that level to the field compat of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating the environment state identification engine and instruction emitting engine. Additionally, value 2 means:

  • Optimize setting the weights of output signals of the instruction emitting engine equal to the 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 (if the field dont_use_instr_class_weights of this structure is zero): set all those weights only on calling a node or returning control to it from another node and update a specific output signal weight by those functions if a node identifier passed to them is equal to the identifier of a currently executed node.
  • The function qsmm_get_nnode returns the actual number of existing nodes in the model rather than the number of reserved nodes—those numbers are equal only in certain cases.
  • The environment state identification engine increments discrete time disregarding whether or not the choice of a current node state is deterministic.
  • The instruction emitting engine increments discrete time disregarding whether or not the choice of an emitted instruction is deterministic.
  • Compute the relative probabilities of QSMM_RELPROB_BUILTIN1 type by the environment state identification engine and instruction emitting engine independently of the number of nodes in the model and the value of ngram_env_la_sz field of this structure.

Set this field to 2 in your new programs. This manual does not include outdated details specific to previous algorithms.

Field: double sparse_fill_max

Maximum fill ratio for sparse vectors holding the relative probabilities of output signals. The environment state identification engine and instruction emitting engine choose 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 both engines must always use ordinary vectors. Value 1 indicates that both engines 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. The function qsmm_engine_create assigns this number to the field sparse_fill_max of qsmm_actor_desc_s structure passed to the function qsmm_actor_create when creating both engines.

Note: if the field is_large_env or is_large_opt of this structure is non-zero, or when loading large assembler programs specifying sparse probability profiles into model nodes, forgetting to set the field sparse_fill_max to a positive value, for example, 0.2 or 1, will cause bad model performance.

Field: qsmm_rng_t rng

The handle of a random number generator the environment state identification engine and instruction emitting engine 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_create creates an instance of default random number generator for use by both engines until model destruction.

Field: struct qsmm_pair_sig_s * range_sig_env_la_p

The ranges of signal identifiers in the look-ahead signal segment. The field ngram_env_la_sz of this structure specifies the length of that segment. The multinode model uses those ranges to check the validity of that segment, to reduce the memory footprint of flat storage if a small actor representing the environment state identification engine uses this type of storage, and to reduce the number of nodes in the multinode model of a large actor representing the engine. 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 that engine.

If the field range_sig_env_la_p is not NULL, then this field must be the pointer to an array holding ngram_env_la_sz elements, where each element is a pair (see Creating an Actor, for a description of qsmm_pair_sig_s structure). The positions of those elements are the positions of signal identifiers in the look-ahead signal segment. The fields first and second of each pair define the minimum value and 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 value of nsig_ngram_env_la field of this structure. If range_sig_env_la_p is NULL, this condition means that every signal in the segment lies in the range 0 (inclusive) to nsig_ngram_env_la (exclusive).

To improve compatibility with future versions of QSMM library, zero by the function memset an instance of qsmm_desc_s structure before setting the fields of this instance passed to the function qsmm_create.

You can retrieve some initial model parameters later by the following functions.

Function: int qsmm_get_use_instr_class_weights (qsmm_t model)

This function returns a positive value if the function qsmm_node_call_default sets the weights of output signals of the instruction emitting engine of a multinode model equal to the weights of instruction classes of a currently executed node, and the functions qsmm_set_instr_class_weight, qsmm_set_instr_class_weight_by_name_f, and qsmm_set_instr_meta_class_weight support setting the weights of instruction classes. If qsmm_node_call_default does not set the weights, and qsmm_set_instr_class_weight, qsmm_set_instr_class_weight_by_name_f, and qsmm_set_instr_meta_class_weight report QSMM_ERR_NOTSUP, the function qsmm_get_use_instr_class_weights returns 0. This function returns a positive value if the field dont_use_instr_class_weights of qsmm_desc_s structure passed to the function qsmm_create was zero when creating the multinode model or returns 0 if that field was non-zero. A returned value is always non-negative.

Function: int qsmm_get_determ_opt (qsmm_t model)

This function returns a positive value if the action emission matrices of all nodes of a multinode model have the restriction to define only deterministic choices of assembler instructions in all node states. The function returns a positive value if the field is_determ_opt of qsmm_desc_s structure passed to the function qsmm_create was non-zero when creating the multinode model or returns 0 if that field was zero. A returned value is always non-negative.

Function: int qsmm_get_nspur (qsmm_t model)

This function returns the number of spur types of a multinode model. It is a number specified in the field nspur of qsmm_desc_s structure passed to the function qsmm_create when creating the multinode model. A 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. It is a number specified in the field stack_sz_max of qsmm_desc_s structure passed to the function qsmm_create when creating the multinode model. A returned value is always positive.

Function: int qsmm_get_ngram_env_la_sz (qsmm_t model)

This function returns the length of look-ahead signal segment of a multinode model. It is length specified in the field ngram_env_la_sz of qsmm_desc_s structure passed to the function qsmm_create when creating the multinode model. A returned value is always non-negative.

Function: int qsmm_get_nsig_ngram_env_la (qsmm_t model)

This function returns an upper bound on the identifier of every signal in the look-ahead signal segment of a multinode model. It is a number specified in the field nsig_ngram_env_la of qsmm_desc_s structure passed to the function qsmm_create when creating the multinode model. A returned value is always non-negative.


Next: , Up: Creating a Multinode Model   [Contents][Index]