Quantum Machine API

This page shows the QM API used with the OPX1000 with QOP 3.x, it is currently not supported by the OPX+. The equivalent OPX+ API can be found here.

qm.api.v2.qm_api.QmApi

id: str property

Hopefully temporary, till we move to the new API.

add_to_queue

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

PARAMETER	DESCRIPTION
program	A QUA program or a compiled program id TYPE: Union[Program, str]
compiler_options	Optional arguments for compilation TYPE: Optional[CompilerOptionArguments] DEFAULT: None

Returns: A job object

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

clear_queue

Clears jobs from the queue based on filtering criteria. All fields are optional.

PARAMETER	DESCRIPTION
job_ids	A list of jobs ids TYPE: Iterable[str] DEFAULT: tuple()
user_ids	A list of user ids TYPE: Iterable[str] DEFAULT: tuple()
description	Jobs' description TYPE: str DEFAULT: ''
status	A list of job statuses TYPE: Union[JobStatus, Iterable[JobStatus]] DEFAULT: tuple()

Returns: A list of the removed jobs ids

close

Closes the quantum machine.

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)
job = qm.add_to_queue(program_id)
job.wait_until("running")

execute

Closes all running jobs in the QM, clears the queue, executes a program, wait for it to start, and returns a job object.

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
compiler_options	Optional arguments for compilation. TYPE: Optional[CompilerOptionArguments] 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_job

Get a job based on the job_id.

PARAMETER	DESCRIPTION
job_id	A list of jobs ids TYPE: str

Returns: The job

get_jobs

Get jobs based on filtering criteria. All fields are optional.

PARAMETER	DESCRIPTION
job_ids	A list of jobs ids TYPE: Iterable[str] DEFAULT: tuple()
user_ids	A list of user ids TYPE: Iterable[str] DEFAULT: tuple()
description	Jobs' description TYPE: str DEFAULT: ''
status	A list of job statuses TYPE: Union[JobStatus, Iterable[JobStatus]] DEFAULT: tuple()

Returns: A list of jobs

get_queue_count

Get the number of jobs currently on the queue

RETURNS	DESCRIPTION
int	The number of jobs in the queue

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).

update_config

Updates the physical config in the QM. The physical config includes the "controllers", "octaves" & "mixers" sections. Updating the config will only update future jobs that were not executed or compiled yet. It will also update the idle values (e.g. DC Offset) which will be active between programs.

PARAMETER	DESCRIPTION
config	The physical config TYPE: DictQuaConfig

qm.api.v2.qm_api_old.QmApiWithDeprecations

close

Closes the quantum machine.

RETURNS	DESCRIPTION
bool	True if the close request succeeded.

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: None DEFAULT: None
data_limit	This parameter is ignored and will be removed in future versions TYPE: None DEFAULT: None
force_execution	This parameter is ignored and will be removed in future versions TYPE: None DEFAULT: None
dry_run	This parameter is ignored and will be removed in future versions TYPE: None DEFAULT: None
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_digital_buffer

Deprecated - This method is going to be moved to the job API, please use job.get_output_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

Deprecated - This method is going to be moved to the job API, please use job.get_output_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_input_dc_offset_by_element

Deprecated - This method is going to be removed, please get the value from qm.get_config().

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_intermediate_frequency

Deprecated - This method is going to be moved to the job API, please use job.get_intermediate_frequency().

Gets the intermediate frequency of the element

PARAMETER	DESCRIPTION
element	the name of the element whose intermediate frequency will be updated TYPE: str

RETURNS	DESCRIPTION
float	The intermediate frequency

get_io1_value

Deprecated - This method is going to be moved to the job API, please use job.get_io_values()[0]

Gets the data stored in IO1

No inference is made on type.

RETURNS	DESCRIPTION
IoValue	A dictionary with data stored in IO1. (Data is in all
IoValue	three format: int, float and bool)

get_io2_value

Deprecated - This method is going to be moved to the job API, please use job.get_io_values()[1]

Gets the data stored in IO2

No inference is made on type.

RETURNS	DESCRIPTION
IoValue	A dictionary with data stored in IO2. (Data is in all
IoValue	three format: int, float and bool)

get_io_values

Deprecated - This method is going to be moved to the job API, please use job.get_io_values()

Gets the data stored in IO1 & IO2

No inference is made on type.

RETURNS	DESCRIPTION
List[IoValue]	A dictionary with data stored in IO1 & IO2 (Data is in all
List[IoValue]	three format: int, float and bool)

get_job_by_id

Deprecated - This method is going to be removed, please use qmm.get_job().

Returns the job object for the given id. Args: job_id: The job id Returns: The job object

get_output_dc_offset_by_element

Deprecated - This method is going to be removed, please get idle value from qm.get_config() or current value from job 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: Optional[Literal['I', 'Q', 'single']] DEFAULT: None

RETURNS	DESCRIPTION
float	the offset, in volts

get_running_job

Deprecated - This method is going to be removed, please use qm.get_jobs(status=['Running'])

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

get_smearing

Deprecated - This method is going to be removed, please get the value from qm.get_config().

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

Deprecated - This method is going to be removed, please get the value from qm.get_config().

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

Deprecated - This method is going to be removed, please use qm.get_config().

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

Deprecated - This method is going to be removed.

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

Deprecated - This method is going to be moved to the job API, please use job.set_output_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

Deprecated - This method is going to be moved to the job API, please use job.set_output_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_input_dc_offset_by_element

Deprecated - This method is going to be moved to the job API, please use job.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

Deprecated - This method is going to be moved to the job API, please use job.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

Deprecated - This method is going to be moved to the job API, please use job.set_io_values(io1=value)

Sets the values of IO1

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: Value

set_io2_value

Deprecated - This method is going to be moved to the job API, please use job.set_io_values(io2=value)

Sets the values of 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_2	The value to be placed in IO2 TYPE: Value

set_io_values

Deprecated - This method is going to be moved to the job API, please use job.set_io_values()

Sets the values of IO1 & `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[NumpySupportedValue] DEFAULT: None
value_2	The value to be placed in IO2 TYPE: Optional[NumpySupportedValue] DEFAULT: None

set_mixer_correction

Deprecated - This method is going to be removed, please use job.set_element_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

Deprecated - This method is going to be removed, please set idle value with qm.update_config() or current value from job job.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. 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.

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_with_deprecations.QmQueueWithDeprecations

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

Deprecated - This method is going to be removed, use qm.add_to_queue().

Adds a compiled QUA program to the end of the queueץ 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

clear

Empties the queue from all pending jobs

RETURNS	DESCRIPTION
int	The number of jobs removed

remove_by_id

Removes the pending job 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_user_id

Removes all pending jobs with a specific user id

PARAMETER	DESCRIPTION
user_id	a user id TYPE: str

RETURNS	DESCRIPTION
int	The number of jobs removed

Example

qm.queue.remove_by_id(job_id)