laboneq.dsl.quantum

laboneq.dsl.quantum.quantum_element

QuantumElement

A quantum element within a quantum device.

For example, a qubit or a coupler.

Attributes:

Name	Type	Description
uid	str	A unique identifier for the quantum element. E.g. q0.
signals	Dict[str, str]	A mapping for experiment signal names to logical signal paths.
parameters	QuantumParameters	Parameter values for the quantum element. For example, qubit frequency, drive pulse lengths.

Class attributes

PARAMETERS_TYPE: The type of the parameters used. Should be a sub-class of QuantumParameters. REQUIRED_SIGNALS: A tuple of experiment signal names that must be provided. OPTIONAL_SIGNALS: A tuple of optional signal names. Optional signals are used by the class but not required. SIGNAL_ALIASES: A mapping from alternative names for signals to their canonical names. Signal names are translated to canonical signal names when a quantum element is instantiated.

This attribute is provided as a means to provide backwards
compatibility with existing device configurations when signal naming
conventions change.

OPTIONAL_SIGNALS = () class-attribute instance-attribute

PARAMETERS_TYPE = QuantumParameters class-attribute instance-attribute

REQUIRED_SIGNALS = () class-attribute instance-attribute

SIGNAL_ALIASES = {} class-attribute instance-attribute

parameters = attrs.field(converter=attrs.Converter(_parameters_converter, takes_self=True), default=None) class-attribute instance-attribute

signals = attrs.field(converter=attrs.Converter(_signals_converter, takes_self=True), default=None) class-attribute instance-attribute

uid = attrs.field() class-attribute instance-attribute

calibration()

Return the calibration for this quantum element.

Calibration for each experiment signal is generated from the quantum element parameters.

Returns:

Type	Description
Calibration	The experiment calibration.

copy()

Returns a copy of the qubit.

create_parameters(**parameters) classmethod

Create a new instance of parameters for this qubit class.

Parameters:

Name	Type	Description	Default
parameters	dict[str, object]	Parameter values for the new parameter instance.	{}

Returns:

Type	Description
QuantumParameters	A new parameter instance.

experiment_signals()

Return the list of the experiment signals for this quantum element.

Returns:

Type	Description
List[ExperimentSignal]	A list of experiment signals.

from_device_setup(device_setup, qubit_uids=None, parameters=None) classmethod

Create a list of quantum elements from a device setup.

Parameters:

Name	Type	Description	Default
device_setup	DeviceSetup	The device setup to create the quantum elements from.	required
qubit_uids	list[str] | None	The set of logical signal group uids to create qubits from, or None to create qubits from all logical signal groups.	None
parameters	dict[str, QuantumParameters | dict[str, Any]] | None	A dictionary mapping quantum element UIDs to the parameters for that quantum element. Parameters may be specified either as a dictionary of parameter names and values, or as instances of the appropriate sub-class of QuantumParameters.	None

Returns:

Type	Description
list[QuantumElement]	A list of quantum elements.

!!! version-changed "Changed in version 2.46.0

The `parameters` argument was added.

In earlier versions, parameters needed to be set separately
after the quantum elements were created.

from_logical_signal_group(uid, lsg, parameters=None) classmethod

Create a quantum element from a logical signal group.

Parameters:

Name	Type	Description	Default
uid	str	A unique identifier for the quantum element. E.g. q0.	required
lsg	LogicalSignalGroup	The logical signal group containing the quantum elements signals.	required
parameters	QuantumParameters | dict[str, Any] | None	A dictionary of quantum element parameters or an instance of QuantumParameters.	None

Returns:

Type	Description
QuantumElement	A quantum element.

Note

The logical signal group prefix, /logical_signal_group/, will be removed from any signal paths if it is present.

load(filename) classmethod

Loads a QuantumElement object from a JSON file.

Parameters:

Name	Type	Description	Default
filename	Union[str, bytes, PathLike]	The name of the JSON file to load the QuantumElement object from.	required

Deprecated in version 2.43.0.

Use q = laboneq.serializers.load(filename) instead.

replace(**parameter_changes)

Return a new quantum element with the parameter changes applied.

Parameters:

Name	Type	Description	Default
parameter_changes	dict[str, object]	Parameter changes to apply passed as keyword arguments.	{}

Return

A new quantum element with the parameter changes applied.

save(filename)

Save a QuantumElement object to a JSON file.

Parameters:

Name	Type	Description	Default
filename	Union[str, bytes, PathLike]	The name of the JSON file to save the QuantumElement object.	required

Deprecated in version 2.43.0.

Use laboneq.serializers.save(q, filename) instead.

update(**parameter_changes)

Update this quantum element with supplied parameter changes.

Parameters:

Name	Type	Description	Default
parameter_changes	dict[str, object]	Parameter changes to apply passed as keyword arguments.	{}

Note

The parameters attribute of this quantum element is replaced with a new parameter instance.

QuantumParameters

Calibration parameters for a QuantumElement.

copy()

Returns a copy of the parameters.

replace(**changes)

Return a new set of parameters with changes applied.

Parameters:

Name	Type	Description	Default
changes	dict[str, object]	Parameter changes to apply passed as keyword arguments. Dotted key names such as a.b.c update nested parameters or items within parameter values that are dictionaries.	{}

Return

A new parameters instance.

laboneq.dsl.quantum.quantum_operations

Core classes for defining sets of quantum operations on qubits.

QuantumOperations(qpu=None)

Quantum operations for a given qubit type.

Parameters:

Name	Type	Description	Default
qpu	QPU | None	The quantum processing unit (QPU).	None

Attributes:

Name	Type	Description
QUBIT_TYPES	type[QuantumElement] | tuple[type[QuantumElement]] | None	(class attribute) The classes of qubits supported by this set of operations. The value may be a single class or a tuple of classes.
BASE_OPS	dict[str, Callable]	(class attribute) A dictionary of names and functions that define the base operations provided.

BASE_OPS = None class-attribute instance-attribute

QUBIT_TYPES = None class-attribute instance-attribute

qpu = qpu instance-attribute

attach_qpu(qpu)

Attach a QPU to the set of quantum operations.

copy()

Return a copy of the quantum operations instance.

Note

This does not copy the attached QPU, so that the quantum operations may be directly attached to a different QPU.

Returns:

Type	Description
QuantumOperations	A copy of the quantum operations instance.

detach_qpu()

Detach a QPU from the set of quantum operations.

keys()

Return the names of the registered quantum operations.

register(f, name=None)

Registers a quantum operation.

The given operation is wrapped in a Operation instance and added to this set of operations.

Parameters:

Name	Type	Description	Default
f	Callable	The function to register as a quantum operation. The first parameter of f should be the set of quantum operations to use. This allows f to use other quantum operations if needed. The qubits f operates on must be passed as positional arguments, not keyword arguments. Additional non-qubit arguments may be passed to f as either positional or keyword arguments.	required
name	str | None	The name of the operation. Defaults to f.__name__.	None

Example

Create a custom operation function, register and call it:

qop = qpu.quantum_operations


def custom_op(qop, q, amplitude):
    pulse = ...
    play(
        q.signals["drive"],
        amplitude=amplitude,
        pulse=pulse,
    )


qop.register(custom_op)
qop.custom_op(q, amplitude=0.5)

In the example above the qop argument to custom_op is unused, but custom_op could call another quantum operation using, e.g., qop.x90(q), if needed.

quantum_operation(f=None, *, broadcast=True, neartime=False)

Decorator that marks a method as a quantum operation.

Methods marked as quantum operations are moved into the BASE_OPS dictionary of the QuantumOperations class they are defined in at the end of class creation.

Functions marked as quantum operations take the QuantumOperations instance they are registered on as their initial self parameter.

Parameters:

Name	Type	Description	Default
f	Callable | None	The method to decorate. f should take as positional arguments the qubits to operate on. It may take additional arguments that specify other parameters of the operation.	None
broadcast	bool	If true, the operation may be broadcast across multiple qubits using .broadcast. Broadcasting requires that all operation arguments do not accept sequences of values (when not broadcasting).	True
neartime	bool	If true, the operation is marked as a near-time operation. Its section is set to near-time and no qubit signals are reserved.	False

