Skip to content

Quantum Machine API

This page shows the QM API used with the OPX+ with QOP2.x. It is also supported by the OPX1000 with QOP 3.x, but some functions have changed and will give a deprecation warning. The equivalent OPX1000 API can be found here.

qm.quantum_machine.QuantumMachine

calibrate_element

Calibrate the up converters associated with a given element for the given LO & IF frequencies.

  • Frequencies can be given as a dictionary with LO frequency as the key and a list of IF frequencies for every LO
  • If no frequencies are given calibration will occur according to LO & IF declared in the element
  • The function need to be run for each element separately
  • The results are saved to a database for later use
PARAMETER DESCRIPTION
qe

The name of the element for calibration

TYPE: str

lo_if_dict

a dictionary with LO frequency as the key and a list of IF frequencies for every LO

TYPE: [Mapping[float, Tuple[float, ...]]] DEFAULT: None

save_to_db

If true (default), The calibration parameters will be saved to the calibration database

TYPE: bool DEFAULT: True

params

Optional calibration parameters

TYPE: Optional[AutoCalibrationParams] DEFAULT: None

close

Closes the quantum machine.

RETURNS DESCRIPTION
bool

True if the close request succeeded, raises an exception

bool

otherwise.

compile

Compiles a QUA program to be executed later. The returned program_id can then be directly added to the queue. For a detailed explanation see Precompile Jobs.

PARAMETER DESCRIPTION
program

A QUA program

TYPE: Program

compiler_options

Optional arguments for compilation

TYPE: Optional[CompilerOptionArguments] DEFAULT: None

RETURNS DESCRIPTION
str

a program_id str

Example
program_id = qm.compile(program)
pending_job = qm.queue.add_compiled(program_id)
job = pending_job.wait_for_execution()

execute

Executes a program and returns a job object to keep track of execution and get results.

Note

Calling execute will halt any currently running program and clear the current queue. If you want to add a job to the queue, use qm.queue.add()

PARAMETER DESCRIPTION
program

A QUA program() object to execute

TYPE: Program

duration_limit

This parameter is ignored and will be removed in future versions

TYPE: int DEFAULT: 1000

data_limit

This parameter is ignored and will be removed in future versions

TYPE: int DEFAULT: 20000

force_execution

This parameter is ignored and will be removed in future versions

TYPE: int DEFAULT: False

dry_run

This parameter is ignored and will be removed in future versions

TYPE: int DEFAULT: False

simulate

If given, will be simulated instead of executed.

TYPE: Optional[SimulationConfig] DEFAULT: None

compiler_options

Optional arguments for compilation.

TYPE: Optional[CompilerOptionArguments] DEFAULT: None

strict

This parameter is deprecated, please use compiler_options

TYPE: Optional[bool] DEFAULT: None

flags

This parameter is deprecated, please use compiler_options

TYPE: Optional[List[str]] DEFAULT: None

Returns: A QmJob object (see QM Job API).

get_config

Gets the current config of the qm

RETURNS DESCRIPTION
DictQuaConfig

A dictionary with the QMs config

get_digital_buffer

Gets the buffer for digital input of the element

PARAMETER DESCRIPTION
element

The name of the element to get the buffer for

TYPE: str

digital_input

The digital input name as appears in the element's config

TYPE: str

RETURNS DESCRIPTION
int

The buffer

get_digital_delay

Gets the delay of the digital input of the element

PARAMETER DESCRIPTION
element

The name of the element to get the delay for

TYPE: str

digital_input

The digital input name as appears in the element's config

TYPE: str

RETURNS DESCRIPTION
int

The delay

get_digital_input_deadtime

Gets the deadtime of the digital input

PARAMETER DESCRIPTION
port

The port, in tuple form, to be updated

TYPE: PortReferenceType

RETURNS DESCRIPTION
int

The deadtime in ns

get_digital_input_polarity

Gets the polarity of the digital input

PARAMETER DESCRIPTION
port

The port, in tuple form, to be updated

TYPE: PortReferenceType

RETURNS DESCRIPTION
str

The polarity

get_digital_input_threshold

Gets the threshold of the digital input

PARAMETER DESCRIPTION
port

