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


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 executed5 by a node of this model. The weights are multipliers for calculated probabilities of selection of those 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 the weights of all instruction classes executable by a node.

Warning: changing the 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 the weights of instruction classes if you use those 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 this node. The argument instr_class specifies the index of this instruction class in the instruction class set of this 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 this node. The argument instr_class specifies the index of this instruction class in the instruction class set of this 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 this 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 model specifies a multinode model handle. The argument node specifies a node identifier. The argument fmt and subsequent arguments interpreted as in 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 the text parameters of this instruction class, and a sequence of zero or more whitespace characters.

Before searching the instruction class in the instruction class set of this node, the functions convert the formatted name to the canonical form: the instruction meta-class name optionally followed by the space character and the text parameters of this instruction class 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 this 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.

For example, to set the weight of ‘move north’ instruction class to 0 to disable moving an agent in the north direction, use a line of code like this:

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

Use the following function to set to the same value the weights of all instruction classes derived from an instruction meta-class for a node.

Function: int qsmm_set_instr_meta_class_weight (qsmm_t model, const char *instr_meta_class_name, qsmm_sig_t node, double weight)

This function sets the weights of all instruction classes derived from an instruction meta-class instr_meta_class_name and executable by a node of a multinode model to weight divided by the number of those instruction classes. The argument node specifies the identifier of this 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

The instruction meta-class instr_meta_class_name not found, or a node with identifier node does not exist, or there are no instruction classes derived from that instruction meta-class in the instruction class set of this node.

QSMM_ERR_INVAL

The argument weight is negative or not finite.

QSMM_ERR_TYPE

An entity named instr_meta_class_name is not an instruction meta-class. The entity is an instruction class set.

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.

The function qsmm_node_call_default sets the weights of output signals of instruction emitting engine equal to the weights of instruction classes executable by a node on transferring control to it—calling the node or returning control to it from another node. The aforementioned functions for setting the weights of instruction classes immediately update the 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.


Footnotes

(5)

Here and below, “the invocation/execution of an instruction class” means “the invocation/execution of an instruction belonging to an instruction class.”


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