API Reference

Module containing the ArbokDriver class for managing and running sequences on a physical OPX instrument.

class arbok_driver.arbok_driver.ArbokDriver(name, device, **kwargs)

Bases: Instrument

Class containing all functionality to manage and run modular sequences on a physical OPX instrument

property measurements: list[Measurement]

Measurements to be run within program uploaded to the OPX

reset_measurements()

Resets all measurements in the program TODO: delete instances of those measurements

Return type:

None

connect_opx(host_ip, qm_config=None, reconnect=False, **kwargs)

Creates QuantumMachinesManager and opens a quantum machine on it with the given IP address

Parameters:

• host_ip (str) – Ip address of the OPX

• qm_config (dict) – QM/OPX config dictionary to be used. Defaults to None, in which case the config from the device is used. If given overwrites the device config.

• reconnect (bool) – Whether to reconnect to the OPX if already connected. Keeps QMM alive if true. Defaults to False.

• **kwargs – Arbitrary keyword arguments for QMM instanciation

Return type:

None

reconnect_opx(host_ip, qm_config=None)

Reconnects to the OPX with the given IP address and closes the previous connection

Parameters:

• host_ip (str) – Ip address of the OPX

• qm_config (dict) – QM/OPX config dictionary to be used. Defaults to None, in which case the config from the device is used. If given overwrites the device config.

Return type:

None

add_measurement(new_measurement)

Adds a class which inherits Measurement to the program and adds it as a QCoDeS sub-module

Parameters:

• new_measurement (Measurement) – The instance which inherits

• added (Measurement to be)

run(qua_program, **kwargs)

Sends the qua program for execution to the OPX and sets the programs result handles

Parameters:

qua_program (program) – QUA program to be executed

print_qua_program_to_file(path, qua_program, add_config=False)

Creates file with ‘filename’ and prints the QUA code to this file

Parameters:

• file_name (str) – File name of target file

• qua_program (program) – QUA program to be printed

• add_config (bool) – Whether config is added to output file

Return type:

None

run_local_simulation(qua_program, duration, nr_controllers=1, plot=True, **kwargs)

Simulates the given program of the sequence for duration cycles TODO: Move to SequenceBase and add checks if OPX is connected :type qua_program: program :param qua_program: QUA program to be simulated :type qua_program: program :type duration: int :param duration: Simulation duration in cycles :type duration: int :type nr_controllers: int :param nr_controllers: Number of controllers to simulate :type nr_controllers: int :type plot: bool :param plot: Whether to plot the simulation results :type plot: bool :type **kwargs: :param **kwargs: Arbitrary keyword arguments for QMM simulation

Returns:

QM job with waveform simulation result nr_controllers (int): Nr of controllers to fetch simulation results

Return type:

simulated_job (SimulatedJob)

get_idn()

Overload the get_idn method as we don’t have one.

ask_raw(cmd)

Abstract method from qcodes Instrument

Return type:

str

write_raw(cmd)

Abstract method from qcodes Instrument

Return type:

str

create_measurement_from_experiment(experiment, qc_measurement_name=None, name='measurement')

Creates an arbok and QCoDeS measurement from an arbok-experiment

Parameters:

• name (str) – Name of the measurement (py. variable name compliant)

• experiment (arbok_driver.Experiment) – Experiment to be run

• qc_measurement_name (str) – Name of the QCoDeS measurement (as it will be saved in the database)

Returns:

Measurement instance

Return type:

measurement (arbok_driver.Measurement)

check_db_engine_and_bucket_connected()

Checks if database engine and s3 bucket are connected Raises error if not connected TODO: ping both TCP connections to check if still alive

get_run_from_id(run_id)

Fetches a run from the connected arbok database engine based on the given run ID

Parameters:

run_id (int) – ID of the run to be fetched

Returns:

detached run instance

Return type:

run (arbok_driver.sqlalchemy_classes.SqlRun)

get_data_from_id(run_id)

Fetches data from the connected database engine based on the given run ID

Parameters:

run_id (int) – ID of the run to fetch data from

Returns:

Lazy loaded xarray dataset. Will only

load data when using .load() or .compute() methods!

Return type:

xr_dataset (xarray.Dataset)

Module containing abstract class for dependent readouts

class arbok_driver.abstract_readout.EmptyParameterClass

Bases: ParameterClass

class arbok_driver.abstract_readout.AbstractReadout(name, read_sequence, signal, save_results=True, parameters=None)

Bases: Generic[P], ABC

Abstract base class for abstract readouts. This base class handles qua variable and stream declaration, saving and streaming. The child class only needs to handle the abstract method qua_measure

