5.9.2 Controlled Variables

Controlled probability variables are the means of changing a probability profile loaded into a node, for example, as a result of reasoning or self-programming.

An assembler program can contain controlled probability variables for profile probabilities in the state transition matrix only if the environment state identification engine is a small actor—if the field is_large_env of qsmm_desc_s structure passed to the function qsmm_create is zero. An assembler program can contain controlled probability variables for profile probabilities in the action emission matrix only if the instruction emitting engine is a small actor—if the field is_large_opt of qsmm_desc_s is zero.

You have to register controlled probability variables in the instruction class set of a node. After registering the variables, you can load into the node an assembler program referencing a subset of those variables. Later, you can change their values for the node, thereby changing its probability profile (e.g. while processing instruction invocations by the event handlers of instruction meta-classes). Changing the value of a controlled probability variable updates profile probabilities in the state transition matrix and/or action emission matrix for the occurrences of jprob and case instructions containing this variable as a probability.

Use the following function to register a controlled probability variable in an instruction class set.

Function: int qsmm_reg_var_prob (qsmm_t model, const char *instr_class_set_name, const char *var_name, size_t *var_idx_p)

This function registers a controlled probability variable var_name in the instruction class set instr_class_set_name of a multinode model. If var_idx_p is not NULL, the function sets *var_idx_p to the index of this variable in the instruction class set.

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 class set instr_class_set_name does not exist.

QSMM_ERR_TYPE

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

QSMM_ERR_EXIST

The instruction class set already has a controlled probability variable var_name registered.

QSMM_ERR_VIOLNODE

There exist nodes belonging to a node class represented by the instruction class set instr_class_set_name—cannot change its structure.

QSMM_ERR_UNSUPPLA

The multinode model has positive length of look-ahead signal segment.

QSMM_ERR_NOTSUP

The environment state identification engine and instruction emitting engine are large actors.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Currently, there are no API functions taking as an argument the index of a controlled probability variable returned by the function qsmm_reg_var_prob. Instead, functions that query and set the values of controlled probability variables take the name of a variable as an argument. To speed up querying and setting the values, future QSMM versions may include counterpart functions taking the index of a variable instead of its name.

Use the following macro to register a controlled probability variable on processing an event QSMM_EVT_ENT_INIT by the event handler of an instruction class set.

Macro: QSMM_REG_VAR_PROB (var_name)

This macro registers a controlled probability variable var_name. The macro expands to:

qsmm_reg_var_prob((qsmm), __FUNCTION__, (var_name), 0)

This macro is for expansion from the event handler of an instruction class set. The macro expects that the name of the event handler function is equal to the name of the instruction class set and the variable qsmm holding the handle of a multinode model is accessible in the event handler function. Normally, that variable is an event handler function argument.

Use the following function to get the names of controlled probability variables registered in an instruction class set.

Function: int qsmm_enum_var_prob (qsmm_t model, const char *instr_class_set_name, qsmm_enum_ent_callback_func_t callback_func, void *paramp)

This function enumerates controlled probability variables registered in the instruction class set instr_class_set_name of a multinode model. The process of enumeration is repeated calling a callback function callback_func receiving QSMM_LREF_PROB_VAR_CTRL as the type of a local entity reference, the name of a controlled probability variable in a local entity identifier, and a user parameter paramp. See Enumerating Entities, for the description of callback function type.

If the callback function returns a positive value, the function qsmm_enum_var_prob continues the enumeration. If the callback function returns zero, qsmm_enum_var_prob terminates the enumeration and reports success. If the callback function returns a negative value, qsmm_enum_var_prob terminates the enumeration and reports failure.

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 class set instr_class_set_name does not exist.

QSMM_ERR_TYPE

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

QSMM_ERR_CALLBACK

The callback function reported an error.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Use the following functions to query or set the value of a controlled probability variable.

Function: int qsmm_get_node_var_prob (qsmm_t model, const char *var_name, qsmm_sig_t node, double *valp)

This function retrieves the value of the controlled probability variable var_name of a node of a multinode model. The argument node specifies the identifier of this node. If valp is not NULL, the function sets *valp to a retrieved value.

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 or a controlled probability variable named var_name does not exist.

QSMM_ERR_UNSUPPLA

The multinode model has positive length of look-ahead signal segment.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Function: int qsmm_set_node_var_prob (qsmm_t model, const char *var_name, qsmm_sig_t node, double val)

This function sets to val the value of the controlled probability variable var_name of a node of a multinode model. The argument node specifies the identifier of this node. However, corresponding profile probabilities in the state transition matrix and/or action emission matrix of this node remain unchanged until calling the function qsmm_node_var_realize (described further on in this subsection).

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_INVAL

The argument val is not finite or is negative or greater than 1.

QSMM_ERR_NOTFOUND

A node with identifier node or a controlled probability variable named var_name does not exist.

QSMM_ERR_UNSUPPLA

The multinode model has positive length of look-ahead signal segment.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

After loading an assembler program into a node, controlled probability variables associated with the node take on initial values defined in the assembler program.

Assignments to controlled probability variables declared in an instruction class set but not defined in the assembler program have no effect on profile probabilities in the state transition matrix and action emission matrix of a node. Assignments to the controlled probability variables of a node without a loaded assembler program also have no effect on the profile probabilities.

After assigning values to controlled probability variables by the function qsmm_set_node_var_prob, call the following function to actually update profile probabilities in the state transition matrix and action emission matrix.

Function: int qsmm_node_var_realize (qsmm_t model, qsmm_sig_t node, int rez1)

This function updates profile probabilities in the state transition matrix and/or action emission matrix of a node of a multinode model according to assignments to controlled probability variables of this node previously made by calling the function qsmm_set_node_var_prob and clears the queue of pending updates. The argument node specifies the identifier of this node. The argument rez1 is for future use and must be equal to 0.

For affected action choice states, the function updates the fields nsig_pos and nsig_ctrl of qsmm_state_s structure. For affected cycle types, the function updates the field profile of qsmm_cycle_s structure.

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_PROFSRCP

The node is a probability profile source for other nodes. See Memory Efficient Cloning the Probability Profile, for more information on this mode.

QSMM_ERR_UNTIMELY

The model instance does not exist.

QSMM_ERR_UNSUPPLA

The multinode model has positive length of look-ahead signal segment.

QSMM_ERR_PSUMGT1

The sum of probabilities of case instructions in a choice instruction block would exceed 1.

QSMM_ERR_STORAGE

A Storage API function reported storage failure.

QSMM_ERR_STATS

Inconsistent statistics on an action choice state or cycle type detected.

QSMM_ERR_ILSEQ

Unable to convert a multibyte string to a wide string or vice versa according to a current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Errors QSMM_ERR_PSUMGT1, QSMM_ERR_STORAGE, QSMM_ERR_STATS, QSMM_ERR_ILSEQ, and QSMM_ERR_NOMEM can leave the probability profile of this node in inconsistent state. If after removing a reason of this error a repeated call to this function succeeds, the probability profile becomes consistent.