qick.asm_v1

Assembly language wrapper class and auxiliary functions for the v1 tProcessor.

Classes

AbsGenManager(prog, gen_ch)	Manages the envelope and pulse information for a signal generator channel.
AbsRegisterManager(prog, tproc_ch, ch_name)	Generic class for managing registers that will be written to a tProc-controlled block (signal generator or readout).
AcquireProgram(*args, **kwargs)	Base class for tProc v1 programs with shot counting and readout acquisition.
FullSpeedGenManager(prog, gen_ch)	Manager for the full-speed (non-interpolated, non-muxed) signal generators.
InterpolatedGenManager(prog, gen_ch)	Manager for the interpolated signal generators.
MultiplexedGenManager(prog, gen_ch)	Manager for the muxed signal generators.
QickProgram(soccfg)	QickProgram is a Python representation of the QickSoc processor assembly program.
QickRegister(prog, page, addr[, reg_type, ...])	A qick register object that keeps the page, address, generator/readout channel and register type information, provides functions that make it easier to set register value given input values in physical units.
QickRegisterManagerMixin(*args, **kwargs)	A mixin class for QickProgram that provides manager functions for getting and declaring new qick registers.
ReadoutManager(prog, ro_ch)	Manages the frequency and mode registers for a tProc-controlled readout channel.

class qick.asm_v1.AbsRegisterManager(prog, tproc_ch, ch_name)

Bases: ABC

Generic class for managing registers that will be written to a tProc-controlled block (signal generator or readout).

set_reg(name, val, comment=None, defaults=False)

Wrapper around regwi. Looks up the register name and keeps track of whether the register already has a default value.

Parameters:

• name (str) – Register name

• val (int) – Register value

• comment (str) – Comment to be printed in ASM output

• defaults (bool) – This is a default value, which doesn’t need to be rewritten for every pulse

set_defaults(kwargs)

Set default values for parameters. This is called by QickProgram.set_default_registers().

Parameters:

kwargs (dict) – Parameter values

set_registers(kwargs)

Set pulse parameters. This is called by QickProgram.set_pulse_registers().

Parameters:

kwargs (dict) – Parameter values

class qick.asm_v1.ReadoutManager(prog, ro_ch)

Bases: AbsRegisterManager

Manages the frequency and mode registers for a tProc-controlled readout channel.

check_params(params)

Check whether the parameters defined for a pulse are supported and sufficient for this generator and pulse type. Raise an exception if there is a problem.

Parameters:

params (dict) – Parameter values

get_mode_code(length, outsel=None, mode=None, phrst=None)

Creates mode code for the mode register in the set command, by setting flags and adding the pulse length.

Parameters:

• length (int) – The number of ADC fabric cycles in the pulse

• outsel (str) –

  Selects the output source. The output is complex. Tables define envelopes for I and Q. The default is “product”.

  • If “product”, the output is the product of table and DDS.

  • If “dds”, the output is the DDS only.

  • If “input”, the output is from the table for the real part, and zeros for the imaginary part.

  • If “zero”, the output is always zero.

• mode (str) – Selects whether the output is “oneshot” or “periodic”. The default is “oneshot”.

• phrst (int) – If 1, it resets the phase coherent accumulator. The default is 0.

Returns:

Compiled mode code in binary

Return type:

int

class qick.asm_v1.AbsGenManager(prog, gen_ch)

Bases: AbsRegisterManager

Manages the envelope and pulse information for a signal generator channel.

check_params(params)

Check whether the parameters defined for a pulse are supported and sufficient for this generator and pulse type. Raise an exception if there is a problem.

Parameters:

params (dict) – Parameter values

get_mode_code(length, mode=None, outsel=None, stdysel=None, phrst=None)

Creates mode code for the mode register in the set command, by setting flags and adding the pulse length.

Parameters:

• length (int) – The number of DAC fabric cycles in the pulse

• mode (str) – Selects whether the output is “oneshot” or “periodic”. The default is “oneshot”.