PARAMETER_CLASS: Type[P]

read_sequence: ReadSequence

signal: Signal

arbok_params: P

abstractmethod qua_measure()

Measures the qua variables for the given abstract readout

property parameters: dict[str, SequenceParameter]

Returns the parameters of the readout

property gettables: dict[str, GettableParameterBase]

Returns the gettables of the readout

create_gettable(gettable_name, var_type)

Creates a new GettableParameter for the AbstractReadout. The gettable is added to the read sequence as a parameter and registered

under the given name.

Parameters:

• gettable_name (str) – Name of the gettable to be created

• var_type (int | bool | qua.fixed) – Type of the gettable variable

Returns:

The created gettable parameter

Return type:

GettableParameter

create_multi_gettable(gettable_name, var_type, internal_setpoints)

Creates a new GettableParameterMulti for the AbstractReadout. The gettable is added to the read sequence as a parameter and registered under the given name.

Parameters:

• gettable_name (str) – Name of the gettable to be created

• var_type (int | bool | qua.fixed) – Type of the gettable variable

• (internal_setpoints (internal_setpoints) – Sequence[Parameter]): setpoints for this multi gettable

Returns:

The created gettable parameter

Return type:

GettableParameter

qua_declare_variables()

Declares all necessary qua variables for readout

Return type:

None

qua_save_variables()

Saves the qua variables of all gettables in this readout

Return type:

None

qua_save_streams()

Saves acquired results to qua stream

Return type:

None

qua_measure_and_save(*args, **kwargs)

Measures and saves the result of the given readout

add_qc_params_from_config(param_dict)

Adds the given parameters to the sequence with the readout prefix

Parameters:

params (list) – List of parameter names to be added to the sequence

Return type:

None

map_arbok_params()

Adds the parameters to a ParameterClass instance

Returns:

ParameterClass with references to all needed params

Return type:

ParameterClass

get_gettable_from_path(attr_path)

Returns the gettable from a given path from a given string. If the string leads to an AbstractReadout it is being tried to find a single gettable associated to that AbstractReadout

Parameters:

attr_path (str) – Path to the given gettable relative to the ReadSequence with the format ‘signal.gettable_name’

Returns:

The found gettable from the given path

Return type:

gettable

Raises:

• ValueError – If the path is not in the format ‘signal.gettable_name’

• KeyError – If the signal or gettable is not found in the read sequence

• TypeError – If the found object is not a child class of gettable

Module containing Devices class

class arbok_driver.device.Device(name, opx_config, divider_config, master_config=None)

Class describing the used device by its config and the used sequence.

property master_config_path

Getter for master_config.

Returns:

The current configuration dictionary.

Return type:

str

reload_master_config()

If the master config path is set, force reloading

Module containing abstract class for experiments

class arbok_driver.experiment.Experiment(**configs_to_prepare)

Abstract class describing a type of experiment to run on the QM. This enforces a certain order of sequences that only requires certain input parameters or configurations to be set. E.g. for a rabi experiment, the order of sequences is:

1. Initialization of quantum state

2. Rabi pulse

3. Readout of quantum state

abstract property sequences_config: dict

Sequences to be run within program uploaded to the OPX

property name: str

Name of the experiment to run

get_device_specific_subsequences_dict(device)

Prepare configurations for the experiment by updating the default configs.

Parameters:

device (dict) – Device to use for default sequences

Module containing the Measurement class

class arbok_driver.measurement.Measurement(parent, name, sequence_config=None)

Class describing a Measurement in an OPX driver

merge_with_device_config(device, sequence_config)

Merges a sequence configuration with a device’s master configuration.

If both sequence_config and device.master_config are provided, the device’s master configuration takes precedence in case of key conflicts.

Parameters:

• device – An object with a ‘master_config’ attribute (dict or None).

• sequence_config – A dictionary representing the sequence configuration, or None.

Returns:

A new dictionary containing the merged configurations. If neither sequence_config nor device.master_config is provided, an empty dictionary is returned.

reset()

On reset, call super to reset then, reset local params, sweeps and gettables

Return type:

None

reset_registered_gettables()

Resets gettables to prepare for new measurement

Return type:

None

property sweeps: list[Sweep]

List of Sweep objects for SubSequence

property gettables: dict[str, GettableParameterBase]

List of `GettableParameter`s for data acquisition

property sweep_size: int

Product of sweep axes sizes

property sweep_dims: tuple[int]

Dimensionality of sweep axes

property step_requirements: list

Registered input stream parameters

property available_gettables: list[GettableParameter]

List of all available gettables from all sub sequences

property is_mock: bool

Returns True if the measurement is a mock measurement

