laboneq.simple.dsl

LabOne Q builtins recommended for use with the LabOne Q Applications library.

This is intended to be the equivalent of laboneq.simple for the LabOne Q builtins, laboneq.dsl.experiment.builtins.

QuantumOperations()

Quantum operations for a given qubit type.

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: dict[str, Callable] = None class-attribute instance-attribute

QUBIT_TYPES: type[QuantumElement] | tuple[type[QuantumElement]] | None = None class-attribute instance-attribute

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.

acquire(signal, handle, kernel=None, length=None, pulse_parameters=None)

Perform an acquisition on the given signal in the active section.

Adds an acquire operation to the active section.

Parameters:

Name	Type	Description	Default
signal	str	A string that specifies the signal for the acquisition.	required
handle	str	A string that specifies the handle of the acquired results.	required
kernel	Pulse | list[Pulse] | None	An optional Pulse object that specifies the kernel for integration. In case of multistate discrimination, a list of kernels.	None
length	float | None	An optional float that specifies the integration length.	None
pulse_parameters	dict[str, Any] | list[dict[str, Any] | None] | None	An optional dictionary that contains pulse parameters for the integration kernel. In case of multistate discrimination, a list of dictionaries.	None

Raises:

Type	Description
LabOneQException	If there is no active section.

acquire_loop_rt(count, *, acquisition_type=AcquisitionType.INTEGRATION, averaging_mode=AveragingMode.CYCLIC, repetition_mode=RepetitionMode.FASTEST, repetition_time=None, reset_oscillator_phase=False, uid=None, name='unnamed')

Returns an acquire loop section context manager.

The arguments are the same as those of AcquireLoopRt.

Upon entering the returned context manager an AcquireLoopRt section is returned. Within the context block, operations and subsections are automatically added to the section.

Parameters:

Name	Type	Description	Default
count	int	Number of loops to perform.	required
acquisition_type	AcquisitionType	Type of the acquisition. One of integration, spectroscopy, discrimination or RAW.	INTEGRATION
averaging_mode	AveragingMode	Averaging method. One of sequential, cyclic or single shot.	CYCLIC
repetition_mode	RepetitionMode	Repetition method. One of fastest, constant or auto.	FASTEST
repetition_time	float | None	The repetition time, when repetition_mode is RepetitionMode.CONSTANT.	None
reset_oscillator_phase	bool	When true, reset all oscillators at the start of every step.	False
uid	str | None	Unique identifier for the section. Maybe be omitted if one is not required.	None
name	str	A name for the section. The name need not be unique. The name is used as a prefix for generating a uid for the section if one is not specified.	'unnamed'

Returns:

Type	Description
AcquireLoopRtSectionContextManager	An real-time acquire loop context manager.

active_section()

Return the currently active section.

Returns:

Type	Description
Section	The currently active section.

Raises:

Type	Description
LabOneQException	If no section is active.

add(section)

Add the given section or operation to the active section or experiment.

Parameters:

Name	Type	Description	Default
section	Section | Operation	The section or operation to add.	required

Raises:

Type	Description
LabOneQException	If there is no active section and no active experiment.

call(funcname, **kwargs)

Call a near-time function in the active section.

Adds a call operation to the active section.

Parameters:

Name	Type	Description	Default
funcname	str | Callable	Function that should be called.	required
kwargs	object	Arguments of the function call.	{}

Raises:

Type	Description
LabOneQException	If there is no active section.

case(state, *, uid=None, name='unnamed')

Returns a case section context manager.

Upon entering the returned context manager a Case is returned. Within the context block, operations and subsections are automatically added to the match section.

Case sections may appear as children of a match section.

Parameters:

Name	Type	Description	Default
state	int	Which state value this case is for.	required
uid	str | None	Unique identifier for the section. Maybe be omitted if one is not required.	None
name	str	A name for the section. The name need not be unique. The name is used as a prefix for generating a uid for the section if one is not specified.	'unnamed'

Raises:

Type	Description
LabOneQException	Upon entering the context manager if the case section would be created outside of a match section.

create_pulse(parameters, overrides=None, name=None)

Create a pulse from the given parameters and parameter overrides.

The parameters are dictionary that contains:

• a key "function" that specifies which function from the LabOne Q pulse_library to use to construct the pulse. The function may either be the name of a registered pulse functional or "sampled_pulse" which uses pulse_library.sampled_pulse.
• any other parameters required by the given pulse function.

Parameters:

