Next: , Previous: , Up: Using Probability Variables   [Contents][Index]


5.9.2 Controlled Variables

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

Controlled probability variables that correspond to profile probabilities in the state transition matrix can only be used when the environment state identification engine is represented by a small actor, which will take place when the field is_large_env of structure qsmm_desc_s passed to the function qsmm_create has zero value. Controlled probability variables that correspond to profile probabilities in the action emission matrix can only be used when the instruction emitting engine is represented by a small actor, which will take place when the field is_large_opt of structure qsmm_desc_s has zero value.

Controlled probability variables must be registered in an instruction class set that represents the node class of the node. After registering the variables in the instruction class set, an assembler program that contains references to a subset of those variables in its text can be loaded into the node. Later, the application program may change values of controlled probability variables of the node, thus changing its probability profile. Changing values of the variables can be performed while processing invocation of specific instructions by event handler functions of instruction meta-classes.

When changing the value of a controlled probability variable via API function calls, profile probabilities in the state transition matrix and/or in the action emission matrix, which correspond to occurrences of jprob and case instructions, where that variable is used for a probability, and to jump labels in arguments of casels instructions, for which that variable specifies a probability, are updated accordingly.

To register a controlled probability variable in an instruction class set, the following function can be used.

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

This function registers a controlled probability variable of instruction class set instr_class_set_name of a multinode model specified by handle model. Argument var_name specifies the name of the variable. Argument rez1 is reserved for future use and must be equal to 0.

On success, the function returns a non-negative index of the variable registered in the instruction class set. On failure, a negative error code is returned. Currently, the following error codes can be returned.

QSMM_ERR_NOTFOUND

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

Probability variable var_name is already registered in instruction class set instr_class_set_name.

QSMM_ERR_VIOLNODE

There exist nodes that belong to a node class represented by instruction class set instr_class_set_name. Therefore, changing the structure of the instruction class set is not allowed.

QSMM_ERR_UNSUPPLA

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

QSMM_ERR_NOTSUP

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

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Currently, there are no QSMM API functions that take as an argument an index of variable returned by the function qsmm_reg_var_prob. Instead, functions, which query and set values of controlled probability variables, take the name of variable as an argument. To speed up querying and setting values of the variables, in future versions of the library counterpart functions can be introduced, to which the index of a variable instead of the name of the variable is passed.

To register a controlled probability variable when processing event QSMM_EVT_ENT_INIT by the event handler function of instruction class set, the following macro can be used.

Macro: QSMM_REG_VAR_PROB (var_name)

This macro registers controlled probability variable var_name. The macro is expanded to:

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

The macro is to be expanded from the event handler function of an instruction class set. The name of the event handler function must coincide with the name of the instruction class set, and normally it does coincide. There must be the variable qsmm, which is a handle of the multinode model, defined in a function from which the macro is expanded. Normally, that variable is an argument of the event handler function.

To get names of controlled probability variables registered in an instruction class set, the following function can be used.

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 specified by handle model. The process of enumeration is a repeated calling callback function callback_func, to which the entity type QSMM_ENT_VAR_PROB, the name of a controlled probability variable, and user parameter paramp are passed. The type of the callback function is described in Enumerating Entities.

If the callback function returns a positive value, then the process of enumeration will be continued. If the callback function returns zero, then the process of enumeration will be terminated, and the function qsmm_enum_var_prob will report success. If the callback function returns a negative value, then the process of enumeration will be terminated, and the function qsmm_enum_var_prob will report failure.

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

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 did return an error.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

To query or set the value of a controlled probability variable from an application program, the following functions can be used.

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

This function sets *valp to the value of controlled probability variable var_name of a node of a multinode model specified by handle model. Argument node specifies the identifier of the node. If valp is NULL, then *valp will not be set.

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

QSMM_ERR_UNSUPPLA

The multinode model has positive length of the 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, int node, double val)

This function sets to val the value of controlled probability variable var_name of a node of a multinode model specified by handle model. Argument node specifies the identifier of the node. However, corresponding profile probabilities in the state transition matrix and/or the action emission matrix of the node will 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 following error codes can be returned.

QSMM_ERR_INVAL

The value of val is not finite or is negative or is greater than 1.

QSMM_ERR_NOTFOUND

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

QSMM_ERR_UNSUPPLA

The multinode model has positive length of the 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.

It is allowed to set values of controlled probability variables declared in an instruction class set, but not defined in the assembler program. It is also allowed to set values of controlled probability variables for a node, to which an assembler program was not loaded. Such assignments to variables do not cause changing profile probabilities in the state transition matrix and the action emission matrix of the node.

After assigning values to controlled probability variables by the function qsmm_set_node_var_prob, the actual update of profile probabilities in the state transition matrix and the action emission matrix of the node can be performed using the following function.

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

This function updates the state transition matrix and/or the action emission matrix of a node of a multinode model specified by handle 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. Argument node specifies the identifier of the node. Argument rez1 is reserved for future use and must be equal to 0.

For affected cycle types, values of field profile of structure qsmm_cycle_s are updated. For affected action choice states, values of fields nsig_pos and nsig_ctrl of structure qsmm_state_s are updated.

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_PSUMGT1

The sum of probabilities of case instructions in a choice instruction block or the sum of elements of a probabilities list used by a casels instruction will exceed 1. This could leave the model instance in indeterminate state. If the model instance is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds, then the model instance state will become determinate.

QSMM_ERR_PROFSRCP

A node with identifier node is the source of probability profile 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 the look-ahead signal segment.

QSMM_ERR_STORAGE

Statistics storage failure. This could leave the model instance in indeterminate state. If the model instance is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds, then the model instance state will become determinate.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation. This could leave the model instance in indeterminate state. If the model instance is in indeterminate state, then after removing a reason of the error, the operation can be repeated, and if the function succeeds, then the model instance state will become determinate.

To prevent relying on a rather weak concept of the mean number of actor’s output signals described in Other Parameters of an Actor, it is recommended to use controlled probability variables in a somewhat restricted way when they specify either deterministic choices or do not change the number of choice alternatives if it is greater than 1. To achieve this, it is recommended to use jprob instructions when the potential number of choice alternatives is equal to 2 and use choice instruction blocks or casels instructions when the potential number of choice alternatives is greater than 2. At all places in the assembler program where the choice is not deterministic, there should be used certain fixed number of choice alternatives greater than 1.

Consider the following example with a jprob instruction:

        user    0               ; a user instruction
        jprob   var0, L1
        jmp     L2

If the number of alternatives of non-deterministic choices at all places in the assembler program is equal to 2, then correct values of controlled probability variable var0 will be 0, 0.5, and 1. Value 0 specifies deterministic jump to location label L2, value 1 specifies deterministic jump to location label L1, and value 0.5 provides two jump alternatives, which corresponds to the actual number of actor’s output signals equal to 2. The concept of the actual number of output signals is described in Other Parameters of an Actor.

Consider the following example with a choice instruction block:

        user    0               ; a user instruction

        choice
        case    var1, L1
        case    0.25, L2
        case    var3, L3
        case    var4, L4
        case    var5, L5
        case    var6, L6
        case    var7, L7
        end     choice

        jmp     L8

Correct sets of values of controlled probability variables var1, var3, var4, var5, var6, and var7 are the sets in which exactly two or three variables have values 0.25 and all other variables have values 0. Such sets correspond to the actual number of actor’s output signals equal to 4, which should be the number of alternatives of every non-deterministic choice made in the assembler program.


Next: , Previous: , Up: Using Probability Variables   [Contents][Index]