• outsel (str) –

  Selects the output source. The output is complex. Tables define envelopes for I and Q. The default is “product”.

  • If “product”, the output is the product of table and DDS.

  • If “dds”, the output is the DDS only.

  • If “input”, the output is from the table for the real part, and zeros for the imaginary part.

  • If “zero”, the output is always zero.

• stdysel (str) –

  Selects what value is output continuously by the signal generator after the generation of a pulse. The default is “zero”.

  • If “last”, it is the last calculated sample of the pulse.

  • If “zero”, it is a zero value.

• phrst (int) – If 1, it resets the phase coherent accumulator. The default is 0.

Returns:

Compiled mode code in binary

Return type:

int

class qick.asm_v1.FullSpeedGenManager(prog, gen_ch)

Bases: AbsGenManager

Manager for the full-speed (non-interpolated, non-muxed) signal generators.

write_regs(params, defaults)

Write whichever pulse registers are fully determined by the defined parameters.

The following pulse styles are supported:

• const: A constant (rectangular) pulse. There is no outsel setting for this pulse style; “dds” is always used.

• arb: An arbitrary-envelope pulse.

• flat_top: A flattop pulse with arbitrary ramps. The waveform is played in three segments: ramp up, flat, and ramp down. To use these pulses one should use add_envelope to add the ramp waveform which should go from 0 to maxamp and back down to zero with the up and down having the same length, the first half will be used as the ramp up and the second half will be used as the ramp down.

  If the waveform is not of even length, the middle sample will be skipped. It’s recommended to use an even-length waveform with flat_top.

  There is no outsel setting for flat_top; the ramps always use “product” and the flat segment always uses “dds”. There is no mode setting; it is always “oneshot”.

Parameters:

• params (dict) – Pulse parameters

• defaults – These are default values, which don’t need to be rewritten for every pulse

get_mode_code(**kwargs)

Creates mode code for the mode register in the set command, by setting flags and adding the pulse length.

Parameters:

• length (int) – The number of DAC fabric cycles in the pulse

• mode (str) – Selects whether the output is “oneshot” or “periodic”. The default is “oneshot”.

• outsel (str) –

  Selects the output source. The output is complex. Tables define envelopes for I and Q. The default is “product”.

  • If “product”, the output is the product of table and DDS.

  • If “dds”, the output is the DDS only.

  • If “input”, the output is from the table for the real part, and zeros for the imaginary part.

  • If “zero”, the output is always zero.

• stdysel (str) –

  Selects what value is output continuously by the signal generator after the generation of a pulse. The default is “zero”.

  • If “last”, it is the last calculated sample of the pulse.

  • If “zero”, it is a zero value.

• phrst (int) – If 1, it resets the phase coherent accumulator. The default is 0.

Returns:

Compiled mode code in binary

Return type:

int

class qick.asm_v1.InterpolatedGenManager(prog, gen_ch)

Bases: AbsGenManager

Manager for the interpolated signal generators.

write_regs(params, defaults)

Write whichever pulse registers are fully determined by the defined parameters.

The following pulse styles are supported:

• const: A constant (rectangular) pulse. There is no outsel setting for this pulse style; “dds” is always used.

• arb: An arbitrary-envelope pulse.

• flat_top: A flattop pulse with arbitrary ramps. The waveform is played in three segments: ramp up, flat, and ramp down. To use these pulses one should use add_envelope to add the ramp waveform which should go from 0 to maxamp and back down to zero with the up and down having the same length, the first half will be used as the ramp up and the second half will be used as the ramp down.

  If the waveform is not of even length, the middle sample will be skipped. It’s recommended to use an even-length waveform with flat_top.

  There is no outsel setting for flat_top; the ramps always use “product” and the flat segment always uses “dds”. There is no mode setting; it is always “oneshot”.

Parameters:

• params (dict) – Pulse parameters

• defaults – These are default values, which don’t need to be rewritten for every pulse

class qick.asm_v1.MultiplexedGenManager(prog, gen_ch)

Bases: AbsGenManager

Manager for the muxed signal generators.

write_regs(params, defaults)

