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


4.11 Setting Instruction Classes Weights

If the field dont_use_instr_class_weights of structure qsmm_desc_s passed to the function qsmm_create when creating a multinode model has zero value, then nodes of the model may have weights assigned to instruction classes that can be executed by the nodes5. Those weights are multipliers for optimal probabilities of invocation of instruction classes. The multiplied probabilities are renormalized and become probabilities that are actually used when stochastically choosing which instruction class to invoke. In fact, the weights are assigned using the function qsmm_set_actor_sig_weight to output signals of the instruction emitting engine. The function qsmm_node_create initializes weights of all instruction classes, which can be executed by the node, to 1.

To retrieve or set the weight of an instruction class, which is specified by a number that uniquely identifies it in an instruction class set, the following functions can be used.

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

This function retrieves the weight of an instruction class that can be executed by node of multinode model. The instruction class is specified by number instr_class that uniquely identifies it in an instruction class set which is a node class of node. If weight_p is not NULL, then *weight_p will be set to the retrieved weight.

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

QSMM_ERR_NOTFOUND

A node with identifier node does not exist.

QSMM_ERR_INVAL

The value of instr_class is negative or is greater than or equal to the number of instruction classes in an instruction class set which is a node class of node.

QSMM_ERR_NOTSUP

The multinode model does not allow to assign weights to instruction classes.

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

This function sets to weight the weight of an instruction class that can be executed by node of multinode model. The instruction class is specified by number instr_class that uniquely identifies it in an instruction class set which is a node class of node.

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

QSMM_ERR_NOTFOUND

A node with identifier node does not exist.

QSMM_ERR_INVAL

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

QSMM_ERR_NOTSUP

The multinode model does not allow to assign weights to instruction classes.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

To retrieve or set the weight of an instruction class, which is specified by its name that consists of an instruction meta-class name and an optional text representation of instruction class parameters, the following functions can be used.

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

This function retrieves the weight of an instruction class that can be executed by node of multinode model. The instruction class is specified by its name, which is the name of instruction meta-class followed by an optional text representation of instruction class parameters after one or more whitespace characters. The name of instruction class is formatted according to argument fmt and subsequent arguments, the meaning of which is the same as in the function printf. If weight_p is not NULL, then *weight_p will be set to the retrieved weight.

Before searching the instruction class in an instruction class set which is a node class of node, the formatted name is converted to a canonical form: extra whitespace characters before and after the name of instruction meta-class are removed, and text representation of instruction class parameters is normalized according to rules described in Setting the Instruction Parameters String.

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

QSMM_ERR_NOTFOUND

A node with identifier node does not exist or the instruction class not found in an instruction class set which is a node class of node.

QSMM_ERR_INVAL

The name of instruction class has invalid format.

QSMM_ERR_ILSEQ

The name of instruction class cannot be converted to a wide string according to the current locale.

QSMM_ERR_NOTSUP

The multinode model does not allow to assign weights to instruction classes.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

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

This function sets to weight the weight of an instruction class that can be executed by node of multinode model. The instruction class is specified by its name, which is the name of instruction meta-class followed by an optional text representation of instruction class parameters after one or more whitespace characters. The name of instruction class is formatted according to argument fmt and subsequent arguments, the meaning of which is the same as in the function printf.

Before searching the instruction class in an instruction class set which is a node class of node, the formatted name is converted to a canonical form: extra whitespace characters before and after the name of instruction meta-class are removed, and text representation of instruction class parameters is normalized according to rules described in Setting the Instruction Parameters String.

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

QSMM_ERR_NOTFOUND

A node with identifier node does not exist or the instruction class not found in an instruction class set which is a node class of node.

QSMM_ERR_INVAL

The value of weight is not finite or is negative, or the name of instruction class has invalid format.

QSMM_ERR_ILSEQ

The name of instruction class cannot be converted to a wide string according to the current locale.

QSMM_ERR_NOTSUP

The multinode model does not allow to assign weights to instruction classes.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

For example, to set the weight of instruction class ‘move north’ 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");

To set weights of all instruction classes of a node, which are derived from an instruction meta-class, to the same value, the following function can be used.

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

This function sets weights of all instruction classes, which belong to instruction meta-class instr_meta_class_name and which can be executed by node of multinode model, to a value equal to weight divided by the number of those instruction classes.

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

QSMM_ERR_INVAL

The value of weight is not finite or is negative.

QSMM_ERR_NOTFOUND

Instruction meta-class instr_meta_class_name not found, or a node with identifier node does not exist, or no instruction classes derived from instruction meta-class instr_meta_class_name are found in an instruction class set which is a node class of node.

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 allow to assign weights to instruction classes.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.


Footnotes

(5)

Here and below “invocation/execution of an instruction class” actually means “invocation/execution of an instruction that belongs to the instruction class.”


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