property run_id: int

Run id of the measurement

property dataset: Dataset

Xarray Dataset of the measurement

property input_stream_parameters: list[SequenceParameter]

Registered input stream parameters

qua_declare()

Contains raw QUA code to declare variables

qua_before_sweep()

Qua code to be executed before the sweep loop but after the qua.pause statement that aligns the measurement results

Return type:

None

qua_before_sequence(simulate=False)

Qua code to be executed before the inner measurement

qua_after_sequence()

Qua code to be executed after the measurement loop and the code it contains

qua_increment_shot_tracker()

Increments the shot tracker variable by one and saves it to stream

qua_stream()

Contains raw QUA code to define streams

set_sweeps(*args)

Sets the given sweeps from its dict type arguments. Each argument creates one sweep axis. Each dict key, value pair is sweept concurrently along this axis.

Parameters:

*args (dict) – Arguments of type dict with SequenceParameters as keys and np arrays as setpoints. All values (arrays) must have same length!

Return type:

None

register_gettables(*args, keywords=None, verbose=False)

Registers GettableParameters that will be retreived during measurement. Gettable parameters can be given as arguments or automatically seached by keywords.

Parameters:

• *args (GettableParameter) – Parameters to be measured

• keywords (str | list) – Keywords to find gettables by name

Return type:

None

get_qua_code(simulate=False)

Compiles all qua code from its sub-sequences and writes their loops

Parameters:

simulate (bool) – True if the program is meant to be simulated

Return type:

program

Reterns:

qua_program: Program from qm context manager

compile_qua_and_run(save_path=None)

Compiles the QUA code and runs it

Return type:

None

insert_single_value_input_streams(value_dict)

Compresses all input streams to single array stream

Parameters:

value_dict (dict) – Dictionary containing all input stream parameters (SequenceParameters) and their values

Raises:

• KeyError – If not all input stream parameters that were added to the input_stream_parameters attribute are given in value_dict

• ValueError – If the given value_dict contains invalid types

Return type:

None

add_available_gettables(gettables)

Adds given gettables to the list of all gettables

Parameters:

gettables (list) – List of GettableParameters

Return type:

None

get_sequence_path()

Returns its name since Measurement is the top level

add_input_stream_parameter(parameter)

Adds given parameter to input stream parameters

Return type:

None

advance_input_streams(new_value_dict)

Advances all input streams by one step with the new given values

Parameters:

new_value_dict (dict) – Dictionary containing all parameters and their new values

Return type:

None

qua_check_step_requirements(action, requirements_list=None)

Checks if the qua variables corresponding to the given save requirements are true and save results to GettableParameters. Otherwise continue without saving. This is useful for feedback sequences or conditional operations.

find_parameter_from_sub_sequence(attr_path)

Returns the parameter from a given path

Return type:

SequenceParameter

add_step_requirement(requirement)

Adds a bool qua variable as a step requirement for the measurement

Return type:

None

add_subsequences_from_dict(subsequence_dict, namespace_to_add_to=None)

Adds subsequences to the sequence from a given dictionary

Parameters:

• subsequence_dict (dict) – Dictionary containing the subsequences

• namespace_to_add_to (dict) – Name space to insert the subsequence into (e.g locals(), globals()) defaults to None

Return type:

None

get_qc_measurement(measurement_name=None)

Creates a QCoDeS measurement from the given experiment

Parameters:

measurement_name (str) – Name of the QCoDeS measurement (as it will be saved in the database)

Returns:

Measurement instance

Return type:

qc_measurement (qc.dataset.Measurement)

get_xr_dataset_and_id()

Creates a QCoDeS dataset from the given experiment TODO: THIS NEEDS TO BE IN QCODES MEASUREMENT RUNNER

Returns:

Dataset instance

Return type:

qc_dataset (qc.dataset.Dataset)

run_measurement(ext_sweep_list=None, inner_func=None, qua_program_save_path=None, opx_address=None, measurement_backend='qcodes')

Runs the measurement with the given sweep list based on MeasurementRunner class TODO: add default save path!

Parameters:

• ext_sweep_list (list[dict]) – List of dictionaries with parameters as keys and np.ndarrays as setpoints. Each list entry creates one sweep axis. If you want to sweep params concurrently enter more entries into their sweep dict

• inner_func (callable) – The function to be executed for each setpoint in the sweep list (e.g on every opx data fetch)

• qua_program_save_path (str) – The file path to save the compiled QUA program. Defaults to None. If not given, the program is being auto-saved next to the database.

• opx_address (str) – The address of the OPX. Defaults to None. If not given does not attempt to connect to the OPX.