Write whichever pulse registers are fully determined by the defined parameters.

Only the “const” pulse style, with the “mask” and “length” parameters, is supported. The frequency and gain are set at program initialization.

Parameters:

• params (dict) – Pulse parameters

• defaults – These are default values, which don’t need to be rewritten for every pulse

class qick.asm_v1.QickProgram(soccfg)

Bases: AbsQickProgram

QickProgram is a Python representation of the QickSoc processor assembly program. It can be used to compile simple assembly programs and also contains macros to help make it easy to configure and schedule pulses.

ch_page(gen_ch)

Gets tProc register page associated with generator channel.

Parameters:

gen_ch (int) – generator channel (index in ‘gens’ list)

Returns:

tProc page number

Return type:

int

sreg(gen_ch, name)

Gets tProc special register number associated with a generator channel and register name.

Parameters:

• gen_ch (int) – generator channel (index in ‘gens’ list)

• name (str) – Name of special register (“gain”, “freq”)

Returns:

tProc special register number

Return type:

int

ch_page_ro(ro_ch)

Gets tProc register page associated with tProc-controlled readout channel.

Parameters:

ro_ch (int) – readout channel (index in ‘readouts’ list)

Returns:

tProc page number

Return type:

int

sreg_ro(ro_ch, name)

Gets tProc special register number associated with a readout channel and register name.

Parameters:

• ro_ch (int) – readout channel (index in ‘readouts’ list)

• name (str) – Name of special register (“gain”, “freq”)

Returns:

tProc special register number

Return type:

int

add_pulse(ch, name, idata=None, qdata=None)

Adds a waveform to the waveform library within the program.

Parameters:

• ch (int) – generator channel (index in ‘gens’ list)

• name (str) – Name of the pulse

• idata (array) – I data Numpy array

• qdata (array) – Q data Numpy array

default_pulse_registers(ch, **kwargs)

Set default values for pulse parameters. If any registers can be written at this point, write them in order to save time later.

This is optional (you can set all parameters in set_pulse_registers). You can only call this method once per channel. There cannot be any overlap between the parameters defined here and the parameters you define in set_pulse_registers.

Parameters:

• ch (int) – generator channel (index in ‘gens’ list)

• **kwargs (dict) – Pulse parameters

set_pulse_registers(ch, **kwargs)

Set the pulse parameters including frequency, phase, address of pulse, gain, stdysel, mode register (compiled from length and other flags), outsel, and length. The time is scheduled when you call pulse(). See the write_regs() method of the relevant generator manager for the list of supported pulse styles.

Parameters:

• ch (int) – generator channel (index in ‘gens’ list)

• style (str) – Pulse style (“const”, “arb”, “flat_top”)

• freq (int) – Frequency (register value)

• phase (int) – Phase (register value)

• gain (int) – Gain (DAC units)

• phrst (int) – If 1, it resets the phase coherent accumulator

• stdysel (str) – Selects what value is output continuously by the signal generator after the generation of a pulse. If “last”, it is the last calculated sample of the pulse. If “zero”, it is a zero value.

• mode (str) – Selects whether the output is “oneshot” or “periodic”

• outsel (str) – Selects the output source. The output is complex. Tables define envelopes for I and Q. If “product”, the output is the product of table and DDS. If “dds”, the output is the DDS only. If “input”, the output is from the table for the real part, and zeros for the imaginary part. If “zero”, the output is always zero.

• length (int) – The number of fabric clock cycles in the flat portion of the pulse, used for “const” and “flat_top” styles

• waveform (str) – Name of the envelope waveform loaded with add_envelope(), used for “arb” and “flat_top” styles

• mask (list of int) – for a muxed signal generator, the list of tones to enable for this pulse

set_readout_registers(ch, **kwargs)

Set the readout parameters including frequency, mode, outsel, and length. The time is scheduled when you call readout().

Parameters:

• ch (int) – readout channel (index in ‘readouts’ list)

• freq (int) – Frequency (register value)

• phrst (int) – If 1, it resets the phase coherent accumulator