Name	Type	Description	Default
parameters	dict	A dictionary of pulse parameters. If None, then the overrides must completely define the pulse.	required
overrides	dict | None	A dictionary of overrides for the pulse parameters. If the overrides changes the pulse function, then the overrides completely replace the existing pulse parameters. Otherwise they extend or override them. The dictionary of overrides may contain sweep parameters.	None
name	str | None	The name of the pulse. This is used as a prefix to generate the pulse uid.	None

Returns:

Name	Type	Description
pulse	Pulse	The pulse described by the parameters.

delay(signal, time, *, precompensation_clear=None)

Apply a delay on the given signal in the active section.

Adds a delay operation to the active section.

Parameters:

Name	Type	Description	Default
signal	str	The name of the signal to delay on.	required
time	float | Parameter	The duration of the delay (in seconds).	required
precompensation_clear	bool | None	If true, clear the precompensation filter of the signal.	None

Raises:

Type	Description
LabOneQException	If there is no active section.

experiment(*, uid=None, name=None, signals=None)

Returns an experiment context manager.

The arguments are the same as those of Experiment, except that sections, version and epsilon may not be directly supplied.

Upon entering the returned context manager an Experiment is returned. Within the context block, operations and subsections are automatically added to the experiment.

The experiment context manager may also be used as a decorator. The function being decorated will be executed withint the experiment context and the resulting experiment will be returned.

Parameters:

Name	Type	Description	Default
uid	str | None	Unique identifier for the experiment. If not specified, it will default to None unless the experiment context is used as a decorator, in which case it will default to the name of the decorated function.	None
name	str | None	A name for the experiment. The name need not be unique. If not specified, it will default to "unnamed" unless the experiment context is used as a decorator, in which case it will default to the name of the decorated function.	None
signals	dict[str, ExperimentSignal] | list[ExperimentSignal | str]	Experiment signals, if any.	None

Returns:

Type	Description
ExperimentContextManager	A new experiment context manager.

experiment_calibration()

Return the calibration of the active experiment in context.

Returns:

Type	Description
Calibration	The experiment calibration of the active experiment.

Raises:

Type	Description
LabOneQException	If there is no active experiment context.

map_signal(experiment_signal, logical_signal)

Connect an experiment signal to a logical signal.

This connects a signal on the active experiment to a logical signal on a device.

Parameters:

Name	Type	Description	Default
experiment_signal	str	The name of experiment signal.	required
logical_signal	LogicalSignal | str	The logical signal to connect to the experiment signal.	required

Note

One can also call Experiment.map_signal directly on the experiment after it is created.

match(handle=None, *, user_register=None, prng_sample=None, sweep_parameter=None, local=None, uid=None, name=None, play_after=None)

Returns a match section context manager.

The arguments are the same as those of Match, except that children may not be directly supplied.

Upon entering the returned context manager a Match is returned. Within the context block, operations and subsections are automatically added to the match section.

Only case(...) sections may appear as children of a match section.

Parameters:

Name	Type	Description	Default
handle	str | None	Handle from which to obtain results. See Section.measure and Section.acquire for where handles are specified.	None
user_register	int | None	User register on which to match.	None
prng_sample	PRNGSample | None	PRNG sample to match.	None
sweep_parameter	Parameter | None	Sweep parameter to match.	None
local	bool | None	Whether to fetch the codeword via the PQSC (False), SHFQC-internal bus (True) or automatic (None).	None
uid	str | None	Unique identifier for the section. Maybe be omitted if one is not required.	None
name	str | None	A name for the section. The name need not be unique. The name is used as a prefix for generating a uid for the section if one is not specified.	None
play_after	str | list[str] | None	A list of sections that must complete before this section may be played. If None, the section is played as soon as allowed by the signal lines required.	None

measure(*, acquire_signal, handle, integration_kernel=None, integration_kernel_parameters=None, integration_length=None, measure_signal=None, measure_pulse=None, measure_pulse_length=None, measure_pulse_parameters=None, measure_pulse_amplitude=None, acquire_delay=None, reset_delay=None)

Add a measurement to the active section.

A measurement consists of an optional playback of a measurement pulse, the acquisition of the return signal and an optional delay after the end of the acquisition.

Both spectroscopy and ordinary measurements are supported:

• For pulsed spectroscopy, set integration_length and either measure_pulse or measure_pulse_length.
• For CW spectroscopy, set only integration_length and do not specify the measure signal.
• For all other measurements, set either length or pulse for both the measure pulse and integration kernel.

