A model handle refers to a multinode model.
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.
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.
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
.
This structure describes parameters for creating a multinode model by the function qsmm_create
.
The structure contains the following fields.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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
oris_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 fieldsparse_fill_max
to a positive value, for example, 0.2 or 1, will cause bad model performance.
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.
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.
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.
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.
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.
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.
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.
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.