You can convert the state transition matrix and action emission matrix of a node to an assembler program—disassemble the node. You typically disassemble a node after executing or training it.
Before executing a node, you can load into it an assembler program specifying a probability profile for the state transition matrix and action emission matrix.
To simplify the analysis of results of training a node by disassembling the node, it might be desirable to obtain a disassembled program as an assembler program previously loaded into the node, but with profile probabilities in jprob and case instructions changed to probabilities learned while training the node.
To turn on this mode—disassembling using an assembler program template,—pass the QSMM_ASM_TEMPLATE flag to the function qsmm_node_asm when loading an assembler program into a node you are going to disassemble later (see Loading a Parsed Program into a Node).
If a node does not have an assembler program loaded, or the node has an assembler program loaded without specifying the QSMM_ASM_TEMPLATE flag, you disassemble the node without using an assembler program template.
Use the following function to disassemble a node.
int qsmm_node_disasm (qsmm_t model, qsmm_sig_t node, struct qsmm_disasm_desc_s *desc_p, qsmm_prg_t *prg_p) ¶This function disassembles a node of a multinode model and stores the allocated handle of a disassembled program in *prg_p if prg_p is not NULL.
The argument node specifies the identifier of the node.
If desc_p is not NULL, *desc_p specifies disassembling parameters.
If desc_p is NULL, the function uses default disassembling parameters.
If the function qsmm_node_asm previously assembled the node with the QSMM_ASM_TEMPLATE flag, or the node uses a source probability profile provided by another node assembled with the QSMM_ASM_TEMPLATE flag, the disassembled program is a template assembler program with replaced probabilities in jprob and case instructions.
If desc_p is not NULL, probabilities of desc_p->prob_type type replace profile probabilities in the jprob and case instructions.
If desc_p is NULL, probabilities of QSMM_PROB_AGGR type replace the profile probabilities.
In the current implementation the function does not modify *desc_p if desc_p is not NULL.
However, in a future implementation the function may modify *desc_p, for example, to store there statistics on the disassembling process.
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_NOTFOUNDA node with identifier node does not exist.
QSMM_ERR_INVALThe argument desc_p is not NULL, and parameters in *desc_p are invalid.
QSMM_ERR_UNTIMELYThe model instance does not exist.
QSMM_ERR_CALLBACKA helper function for computing the relative probability of an output signal reported an error by returning NaN.
The function qsmm_actor_calc_action_prob calls the helper function.
QSMM_ERR_STORAGEA Storage API function reported storage failure.
QSMM_ERR_STATSInconsistent statistics on an action choice state or cycle type detected.
QSMM_ERR_ILSEQUnable to convert a multibyte string to a wide string or vice versa according to a current locale.
QSMM_ERR_NOMEMThere was not enough memory to perform the operation.
Errors QSMM_ERR_CALLBACK, QSMM_ERR_STORAGE, QSMM_ERR_STATS, QSMM_ERR_ILSEQ, and QSMM_ERR_NOMEM can leave the model instance in inconsistent state.
If after removing a reason of an error a repeated call to this function succeeds, the instance’s state becomes consistent.
The description of a structure passed to the function qsmm_node_disasm is below.
This structure specifies the parameters of disassembling. The structure contains the following fields.
char use_stt_start ¶If not 0, generate an stt instruction at the beginning of an assembler program if it started with a lookup instruction, and generate stt and nop1 instructions at the beginning of an assembler program if it started with a jprob instruction or choice instruction block.
The default is not to generate.
The disassembler ignores this field when disassembling a node using an assembler program template.
char use_stt_state ¶If not 0, generate an stt instruction at the beginning of each state.
The default is not to generate.
The disassembler ignores this field when disassembling a node using an assembler program template.
char use_stt_lookup ¶If not 0, generate stt instructions before lookup instructions.
The default is not to generate.
The disassembler ignores this field when disassembling a node using an assembler program template.
char use_stt_abort ¶If not 0, generate stt instructions before abort instructions.
This is not very useful unless there is not more than one abort instruction in an assembler program (the field use_abort_1 sets this mode).
The default is not to generate.
The disassembler ignores this field when disassembling a node using an assembler program template.
char use_choice ¶If not 0, generate choice instruction blocks instead of contiguous blocks of jprob instructions when the number of jprob instructions in a block is greater than one.
The default is to generate.
The disassembler ignores this field when disassembling a node using an assembler program template.
char use_abort_1 ¶If is 0, and there is no information what to execute after an individual user or mixed-type instruction or a sequence of user or mixed-type instructions, generate an abort instruction at this location.
If not 0, generate a jump at this location to a single abort instruction at the end of an assembler program and generate a jump to its start after the abort instruction.
If not 0, and there are no jumps to the abort instruction at program end, skip generating that abort instruction followed by a jump to program start.
The default is to generate an abort instruction after an individual user or mixed-type instruction or a sequence of user or mixed-type instructions.
The disassembler ignores this field when disassembling a node using an assembler program template.
char comment_state_idx ¶[New in QSMM 1.19] If not 0, add a comment containing a state index above the beginning of each state. If is 0, do not add the comments. The default is to add the comments. The disassembler ignores this field when disassembling a node using an assembler program template.
char comment_fq ¶[New in QSMM 1.19] If not 0, add (where possible) comments containing numbers of state activations, instruction invocations, and jumps performed. If is 0, do not add the comments. The default is to add the comments. The disassembler ignores this field when disassembling a node using an assembler program template.
char do_calc_prob[QSMM_PROB_COUNT] ¶An array specifying additional types of probabilities to calculate for jprob and case instructions optionally printed in comments to the right of them.
Array indices are the elements of qsmm_prob_e enumeration (except for its last element) described in Emitting an Output Signal.
If an array element is non-zero, the disassembler calculates probabilities of a corresponding type and stores them in the instructions.
The disassembler calculates probabilities of a type specified in the field prob_type regardless of do_calc_prob field.
The default is not to calculate probabilities of additional types.
long fq_goto_min ¶The minimum number of nondeterministic transitions to a target state for a quadruple consisting of a source state, an individual user or mixed-type instruction or a sequence of user or mixed-type instructions emitted in the source state, an instruction outcome, and the content of look-ahead signal segment. The disassembler discards nondeterministic transitions performed lesser numbers of times. The default minimum number of nondeterministic transitions is 0. The disassembler ignores this field when disassembling a node using an assembler program template.
long fq_action_min ¶The minimum number of nondeterministic invocations of an individual user or mixed-type instruction or a sequence of user or mixed-type instructions in a state. The disassembler discards individual user or mixed-type instructions or sequences of user or mixed-type instructions nondeterministically invoked lesser numbers of times. The default minimum number of nondeterministic invocations is 0. The disassembler ignores this field when disassembling a node using an assembler program template.
double prob_goto_min ¶A minimum probability for jprob and case instructions corresponding to the state transition matrix.
The disassembler removes instructions containing lesser probabilities from a disassembled program.
The field prob_type specifies the type of analyzed probabilities.
The default minimum probability is 0.
When disassembling a node without using an assembler program template, the disassembler removes the instructions after discarding nondeterministic state transitions with lesser frequencies according to the field fq_goto_min and renormalizing state transition probabilities.
double prob_action_min ¶A minimum probability for jprob and case instructions corresponding to the action emission matrix.
The disassembler removes instructions containing lesser probabilities from a disassembled program.
The field prob_type specifies the type of analyzed probabilities.
The default minimum probability is 0.
When disassembling a node without using an assembler program template, the disassembler removes the instructions after discarding nondeterministic instruction invocations with lesser frequencies according to the field fq_action_min and renormalizing instruction invocation probabilities.
qsmm_sig_t n_retain_goto_max ¶[New in QSMM 1.19] The retained number of most probable transitions to target states for a quadruple consisting of a source state, an individual user or mixed-type instruction or a sequence of user or mixed-type instructions emitted in the source state, an instruction outcome, and the content of look-ahead signal segment.
The disassembler discards less probable state transitions after discarding nondeterministic state transitions with lesser frequencies according to the field fq_goto_min and renormalizing state transition probabilities.
The field prob_type specifies the type of analyzed probabilities.
If n_retain_goto_max is equal to 0, the disassembler retains all state transitions.
The default is to retain all state transitions.
The disassembler ignores this field when disassembling a node using an assembler program template.
qsmm_sig_t n_retain_action_max ¶[New in QSMM 1.19] The retained number of most probable invocations of individual user or mixed-type instructions or sequences of user or mixed-type instructions in a state.
The disassembler discards less probable instruction invocations after discarding nondeterministic instruction invocations with lesser frequencies according to the field fq_action_min and renormalizing instruction invocation probabilities.
The field prob_type specifies the type of analyzed probabilities.
If n_retain_action_max is equal to 0, the disassembler retains all instruction invocations.
The default is to retain all instruction invocations.
The disassembler ignores this field when disassembling a node using an assembler program template.
enum qsmm_prob_e prob_type ¶The type of state transition and instruction invocation probabilities for discarding less probable state transitions and instruction invocations according to the fields n_retain_goto_max and n_retain_action_max.
The type of probabilities to calculate for jprob and case instructions.
The disassembler compares the probabilities in jprob and case instructions with probabilities in the fields prob_goto_min and prob_action_min to determine whether to discard specific jprob and case instructions.
When disassembling a node without using an assembler program template, this field specifies the type of probabilities for sorting jprob and case instructions in descending order within corresponding instruction blocks.
See Emitting an Output Signal, for the description of elements of qsmm_prob_e enumeration.
The default type of probabilities is QSMM_PROB_AGGR.
Zero by the function memset an instance of qsmm_disasm_desc_s structure before setting its fields.
See below for a list of types of comments generated when disassembling a node without using an assembler program template.
Note that the disassembler cannot obtain numbers of deterministic instruction invocations and deterministic state transitions for putting in comments because the function qsmm_node_call_default does not increment the numbers on deterministic selection of instructions and target states.
The disassembler generates this comment if the field comment_state_idx of qsmm_disasm_desc_s structure is non-zero.
If all invocations of individual user or mixed-type instructions or sequences of user or mixed-type instructions in a state are nondeterministic, the number of state activations is equal to the sum of numbers of all invocations. If there is a deterministic invocation, and all transitions from the state are nondeterministic, the number of state activations is equal to the sum of numbers of all transitions from the state. If there is a deterministic invocation, and there is at least one deterministic transition from the state, the disassembler does not add this comment.
The disassembler generates the comment only if the field comment_fq of qsmm_disasm_desc_s structure is non-zero.
If the invocation is nondeterministic, the disassembler uses available number of invocations. If the invocation is deterministic, and all transitions from the state after the invocation are nondeterministic, the number of invocations is equal to the sum of numbers of transitions from the state. If the invocation is deterministic, and there is at least one deterministic state transition, the disassembler does not add this comment.
The disassembler generates the comment only if the field comment_fq of qsmm_disasm_desc_s structure is non-zero.
joe instruction or a jmp instruction after analyzing an instruction outcomeThe disassembler generates this comment if the field comment_fq of qsmm_disasm_desc_s structure is non-zero, and the joe or jmp instruction transfers control to a block of jprob instructions or a choice instruction block performing nondeterministic transitions to target states.
jprob or case instructionThe disassembler generates this comment if the field comment_fq of qsmm_disasm_desc_s structure is non-zero.
jmp instruction at the end of a block of jprob instructions or a choice instruction block transferring control to target statesThe disassembler generates this comment if the field comment_fq of qsmm_disasm_desc_s structure is non-zero.
Note: numbers of state activations, instruction invocations, and jumps performed may be inconsistent among themselves if the disassembler discarded some instructions according to disassembling parameters.
To generate the most probable completely deterministic program when disassembling a node without using an assembler program template, set to 1 the fields n_retain_goto_max and n_retain_action_max of qsmm_disasm_desc_s structure.
Below there is an example of calling the function qsmm_node_disasm to generate a program for subsequent assembling.
A disassembled node does not have an assembler program loaded.
qsmm_prg_t prg=0; struct qsmm_disasm_desc_s disasm_desc; memset(&disasm_desc,0,sizeof(disasm_desc)); // Insert `stt' instructions in appropriate places. disasm_desc.use_stt_start=1; disasm_desc.use_stt_state=1; disasm_desc.use_stt_lookup=1; disasm_desc.use_stt_abort=1; // Improve the readability of probabilistic jumps. disasm_desc.use_choice=1; // Simplify handling unexplored control paths. disasm_desc.use_abort_1=1;
// Do not generate never executed code. disasm_desc.fq_goto_min=1; disasm_desc.fq_action_min=1;
// Remove `jprob' and `case' instructions with // rounded probabilities less than 1%. disasm_desc.prob_goto_min=0.005; disasm_desc.prob_action_min=0.005; qsmm_node_disasm(qsmm,node,&disasm_desc,&prg);
An example of calling the function qsmm_node_disasm for a node assembled with the QSMM_ASM_TEMPLATE flag occupies a lesser number of lines because the disassembler uses a small subset of fields of qsmm_disasm_desc_s structure in this mode.
qsmm_prg_t prg=0; struct qsmm_disasm_desc_s disasm_desc; memset(&disasm_desc,0,sizeof(disasm_desc));
// Remove `jprob' and `case' instructions with // rounded probabilities less than 1%. disasm_desc.prob_goto_min=0.005; disasm_desc.prob_action_min=0.005; qsmm_node_disasm(qsmm,node,&disasm_desc,&prg);
Refer to the files tests/disasm2.c and tests/lookup2.c for the methods of assembling a previously disassembled program.