The port, in tuple form, to be updated

TYPE: PortReferenceType

RETURNS DESCRIPTION
float

The threshold in volts

get_input_dc_offset_by_element

Get the current DC offset of the OPX analog input channel associated with an element.

PARAMETER DESCRIPTION
element

the name of the element to get the correction for

TYPE: str

output

the output key name as appears in the element config under 'outputs'.

TYPE: str

RETURNS DESCRIPTION
float

The offset, in volts

get_io1_value

Gets the data stored in IO1

No inference is made on type.

RETURNS DESCRIPTION
Dict[str, Value]

A dictionary with data stored in IO1. (Data is in all

Dict[str, Value]

three format: int, float and bool)

get_io2_value

Gets the data stored in IO2

No inference is made on type.

RETURNS DESCRIPTION
Dict[str, Value]

A dictionary with data from the second IO register. (Data is

Dict[str, Value]

in all three format: int, float and bool)

get_io_values

Gets the data stored in both IO1 and IO2

No inference is made on type.

RETURNS DESCRIPTION
List[Dict[str, Value]]

A list that contains dictionaries with data from the IO

List[Dict[str, Value]]

registers. (Data is in all three format: int, float

List[Dict[str, Value]]

and bool)

get_job

Get a job based on the job_id.

PARAMETER DESCRIPTION
job_id

A list of jobs ids

TYPE: str

Returns: The job

get_output_dc_offset_by_element

Get the current DC offset of the OPX analog output channel associated with an element.

PARAMETER DESCRIPTION
element

the name of the element to get the correction for

TYPE: str

iq_input

the port name as appears in the element config. Options:

'single' for an element with a single input

'I' or 'Q' for an element with mixer inputs

TYPE: str

RETURNS DESCRIPTION
float

the offset, in volts

get_running_job

Gets the currently running job. Returns None if there isn't one.

get_smearing

Gets the smearing associated with a measurement element.

This is a broadening of the raw results acquisition window, to account for dispersive broadening in the measurement elements (readout resonators etc.) The acquisition window will be broadened by this amount on both sides.

PARAMETER DESCRIPTION
element

The name of the element to get smearing for

TYPE: str

RETURNS DESCRIPTION
int

The smearing, in ns.

get_time_of_flight

Gets the time of flight, associated with a measurement element.

This is the amount of time between the beginning of a measurement pulse applied to element and the time that the data is available to the controller for demodulation or streaming.

PARAMETER DESCRIPTION
element

The name of the element to get time of flight for

TYPE: str

RETURNS DESCRIPTION
int

The time of flight, in ns

list_controllers

Gets a list with the defined controllers in this qm

RETURNS DESCRIPTION
Tuple[str, ...]

The names of the controllers configured in this qm

save_config_to_file

Saves the qm current config to a file

PARAMETER DESCRIPTION
filename

The name of the file where the config will be saved

TYPE: PathLike

set_digital_buffer

Sets the buffer for digital input of the element

PARAMETER DESCRIPTION
element

The name of the element to update buffer for

TYPE: str

digital_input

the digital input name as appears in the element's config

TYPE: str

buffer

The buffer value to set to, in ns.

TYPE: int

set_digital_delay

Sets the delay of the digital input of the element

PARAMETER DESCRIPTION
element

The name of the element to update delay for

TYPE: str

digital_input

The digital input name as appears in the element's config

TYPE: str

delay

The delay value to set to, in ns.

TYPE: int

set_digital_input_deadtime

Sets the threshold of the digital input

PARAMETER DESCRIPTION
port

The port, in tuple form, to be updated

TYPE: PortReferenceType

deadtime

The deadtime in ns

TYPE: int

set_digital_input_polarity

Sets the polarity of the digital input

PARAMETER DESCRIPTION
port

The port, in tuple form, to be updated

TYPE: PortReferenceType

polarity

The polarity: "RISING" or "FALLING"

TYPE: str

set_digital_input_threshold

Sets the threshold of the digital input

PARAMETER DESCRIPTION
port

The port, in tuple form, to be updated

TYPE: PortReferenceType

threshold

The threshold in volts

TYPE: float

set_input_dc_offset_by_element

