Q1ASM User guide

Q1ASM is an assembly language used to program the sequencers.

Assembly syntax

An assembly source file consists of a sequence of lines. Each line contains a directive or a code instruction (optionally followed by a comment), or a comment.

• Case Sensitivity: The entire syntax is case-sensitive.

• Comments: Begin with a hash symbol (#). The assembler ignores all comments.

Directives

The .DEF directive creates a user-defined alias. .DEF <name> <value> allows you to assign a symbolic <name> to a <value>.

• <name>: Starts with a letter (cannot start with a number). Consists of uppercase/lowercase letters and/or numbers.

• <value>: The string literal that will replace <name>. Can be any string (e.g., 42, R63).

Code

A source line has the following format:

[label:] instruction argument,argument,... [comment]

Fields are separated by whitespace (spaces or tabs). Operands may also be separated by whitespace.

Arguments

Q1ASM instructions use the following types of arguments:

Type	Acronym	Format	Description
Immediate	I	#	32-bit decimal or hexadecimal value (e.g. 1000, -42, 0x3a)
Register	R	R#	Register address in range 0 to 63 (e.g. R0), containing a 32-bit value.

Labels

Labels are used to mark addresses for program flow control (e.g., for jumps and loops). A label is defined by placing an identifier followed by a colon :. e.g. mylabel:

• Any instruction can be preceded by a label.

• Labels can be placed on a separate line (See the Q1 core section for an example).

Label references

A label is referenced by placing an at-symbol @ followed by the label’s name. e.g. mylabel: is referred as @mylabel.

• A label reference has to be an immediate argument.

• Forward references are allowed, meaning you can refer to a label before it is defined.

Alias references

An alias is referenced by placing a dollar sign $ followed by the alias’s name.

Tip

Example

.DEF                SQG_TIME                100         # Time in ns for single qubit gate

wait                $SQG_TIME

• An alias reference can be immediate or register argument.

• Forward references are not allowed; the .DEF must appear before the alias is used.

Instructions

A sequencer consists of the Q1 core and the real-time (RT) core. The Q1 core pushes instructions to a queue, which are then executed by the RT core. See Q1 instructions and RT instructions for more specific instructions.

The total duration of an experiment, or its wall-time, is determined only by the duration argument of RT instructions. The Q1 core’s processing time is only relevant if it cannot prepare instructions fast enough to keep the RT core busy.

If the RT queue runs empty, the sequencer will halt and raise an error.

In the tables below, the arguments of an instruction are specified as arg0_name: type. An instruction may have multiple allowed combinations of arguments, which are specified on separate lines.

Q1 Instructions

Core Instructions

Instruction	Execution time (ns)	Description of instruction
illegal	4	An invalid instruction. If executed, the sequencer halts with an error.
stop	4	Stops the sequencer.
nop	4	No operation. Does nothing for one Q1 clock cycle.

Jump Instructions

For jump instructions, the immediate is generally a label, representing the instruction address of the following instruction. The functionality of jumping to addresses stored in registers can be used for creating subroutines, to add offsets to labels, writing case tables, and so on.

Instruction	Signature	Execution time (ns)	Description of instruction
jmp	address: I address: R	16 16	Jumps to the instruction at address.
jge	a: R, b: I, address: I a: R, b: I, address: R	24 on jump, 12 on continue	If a \(\ge\) b, jumps to address.
jlt	a: R, b: I, address: I a: R, b: I, address: R	24 on jump, 12 on continue	If a \(\le\) b, jumps to address.
loop	a: R, b: I, address: I a: R, b: I, address: R	24 on jump, 12 on continue	Decrements a by one. If the result is not zero, jumps to address.

Note

For jump instructions, register values are treated as an unsigned 32-bit integers.

Arithmetic Instructions

Instruction	Signature	Execution time (ns)	Description
move	source: I, destination: R source: R, destination: R	4 4	Move/copy source to destination. destination = source
not	source: I, destination: R source: R, destination: R	12 12	Bitwise invert source and move the result to destination. destination = ~source
add	a: R, b: I, destination: R a: R, b: R, destination: R	12 16	Add b to a and move the result to destination. destination = a + b
sub	a: R, b: I, destination: R a: R, b: R, destination: R	12 16	Subtract b from a and move the result to destination. destination = a - b
and	a: R, b: I, destination: R a: R, b: R, destination: R	12 16	Bitwise AND a and b and move the result to destination. destination = a & b
or	a: R, b: I, destination: R a: R, b: R, destination: R	12 16	Bitwise OR a and b and move the result to destination. destination = a | b
xor	a: R, b: I, destination: R a: R, b: R, destination: R	12 16	Bitwise XOR a and b and move the result to destination. destination = a ^ b
asl	a: R, b: I, destination: R a: R, b: R, destination: R	12 16	Bitwise left-shift a by b bits and move the result to destination. destination = a << b
asr	a: R, b: I, destination: R a: R, b: R, destination: R	12 16	Bitwise right-shift a by b bits and move the result to destination. destination = a >> b

Note

For arithmetic instructions, the register value is treated as an unsigned 32-bit integer.

Immediates must be in the range [0, 4294967295].

To use a negative number, move 0 to a register and then subtract the desired positive value from it. Alternatively, directly use the 2’s complement form of the number.

Latched Instructions

Some instructions like set_awg_offs and set_freq change special latched registers in the FPGA. The new values are “latched” (held) until a subsequent RT instruction (like upd_param or play) applies them to a sequencer. More information can be found here.

Instruction	Signature	Execution Time (ns)	Description
set_cond	enable: I, mask: I, operator: I, else_duration: I enable: R, mask: R, operator: R, else_duration: I	4 12	Configures the condition for following RT instructions. If the condition is true, the RT instruction is executed. Else, the RT core waits for else_duration and moves on to the next instruction in the RT queue. See trigger handling for more information. Caution: The minimum time between the start of wait_trigger and set_cond is 8 ns.

Control/Readout Latched Instructions

All parameters below are latched and only updated when a real-time instruction (like upd_param or play) is executed. The wait real-time instruction does not update latched parameters.

To understand the functionalities of the instructions that follow, let us model the total phase of the NCO as defined in the control sequencer page.

\(\phi_\text{acc}(t) = 2\pi f t' + \Phi + \phi\)

Hereon, by accumulated phase we mean \(\phi_\text{acc}\), by phase we mean \(\phi_0\), and by phase kick we refer to \(\delta\phi\).

Control/Readout latched instructions

Instruction	Signature	Execution Time (ns)	Description
set_mrk	mask: I mask: R	4 4	Set marker output channels to mask (bits 0–3), where the bit index corresponds to the channel index for baseband modules. For example, set_mrk {0b0001} sets marker M1 high. For QCM-RF modules: bit indices 0 & 1 correspond to enabling output 1 and 2 switches; indices 2 & 3 correspond to marker output 2 and 1 (sic!) respectively. For example, set_mrk {0b0110} turns on the output 2 switch and sets marker M2 high. For QRM-RF modules: bit index 0 is inactive; bit index 1 corresponds to enabling output 1 switch; indices 2 & 3 correspond to marker output 1 and 2 (sic!) respectively. For example, set_mrk {0b0110} turns on the output 1 switch and sets marker M1 high. The values are OR’ed with those of other sequencers. The mask is overridden if ControlSequencer.marker_ovr_en() is True. In this case, the ControlSequencer.marker_ovr_value() sets the 4 bits.
set_freq	value: I value: R	4 4	Sets the NCO frequency (f) to value. The frequency is set using an integer between –\(2 \times 10^9\) and \(2 \times 10^9\), which corresponds to a range of –500 and 500 MHz. This provides \(4 \times 10^9\) discrete steps, where 1 MHz is represented by the integer \(4 \times 10^6\).
reset_ph	—	4	Resets the NCO’s accumulated phase to zero. by setting \(t' \rightarrow 0\), \(\Phi \rightarrow 0\) and \(\Phi \rightarrow 0\).
set_ph	value: I value: R	4 4	Sets the NCO phase offset \(\phi\) to value. The phase is set using an integer that maps a full \(360^\circ\) circle to an integer between \(0\) and \(10^9\) (e.g. \(45^\circ = 125 \times 10^6\)).
set_ph_delta	value: I value: R	4 4	Adds an instantaneous phase kick (\(\Delta\phi\)) to the NCO’s total phase (\(t'\rightarrow t' + \delta\phi/(2\pi f)\)). This is useful for applying dynamic phase shifts during a sequence.
set_awg_gain	value_0: I, value_1: I value_0: R, value_1: R	4 8	Sets the signal gain for the two AWG paths. Values are integers from –32,768 to 32,767.
set_awg_offs	value_0: I, value_1: I value_0: R, value_1: R	4 8	Sets the signal offset for the two AWG paths. Values are integers from –32,768 to 32,767.

Time tag Latched Instructions

QTM latched instructions

Instruction	Signature	Execution Time (ns)	Description
set_digital	enable: I, mask: I, fine_delay: I enable: R, mask: R, fine_delay: R	4 8	Set the output of sequencer/channel to high or low using enable. The parameter mask should always be set to 1.
set_time_ref	—	4	Configure the reference timestamp to the current sequencer time. This timestamp may be used by the acquire_timetags command to determine time differences. This command must be set during or before the command that closes the acquisition window.
set_scope_en	enable: I enable: R	4 4	Set enable = 1 to trigger scope/trace acquisition by subsequent acquisition instructions.

Note

Adjustment range of fine_delay is [0, 2047] where each number is a multiple of 1/ 128 ns. This fine resolution is limited by hardware resolution of 39 ps (5 steps). Mask should always be set to 1.

Real-time Instructions

These instructions are executed by the real-time (RT) core and define the experiment’s timing (wall-time).

The duration argument dictates how long the RT core spends on that step, with a resolution of 1ns and minimum of 4 ns. See link.

The duration is counted from the beginning of an instruction. This is what enables, for example, parallel playback and acquisition.

Once started, the RT timeline is uninterruptible to ensure deterministic timing. In case of a conflict to the Q1 core, the sequencer will halt and raise an error flag.

Instruction	Signature	Execution Time (ns)	Description
set_latch_en	enable: I, duration: I enable: R, duration: I	4 4	Enables or disables all trigger network address counters. Once enabled, the counters will count all triggers on the trigger network. When disabled, the counters hold their last values.
latch_rst	duration: I duration: R	4 4	Resets all trigger network address counters to 0.
wait	duration: I duration: R	4 4	Waits for the specified duration in nanoseconds.
wait_trigger	trigger: I, duration: I trigger: R, duration: R	4 4	Waits for a hardware trigger signal. The duration sets a timeout. Caution: Minimum time between wait_trigger and set_cond is 8 ns.
wait_sync	duration: I duration: R	4 4	Wait for SYNQ to complete all previous tasks of all the sequencers.

Control real-time

The execution of any of these instructions will cause the latched parameters to be updated. Please note that the duration argument for all these instructions has been explained at the start of this section!

Also note that for all real-time instructions, duration \(\in\) [4, 65535]. For longer wall times, extra waits must be added after the instructions.

Control real-time instructions

Instruction	Signature	Execution Time (ns)	Description
upd_param	duration: I	4	Update the latched parameters, and then wait for duration nanoseconds.
play	wave_0: I, wave_1: I, duration: I wave_0: R, wave_1: R, duration: I	4 8	Update the latched parameters, interrupt currently playing waves, and start playing AWG waveforms stored at indexes wave_0 on path 0 and wave_1 on path 1.

Readout real-time

The execution of any of these instructions will cause the latched parameters to be updated. Please note that the duration argument for all these instructions has been explained at the start of this section!

Also note that for all real-time instructions, duration \(\in\) [4, 65535]. For longer wall times, extra waits must be added after the instructions.

Readout real-time instructions

Instruction	Signature	Q1 Execution Time (ns)	Description
upd_param	duration: I	4	Update the latched parameters, and then wait for duration nanoseconds.
play	wave_0: I, wave_1: I, duration: I wave_0: R, wave_1: R, duration: I	4 8	Update the latched parameters, interrupt currently playing waves, and start playing AWG waveforms stored at indexes wave_0 on path 0 and wave_1 on path 1.
acquire	acquisition: I, bin: I, duration: I acquisition: I, bin: R, duration: I	4 4	Update the latched parameters, interrupt currently active acquisitions, and start the acquisition referred to using index acquisition and store the bin data in bin index bin. Integration is executed using a square weight with a preset length through the ReadoutSequencer.integration_length_acq() QCoDeS parameter.
acquire_weighed	acquisition: I, bin: I, weight_0: I, weight_1: I, duration: I acquisition: I, bin: R, weight_0: R, weight_1: R, duration: I	4 12	Update the latched parameters, interrupt currently active acquisitions, and start the acquisition referred to using index acquisition and store the bin data in bin index bin. Integration is executed using weights stored at indices weight_0 for path 0 and weight_1 for path 1.
acquire_ttl	acquisition: I, bin: I, enable: I, duration: I acquisition: I, bin: R, enable: I, duration: I	4 4	Update the latched parameters, start the TTL trigger acquisition referred to using index acquisition, and store the bin data in bin index bin. Enable the acquisition by writing 1 to enable. The TTL trigger acquisition has to be actively disabled afterwards by writing 0 to enable.

Time tag real-time

The time tag sequencers have their own set of unique real-time instructions, detailed below.

As with the other modules, executing any of these instructions will update the latched parameters.

QTM real-time instructions

Instruction	Signature	Execution Time (ns)	Description
acquire_timetags	acq_idx: I, bin_idx: I, enable: I, fine_delay: I, duration: I acq_idx: I, bin_idx: R, enable: I, fine_delay: R, duration: I	8 12	Opens or closes (depending on enable) the time tag counting acquisition window. fine_delay adjusts the start of the acquisition window relative to the current sequencer time. The values of acq_idx and bin_idx are defined by the closing acquire_timetags instruction. When the acquisition window closes, a measurement outcome is determined by comparing the event count to the threshold set via upd_thres. Closing the window also sends a trigger on the trigger network if the QCoDeS parameters thresholded_acq_trigger_en and thresholded_acq_trigger_address_[low|mid|high|invalid] are enabled.
acquire_digital	acq_idx: I, bin_idx: I, duration: I acq_idx: I, bin_idx: R, duration: I	8 8	Updates latched parameters, samples and records the inputs mapped to the sequencer. Depending on the sampled input level, a trigger may be sent to the trigger network for feedback. Trigger generation requires forward_trigger_en = 1, an appropriate forward_trigger_mode (typically sampled-*), and a specified forward_trigger_address. The input comparison thresholds are set using thresholded_acq_trigger_address_[low|mid|high|invalid].
upd_thres	index: I, value: I, duration: I index: I, value: R, duration: I	8 8	Updates latched parameters and sets the event count threshold at the given index. This threshold determines how the number of detected edge events in an acquire_timetags window maps to the measurement outcome. duration >= 4 ns must hold.

Note

Adjustment range of fine_delay is [0, 2047] where each number is a multiple of 1/ 128 ns. This fine resolution is limited by hardware resolution of 39 ps (5 steps). Mask should always be set to 1.

Note

When using the same bin in acquire_ttl across multiple acquisition runs, the TTL event counts within that bin are accumulated. In contrast, acquire_timetags averages the timestamps of the TTL events acquired within the corresponding window.