Returns:

Type	Description
Callable	If f is given, returns the decorated method.
Callable	Otherwise returns a partial evaluation of quantum_operation with
Callable	the other arguments set.

laboneq.dsl.quantum.qpu

This module defines the QuantumPlatform and QPU classes.

A QPU contains the "physics" of a quantum device -- the quantum element parameters and definition of operations on quantum elements.

A QuantumPlatform contains the QPU, and the DeviceSetup which describes the control hardware used to interface to the device.

By itself a QPU provides everything needed to build or design an experiment for a quantum device. The DeviceSetup provides the additional information needed to compile an experiment for specific control hardware.

Together these provide a QuantumPlatform -- i.e. everything needed to build, compile and run experiments on real devices.

QPU(quantum_elements, quantum_operations)

A Quantum Processing Unit (QPU).

A QPU provides the logical description of a quantum device needed to build experiments for it. For example, the quantum element parameters and the definition of operations on those quantum elements.

It does not provide a description of the control hardware needed to compile an experiment.

In short, a QPU defines the device physics and a DeviceSetup defines the control hardware being used.

Deprecated in version 2.52.0.

The argument qubits was deprecated and replaced with the argument quantum_elements.

Parameters:

Name	Type	Description	Default
quantum_elements	QuantumElements	The quantum elements to run the experiments on.	required
quantum_operations	QuantumOperations | type[QuantumOperations]	The quantum operations to use when building the experiment.	required

Attributes: topology: The topology information for the QPU. Raises: TypeError: If quantum_operations has an invalid type.

quantum_elements = [quantum_elements] if isinstance(quantum_elements, QuantumElement) else list(quantum_elements) instance-attribute

quantum_operations = quantum_operations instance-attribute

qubits property

Return qubits.

Deprecated in version 2.52.0.

The attribute qubits was deprecated and replaced with the attribute quantum_elements.

topology = QPUTopology(self.quantum_elements) instance-attribute

copy_quantum_elements()

Return new quantum elements that are a copy of the original quantum elements.

copy_qubits()

Return new qubits that are a copy of the original qubits.

Deprecated in version 2.52.0.

The method copy_qubits was deprecated and replaced with the method copy_quantum_elements.

measure_section_length(quantum_elements) staticmethod

Calculates the length of the measure section for multiplexed readout.

In order to allow the quantum elements to have different readout and/or integration lengths, the measure section length needs to be fixed to the longest one across the quantum elements used in the experiment.

Parameters:

Name	Type	Description	Default
quantum_elements	QuantumElements	The quantum elements that are being measured.	required

Returns: The length of the multiplexed-readout measure section.

override_quantum_elements(quantum_element_parameters)

Override quantum element parameters and return a new QPU.

Note

This method detaches the quantum operations from the QPU and attaches them to the new QPU.

Parameters:

Name	Type	Description	Default
quantum_element_parameters	dict[str, dict[str, int | float | str | dict | None]]	The quantum elements and their parameters that need to be updated passed a dict of the form: {qb_uid: {qb_param_name: qb_param_value}}	required

Returns: A new QPU with overridden quantum element parameters. Raises: ValueError: If one of the quantum elements passed is not found in the qpu. If one of the parameters passed is not found in the quantum element.

override_qubits(qubit_parameters)

Override qubit parameters and return a new QPU.

Note

This method detaches the quantum operations from the QPU and attaches them to the new QPU.

Deprecated in version 2.52.0.

The method override_qubits was deprecated and replaced with the method override_quantum_elements.

Parameters:

Name	Type	Description	Default
qubit_parameters	dict[str, dict[str, int | float | str | dict | None]]	The qubits and their parameters that need to be updated passed a dict of the form: {qb_uid: {qb_param_name: qb_param_value}}	required

Returns: A new QPU with overridden qubit parameters. Raises: ValueError: If one of the qubits passed is not found in the qpu. If one of the parameters passed is not found in the qubit.

quantum_element_by_uid(uid)

Returns quantum element by UID.

Deprecated in version 2.55.0.

The method quantum_element_by_uid was deprecated. Use .__getitem__ instead.