Set the current DC offset of the OPX analog input channel associated with an element.

PARAMETER DESCRIPTION
element

the name of the element to update the correction for

TYPE: str

output

the output key name as appears in the element config under 'outputs'.

TYPE: str

offset

the dc value to set to, in volts. Ranges from -0.5 to 0.5 - 2^-16 in steps of 2^-16.

TYPE: float

Note

If the sum of the DC offset and the largest waveform data-point exceed the range, DAC output overflow will occur and the output will be corrupted.

set_intermediate_frequency

Sets the intermediate frequency of the element

PARAMETER DESCRIPTION
element

the name of the element whose intermediate frequency will be updated

TYPE: str

freq

the intermediate frequency to set to the given element

TYPE: float

set_io1_value

Sets the value of IO1.

This can be used later inside a QUA program as a QUA variable IO1 without declaration. The type of QUA variable is inferred from the python type passed to value_1, according to the following rule:

int -> int float -> fixed bool -> bool

PARAMETER DESCRIPTION
value_1

the value to be placed in IO1

TYPE: Union[float, bool, int]

set_io2_value

Sets the value of IO1.

This can be used later inside a QUA program as a QUA variable IO2 without declaration. The type of QUA variable is inferred from the python type passed to value_2, according to the following rule:

int -> int float -> fixed bool -> bool

PARAMETER DESCRIPTION
value_2

the value to be placed in IO1

TYPE: Union[float, bool, int]

set_io_values

Sets the values of IO1 and IO2

This can be used later inside a QUA program as a QUA variable IO1, IO2 without declaration. The type of QUA variable is inferred from the python type passed to value_1, value_2, according to the following rule:

int -> int float -> fixed bool -> bool

PARAMETER DESCRIPTION
value_1

the value to be placed in IO1

TYPE: Optional[Union[float, bool, int]] DEFAULT: None

value_2

the value to be placed in IO2

TYPE: Optional[Union[float, bool, int]] DEFAULT: None

set_mixer_correction

Sets the correction matrix for correcting gain and phase imbalances of an IQ mixer for the supplied intermediate frequency and LO frequency.

PARAMETER DESCRIPTION
mixer

the name of the mixer, as defined in the configuration

TYPE: str

intermediate_frequency

the intermediate frequency for which to apply the correction matrix

TYPE: Union[int | float]

lo_frequency

the LO frequency for which to apply the correction matrix

TYPE: int

values

tuple is of the form (v00, v01, v10, v11) where the matrix is | v00 v01 | | v10 v11 |

TYPE: tuple

Note:

Currently, the OPX does not support multiple mixer calibration entries.
This function will accept IF & LO frequencies written in the config file,
and will update the correction matrix for all the elements with the given
mixer/frequencies combination when the program started.

It’s not recommended to use this method while a job is running.
To change the calibration values for a running job,
use job.set_element_correction

set_output_dc_offset_by_element

Set the current DC offset of the OPX analog output channel associated with an element.

PARAMETER DESCRIPTION
element

the name of the element to update the correction for

TYPE: str

input

the input name as appears in the element config. Options:

'single' for an element with a single input

'I' or 'Q' or a tuple ('I', 'Q') for an element with mixer inputs

TYPE: Union[str, Tuple[str, str], List[str]]

offset

The dc value to set to, in volts. Ranges from -0.5 to 0.5 - 2^-16 in steps of 2^-16.

TYPE: Union[float, Tuple[float, float], List[float]]

Examples:

qm.set_output_dc_offset_by_element('flux', 'single', 0.1)
qm.set_output_dc_offset_by_element('qubit', 'I', -0.01)
qm.set_output_dc_offset_by_element('qubit', ('I', 'Q'), (-0.01, 0.05))

Note:

If the sum of the DC offset and the largest waveform data-point exceed the range,
DAC output overflow will occur and the output will be corrupted.

set_output_filter_by_element

Sets the intermediate frequency of the element

PARAMETER DESCRIPTION
element

the name of the element whose ports filters will be updated

TYPE: str

input

the input name as appears in the element config. Options:

'single' for an element with single input

'I' or 'Q' for an element with mixer inputs

TYPE: str

feedforward

