Next: Output Variables, Previous: Variables in an Assembler Program, Up: Using Probability Variables [Contents][Index]
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.
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.
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.
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.
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.
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.
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.
Next: Output Variables, Previous: Variables in an Assembler Program, Up: Using Probability Variables [Contents][Index]