• mode (str) – Selects whether the output is “oneshot” or “periodic”

• outsel (str) – Selects the output source. The output is complex. The input comes from the ADC and is purely real. If “product”, the output is the product of input and DDS. If “dds”, the output is the DDS only. If “input”, the output is from the input for the real part, and zeros for the imaginary part. If “zero”, the output is always zero.

• length (int) – The number of fabric clock cycles for which these readout parameters are defined.

default_readout_registers(ch, **kwargs)

Set default values for readout parameters. If any registers can be written at this point, write them in order to save time later.

This is optional (you can set all parameters in set_readout_registers). You can only call this method once per channel. There cannot be any overlap between the parameters defined here and the parameters you define in set_readout_registers.

Parameters:

• ch (int) – readout channel (index in ‘readouts’ list)

• **kwargs (dict) – Pulse parameters

readout(ch, t)

Play the pulse currently programmed into the registers for this tProc-controlled readout channel. You must have already run set_readout_registers for this channel.

Parameters:

• ch (int) – readout channel (index in ‘readouts’ list)

• t (int) – The number of tProc cycles at which the pulse starts

setup_and_pulse(ch, t='auto', **kwargs)

Set up a pulse on this generator channel, and immediately play it. This is a wrapper around set_pulse_registers() and pulse(), and takes the arguments from both. You can only run this on a single generator channel.

Parameters:

• ch (int) – generator channel (index in ‘gens’ list)

• t (int, optional) – Pulse time, in tProc cycles

• **kwargs (dict) – Pulse parameters: refer to set_pulse_registers

setup_and_measure(adcs, pulse_ch, pins=None, adc_trig_offset=270, t='auto', wait=False, syncdelay=None, **kwargs)

Set up a pulse on this generator channel, and immediately do a measurement with it. This is a wrapper around set_pulse_registers() and measure(), and takes the arguments from both. You can only run this on a single generator channel.

Parameters:

• adcs (list of int) – readout channels (index in ‘readouts’ list)

• pulse_ch (int) – generator channel (index in ‘gens’ list)

• pins (list of int, optional) – refer to trigger()

• adc_trig_offset (int, optional) – refer to trigger()

• t (int, optional) – refer to pulse()

• wait (bool, optional) – refer to measure()

• syncdelay (int, optional) – refer to measure()

• **kwargs (dict) – Pulse parameters: refer to set_pulse_registers()

pulse(ch, t='auto')

Play the pulse currently programmed into the registers for this generator channel. You must have already run set_pulse_registers for this channel.

Parameters:

• ch (int or list of int) – generator channel (index in ‘gens’ list)

• t (int, optional) – The number of tProc cycles at which the pulse starts (None to use the time register as is, ‘auto’ to start whenever the last pulse ends)

safe_regwi(rp, reg, imm, comment=None)

Due to the way the instructions are setup immediate values can only be 30bits before not loading properly. This comes up mostly when trying to regwi values into registers, especially the _frequency_ and _phase_ pulse registers. safe_regwi can be used wherever one might use regwi and will detect if the value is >2**30 and if so will break it into two steps, putting in the first 30 bits shifting it over and then adding the last two.

Parameters:

• rp (int) – Register page

• reg (int) – Register number

• imm (int) – Value of the write

• comment (str, optional) – Comment associated with the write

sync_all(t=0, gen_t0=None)

Aligns and syncs all channels with additional time t. Accounts for both generator pulses and readout windows. This does not pause the tProc. gen_t0 is an optional list of additional delays for each individual generator channel, e.g. when the channels are on different tiles so they don’t natively sync.

Parameters:

• t (int, optional) – The time offset in tProc cycles

• gen_t0 (list, optional) – List of additional delays for each individual generator channel, in tProc cycles

wait_all(t=0)

Pause the tProc until all ADC readout windows are complete, plus additional time t. This does not sync the tProc clock.

Parameters:

t (int, optional) – The time offset in tProc cycles

trigger(adcs=None, pins=None, ddr4=False, mr=False, adc_trig_offset=270, t=0, width=10, rp=0, r_out=16)

