---

5.8.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.

Note: in the current implementation, an assembler program can contain controlled probability variables for profile probabilities in the state transition matrix or action emission matrix only if the environment state identification engine or instruction emitting engine respectively is a small actor. As well-defined model operation generally requires using large actors for the environment state identification engine and instruction emitting engine, practical ability to use controlled probability variables will appear after an improvement of QSMM library.

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

The argument var_name does not contain a valid name for a probability variable.

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 exists a node belonging to a node class represented by the instruction class set instr_class_set_name.

QSMM_ERR_NOTSUP

The environment state identification engine and instruction emitting engine are large actors, or the multinode model has positive length of look-ahead signal segment.

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 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 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 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 as 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, qsmm_enum_var_prob continues enumeration. If the callback function returns zero, qsmm_enum_var_prob terminates enumeration and reports success. If the callback function returns a negative value, qsmm_enum_var_prob terminates 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 controlled probability variable var_name of a node in a multinode model. The argument node specifies the identifier of the 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_INVAL

The argument var_name does not contain a valid name for a probability variable.

QSMM_ERR_NOTFOUND

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

QSMM_ERR_NOTSUP

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 controlled probability variable var_name of a node in a multinode model. The argument node specifies the identifier of the node. However, corresponding profile probabilities in the state transition matrix and/or action emission matrix of the 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, or the argument var_name does not contain a valid name for a probability variable.

QSMM_ERR_NOTFOUND

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

QSMM_ERR_NOTSUP

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, its controlled probability variables take on initial values specified in the assembler program. Assignments to controlled probability variables declared in an instruction class set but not defined in the assembler program do not affect profile probabilities in the state transition matrix and action emission matrix.

After assigning values to controlled probability variables by the function qsmm_set_node_var_prob, call the following function to 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 in a multinode model according to assignments to controlled probability variables of the 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 the node. The argument rez1 is for future use and must be equal to 0.

For affected action choice states, the function updates the field nsig_ctrl and, possibly, the field sig_cycle_next in the structure qsmm_state_s. For affected cycle types, the function updates the field profile in the structure qsmm_cycle_s.

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_PSUMGT1

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

QSMM_ERR_UNTIMELY

A model instance does not exist.

QSMM_ERR_NOPROF

A node with identifier node does not have a probability profile specified.

QSMM_ERR_PROFSRCP

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

QSMM_ERR_NOTSUP

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

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 a node probability profile in inconsistent state. If after removing a reason of an error a repeated call to this function succeeds, the probability profile becomes consistent.