Parameters:

Name	Type	Description	Default
acquire_signal	str	A string that specifies the signal for the data acquisition.	required
handle	str	A string that specifies the handle of the acquired results.	required
integration_kernel	Pulse | list[Pulse] | None	An optional Pulse object that specifies the kernel for integration. In case of multistate discrimination, a list of kernels.	None
integration_kernel_parameters	dict[str, Any] | list[dict[str, Any] | None] | None	An optional dictionary that contains pulse parameters for the integration kernel. In case of multistate discrimination, a list of dictionaries.	None
integration_length	float | None	An optional float that specifies the integration length.	None
measure_signal	str | None	An optional string that specifies the signal to measure.	None
measure_pulse	Pulse | None	An optional Pulse object that specifies the readout pulse for measurement. If this parameter is not supplied, no pulse will be played back for the measurement, which enables CW spectroscopy on SHFQA instruments.	None
measure_pulse_length	float | None	An optional float that specifies the length of the measurement pulse.	None
measure_pulse_parameters	dict[str, Any] | None	An optional dictionary that contains parameters for the measurement pulse.	None
measure_pulse_amplitude	float | None	An optional float that specifies the amplitude of the measurement pulse.	None
acquire_delay	float | None	An optional float that specifies the delay between the acquisition and the measurement.	None
reset_delay	float | None	An optional float that specifies the delay after the acquisition to allow for state relaxation or signal processing.	None

Raises:

Type	Description
LabOneQException	If there is no active section.

play(signal, pulse, amplitude=None, phase=None, increment_oscillator_phase=None, set_oscillator_phase=None, length=None, pulse_parameters=None, precompensation_clear=None, marker=None)

Play a pulse on the given signal in the active section.

Adds a play pulse operation to the active section.

Parameters:

Name	Type	Description	Default
signal	str	The name of the signal to play the pulse on.	required
pulse	Pulse	Pulse that should be played on the signal.	required
amplitude	float | complex | Parameter | None	Amplitude of the pulse that should be played.	None
phase	float | None	Phase of the pulse that should be played.	None
increment_oscillator_phase	float | Parameter | None	Increment the phase angle of the modulating oscillator at the start of playing this pulse by this angle (in radians).	None
set_oscillator_phase	float | None	Set the phase of the modulating oscillator at the start of playing this pulse to this angle (in radians).	None
length	float | Parameter | None	Modify the length of the pulse to the given value.	None
pulse_parameters	dict[str, Any] | None	Dictionary with user pulse function parameters (re)binding.	None
precompensation_clear	bool | None	Clear the precompensation filter during the pulse.	None
marker	dict | None	Instruction for playing marker signals along with the pulse.	None

Raises:

Type	Description
LabOneQException	If there is no active section.

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

Decorator that marks an 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.

qubit_experiment(exp_func=None, name=None, *, context=True)

qubit_experiment(exp_func: None = ..., name: str | None = ..., context: bool = ...) -> Callable[[Callable[T]], Callable[T, Experiment]]

qubit_experiment(exp_func: Callable[T], name: str | None = ..., context: bool = ...) -> Callable[T, Experiment]

Decorator for functions that build experiments for qubits.

Parameters:

Name	Type	Description	Default
exp_func	Callable[T] | None	The wrapped function that builds the experiment.	None
name	str | None	A name for this experiment. Defaults to exp_func.__name__ if no name is given.	None
context	bool	If true, the decorated function exp_func is called inside an experiment context using exp_func(*args, **kw). If false, the decorated function exp_func is passed the experiment as the first argument instead using exp_func(exp, *args, **kw) and no experiment context is active.	True

Returns:

Type	Description
Callable[T, Experiment] | Callable[[Callable[T]], Callable[T, Experiment]]	If exp_func is given, returns exp_func wrapped in an ExperimentBuilder.
Callable[T, Experiment] | Callable[[Callable[T]], Callable[T, Experiment]]	Otherwise returns a partial evaluation of qubit_experiment with the other
Callable[T, Experiment] | Callable[[Callable[T]], Callable[T, Experiment]]	parameters already set.

Examples:

@qubit_experiment
def rx_exp(qops, q, angle):
    qops.rx(q, angle)


@qubit_experiment(name="rx_exp")
def my_exp(qops, q, angle):
    qops.rx(q, angle)


