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.
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 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_INVALParameters in *desc_p are invalid.
QSMM_ERR_NOMEMThere was not enough memory to create a multinode model.
void qsmm_destroy (qsmm_t model) ¶This function destroys a multinode model.
You must not use model after its destruction.
If model is NULL, the function has no effect.
The following enumeration contains an element denoting an environment state identification engine and an element denoting an instruction emitting engine.
The structure qsmm_desc_s uses the enumeration for specifying engine parameters when creating a multinode model.
This enumeration specifies the type of a multinode model engine. The enumeration contains the following elements.
QSMM_ENGINE_ENVEnvironment state identification engine
QSMM_ENGINE_IEEInstruction emitting engine
QSMM_ENGINE_COUNTThe last element of this enumeration equal to the number of engine types
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.
char dont_use_instr_class_weights ¶A flag defining whether 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 and qsmm_set_instr_class_weight_by_name_f (see Setting Instruction Classes Weights, for function descriptions).
Zero flag means to set the weights, and non-zero flag means not to set them.
If the flag is non-zero, the two functions report QSMM_ERR_NOTSUP.
If the field engine_desc[QSMM_ENGINE_IEE].is_determ or engine_desc[QSMM_ENGINE_IEE].is_large of this structure is non-zero, qsmm_create implicitly sets the flag to a non-zero value.
Eliminating the need to set the weights speeds up model execution when the number of instruction classes in the instruction class set is large.
int stack_sz_max ¶The maximum allowed number of frames in the node call stack.
If the actual number of stack frames exceeds that value, 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.
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. The 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.
int compat ¶Compatibility level of algorithms. Must be equal to 3.
qsmm_sig_t nnode_max ¶[New in QSMM 1.19] The maximum number of nodes.
It must not exceed QSMM_SIG_MAX.
If this field is equal to 0, qsmm_create uses value QSMM_SIG_MAX instead.
Setting this field to 1 means to create a single-node model.
qsmm_sig_t 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, the upper bound must also be positive.
If the length is zero, the upper bound must also be zero.
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, qsmm_create creates an instance of default random number generator for use by both engines until model destruction.
struct qsmm_pair_sig_s * range_sig_env_la_p ¶Ranges of signal identifiers in the look-ahead signal segment.
The field ngram_env_la_sz of this structure specifies look-ahead signal segment length.
The multinode model uses the ranges to check segment validity.
If range_sig_env_la_p is not NULL, the 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).
Indices of the elements are indices of signal identifiers in the look-ahead signal segment.
The fields first and second of each pair define a minimum value and maximum value for 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.
Setting range_sig_env_la_p to NULL means that every signal in the segment can lie in the range 0 (inclusive) to nsig_ngram_env_la (exclusive).
struct qsmm_engine_desc_s engine_desc[QSMM_ENGINE_COUNT] ¶[New in QSMM 1.19] Parameters for creating the environment state identification engine and instruction emitting engine.
To improve compatibility with future versions of QSMM library, zero by the function memset an instance of qsmm_desc_s structure before setting its fields.
Below there is a description of a structure defining the type of elements of engine_desc array in the structure qsmm_desc_s.
This structure describes parameters for creating an environment state identification engine or instruction emitting engine for a multinode model. The structure contains the following fields.
char is_determ ¶If this field is non-zero, it imposes a restriction on assembler programs loadable into the nodes of a multinode model.
This field can be non-zero only if the field large_desc_p of this structure is NULL.
For the environment state identification engine, the restriction is that assembler programs must define deterministic probability profiles for state transition matrices: for every triple comprised of a source node state, an individual instruction or instruction sequence emitted in the source node state, and an instruction outcome, the probability profiles must specify a single target state, that is, the selection of a target node state must be deterministic.
In this mode the node assembler considers jprob instructions and choice instruction blocks in an assembler program as specifying nondeterministic instruction emissions unless the action emission matrix is also deterministic.
You can omit marking node states by stt instructions, as node states implicitly begin just before blocks of jprob instructions and choice instruction blocks, just before individual user or mixed-type instructions without probabilistic jumps to them, and just before sequences of user or mixed-type instructions without probabilistic jumps to them.
For the instruction emitting engine, the restriction is that assembler programs must define deterministic probability profiles for action emission matrices: for every node state, the probability profiles must specify a single instruction or a single instruction sequence emitted in the node state, that is, the selection of an individual instruction or instruction sequence must be deterministic.
In this mode the node assembler considers jprob instructions and choice instruction blocks in an assembler program as specifying nondeterministic state transitions unless the state transition matrix is also deterministic.
You can omit marking node states by stt instructions, as node states implicitly begin just before individual user or mixed-type instructions and sequences of user or mixed-type instructions.
If you use stt instructions, you cannot place them just before jprob instructions and choice instruction blocks.
int nspur ¶The number of spur types. This field must have a non-negative value.
int ntime ¶The number of continuous time types. This field must have a non-negative value.
const struct qsmm_actor_large_desc_s * large_desc_p ¶The parameters of a large actor representing the environment state identification engine or instruction emitting engine.
A non-NULL value of this field means to use a large actor for the engine.
See Creating an Actor, for a description of qsmm_actor_large_desc_s structure.
The function qsmm_create copies a structure instance referenced by this field to an internal structure.
This field can be non-NULL only if the field is_determ of this structure is zero.
You can retrieve some initial model parameters later by the following functions.
int qsmm_get_use_instr_class_weights (qsmm_t model) ¶This function returns a positive value if the function qsmm_node_call_default sets weights of output signals of the instruction emitting engine of a multinode model equal to weights of instruction classes of a currently executed node, and the functions qsmm_set_instr_class_weight and qsmm_set_instr_class_weight_by_name_f support setting weights of instruction classes.
If qsmm_node_call_default does not set the weights and qsmm_set_instr_class_weight and qsmm_set_instr_class_weight_by_name_f report QSMM_ERR_NOTSUP, qsmm_get_use_instr_class_weights returns 0.
A value returned by qsmm_get_use_instr_class_weights may depend on the field dont_use_instr_class_weights of qsmm_desc_s structure passed to the function qsmm_create when creating the multinode model.
A returned value is always non-negative.
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.
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.
qsmm_sig_t 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.
const struct qsmm_actor_large_desc_s * qsmm_get_engine_desc (qsmm_t model, enum qsmm_engine_e engine_type) ¶This function returns the parameters of an engine of a multinode model stored in its internal structure.
The field engine_desc of qsmm_desc_s structure passed to the function qsmm_create when creating the multinode model specifies the parameters.
The argument engine_type selects the environment state identification engine or instruction emitting engine.
If engine_type is incorrect, the function returns NULL.