Parameters:

Name	Type	Description	Default
uid	str	Unique identifier of the quantum element within the QPU.	required

Returns: Quantum element with given uid. Raises: KeyError: Quantum element does not exist.

qubit_by_uid(uid)

Returns qubit by UID.

Deprecated in version 2.52.0.

The method qubit_by_uid was deprecated and replaced with the method quantum_element_by_uid.

Parameters:

Name	Type	Description	Default
uid	str	Unique identifier of the qubit within the QPU.	required

Returns: Qubit with given uid. Raises: KeyError: Qubit does not exist.

update_quantum_elements(quantum_element_parameters)

Updates quantum element parameters.

Parameters:

Name	Type	Description	Default
quantum_element_parameters	dict[str, dict[str, int | float | str | dict | None]]	The quantum elements and their parameters that need to be updated passed a dict of the form: {qb_uid: {qb_param_name: qb_param_value}}	required

Raises: ValueError: If one of the quantum elements passed is not found in the qpu. If one of the parameters passed is not found in the quantum element.

update_qubits(qubit_parameters)

Updates qubit parameters.

Deprecated in version 2.52.0.

The method update_qubits was deprecated and replaced with the method update_quantum_elements.

Parameters:

Name	Type	Description	Default
qubit_parameters	dict[str, dict[str, int | float | str | dict | None]]	The qubits and their parameters that need to be updated passed a dict of the form: {qb_uid: {qb_param_name: qb_param_value}}	required

Raises: ValueError: If one of the qubits passed is not found in the qpu. If one of the parameters passed is not found in the qubit.

QuantumPlatform(setup, qpu)

A quantum hardware platform.

A QuantumPlatform provides the logical description of a quantum device needed to define experiments (the QPU) and the description of the control hardware needed to compile an experiment (the DeviceSetup).

In short, a QPU defines the device physics and a DeviceSetup defines the control hardware being used.

Parameters:

Name	Type	Description	Default
setup	DeviceSetup	The DeviceSetup describing the control hardware of the device.	required
qpu	QPU	The QPU describing the parameters and topology of the quantum device and providing the definition of quantum operations on the device.	required

Initialize a new QPU.

Parameters:

Name	Type	Description	Default
setup	DeviceSetup	The device setup to use when running an experiment.	required
qpu	QPU	The QPU to use when building an experiment.	required

qpu = qpu instance-attribute

setup = setup instance-attribute

session(do_emulation=False)

Return a new LabOne Q session.

Parameters:

Name	Type	Description	Default
do_emulation	bool	Specifies if the session should connect to an emulator (in the case of 'True'), or the real system (in the case of 'False')	False

laboneq.dsl.quantum.qpu_topology

QPUTopology(quantum_elements)

The QPU topology.

QPU topology provides a description of how quantum elements in the QPU are connected. In general, this can be described by a graph, with a subset of quantum elements at the nodes, e.g. qubits, and a distinct subset of quantum elements at the edges, e.g. couplers. Connections between nodes are directed.

Parameters:

Name	Type	Description	Default
quantum_elements	list[QuantumElement]	The quantum elements that make up the QPU.	required

Each node of the graph contains a single quantum element. Edges are identified by an edge tag and a source and target node. Optionally, each edge has their own QuantumParameters and a quantum element that is related to the edge. There may be multiple edges connecting two quantum elements in the same direction.

QPU topology is most relevant for multi-qubit gates, and so it can be omitted entirely for experiments with only single-qubit operations. However, it may also be useful for single-qubit experiments, e.g. when accounting for crosstalk.

Initialize the QPU topology graph.

Constructs the QPU topology graph from the list of quantum elements at the nodes.

add_edge(tag, source_node, target_node, *, parameters=None, quantum_element=None)

Add an edge between two quantum element nodes.

Edges are directed and identified by a tag together with a source and target node. Optionally, each edge has its own QuantumParameters and a quantum element that is associated to the edge. There may be multiple edges connecting two quantum elements in the same direction.

For example, two tunable transmon qubits may be connected by an edge, which contains a single quantum element, a tunable coupler, used to apply a swap gate.

Parameters:

Name	Type	Description	Default
tag	str	The edge tag (unique between two quantum element nodes in a given direction). This string is a user-defined tag used to categorize the edges. The edge tag, together with the source and target node UIDs, uniquely defines an edge.	required
source_node	str | QuantumElement	The quantum element at the source node. Either the quantum element UID or the quantum element object may be provided.	required
target_node	str | QuantumElement	The quantum element at the target node. Either the quantum element UID or the quantum element object may be provided.	required
parameters	QuantumParameters | None	The quantum parameters for the edge.	None
quantum_element	QuantumElement | str | None	The quantum element associated to the edge.	None

Raises: TypeError: If quantum_element has an invalid type.

Warning

Multiple edges between two quantum elements in a given direction with the same edge type are not allowed. Adding such an edge multiple times will overwrite the previous edge. In these cases, remove the previous edge before adding the new one.

copy()

Return a copy of the QPU topology.

edge_keys()

An iterator over the keys (UIDs) of the edges of the topology graph.

Each key is a tuple consisting of (tag, source_node, target_node).

edges()

An iterator over the edges of the topology graph.

get_edge(tag, source_node, target_node)

Get the edge between two quantum element nodes.

Return the (directed) edge between two quantum element nodes.

Parameters:

Name	Type	Description	Default
tag	str	The edge tag (unique between two quantum element nodes in a given direction). This string is a user-defined tag used to categorize the edges. The edge tag, together with the source and target node UIDs, uniquely defines an edge.	required
source_node	str | QuantumElement	The quantum element at the source node. Either the quantum element UID or the quantum element object may be provided.	required
target_node	str | QuantumElement	The quantum element at the target node. Either the quantum element UID or the quantum element object may be provided.	required

Returns: The edge. Raises: KeyError: If the edge key (tag, source_node, target_node) does not exist in the QPU.

get_edges(node=None, tag=None, *, other_node=None, incoming=None, outgoing=None)

Return a list of edges.

Parameters:

Name	Type	Description	Default
node	str | QuantumElement | None	If specified, filter the edges by node. May be passed as either the UID or the QuantumElement object.	None
tag	str | None	If specified, filter the list of edges by tag.	None
other_node	str | QuantumElement | None	If specified, filter the list of edges to contain only those connecting node and other_node. Only applicable if node is not None.	None
incoming	bool | None	If false, exclude incoming edges to node. If true, include incoming edges. Only applicable if node is not None.	None
outgoing	bool | None	If false, exclude outgoing edges from node. If true, include outgoing edges. Only applicable if node is not None.	None

Returns: The list of edges. Raises: ValueError: If node is None and any of other_node, incoming, or outgoing are not None.

Note

If incoming and outgoing are both None, all edges are returned. If only one is None, the other takes the sensible default of not the other.

get_node(node)

Get the node on the QPU topology graph.

Return the quantum element at the node.

Parameters:

Name	Type	Description	Default
node	str	The node UID.	required

Returns: The quantum element at the node. Raises: KeyError: If the node UID is not in the topology graph.

neighbours(node, tag=None, *, incoming=None, outgoing=None)

Return a list of neighbouring nodes attached to a quantum element node.

Parameters:

Name	Type	Description	Default
node	str | QuantumElement	The quantum element whose neighbours to return. May be passed as either the UID or the QuantumElement object.	required
tag	str | None	If specified, filter the list of neighbours by edge tag.	None
incoming	bool | None	If false, exclude incoming edges to node. If true, include incoming edges.	None
outgoing	bool | None	If false, exclude outgoing edges from node. If true, include outgoing edges.	None

Returns: The list of neighbouring nodes.

Note

If incoming and outgoing are both None, all neighbours are returned. If only one is None, the other takes the sensible default of not the other.

node_keys()

An iterator over the keys (UIDs) of the quantum elements (nodes) of the topology graph.

nodes()

An iterator over the quantum elements (nodes) of the topology graph.

plot(*, ax=None, disconnected=True)

Plot the QPU topology.

Plot a simple directed graph of the QPU topology, including: nodes, node labels, edges, edge labels, and directionality. The node labels are the UIDs of the quantum elements at the nodes. The edge labels are the custom edge tags in get_edge. The arrows on the graph indicate the directionality.

