During the execution of a multinode model, its nodes execute instructions.
When a node has to invoke an instruction, the node triggers an event QSMM_EVT_ACTIVATE of the instruction meta-class of the instruction.
On triggering the event QSMM_EVT_ACTIVATE, the function qsmm_node_call_default passes the identifier of the node to the event handler of that instruction meta-class via mehcall->node, where mehcall is the argument of that event handler.
The event handler can fetch binary instruction class parameters for the instruction by calling the function qsmm_get_mehcall_instr_param_bin.
The function qsmm_get_mehcall_instr_class_set retrieves the name of an instruction class set containing the instruction class.
Use the following call to fetch from the current frame of node call stack (see Working with the Node Call Stack) index idx that uniquely identifies the instruction class in the instruction class set:
qsmm_get_mehcall_stack_instr_class(mehcall,0,&idx);
While processing an event QSMM_EVT_ACTIVATE, the event handler of an instruction meta-class can perform custom effective work or:
qsmm_set_mehcall_outcome.
This operation is mandatory in certain cases.
qsmm_actor_spur_delta and qsmm_actor_time_delta_v2 called for the environment state identification engine or instruction emitting engine.
qsmm_node_call_default.
See Calling a Node.
qsmm_set_mehcall_return.
See Returning Control from a Node.
qsmm_set_continue or macro QSMM_TERMINATE.
See Terminating Model Execution.
qsmm_get_mehcall_stack_frame.
See Working with the Node Call Stack.
qsmm_set_la_sig.
See Setting Look-Ahead Signals.
qsmm_set_instr_class_weight and qsmm_set_instr_class_weight_by_name_f.
See Setting Instruction Classes Weights.
An instruction outcome affects the selection of next node state after an instruction invocation. Use the following functions to query or set an instruction outcome.
int qsmm_get_mehcall_outcome (qsmm_mehcall_t mehcall, qsmm_sig_t *outcome_p) ¶This function retrieves an instruction outcome associated with an event QSMM_EVT_ACTIVATE sent to the event handler of an instruction meta-class, where mehcall is an argument of that event handler passing information about the event.
If outcome_p is not NULL, the function sets *outcome_p to a retrieved outcome.
An instruction outcome associated with the event is the last instruction outcome set by the function qsmm_set_mehcall_outcome while handling the event.
If there was no call to qsmm_set_mehcall_outcome, and the instruction class has a positive number of outcomes, the instruction outcome returned is QSMM_SIG_INVALID.
If there was no call to qsmm_set_mehcall_outcome, and the instruction class has zero number of outcomes, instruction outcome returned is the outcome of the previous instruction invoked by the node after transferring control to it or 0 if there was no such instruction.
On success, the function returns a non-negative value.
If the context of calling the function is not the event handler of an instruction meta-class on processing an event QSMM_EVT_ACTIVATE, the function returns negative error code QSMM_ERR_UNTIMELY.
int qsmm_set_mehcall_outcome (qsmm_mehcall_t mehcall, qsmm_sig_t outcome) ¶This function sets to outcome instruction outcome associated with an event QSMM_EVT_ACTIVATE sent to the event handler of an instruction meta-class, where mehcall is an argument of that event handler passing information about the event.
The function performs only a preliminary check on the validity of that outcome.
The function qsmm_node_call_default performs final checks after a return from the event handler, and, if the outcome is invalid, that function reports QSMM_ERR_OUTCOME.
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_INVALThe argument outcome is greater than or equal to QSMM_SIG_MAX and is not QSMM_SIG_INVALID.
QSMM_ERR_UNTIMELYThe context of calling the function is not the event handler of an instruction meta-class on processing an event QSMM_EVT_ACTIVATE.
The function qsmm_set_mehcall_noutcome specifies the number of instruction outcomes during instruction class initialization (on processing an event QSMM_EVT_INSTR_CLASS_INIT by the event handler of an instruction meta-class).
The default number of instruction outcomes used in case of omitting a call to that function is equal to 1.
The number of instruction outcomes equal to 0 has special meaning.
Before calling the event handler of an instruction meta-class to process an event QSMM_EVT_ACTIVATE, the function qsmm_node_call_default sets instruction outcome associated with the event to QSMM_SIG_INVALID if the instruction class has a positive number of outcomes.
If the instruction class has zero number of outcomes, qsmm_node_call_default sets instruction outcome associated with the event to the outcome of the previous instruction invoked by the node after transferring control to it or to 0 if there was no such instruction.
After calling the event handler of an instruction meta-class to process an event QSMM_EVT_ACTIVATE, if node execution continues, instruction outcome associated with the event is QSMM_SIG_INVALID, and the number of outcomes of the instruction class is equal to 1, qsmm_node_call_default uses outcome 0 to select the next node state.
This behavior makes it possible to omit calls to the function qsmm_set_mehcall_outcome for instruction classes with only one possible instruction outcome.
If after calling the event handler node execution continues, instruction outcome associated with the event is QSMM_SIG_INVALID, and the number of outcomes of the instruction class is not equal to 1, qsmm_node_call_default reports QSMM_ERR_OUTCOME.
This check compels to set an instruction outcome by qsmm_set_mehcall_outcome if the number of outcomes of the instruction class is greater than 1.
If the instruction class has zero number of outcomes, the event handler of a corresponding instruction meta-class can call the function qsmm_get_mehcall_outcome on processing an event QSMM_EVT_ACTIVATE to analyze the outcome of the previous instruction invoked by the node after transferring control to it.
The event handler can leave that outcome intact or change it to a value less than the maximum number among numbers of outcomes of instruction classes in the instruction class set of that node.
The functions described below return the probability of the last state transition for a currently executed node and the probability of the last instruction emission in a current node state.
The probabilities have the type QSMM_PROB_AGGR and are in the cells of the state transition matrix and action emission matrix of the node.
You can call the functions while processing an event QSMM_EVT_ACTIVATE by the event handler of an instruction meta-class, for example, to compute the time when an instruction has to take effect.
double qsmm_get_mehcall_prob_goto (qsmm_mehcall_t mehcall) ¶This function returns the probability of the last state transition performed just before the last instruction invocation.
That probability has the type QSMM_PROB_AGGR and is in a cell of a state transition matrix.
You should call the function from within an event handler, where mehcall is its argument.
If a model instance does not exist, or model nodes did not yet invoke instructions, the function returns 0.
A returned value is always in the range 0 to 1 inclusive.
double qsmm_get_mehcall_prob_action (qsmm_mehcall_t mehcall) ¶This function returns the probability of the last instruction emission in a current node state just after performing the last state transition.
That probability has the type QSMM_PROB_AGGR and is in a cell of an action emission matrix.
You should call the function from within an event handler, where mehcall is its argument.
If a model instance does not exist, or model nodes did not yet invoke instructions, the function returns 0.
A returned value is always in the range 0 to 1 inclusive.
To make it possible for a multinode model to adapt and improve its behavior, a program supplies spur and continuous time increments to the environment state identification engine or instruction emitting engine while handling instruction invocations.
Use the following lines of code to supply a spur increment and continuous time increment to the environment state identification engine from within an event handler function, where qsmm is its argument.
int rc;
const qsmm_actpair_t actpair=qsmm_get_actpair(qsmm);
const qsmm_actor_t actor_env=qsmm_get_actpair_actor(actpair,
QSMM_ENGINE_ENV);
if ((rc=
qsmm_actor_spur_delta(actor_env, spur_type,
spur_delta))<0)
REPORT_ERROR(rc);
if ((rc=
qsmm_actor_time_delta_v2(actor_env, time_type, 0,
time_delta))<0)
REPORT_ERROR(rc);
Use similar lines of code to supply a spur increment and continuous time increment to an instruction emitting engine.
const qsmm_actor_t actor_iee=qsmm_get_actpair_actor(actpair,
QSMM_ENGINE_IEE);
if ((rc=
qsmm_actor_spur_delta(actor_iee, spur_type,
spur_delta))<0)
REPORT_ERROR(rc);
if ((rc=
qsmm_actor_time_delta_v2(actor_iee, time_type, 0,
time_delta))<0)
REPORT_ERROR(rc);