4.3.5 Setting Instruction Classes Weights ¶

If the field dont_use_instr_class_weights of qsmm_desc_s structure passed to the function qsmm_create when creating a multinode model is zero, and the instruction emitting engine is a small actor, you can assign weights to instruction classes executed³ by a node. The weights are multipliers for calculated probabilities of selection of the instruction classes by the instruction emitting engine assigned to its output signals by the function qsmm_set_actor_sig_weight. The function qsmm_node_create_v2 initializes to 1 weights of all instruction classes executable by a node.

Warning: changing weights of instruction classes leads to ill-defined behavior of built-in functions for computing the relative probability of an output signal by the instruction emitting engine. Therefore, avoid changing weights of instruction classes if you use the built-in functions. See Number of Output Signals, for the explanation why the behavior becomes ill-defined.

You can use the following functions to query or set the weight of an instruction class specified by its index uniquely identifying the instruction class in an instruction class set.

Function: int qsmm_get_instr_class_weight (qsmm_t model, qsmm_sig_t node, qsmm_sig_t instr_class, double *weight_p) ¶

This function retrieves the weight of an instruction class executable by a node of a multinode model. The argument node specifies the identifier of the node. The argument instr_class specifies the index of the instruction class in the instruction class set of the node. If weight_p is not NULL, the function sets *weight_p to retrieved weight.

The function returns a non-negative value on success or a negative error code on failure. Currently, the function can return the following error codes.

QSMM_ERR_NOTFOUND

A node with identifier node does not exist.

QSMM_ERR_INVAL

The argument instr_class is greater than or equal to the number of instruction classes in the instruction class set of the node.

QSMM_ERR_NOTSUP

The multinode model does not support assigning weights to instruction classes.

Function: int qsmm_set_instr_class_weight (qsmm_t model, qsmm_sig_t node, qsmm_sig_t instr_class, double weight) ¶

This function sets to weight the weight of an instruction class executable by a node of a multinode model. The argument node specifies the identifier of the node. The argument instr_class specifies the index of the instruction class in the instruction class set of the node.

The function returns a non-negative value on success or a negative error code on failure. Currently, the function can return the following error codes.

QSMM_ERR_NOTFOUND

A node with identifier node does not exist.

QSMM_ERR_INVAL

The argument weight is negative or not finite, or instr_class is greater than or equal to the number of instruction classes in the instruction class set of the node.

QSMM_ERR_NOTSUP

The multinode model does not support assigning weights to instruction classes.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Use the following functions to query or set the weight of an instruction class specified by its name consisting of an instruction meta-class name and optional text parameters of the instruction class.

Function: int qsmm_get_instr_class_weight_by_name_f (qsmm_t model, qsmm_sig_t node, double *weight_p, const char *fmt, ...) ¶

Function: int qsmm_set_instr_class_weight_by_name_f (qsmm_t model, qsmm_sig_t node, double weight, const char *fmt, ...) ¶

The function qsmm_get_instr_class_weight_by_name_f retrieves the weight of an instruction class executable by a node of a multinode model. If weight_p is not NULL, the function sets *weight_p to retrieved weight. The function qsmm_set_instr_class_weight_by_name_f sets to weight the weight of an instruction class executable by a node of a multinode model.

The argument node specifies the identifier of the node. The argument fmt and subsequent arguments interpreted similarly to the function printf specify an instruction class name: a sequence of zero or more whitespace characters, an instruction meta-class name optionally followed by a sequence of one or more whitespace characters and text instruction class parameters, and a sequence of zero or more whitespace characters.

Before searching an instruction class in an instruction class set, the functions convert a formatted instruction class name to the canonical form: an instruction meta-class name optionally followed by the space character and text instruction class parameters converted to their canonical form according to rules described in Setting Text Instruction Parameters.

The functions return a non-negative value on success or a negative error code on failure. Currently, the functions can return the following error codes.

QSMM_ERR_NOTFOUND

A node with identifier node does not exist, or the instruction class not found in the instruction class set of the node.

QSMM_ERR_INVAL

The argument weight is negative or not finite, or an instruction class name has invalid format.

QSMM_ERR_NOTSUP

The multinode model does not support assigning weights to instruction classes.

QSMM_ERR_ILSEQ

Unable to convert an instruction class name to a wide string according to a current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

The following call sets the weight of ‘move north’ instruction class to 0 to disable moving an agent in the north direction:

qsmm_set_instr_class_weight_by_name_f(qsmm,node,0,"move north");

A node has an internal array holding weights of instruction classes executable by the node. On transferring control to the node (calling it or returning control to it from another node), the function qsmm_node_call_default sets weights of output signals of instruction emitting engine equal to weights stored in the internal array. The aforementioned functions for setting weights of instruction classes immediately update weights of corresponding output signals of instruction emitting engine if the model instance exists, the node call stack is not empty, and the identifier of a currently executed node is equal to node. Otherwise, the functions update the weights in the internal array.