Parameters:

Name	Type	Description	Default
ax	Axes | None	The Matplotlib axes on which to draw the graph.	None
disconnected	bool	Whether to plot disconnected nodes.	True

remove_edge(tag, source_node, target_node)

Remove the edge between two quantum element nodes.

Remove the (directed) edge between two quantum element nodes from the QPU topology graph.

Parameters:

Name	Type	Description	Default
tag	str	The edge tag (unique between two quantum element nodes in a given direction). This string is a user-defined tag used to categorize the edges. The edge tag, together with the source and target node UIDs, uniquely defines an edge.	required
source_node	str | QuantumElement	The quantum element at the source node. Either the quantum element UID or the quantum element object may be provided.	required
target_node	str | QuantumElement	The quantum element at the target node. Either the quantum element UID or the quantum element object may be provided.	required

Raises: KeyError: If the edge key (tag, source_node, target_node) does not exist in the QPU.

TopologyEdge(tag, source_node, target_node, parameters, quantum_element)

An edge on the QPU topology graph.

Attributes:

Name	Type	Description
tag		The edge tag (unique between two quantum element nodes in a given direction). This string is a user-defined tag used to categorize the edges. The edge tag, together with the source and target node UIDs, uniquely defines an edge.
source_node		The source quantum element for the edge.
target_node		The target quantum element for the edge.
parameters		The quantum parameters for the edge.
quantum_element		The quantum element associated to the edge.

parameters = parameters instance-attribute

quantum_element = quantum_element instance-attribute

source_node = source_node instance-attribute

tag = tag instance-attribute

target_node = target_node instance-attribute

laboneq.dsl.quantum.qubit

Qubit = Transmon module-attribute

QubitParameters = TransmonParameters module-attribute

laboneq.dsl.quantum.transmon

Transmon

Bases: QuantumElement

A class for a superconducting, flux-tunable Transmon Qubit.

Deprecated in version 2.43.0.

This class is deprecated and was intended primarily for demonstration purposes. Instead of using it write a class that directly inherits from QuantumElement.

OPTIONAL_SIGNALS = ('drive_ef', 'drive_cr', 'flux') class-attribute instance-attribute

PARAMETERS_TYPE = TransmonParameters class-attribute instance-attribute

REQUIRED_SIGNALS = ('acquire', 'drive', 'measure') class-attribute instance-attribute

SIGNAL_ALIASES = {'acquire_line': 'acquire', 'drive_line': 'drive', 'measure_line': 'measure', 'drive_ef_line': 'drive_ef', 'drive_line_ef': 'drive_ef', 'drive_cr_line': 'drive_cr', 'flux_line': 'flux'} class-attribute instance-attribute

calibration()

Return the experiment calibration for this transmon.

Calibration for each experiment signal is generated from the transmon parameters.

Returns:

Type	Description
Calibration	The experiment calibration.

TransmonParameters

Bases: QuantumParameters

A class for the parameters of a superconducting, flux-tunable transmon qubit.

Deprecated in version 2.43.0.

This class is deprecated and was intended primarily for demonstration purposes. Instead of using it write a class that directly inherits from QuantumParameters.

drive_frequency_ef property

Qubit drive frequency for the e-f transition.

drive_frequency_ge property

Qubit drive frequency for the g-e transition.

drive_lo_frequency = None class-attribute instance-attribute

drive_range = 10.0 class-attribute instance-attribute

flux_offset_voltage = 0.0 class-attribute instance-attribute

readout_frequency property

Readout baseband frequency.

readout_integration_delay = 2e-08 class-attribute instance-attribute

readout_lo_frequency = None class-attribute instance-attribute

readout_range_in = 10.0 class-attribute instance-attribute

readout_range_out = 5.0 class-attribute instance-attribute

readout_resonator_frequency = None class-attribute instance-attribute

resonance_frequency_ef = None class-attribute instance-attribute

resonance_frequency_ge = None class-attribute instance-attribute

user_defined = attrs.field(factory=dict) class-attribute instance-attribute