Pulse the readout(s) and marker pin(s) with a specified pulse width at a specified time t+adc_trig_offset. If no readouts are specified, the adc_trig_offset is not applied.

Parameters:

• adcs (list of int) – List of readout channels to trigger (index in ‘readouts’ list)

• pins (list of int) – List of marker pins to pulse. Use the pin numbers in the QickConfig printout.

• ddr4 (bool) – If True, trigger the DDR4 buffer.

• mr (bool) – If True, trigger the MR buffer.

• adc_trig_offset (int, optional) – Offset time at which the ADC is triggered (in tProc cycles)

• t (int, optional) – The number of tProc cycles at which the ADC trigger starts

• width (int, optional) – The width of the trigger pulse, in tProc cycles

• rp (int, optional) – Register page

• r_out (int, optional) – Register number

measure(adcs, pulse_ch, pins=None, adc_trig_offset=270, t='auto', wait=False, syncdelay=None)

Wrapper method that combines an ADC trigger, a pulse, and (optionally) the appropriate wait and a sync_all. You must have already run set_pulse_registers for this channel.

If you use wait=True, it’s recommended to also specify a nonzero syncdelay.

Parameters:

• adcs (list of int) – readout channels (index in ‘readouts’ list)

• pulse_ch (int or list of int) – generator channel(s) (index in ‘gens’ list)

• pins (list of int, optional) – refer to trigger()

• adc_trig_offset (int, optional) – refer to trigger()

• t (int, optional) – refer to pulse()

• wait (bool, optional) – Pause tProc execution until the end of the ADC readout window

• syncdelay (int, optional) – The number of additional tProc cycles to delay in the sync_all

reset_phase(gen_ch: Optional[Union[int, List[int]]] = None, ro_ch: Optional[Union[int, List[int]]] = None, t: int = 0)

Reset the phase of generator and tproc-controlled readout channels at tproc time t. This will play an empty pulse that lasts 3 fabric clock cycles, just to trigger the phase reset.

This command is designed to be transparent to previous ‘set_pulse/readout_registers()’ calls. i.e. the register values set using ‘set_pulse/readout_registers()’ before this command will remain the same after this command. However, pulse registers set using other functions will need to be re-set, e.g. if a pulse register value was set by directly calling ‘regwi()’, calling this function will overwrite that register value, and user need to redo the ‘regwi()’ after this phase reset.

Parameters:

• gen_ch – generator channel(s) to reset phase (index in ‘gens’ list)

• ro_ch – tProc-controlled readout channel(s) to reset phase (index in ‘readouts’ list)

• t – the number of tProc cycles at which the phase reset happens

convert_immediate(val)

Convert the register value to ensure that it is positive and not too large. Throws an error if you ever try to use a value greater than 2**31 as an immediate value.

Parameters:

val (int) – Original register value

Returns:

Converted register value

Return type:

int

compile_instruction(inst, labels, debug=False)

Converts an assembly instruction into a machine bytecode.

Parameters:

• inst (dict) – Assembly instruction

• labels (dict) – Map from label name to program counter

• debug (bool) – If True, debug mode is on

Returns:

Compiled instruction in binary

Return type:

int

compile(debug=False)

Compiles program to machine code.

Parameters:

debug (bool) – If True, debug mode is on

Returns:

List of binary instructions

Return type:

list of int

append_instruction(name, *args)

Append instruction to the program list

Parameters:

• name (str) – Instruction name

• *args (dict) – Instruction arguments

label(name)

Add line number label to the labels dictionary. This labels the instruction by its position in the program list. The loopz and condj commands use this label information.

Parameters:

name (str) – Label name

hex()

Returns hex representation of program as string.

Returns:

Compiled program in hex format

Return type:

str

bin()

Returns binary representation of program as string.

Returns:

Compiled program in binary format

Return type:

str

asm()

Returns assembly representation of program as string, should be compatible with the parse_prog from the parser module.

Returns:

asm file

Return type:

str

compare_program(fname)

