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

Quantum Machine API¶

qm.quantum_machine.QuantumMachine ¶

calibrate_element ¶

close ¶

compile ¶

execute ¶

get_config ¶

get_digital_buffer ¶

get_digital_delay ¶

get_digital_input_deadtime ¶

get_digital_input_polarity ¶

get_digital_input_threshold ¶

get_input_dc_offset_by_element ¶

get_io1_value ¶

get_io2_value ¶

get_io_values ¶

get_job ¶

get_output_dc_offset_by_element ¶

get_running_job ¶

get_smearing ¶

get_time_of_flight ¶

list_controllers ¶

save_config_to_file ¶

set_digital_buffer ¶

set_digital_delay ¶

set_digital_input_deadtime ¶

set_digital_input_polarity ¶

set_digital_input_threshold ¶

set_input_dc_offset_by_element ¶

set_intermediate_frequency ¶

set_io1_value ¶

set_io2_value ¶

set_io_values ¶

set_mixer_correction ¶

set_output_dc_offset_by_element ¶

set_output_filter_by_element ¶

simulate ¶

Queue API¶

qm.jobs.job_queue_base.QmQueueBase ¶

count: int property ¶

pending_jobs: Tuple[JobTypeVar, ...] property ¶

add_to_start ¶

get ¶

qm.jobs.job_queue_old_api.QmQueue ¶

add ¶

add_compiled ¶

add_to_start ¶

clear ¶

get_at ¶

remove_by_id ¶

remove_by_position ¶

`qm.quantum_machine.QuantumMachine` ¶

`calibrate_element` ¶

`close` ¶

`compile` ¶

`execute` ¶

`get_config` ¶

`get_digital_buffer` ¶

`get_digital_delay` ¶

`get_digital_input_deadtime` ¶

`get_digital_input_polarity` ¶

`get_digital_input_threshold` ¶

`get_input_dc_offset_by_element` ¶

`get_io1_value` ¶

`get_io2_value` ¶

`get_io_values` ¶

`get_job` ¶

`get_output_dc_offset_by_element` ¶

`get_running_job` ¶

`get_smearing` ¶

`get_time_of_flight` ¶

`list_controllers` ¶

`save_config_to_file` ¶

`set_digital_buffer` ¶

`set_digital_delay` ¶

`set_digital_input_deadtime` ¶

`set_digital_input_polarity` ¶

`set_digital_input_threshold` ¶

`set_input_dc_offset_by_element` ¶

`set_intermediate_frequency` ¶

`set_io1_value` ¶

`set_io2_value` ¶

`set_io_values` ¶

`set_mixer_correction` ¶

`set_output_dc_offset_by_element` ¶

`set_output_filter_by_element` ¶

`simulate` ¶

`qm.jobs.job_queue_base.QmQueueBase` ¶

`count: int` `property` ¶

`pending_jobs: Tuple[JobTypeVar, ...]` `property` ¶

`add_to_start` ¶

`get` ¶

`qm.jobs.job_queue_old_api.QmQueue` ¶

`add` ¶

`add_compiled` ¶

`add_to_start` ¶

`clear` ¶

`get_at` ¶

`remove_by_id` ¶

`remove_by_position` ¶