• measurement_backend (str) – The measurement backend to use. Can be either ‘qcodes’ or ‘native’.

Return type:

Dataset

get_measurement_runner(ext_sweep_list=None, measurement_backend='qcodes')

Returns the measurement runner for the current measurement

Parameters:

• ext_sweep_list (list[dict]) – List of dictionaries with parameters as keys and np.ndarrays as setpoints. Each list entry creates one sweep axis. If you want to sweep params concurrently enter more entries into their sweep dict

• measurement_backend (str) – The measurement backend to use. Can be either ‘qcodes’ or ‘native’.

Returns:

The measurement runner instance

Return type:

MeasurementRunner

wait_until_result_buffer_full(progress_tracker=None)

Waits until the result buffer is full and updates the progress bar if given

Parameters:

progress_bar (tuple) – Tuple containing the progress bar and the total number of results

fetch_all_results()

Fetches all results from the quantum machine

Returns:

Contains a dict with result names and results as key value pair

Return type:

dict

Module containing BaseSequence class

class arbok_driver.sequence_base.SequenceBase(parent, name, sequence_config=None, check_step_requirements=False, **kwargs)

Class describing a subsequence of a QUA programm (e.g Init, Control, Read).

classmethod config_template()

The user can get an example config template. This feature is useful if building from scratch or for UI prompting.

Return type:

None

Returns:

A dictionary with an example config template.

qua_declare()

Contains raw QUA code to initialize the qua variables

Return type:

None

qua_before_sweep()

Contains raw QUA code that is being executed before sweeps

Return type:

None

qua_before_sequence()

Contains raw QUA code that is being executed before the sequence

Return type:

None

qua_sequence()

Contains raw QUA code to define the pulse sequence

Return type:

None

qua_after_sequence()

Contains raw QUA code that is being executed after the sequence

Return type:

None

qua_stream()

Contains raw QUA code to define streams

Return type:

None

property sub_sequences: list[SubSequence]

List of `SubSequences`s that build the given sequence

property sub_sequence_dict: dict

List of `SubSequences`s that build the given sequence

property gettables: list

List of GettableParameter`s that can be registered for acquisition in a `program

add_subsequence(new_sequence)

Adds a subsequence to self

Return type:

None

add_qc_params_from_config(config)

Creates QCoDeS parameters for all entries of the config TODO: Use custom Parameter types for times -> setting in ns ! (cycles)

use validator to check if ns are a multiple of 4 (1 cycle)

TODO: if voltage add scale = 0.5 and validate if |v| <= 0.5

Parameters:

config (dict) – Configuration containing all sequence parameters

draw_sub_sequence_tree()

Draws a tree of the subsequences of the sequence with their names and types

Return type:

None

get_qua_program_as_str(recompile=False)

Returns the qua program as str. Will be compiled if it wasnt yet

Return type:

str

get_qua_program(simulate=False, config=None)

Composes the entire sequence by searching recursively through init, sequence and stream methods of all subsequences and their subsequences. The respective qua sequence will only be added once the recursive scans have reached the lowest level of sequences (e.g sequences have no sub-sequences anymore)

Parameters:

simulate (bool) – Flag whether program is simulated

Returns:

Program compiled into QUA language

Return type:

program

get_qua_code(simulate=False)

Composes the entire qua sequence in qua code. Only execurte with qm.qua.program() environment

Parameters:

simulate (bool) – True if program is generated for simulation

print_qua_program_to_file(file_name)

Creates file with ‘filename’ and prints the QUA code to this file

qua_declare_sweep_vars()

Declares all sweep variables as QUA with their correct type

Return type:

None

recursive_sweep_generation(sweeps)

Recursively generates QUA parameter sweeps by introducing one nested QUA loop per swept axis. The last given sweep and its corresponding setpoints are in the innermost loop. TODO: Reimplement a fast version of this for non-paired parameter

sweeps

Parameters:

sweeps (list) – list of Sweep objects

reset()

On reset, ensure param validators are no longer sweep_validators

Return type:

None

remove_subsequences()

Removes all subsequences from the sequence

Return type:

None

run_remote_simulation(host, port, duration)

Simulates the MW sequence on a remote simulator on the host

Parameters:

• host (str) – Host address

• duration (int) – Amount of cycles (4ns/cycle) to simulate

Returns:

QM job containing simulation results

Return type:

SimulatedJob

find_parameters_from_keywords(keys, elements=None)

Returns a list containing all parameters of the seqeunce with names that contain one of names in the ‘keys’ list. TODO: - raise error if no params were found

Parameters:

• keys (str | list) – string with parameter name sub-string or list of those

• elements (list)

Return type:

dict