@qubit_experiment(context=False)
def my_exp_2(exp, qops, q, andle):
    exp.add(qops.rx(q, angle))

reserve(signal)

Reserve the given signal in the active section.

Adds a reserve operation to the active section.

Parameters:

Name	Type	Description	Default
signal	str	The name of the signal to reserve.	required

Raises:

Type	Description
LabOneQException	If there is no active section.

section(*, uid=None, name='unnamed', alignment=SectionAlignment.LEFT, execution_type=None, length=None, play_after=None, trigger=None, on_system_grid=False)

Returns a new section context manager.

The arguments are the same as those of Section, except that children may not be directly supplied.

Upon entering the returned context manager a Section is returned. Within the context block, operations and subsections are automatically added to the section.

The section context manager may also be used as a decorator. The function being decorated will be executed within the section context and the resulting section will be returned.

Parameters:

Name	Type	Description	Default
uid	str | None	Unique identifier for the section. Maybe be omitted if one is not required.	None
name	str	A name for the section. The name need not be unique. The name is used as a prefix for generating a uid for the section if one is not specified.	'unnamed'
alignment	SectionAlignment	Specifies the time alignment of operations and sections within this section. Left alignment positions operations and sections as early in time as possible, right alignment positions them as late as possible.	LEFT
execution_type	ExecutionType | None	Whether the section is near-time or real-time. If None the section infers its execution type from its parent.	None
length	float | None	Minimum length of the section in seconds. The scheduled section length will be the greater of this minimum length and the length of the section contents, plus a small extra amount of times so that the section length is a multiple of the section timing grid. If None, the section has no minimum length and will be as short as possible.	None
play_after	str | Section | list[str | Section] | None	A list of sections that must complete before this section may be played. If None, the section is played as soon as allowed by the signal lines required.	None
trigger	dict[str, dict] | None	Optional trigger pulses to play during this section. See Experiment.section.	None
on_system_grid	bool	If True, the section boundaries are always rounded to the system grid, even if the contained signals would allow for tighter alignment.	False

Returns:

Type	Description
SectionContextManager	A section context manager.

set_node(path, value)

Set the value of an instrument node.

Adds a set node operation to the active section.

Parameters:

Name	Type	Description	Default
path	str	Path to the node whose value should be set.	required
value	Any	Value that should be set.	required

Raises:

Type	Description
LabOneQException	If there is no active section.

sweep(parameter, *, chunk_count=1, reset_oscillator_phase=False, uid=None, name='unnamed', alignment=SectionAlignment.LEFT)

Returns a sweep context manager.

The arguments are the same as those of Sweep, except that children, length, play_after, trigger and on_system_grid may not be directly supplied.

Upon entering the returned context manager a parameter is returned if only a single parameter is being swept. Otherwise a tuple of swepted parameters is returned.

Within the context block, operations and subsections are automatically added to the sweep section and the active section may be retrieved by calling active_section(...).

Parameters:

Name	Type	Description	Default
parameter	list[Parameter] | Parameter	Parameters that should be swept.	required
chunk_count	int	Split the sweep into N chunks. Default: 1.	1
reset_oscillator_phase	bool	When True, reset all oscillators at the start of every step. Default: False.	False
uid	str | None	Unique identifier for the section. Maybe be omitted if one is not required.	None
name	str	A name for the section. The name need not be unique. The name is used as a prefix for generating a uid for the section if one is not specified.	'unnamed'
alignment	SectionAlignment	Specifies the time alignment of operations and sections within this section. Left alignment positions operations and sections as early in time as possible, right alignment positions them as late as possible.	LEFT

Returns:

Type	Description
SweepSectionContextManager	A sweep section context manager.

uid(prefix)

Generate a unique identifier.

Generates an identifier that is unique to the experiment being constructed. The identifier is created by by appending a count to a given prefix.

Parameters:

Name	Type	Description	Default
prefix	str	The prefix for the unique identifier.	required

Returns:

Type	Description
str	A unique identifier.

Raises:

Type	Description
LabOneQException	If there is no active experiment context.

Workflow and context-based experiment building functions and utilities.

Builtins

• acquire
• acquire_loop_rt
• active_section
• add
• call
• case
• delay
• experiment
• experiment_calibration
• map_signal
• match
• measure
• play
• reserve
• section
• set_node
• sweep
• uid

Pulse library

• pulse_library

Workflow

• handles

Qubit experiments and quantum operations

• qubit_experiment
• QuantumOperations
• create_pulse
• quantum_operation