stt Instruction (QSMM Programmer Manual)

5.3.5 `stt` Instruction

This instruction has the following forms:

        stt
        stt     state_name

They are equivalent to the notation

        stt     [state_name]

The instruction marks the beginning of a state of an assembler program. The state biuniquely corresponds to a state of a node with this assembler program loaded. Both states can have a name specified by a (quoted) string literal state_name. An assembler program must not contain states with duplicate names. See Loading a Parsed Program into a Node, for the description of qsmm_get_node_state_name and qsmm_get_node_state_by_name functions retrieving the name of a node state by its index and retrieving the index of a node state by its name.

The stt instruction chooses the action emission matrix to hold profile probabilities specified by certain other instructions in an assembler program. Without the stt instruction, those other instructions would specify profile probabilities held in the state transition matrix.

The action emission matrix can have the restriction to define only deterministic choices of user and mixed-type instructions in all node states. In this case, all jprob and case instructions in an assembler program specify profile probabilities held in the state transition matrix—if there is no need to assign a name to a state, you can omit an stt instruction marking the beginning of this state.

If the action emission matrix does not have the restriction to define only deterministic choices of user and mixed-type instructions in all node states, omitting an stt instruction in an assembler program causes an unprocessed instruction or a nop instruction implicitly inserted before the unprocessed instruction to become the beginning of the next state. To prevent this undesired behavior, the best practice is to specify stt instructions for all states in the assembler program to know exactly where each state begins. To support this approach, the assembler can generate a warning for every location where a state begins, but an stt instruction is missing there. Note that inserting stt instructions into an assembler program may require rearranging the assembler program.

There are three possible types of places where you can insert an stt instruction.

Before a user instruction or mixed-type instruction:
```
        stt     [state_name]
        user or mixed-type instruction
```
This instruction arrangement means that in a state marked by the stt instruction the instruction emitting engine emits a specified user or mixed-type instruction. The user or mixed-type instruction must not have a location label assigned on condition that a jump from elsewhere to this label exists.

As a result of assembling this instruction arrangement, the action emission matrix defines deterministic choice of this user or mixed-type instruction in this state. The action emission matrix contains profile probability 1 for this state and this user or mixed-type instruction and profile probability 0 for this state and all other user and mixed-type instructions.

If you need to mark the beginning of a state, but there is no effective user or mixed-type instruction to insert beneath the stt instruction, you may insert the nop or nop1 instruction instead of such user or mixed-type instruction.
Before a block of jprob instructions:
```
        stt     [state_name]
        jprob   prob1, L1
        jprob   prob2, L2
        ...
        jprob   probN, LN
        user or mixed-type instruction 0
        ...
```
```
L1:     user or mixed-type instruction 1
        ...
L2:     user or mixed-type instruction 2
        ...
LN:     user or mixed-type instruction N
        ...
```
This instruction arrangement means that in a state marked by the stt instruction the instruction emitting engine emits one of specified user or mixed-type instructions. All those user and mixed-type instructions must belong to different instruction classes, that is, have different combinations of an instruction name and instruction parameters. None of jprob instructions just after the stt instruction must have location labels assigned on condition that jumps from elsewhere to these labels exist.

As a result of assembling this instruction arrangement, the action emission matrix contains the profile probabilities of emitting all specified user or mixed-type instructions in the state and contains profile probability 0 of emitting all other user and mixed-type instructions in this state. However, in the general case, the profile probabilities of emitting the specified user and mixed-type instructions are different from profile probabilities indicated in the corresponding jprob instructions. For more information, see an example block of jprob instructions in jprob Instruction.
Before a choice instruction block:
```
        stt     [state_name]

        choice
        case    prob1, L1
        case    prob2, L2
        ...
        case    probN, LN
        end     choice

        user or mixed-type instruction 0
        ...
```
```
L1:     user or mixed-type instruction 1
        ...
L2:     user or mixed-type instruction 2
        ...
LN:     user or mixed-type instruction N
        ...
```
This instruction arrangement means that in a state marked by the stt instruction the instruction emitting engine emits one of specified user or mixed-type instructions. All those user and mixed-type instructions must belong to different instruction classes, that is, have different combinations of an instruction name and instruction parameters. The choice instruction after the stt instruction must not have a location label assigned on condition that a jump from elsewhere to this label exists. Do not assign location labels to case instructions in the choice instruction block.

As a result of assembling this instruction arrangement, the action emission matrix contains the profile probabilities of emitting all specified user or mixed-type instructions in the state and contains profile probability 0 of emitting all other user and mixed-type instructions in this state. The profile probabilities of emitting the specified user and mixed-type instructions excluding the profile probability of emitting a user or mixed-type instruction beneath the choice instruction block are equal to profile probabilities indicated in the corresponding case instructions.

Adhere to the following assembler program structure after every user or mixed-type instruction in the above three instruction arrangement schemes:

The locations of joe instruction blocks. A contiguous block of joe instructions can follow a user or mixed-type instruction. Those joe instructions analyze the outcome of this user or mixed-type instruction.
The jump targets of joe instructions. Every joe instruction specifies a (conditional) jump to a contiguous block of jprob instructions or to a choice instruction block or to the beginning of a state.
Instructions after a joe instruction block. One of these assembler text fragments follows a contiguous block of joe instructions:
1. A contiguous block of jprob instructions.
2. A choice instruction block.
3. A jmp instruction transferring control to a state.
4. The beginning of another state.
Specifying state transition probabilities. A contiguous block of jprob instructions or a choice instruction block with case instructions can be the jump target of a joe instruction or can follow a contiguous block of joe instructions. Those jprob or case instructions specify probabilities stored in the state transition matrix. The jump targets of those jprob or case instructions are the beginnings of states.
What follows a specification of state transition probabilities. The beginning of a different state or a jmp instruction transferring control to a state follows a contiguous block of jprob instructions or a choice instruction block if they specify state transition probabilities.

The following example illustrates the described assembler program structure.

        user or mixed-type instruction X

        ; A contiguous block of `joe' instructions. They analyze the
        ; outcome of user or mixed-type instruction X.
        ;
        ; Each of L1, L2, ..., LN labels transfers control to the
        ; beginning of one of the following:
        ; - a contiguous block of `jprob' instructions;
        ; - a `choice' instruction block;
        ; - a state.

        joe     outcome1, L1
        joe     outcome2, L2
        ...
        joe     outcomeN, LN

        joe     outcomeN1, LN1          ; The conditional jump to a sample
                                        ; contiguous block of `jprob'
                                        ; instructions.

        joe     outcomeN2, LN2          ; The conditional jump to a sample
                                        ; `choice' instruction block.

        ; An optional contiguous block of `jprob' instructions (can also be
        ; a `choice' instruction block). They specify the probabilities of
        ; transitions to states for the source state, user or mixed-type
        ; instruction X emitted in that source state, and any outcome
        ; of user or mixed-type instruction X different from outcome1,
        ; outcome2, ..., outcomeN, outcomeN1, and outcomeN2.
        ;
        ; Labels SA1, SA2, ..., SAN, and SANN transfer control to the
        ; beginnings of states.


        jprob   probA1, SA1
        jprob   probA2, SA2
        ...
        jprob   probAN, SAN
        jmp     SANN

        ; A sample `choice' instruction block. It specifies the
        ; probabilities of transitions to states for the source state, user
        ; or mixed-type instruction X emitted in that source state, and
        ; outcome outcomeN2 of user or mixed-type instruction X.
        ;
        ; Labels SB1, SB2, ..., SBN, and SBNN transfer control to the
        ; beginnings of states.


LN2:    choice
        case    probB1, SB1
        case    probB2, SB2
        ...
        case    probBN, SBN
        end     choice

        jmp     SBNN

        ; A sample contiguous block of `jprob' instructions. They specify
        ; the probabilities of transitions to states for the source state,
        ; user or mixed-type instruction X emitted in that source state,
        ; and outcome outcomeN1 of user or mixed-type instruction X.
        ;
        ; Labels SC1, SC2, ..., SCN, and SCNN transfer control to the
        ; beginnings of states.


LN1:    jprob   probC1, SC1
        jprob   probC2, SC2
        ...
        jprob   probCN, SCN

        jmp     SCNN                    ; This instruction is not necessary
                                        ; if it specifies the jump to a
                                        ; state going just after this line.

        ; The beginning of another state.

After a user or mixed-type instruction there can be no joe instructions at all. In this case, one of these assembler text fragments should immediately follow this user or mixed-type instruction:

A contiguous block of jprob instructions.
A choice instruction block.
A jmp instruction transferring control to a state.
The beginning of another state.

The following example illustrates this instruction arrangement.

        user or mixed-type instruction Y

        ; An optional contiguous block of `jprob' instructions (can also be
        ; a `choice' instruction block). They specify the probabilities of
        ; transitions to states for the source state, user or mixed-type
        ; instruction Y emitted in that source state, and any possible
        ; outcome of user or mixed-type instruction Y.
        ;
        ; Labels S1, S2, ..., SN, and SNN transfer control to the
        ; beginnings of states.


        jprob   prob1, S1
        jprob   prob2, S2
        ...
        jprob   probN, SN
        jmp     SNN                     ; This instruction is not necessary
                                        ; if it specifies the jump to a
                                        ; state going just after this line.

        ; The beginning of another state.

Adherence to the described assembler program structure simplifies understanding how the assembler converts an assembler program to a probability profile stored in the state transition matrix and action emission matrix of a node. This understanding is necessary to develop an assembler program for a node capable of efficient training.

5.3.5 stt Instruction

5.3.5 `stt` Instruction