the values for the feedforward filter

TYPE: Sequence[NumpySupportedFloat]

feedback

the values for the feedback filter

TYPE: Sequence[NumpySupportedFloat]

simulate

Simulates the outputs of a deterministic QUA program.

Equivalent to execute() with simulate=SimulationConfig (see example).

Note

A simulated job does not support calling QuantumMachine API functions.

PARAMETER DESCRIPTION
program

A QUA program() object to execute

TYPE: Program

simulate

If given, will be simulated instead of executed.

TYPE: SimulationConfig

compiler_options

Optional arguments for compilation.

TYPE: Optional[CompilerOptionArguments] DEFAULT: None

strict

This parameter is deprecated, please use compiler_options

TYPE: Optional[bool] DEFAULT: None

flags

This parameter is deprecated, please use compiler_options

TYPE: Optional[List[str]] DEFAULT: None

Returns: A QmJob object (see QM Job API).

Queue API

qm.jobs.job_queue_base.QmQueueBase

count: int property

Get the number of jobs currently on the queue

RETURNS DESCRIPTION
int

The number of jobs in the queue

Example
qm.queue.count

pending_jobs: Tuple[JobTypeVar, ...] property

Returns all currently pending jobs

RETURNS DESCRIPTION
Tuple[JobTypeVar, ...]

A list of all the currently pending jobs

add_to_start

Adds a QMJob to the start of the queue. Programs in the queue will play as soon as possible.

PARAMETER DESCRIPTION
program

A QUA program

TYPE: Program

compiler_options

Optional arguments for compilation

TYPE: Optional[CompilerOptionArguments] DEFAULT: None

get

Get a pending job object by job_id

PARAMETER DESCRIPTION
job_id

a QMJob id

TYPE: str

RETURNS DESCRIPTION
JobTypeVar

The pending job

Example
qm.queue.get(job_id)

qm.jobs.job_queue_old_api.QmQueue

add

Adds a QmJob to the queue. Programs in the queue will play as soon as possible.

PARAMETER DESCRIPTION
program

A QUA program

TYPE: Program

compiler_options

Optional arguments for compilation

TYPE: Optional[CompilerOptionArguments] DEFAULT: None

Example
qm.queue.add(program)  # adds at the end of the queue
qm.queue.insert(program, position)  # adds at position

add_compiled

Adds a compiled QUA program to the end of the queue, optionally overriding the values of analog waveforms defined in the program. Programs in the queue will play as soon as possible. For a detailed explanation see Precompile Jobs.

PARAMETER DESCRIPTION
program_id

A QUA program ID returned from the compile function

TYPE: str

overrides

Object containing Waveforms to run the program with

TYPE: Optional[ExecutionOverridesType] DEFAULT: None

Example
program_id = qm.compile(...)
pending_job = qm.queue.add_compiled(program_id, overrides={
    'waveforms': {
        'my_arbitrary_waveform': [0.1, 0.2, 0.3],
        'my_constant_waveform': 0.2
    }
})
job = pending_job.wait_for_execution()

add_to_start

Adds a QMJob to the start of the queue. Programs in the queue will play as soon as possible.

PARAMETER DESCRIPTION
program

A QUA program

TYPE: Program

compiler_options

Optional arguments for compilation

TYPE: Optional[CompilerOptionArguments] DEFAULT: None

clear

Empties the queue from all pending jobs

RETURNS DESCRIPTION
int

The number of jobs removed

get_at

Gets the pending job object at the given position in the queue

PARAMETER DESCRIPTION
position

An integer position in queue

TYPE: int

RETURNS DESCRIPTION
QmPendingJob

The pending job

Example
qm.queue.get(job_id)

remove_by_id

Removes the pending job object with a specific job id

PARAMETER DESCRIPTION
job_id

a QMJob id

TYPE: str

RETURNS DESCRIPTION
int

The number of jobs removed

Example
qm.queue.remove_by_id(job_id)

remove_by_position

Remove the PendingQmJob object by position in queue

PARAMETER DESCRIPTION
position

position in queue

TYPE: int

RETURNS DESCRIPTION
int

The number of jobs removed

Example

python qm.queue.remove_by_position(position)python