Returns:

Dict of parameters containing substrings from keys in their name

with element as key

find_parameters(key, elements=None)

Finds all parameters generated from elements and a the given key. Similar to find_parameters_from_keywords but returns a non nested dict with elements as keys and SequenceParameters as key. This function gets its elements straigt from the given quantum machines config, therefore only params with elements that are known to the hardware are returned.

Parameters:

• key (str) – Name of the searched parameters

• elements (list) – List of elements to be searched for

Returns:

Dict with all found SequenceParameters and elements as keys

Return type:

dict

find_parameter(key, element)

Returns parameter with a certain key for a given element

get_attribute_by_path(path)

Access a nested attribute using a dot-separated string. :type path: :param path: a dot delimited path to get the variable from.

Returns:

The variable matching the string path

find_parameter_from_str_path(path)

Returns the parameter from the given path

Parameters:

path (str) – Path to the parameter

Returns:

Parameter at the given path

Return type:

SequenceParameter

ask_raw(*args)

Overwrites abstract method

set_raw(*args)

Overwrites abstract method

set_params_with_unit_to_value(unit, value)

Sets all parameters with the given unit to the given value

Parameters:

• unit (str) – Unit of the parameters to be set

• value (any) – Value to be set

Return type:

None

Module containing signal class

class arbok_driver.signal.Signal(name, read_sequence)

Class managing voltage signal from certain readout elements of OPX

property gettables: dict[str, GettableParameterBase]

Dictionary with all gettables registered on the signal

add_gettable(gettable)

Adds a gettable parameter to the signal

Parameters:

gettable (GettableParameter) – Gettable parameter to be added

Return type:

None

Module containing Sequence class

class arbok_driver.sub_sequence.SubSequence(parent, name, sequence_config=None, check_step_requirements=False, **kwargs)

Class describing a subsequence of a QUA programm (e.g Init, Control, Read).

property measurement: Measurement

Returns parent (sub) sequence

qua_sequence()

Contains raw QUA code to define the pulse sequence

map_arbok_params()

Maps required params for QUA code to arbok_params attribute

Return type:

ParameterClass

add_subsequences_from_dict(subsequence_dict, namespace_to_add_to=None)

Adds subsequences to the sequence from a given dictionary

Parameters:

• subsequence_dict (dict) – Dictionary containing the subsequences

• namespace_to_add_to (dict) – Namespace to add the registered subsequences to

Return type:

None

find_measurement()

Recursively searches the parent sequence

Return type:

Measurement

get_sequence_path(path=None)

Returns the path of subsequences up to the parent sequence

Return type:

str

Module with Sweep class

class arbok_driver.sweep.Sweep(measurement, param_dict, register_all=False)

Class characterizing a parameter sweep along one axis in the OPX

property parameters: list[SequenceParameter]

List containing all varied parameters

property qua_variables

Tuple containing all qua variables of parameters

property qua_sweep_arrays

Tuple containing all qua sweep arrays of parameters

property length: int

Length of sweep array for parameters on the given axis

property input_streams

Returns all input streams if the sweep is set up to be streamed

property inputs_are_streamed: bool

Whether sweep is fed by input stream

property can_be_parameterized

Whether sweep can be parameterized with start, stop and step for memory saving. If the user has not set this value, it will be checked by the entries of the given arrays

property config: dict[SequenceParameter, ndarray]

Config dict for parameter sweep. Keys are params, values setpoints

property config_to_register: dict

Parameters that will be registered in QCoDeS measurement

configure_sweep()

Return type:

None

Configures the sweep from the given dictionairy TODO: This breaks the input stream implementation, needs to be fixed

i am quite sure this can be done more elegantly! perhaps not even using set_sweeps but a different method on measurement

check_input_dict()

Return type:

None

Validates equal sizes of input arrays in three steps:

1. Checks if all parameters are SequenceParameter/Parameter

2. Checks if var_type is int, bool or qua.fixed

3. Checks if all sweep setpoint arrays have same lengths

4. Checks if all input streams have the same dimension

qua_generate_parameter_sweep(next_action, next_sweep)

Return type:

None

Runs a qua loop based on the configured method. Currently three different methods are available:

1. From input stream

2. From parametrized array (start, stop, step)

3. From an explicitly defined qua array

If necessary, we need to reset the snake var for the inner loop before entering the snaking loop.

get_snake_var()

Declare a snake_var if we are snaking and return that var if snaking.

Returns:

The snaking indicator if snaking, None otherwise

Return type:

qua bool var

remove_parameter_dependencies()

Removes all qcodes parameter dependencies set by is_controlled_by and has_control_of methods.

Return type:

None