For debugging purposes to compare binary compilation of parse_prog with the compile.

Parameters:

fname (str) – File the comparison program is stored in

Returns:

True if programs are identical; False otherwise

Return type:

bool

class qick.asm_v1.AcquireProgram(*args, **kwargs)

Bases: AcquireMixin, QickProgram

Base class for tProc v1 programs with shot counting and readout acquisition. You will need to define the acquisition structure with setup_acquire().

class qick.asm_v1.QickRegister(prog: QickProgram, page: int, addr: int, reg_type: Optional[str] = None, gen_ch: Optional[int] = None, ro_ch: Optional[int] = None, init_val=None, name: Optional[str] = None)

Bases: object

A qick register object that keeps the page, address, generator/readout channel and register type information, provides functions that make it easier to set register value given input values in physical units.

val2reg(val)

convert physical value to a qick register value :param val: :return:

reg2val(reg)

converts a qick register value to its value in physical units :param reg: :return:

set_to(a: Union[QickRegister, float, int], operator: str = '+', b: Union[QickRegister, float, int] = 0, physical_unit=True)

a shorthand function that sets the register value using different asm commands based on the input type.

if input “a” is a number, “operator” and “b” will be neglected, “a”(or the register integer that corresponds to “a”) will be assigned to the current register

if input “a” is a QickRegister and “b” is a number, the register will be set to the “mathi” result between “a” and “b”. (when physical_unit==True, “b” will be auto-converted from physical value to register value based on the register type)

if both “a” and “b” are QickRegisters, the register will be set to the “math” result between “a” and “b”.

Parameters:

• a – first operand register or a constant value

• operator – {“+”, “-”, “*”}. math symbol supported by “math” and “mathi” asm commands

• b – second operand register or a constant value

• physical_unit – when True, the constant value operands should be in its physical unit and will be automatically converted to the register integer before assignment.

Returns:

reset()

reset register value to its init_val :return:

class qick.asm_v1.QickRegisterManagerMixin(*args, **kwargs)

Bases: object

A mixin class for QickProgram that provides manager functions for getting and declaring new qick registers.

new_reg(page: int, addr: Optional[int] = None, name: Optional[str] = None, init_val=None, reg_type: Optional[str] = None, gen_ch: Optional[int] = None, ro_ch: Optional[int] = None)

Declare a new register in a specific page.

Parameters:

• page – register page

• addr – address of the new register. If None, the function will automatically try to find the next available address.

• name – name of the new register. Optional.

• init_val – initial value for the register, when reg_type is provided, the reg_val should be in the physical unit of the corresponding type. i.e. freq in MHz, time in us, phase in deg.

• reg_type – {“freq”, “time”, “phase”, “adc_freq”} or None, type of the register

• gen_ch – generator channel numer to which the register is associated with, for unit convert.

• ro_ch – readout channel numer to which the register is associated with, for unit convert.

Returns:

QickRegister

get_gen_reg(gen_ch: int, name: str) → QickRegister

Gets tProc register page and address associated with gen_ch and register name. Creates a QickRegister object for return.

Parameters:

• gen_ch – generator channel number

• name – name of the qick register, as in QickProgram.pulse_registers

Returns:

QickRegister

new_gen_reg(gen_ch: int, name: Optional[str] = None, init_val=None, reg_type: Optional[str] = None, tproc_reg=False) → QickRegister

Declare a new register in the generator register page. Address automatically adds 1 one when each time a new register in the same page is declared.

Parameters:

• gen_ch – generator channel number

• name – name of the new register. Optional.

• init_val – initial value for the register, when reg_type is provided, the reg_val should be in the unit of the corresponding type.

• reg_type – {“freq”, “time”, “phase”, “adc_freq”} or None, type of the register.

• tproc_reg – if True, the new register created will not be associated to a specific generator or readout channel. It will still be on the same page as the gen_ch for math calculations. This is usually used for a time register in t_processor, where we want to calculate “us2cycles” with the t_proc fabric clock rate instead of the generator clock rate.

Returns:

QickRegister