Skip to content

laboneq.dsl.experiment

laboneq.dsl.experiment.section

AcquireLoopNt dataclass

Bases: Section

Near time acquire loop.

Deprecated in 2.14

Use .sweep outside of an acquire_loop_rt instead. For example:

param = SweepParameter(values=[1, 2, 3])
with exp.sweep(param):  # <-- outer near-time sweep
    with exp.acquire_loop_rt(count=2):  # <-- inner real-time sweep
        ...

Attributes:

Name Type Description
averaging_mode AveragingMode

Averaging method. One of sequential, cyclic or single shot. Default: AveragingMode.CYCLIC.
count int

Number of loops to perform.

AcquireLoopNt inherits all the attributes of Section.

The execution type of AcquireLoopNt sections is always ExecutionType.NEAR_TIME and should not be altered.

AcquireLoopRt dataclass

Bases: Section

Real time acquire loop.

Attributes:

Name Type Description
acquisition_type AcquisitionType

Type of the acquisition. One of integration trigger, spectroscopy, discrimination, demodulation and RAW. Default: AcquisitionType.INTEGRATION.
averaging_mode AveragingMode

Averaging method. One of sequential, cyclic or single shot. Default: AveragingMode.CYCLIC.
count int

Number of loops to perform.
repetition_mode RepetitionMode

Repetition method. One of fastest, constant and auto. Default: RepetitionMode.FASTEST
repetition_time float | None

The repetition time, when repetition_mode is RepetitionMode.CONSTANT.
reset_oscillator_phase bool

When true, reset all oscillators at the start of every step. Default: False.

AcquireLoopRt inherits all the attributes of Section.

The execution type of AcquireLoopRt sections is always ExecutionType.REAL_TIME and should not be altered.

Case dataclass

Bases: Section

Branch in a match section.

Attributes:

Name Type Description
state int

Which state value this case is for. Default: 0.

Case inherits all the attributes of Section.

A Case may only be added to a Match section and not to any other kind of section.

A Case may only contain PlayPulse and Delay operations and not other kinds of operations or sections.

add(obj)

Add an operation the Case section.

Parameters:

Name Type Description Default
obj Operation

The PlayPulse or Delay operation to be added.

 required

from_section(section, state) classmethod

Convert a section to a case section.

Parameters:

Name Type Description Default
section Section

The section to convert.

 required
state int

The state the generated case is for.

 required

Returns:

Name Type Description
case Case

A case section for the specified state with the same contents as the original section.

Note

This method may only be used with sections that are of the base Section. type. Sub-classes may not be used.

Match dataclass

Bases: Section

Execute one of the child branches depending on feedback result.

Attributes:

Name Type Description
handle str | None

Handle from which to obtain results. See Section.measure and Section.acquire for where handles are specified.
user_register int | None

User register on which to match.
local bool

Whether to fetch the codeword via the PQSC (False), SHFQC-internal bus (True) or automatic (None). Default: None.

Match inherits all the attributes of Section.

Only subsections of type Case may be added to a Match section.

add(case)

Add a branch to which to switch.

Parameters:

Name Type Description Default
case Case

Branch that is added.

 required

Section dataclass

Representation of a section. A section is a logical concept that groups multiple operations into a single entity that can be though of a container. A section can either contain other sections or a list of operations (but not both at the same time). Operations within a section can be aligned in various ways (left, right). Sections can have a offset and/or a predefined length, and they can be specified to play after another section.

Attributes:

Name Type Description
uid str | None

Unique identifier for the section. Maybe be omitted if one is not required. Default: None.
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. Default: SectionAlignment.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. Default: 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. Default: None.
play_after str | Section | List[Union[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. Default: None.
children List[Union[Section, Operation]]

List of children. Each child may be another section or an operation. Default: [].
trigger Dict[str, Dict]

Optional trigger pulses to play during this section. See Experiment.section. Default: {}.
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. Default: False.

Changed in version 2.0.0

Removed offset member variable.

operations: Tuple[Operation, ...] property

A list of operations in the section.

Note that there may be other children of a section which are not operations but subsections.

sections: Tuple[Section, ...] property

A list of subsections of this section.

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

Acquisition of results of a signal.

Parameters:

Name Type Description Default
signal str

Unique identifier of the signal where the result should be acquired.

 required
handle str

Unique identifier of the handle that will be used to access the acquired result.

 required
kernel Pulse | list[Pulse] | None

Pulse base used for the acquisition. In case of multistate discrimination, a list of kernels.

 None
length float | None

Integration length (only valid in spectroscopy mode).

 None
pulse_parameters dict[str, Any] | list[dict[str, Any] | None] | None

Dictionary with user pulse function parameters (re)binding. In case of multistate discrimination, a list of dicts.

 None

add(section)

Add a subsection or operation to the section.

Parameters:

Name Type Description Default
section Union[Section, Operation, SetNode]

Item that is added.

 required

call(func_name, **kwargs)

Function call.

Parameters:

Name Type Description Default
func_name Union[str, Callable]

Function that should be called.

 required
kwargs dict

Arguments of the function call.

 {}

delay(signal, time, precompensation_clear=None)

Adds a delay on the signal with a specified time.

Parameters:

Name Type Description Default
signal str

Unique identifier of the signal where the delay should be applied.

 required
time Union[float, Parameter]

Duration of the delay.

 required
precompensation_clear Optional[bool]

Clear the precompensation filter during the delay.

 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)

Execute a measurement.

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

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 Optional[Pulse | list[Pulse]]

An optional Pulse object that specifies the kernel for integration. In case of multistate discrimination, a list of kernels.

 None
integration_kernel_parameters Optional[Dict[str, Any] | List[Dict[str, Any] | None]]

An optional dictionary that contains pulse parameters for the integration kernel. In case of multistate discrimination, a list of kernels.

 None
integration_length Optional[float]

An optional float that specifies the integration length.

 None
measure_signal Optional[str]

An optional string that specifies the signal to measure.

 None
measure_pulse Optional[Pulse]

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 Optional[float]

An optional float that specifies the length of the measurement pulse.

 None
measure_pulse_parameters Optional[Dict[str, Any]]

An optional dictionary that contains parameters for the measurement pulse.

 None
measure_pulse_amplitude Optional[float]

An optional float that specifies the amplitude of the measurement pulse.

 None
acquire_delay Optional[float]

An optional float that specifies the delay between the acquisition and the measurement.

 None
reset_delay Optional[float]

An optional float that specifies the delay after the acquisition to allow for state relaxation or signal processing.

 None

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 a signal.

Parameters:

Name Type Description Default
signal str

Signal the pulse should be played on.

 required
pulse Pulse

Pulse that should be played on the signal.

 required
amplitude Union[float, complex, Parameter]

Amplitude of the pulse that should be played.

 None
phase float

Phase of the pulse that should be played.

 None
pulse_parameters Optional[Dict[str, Any]]

Dictionary with user pulse function parameters (re)binding.

 None
precompensation_clear Optional[bool]

Clear the precompensation filter during the pulse.

 None
marker Optional[Dict[str, Any]]

Instruction for playing marker signals along with the pulse

 None

reserve(signal)

Operation to reserve a signal for the active section.

Reserving an experiment signal in a section means that if there is no osperation defined on that signal, it is not available for other sections as long as the active section is scoped.

Parameters:

Name Type Description Default
signal str

Signal that should be reserved.

 required

set_node(path, value)

Set the value of an instrument node.

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

Sweep dataclass

Bases: Section

Sweep loops.

Sweeps are used to sample through a range of parameter values.

Attributes:

Name Type Description
parameters List[Parameter]

Parameters that should be swept. Default: [].
reset_oscillator_phase bool

When True, reset all oscillators at the start of every step. Default: False.
chunk_count int

Split the sweep into N chunks. Default: 1.

Sweep inherits all the attributes of Section.

laboneq.dsl.experiment.experiment

Experiment dataclass

LabOne Q Experiment.

Attributes:

Name Type Description
uid str

Unique identifier for the experiment. If not specified, one will be generated.
signals Union[Dict[str, ExperimentSignal], List[ExperimentSignal]]

Experiment signals. Default: {}.
version DSLVersion

Used DSL version. Default: DSLVersion.V3_0_0
epsilon float

Epsilon. Not used. Default: 0.0.
sections List[Section]

Sections defined in the experiment. Default: [].

experiment_signals_uids: List[str] property

A list of experiment signal UIDs defined in this experiment.

Returns:

Name Type Description
signal_uids List[str]

A list of the UIDs for the signals defined in this experiment.

signal_mapping_status: Dict[str, Any] property

Get an overview of the signal mapping.

Returns:

Name Type Description
signal_mapping Dict[str, Any]

A dictionary with entries for:

  • is_all_mapped: True if all experiment signals are mapped to a logical signal, False otherwise.
  • mapped_signals: A list of experiment signal uids that have a mapping to a logical signal.
  • not_mapped_signals: A list of experiment signal uids that have no mapping to a logical signal.

accept_section_visitor(visitor, sections=None)

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

Acquire a signal and make it available in Result.

Parameters:

Name Type Description Default
signal str

The input signal to acquire data on.

 required
handle str

A unique identifier string that allows to retrieve the acquired data in the Result object.

 required
kernel Pulse | list[Pulse] | None

Pulse(s) for filtering the acquired signal.

 None
length float | None

Integration length for spectroscopy mode.

 None
pulse_parameters dict[str, Any] | list[dict[str, Any] | None] | None

Dictionary with user pulse function parameters (re)binding.

 None

acquire_loop_nt(count, averaging_mode=AveragingMode.CYCLIC, uid=None)

Define an acquire section with averaging in near time.

Deprecated in 2.14

Use .sweep outside of an acquire_loop_rt instead. For example:

param = SweepParameter(values=[1, 2, 3])
with exp.sweep(param):  # <-- outer near-time sweep
    with exp.acquire_loop_rt(count=2):  # <-- inner real-time sweep
        ...

Sections need to open a scope in the following way:

with exp.acquire_loop_nt(...):
    # here come the operations that shall be executed in
    # the acquire_loop_nt section

Note

A near time section cannot be defined in the scope of a real time section.

Parameters:

Name Type Description Default
uid str | None

The unique ID for this section.

 None
count int

The number of acquire iterations.

 required
averaging_mode AveragingMode

The mode of how to average the acquired data. Defaults to AveragingMode.CYCLIC.

 AveragingMode.CYCLIC

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

Define an acquire section with averaging in real time.

Sections need to open a scope in the following way:

    with exp.acquire_loop_rt(...):
        # here come the operations that shall be executed in the acquire_loop_rt section

Note

A near time section cannot be defined in the scope of a real time section.

Parameters:

Name Type Description Default
uid str | None

The unique ID for this section.

 None
count int

The number of acquire iterations.

 required
averaging_mode AveragingMode

The mode of how to average the acquired data. Defaults to AveragingMode.CYCLIC. Further options: AveragingMode.SEQUENTIAL and AveragingMode.SINGLE_SHOT. Single shot measurements are always averaged in cyclic mode.

 AveragingMode.CYCLIC
repetition_mode RepetitionMode

Defines the shot repetition mode. Defaults to RepetitionMode.FASTEST. Further options are RepetitionMode.CONSTANT and RepetitionMode.AUTO.

 RepetitionMode.FASTEST
repetition_time float | None

This is the shot repetition time in seconds. This argument is only required and valid if repetition_mode is RepetitionMode.CONSTANT. The parameter can either be given as a float or as a sweep parameter (Parameter).

 None
acquisition_type AcquisitionType

This is the acquisition type. Defaults to AcquisitionType.INTEGRATION. Further options are AcquisitionType.SPECTROSCOPY, AcquisitionType.DISCRIMINATION and AcquisitionType.RAW.

 AcquisitionType.INTEGRATION
reset_oscillator_phase bool

When True, the phase of every oscillator is reset at the start of the each step of the acquire loop.

 False

add(section)

Add a sweep, a section or an acquire loop to the experiment.

Parameters:

Name Type Description Default
section Section

The object to add.

 required

add_signal(uid=None, connect_to=None)

Add an experiment signal to the experiment.

Parameters:

Name Type Description Default
uid str

The unique id of the new experiment signal (optional).

 None
connect_to LogicalSignalRef

The LogicalSignal this experiment signal shall be connected to. Defaults to None, meaning that there is no connection defined yet.

 None

Returns:

Name Type Description
signal ExperimentSignal

The created and added signal.

See also map_signal.

all_sections()

Return a list of all sections contained within this experiment.

The list includes sections recursively, so all subsections are included to.

Returns:

Name Type Description
sections List[Section]

A list of all sections from this experiment.

call(func_name, **kwargs)

Add a callback function in the execution of the experiment.

The callback is called by the LabOne Q software as part of executing the experiment and in sequence with the other experiment operations.

Parameters:

Name Type Description Default
func_name str

The callback function.

 required
kwargs dict

These arguments are passed to the callback function as is.

 {}

case(state, uid=None)

Define a section which plays after matching with the given value to the result of a QA measurement.

Case needs to open a scope in the following way:

    with exp.case(...):
        # here come the operations that shall be executed in the section

Note

No subsections are allowed, only play and delay.

Parameters:

Name Type Description Default
uid str

The unique ID for this section.

 None
state int

The state that this section is executed for.

 required

delay(signal, time, precompensation_clear=None)

Delay execution of next operation on the given experiment signal.

Parameters:

Name Type Description Default
signal str

The unique id of the signal to delay execution of next operation.

 required
time Union[float, Parameter]

The delay time in seconds. The parameter can either be given as a float or as a sweep parameter.

 required
precompensation_clear Optional[bool]

Clear the precompensation filter during this delay.

 None

get_calibration()

Return the current calibration of the experiment.

Returns:

Name Type Description
calibration Calibration

The calibration of the experiment. The return calibration is built up from the calibration items of the device setup the experiment was or will be executed on.

get_signal_map()

Return a dictionary of mapped experiment signals.

Signals that have not yet been mapped are excluded from the returned dictionary.

Returns:

Name Type Description
signals Dict[str, str]

A dictionary of mapped signals. The keys are the experiment signal UIDs. The values are the logical signal path that the experiment signal is mapped to.

is_experiment_signal(uid)

Check if an experiment signal is defined for this experiment.

Parameters:

Name Type Description Default
uid str

The unique id of the experiment signal to check for.

 required

Returns:

Name Type Description
is_experiment_signal bool

True if the experiment signal is defined in this experiment, False otherwise.

list_calibratables()

Return a dictionary of calibration creation information for the device setup signals mapped to this experiment.

This may be used to introspect an experiment to see the full list of items that may be calibrated.

Returns:

Name Type Description
calibratables Dict[str, dict]

Return a dictionary of calibratable signal UIDs and their corresponding creation information. Each value is itself a dictionary with the keys:

  • type (str): which specifies the type of signal.
  • is_calibrated (bool): which specified whether the signal is currently calibrated.

list_experiment_signals()

A list of experiment signals defined in this experiment.

Returns:

Name Type Description
signals List[ExperimentSignal]

List of defined experiment signals.

load(filename) staticmethod

Load an experiment from a JSON file.

Parameters:

Name Type Description Default
filename str

The name of the file to load the experiment from.

 required

Returns:

Name Type Description
experiment Experiment

The experiment loaded.

load_signal_map(filename)

Load a signal map from a file and apply it to this experiment.

Parameters:

Name Type Description Default
filename str

The name of the file to load the signal map from.

 required

map_signal(experiment_signal_uid, logical_signal)

Connect an experiment signal to a logical signal.

In order to relate an experiment signal to a logical signal defined in a device setup (DeviceSetup), you need to make a connection between these two types of signals.

Parameters:

Name Type Description Default
experiment_signal_uid str

The unique id of the experiment signal to be connected.

 required
logical_signal LogicalSignalRef

The logical signal to connect to.

 required

See also add_signal.

match(handle=None, user_register=None, uid=None, play_after=None)

Define a section which switches between different child sections based on a QA measurement (using handle) or a user register (using user_register).

In case of the QA measurement option, the feedback path (local, or global, via PQSC) is chosen automatically.

Match needs to open a scope in the following way:

    with exp.match(...):
        # here come the different branches to be selected

Note

Only subsections of type Case are allowed. Exactly one of handle or user_register must be specified, the other one must be None. The user register is evaluated only at the beginning of the experiment, not during the experiment, and only a few user registers per AWG can be used due to the limited number of processor registers.

Parameters:

Name Type Description Default
uid str

The unique ID for this section.

 None
handle Optional[str]

A unique identifier string that allows to retrieve the acquired data.

 None
user_register Optional[int]

The user register to use for the match.

 None
play_after Optional[Union[str, Section, List[Union[str, Section]]]]

Play this section after the end of the section(s) with the given ID(s). Defaults to None.

 None

match_global(handle, uid=None, play_after=None)

Define a section which switches between different child sections based on a QA measurement via the PQSC.

Match needs to open a scope in the following way:

    with exp.match_global(...):
        # here come the different branches to be selected

Note

Only subsections of type Case are allowed.

Parameters:

Name Type Description Default
uid str

The unique ID for this section.

 None
handle str

A unique identifier string that allows to retrieve the acquired data.

 required
play_after Optional[Union[str, Section, List[Union[str, Section]]]]

Play this section after the end of the section(s) with the given ID(s). Defaults to None.

 None

match_local(handle, uid=None, play_after=None)

Define a section which switches between different child sections based on a QA measurement on an SHFQC.

Match needs to open a scope in the following way:

    with exp.match_local(...):
        # here come the different branches to be selected

Note

Only subsections of type Case are allowed.

Parameters:

Name Type Description Default
uid str

The unique ID for this section.

 None
handle str

A unique identifier string that allows to retrieve the acquired data.

 required
play_after Optional[Union[str, Section, List[Union[str, Section]]]]

Play this section after the end of the section(s) with the given ID(s). Defaults to None.

 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)

Execute a measurement.

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

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 multistate discrimination, use lists of equal length for integration_kernel and integration_kernel_parameters. 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 Optional[Pulse | list[Pulse]]

An optional Pulse object or list of Pulse objects that specifies the kernel(s) for integration.

 None
integration_kernel_parameters dict[str, Any] | list[dict[str, Any] | None] | None

An optional dictionary (or list thereof) that contains pulse parameters for the integration kernel.

 None
integration_length Optional[float]

An optional float that specifies the integration length.

 None
measure_signal Optional[str]

An optional string that specifies the signal to measure.

 None
measure_pulse Optional[Pulse]

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 Optional[float]

An optional float that specifies the length of the measurement pulse.

 None
measure_pulse_parameters Optional[Dict[str, Any]]

An optional dictionary that contains parameters for the measurement pulse.

 None
measure_pulse_amplitude Optional[float]

An optional float that specifies the amplitude of the measurement pulse.

 None
acquire_delay Optional[float]

An optional float that specifies the delay between the acquisition and the measurement.

 None
reset_delay Optional[float]

An optional float that specifies the delay after the acquisition to allow for state relaxation or signal processing.

 None

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 a signal line.

Parameters:

Name Type Description Default
signal str

The unique id of the signal to play the pulse on.

 required
pulse Pulse

The pulse description of the pulse to be played.

 required
amplitude float | Parameter

Amplitude the pulse shall be played with. Defaults to None, meaning that the pulse is played as is.

 None
length float | Parameter

Length for which the pulse shall be played. Defaults to None, meaning that the pulse is played for its whole length.

 None
phase float

The desired baseband phase (baseband rotation) with which the pulse shall be played. Given in radians, defaults to None, meaning that the pulse is played with its phase as defined.

 None
set_oscillator_phase float

The desired oscillator phase at the start of the played pulse, in radians. The phase setting affects the pulse played in this command, and all following pulses. Defaults to None, meaning no change is made and the phase remains continuous.

 None
increment_oscillator_phase float

The desired phase increment of the oscillator phase at the start of the played pulse, in radians. The new, incremented phase affects the pulse played in this command, and all following pulses. Defaults to None, meaning no change is made and the phase remains continuous.

 None
pulse_parameters dict

Dictionary with user pulse function parameters (re)binding.

 None
marker dict

Dictionary with markers to play. Example: marker={"marker1": {"enable": True}}

 None

Note

If markers are specified but pulse=None, a zero amplitude pulse as long as the end of the longest marker will be automatically generated.

reserve(signal)

Reserves an experiment signal for the duration of the active section.

Reserving an experiment signal in a section means that if there is no operation defined on that signal, it is not available for other sections as long as the active section is scoped.

Parameters:

Name Type Description Default
signal str

The unique id of the signal to be reserved in the active section.

 required

reset_calibration(calibration=None)

Reset the experiment calibration.

Resets the signal calibration for all device setup signals mapped in this experiment.

Parameters:

Name Type Description Default
calibration Calibration | None

The calibration to apply after resetting the experiment calibration. Default: None.

 None

reset_signal_map(signal_map=None)

Reset, i.e. disconnect, all defined signal connections and apply a new signal map if provided.

Parameters:

Name Type Description Default
signal_map Dict[str, LogicalSignalRef]

The new signal map to apply.

 None

save(filename)

Save this experiment to a file.

Parameters:

Name Type Description Default
filename str

The name of the file to save the experiment to.

 required

save_signal_map(filename)

Save this experiments current signal map to a file.

Parameters:

Name Type Description Default
filename str

The name of the file to save the current signal map to.

 required

section(length=None, alignment=None, uid=None, on_system_grid=None, play_after=None, trigger=None)

Define an section for scoping operations.

Sections need to open a scope in the following way:

    with exp.section(...):
        # here come the operations that shall be executed in the section

Note

A near time section cannot be defined in the scope of a real time section.

Parameters:

Name Type Description Default
uid str | None

The unique ID for this section.

 None
length float | None

The minimal duration of the section in seconds. The scheduled section might be slightly longer, as its length is rounded to the next multiple of the section timing grid. Defaults to None which means that the section length is derived automatically from the contained operations. The parameter can either be given as a float or as a sweep parameter (Parameter).

 None
alignment SectionAlignment | None

Alignment of the operations in the section. Defaults to SectionAlignment.LEFT.

 None
play_after Optional[Union[str, Section, List[Union[str, Section]]]]

Play this section after the end of the section(s) with the given ID(s). Defaults to None.

 None
trigger Optional[Dict[str, Dict[str, int]]]

Play a pulse a trigger pulse for the duration of this section. See below for details.

 None
on_system_grid bool | None

If True, the section boundaries are always rounded to the system grid, even if the signals would allow for tighter alignment.

 None

The individual trigger (a.k.a marker) ports on the device are addressed via the experiment signal that is mapped to the corresponding analog port. For playing trigger pulses, pass a dictionary via the trigger argument. The keys of the dictionary must be an ID of an ExperimentSignal. Each value is another dict of the form:

    {"state": value}

value is a bit field that enables the individual trigger signals (on the devices that feature more than a single one).

    {"state": 1}  # raise trigger signal 1
    {"state": 0b10}  # raise trigger signal 2 (on supported devices)
    {"state": 0b11}  # raise both trigger signals

As a more complete example, to fire a trigger pulse on the first port associated with signal "drive_line", call:

    with exp.section(..., trigger={"drive_line": {"state": 0b01}}):
        ...

When trigger signals on the same signal are issued in nested sections, the values are ORed.

Changed in version 2.0.0

Removed deprecated offset argument.

set_calibration(calibration)

Applies the given calibration to the experiment.

Parameters:

Name Type Description Default
calibration Calibration

The calibration to set. Each item within the calibration is applied to the corresponding elements of the device setup the experiment will be executed on.

 required

set_node(path, value)

Set the value of an instrument node.

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

Changed in version 2.0

Method name renamed from set to set_node. Removed key argument.

set_signal_map(signal_map)

Map experiment signals.

Parameters:

Name Type Description Default
signal_map Dict[str, LogicalSignalRef]

A dictionary of mappings to apply. The keys are experiment signal UIDs and the values are logical signal references to map them to.

 required

sweep(parameter, execution_type=None, uid=None, alignment=None, reset_oscillator_phase=False, chunk_count=1)

Define a sweep section.

Sections need to open a scope in the following way:

    with exp.sweep(...):
        # here come the operations that shall be executed in the sweep section

Note

A near time section cannot be defined in the scope of a real time section.

Parameters:

Name Type Description Default
uid str | None

The unique ID for this section.

 None
parameter Parameter | List[Parameter]

The sweep parameter(s) that is used in this section. The argument can be given as a single sweep parameter or a list of sweep parameters of equal length. If multiple sweep parameters are given, the parameters are executed in parallel in this sweep loop.

 required
execution_type ExecutionType

Defines if the sweep is executed in near time or real time. Defaults to ExecutionType.NEAR_TIME.

 None
alignment SectionAlignment | None

Alignment of the operations in the section. Defaults to SectionAlignment.LEFT.

 None
reset_oscillator_phase bool

When True, reset all oscillators at the start of each step.

 False
chunk_count int

The number of chunks to split the sweep into. Defaults to 1.

 1

laboneq.dsl.experiment.experiment_signal

ExperimentSignal(uid=None, map_to=None, calibration=None, oscillator=None, amplitude=None, port_delay=None, delay_signal=None, mixer_calibration=None, precompensation=None, local_oscillator=None, range=None, port_mode=None, threshold=None, mapped_logical_signal_path=None) dataclass

A signal within an experiment.

Experiment signals are mapped to logical signals before an experiment is executed.

The experiment signal calibration maybe specified here either by passing the calibration parameter or by specifying the parts of the calibration as they would be passed to SignalCalibration. See the documentation of SignalCalibration for details of the individual calibration options.

Parameters:

Name Type Description Default
uid str | None

The unique identifier for the signal. If not specified, one will be automatically generated.

 None
map_to LogicalSignalRef | None

The logical signal to map to this experiment signal to. If not specified, it should be set before the experiment is compiled. If both this and mapped_logical_signal_path, the mapped_logical_signal_path value is used.

 None
calibration SignalCalibration | None

The signal calibration. If provided, the values of the other calibration parameters are ignored. If the signal calibration is not specified via either this parameter or the other parameters, it should be set before the experiment is compiled.

 None
oscillator Oscillator | None

The oscillator assigned to the signal calibration. Ignored if the calibration parameter is set.

 None
amplitude float | None

The signal calibration amplitude. Only supported by the SHFQA. The amplitude setting applies to all signals on the same channel. Ignored if the calibration parameter is set.

 None
port_delay float | None

The signal calibration port delay. Ignored if the calibration parameter is set.

 None
mixer_calibration MixerCalibration | None

The signal mixer calibration. Ignored if the calibration parameter is set.

 None
precompensation Precompensation | None

The signal calibration precompenstation settings. Ignored if the calibration parameter is set. Only supported by HDAWG signals.

 None
local_oscillator Oscillator | None

The local oscillator assigned to the signal calibration. Only supported by SHFSG, SHFQA and SHFQC signals. Ignored if the calibration parameter is set.

 None
range float | None

The output or input range setting for the signal calibration. Ignored if the calibration parameter is set.

 None
port_mode PortMode | None

The SHFSG, SHFQA and SHFQC port mode signal calibration. Ignored if the calibration parameter is set.

 None
threshold float | None

The sginal calibration state discrimation threshold. Only supported for acquisition signals on the UHFQA, SHFQA and SHFQC. Ignored if the calibration parameter is set.

 None
mapped_logical_signal_path str | None

The path of the logical signal to map this experiment signal to. If not specified, it should be set before the experiment is compiled. If both this and map_to are specified, this value is used.

 None

Attributes:

Name Type Description
uid str

The unique identifier for the signal.
calibration SignalCalibration | None

The signal calibration. Must be set before the experiment is executed if the calibration for this signal is used by the experiment.
mapped_logical_signal_path str | None

The path of the logical signal mapped to this experiment signal. Must be set before the experiment is executed.

amplifier_pump: AmplifierPump | None property writable

The amplifier pump settings assigned to this signal or None if none is assigned.

amplitude: float | None property writable

The amplitude to multiply all waveforms played on this signal by, or None to not modify the amplitude.

Only supported by the SHFQA.

Note

The amplitude setting applies to all signals on the same channel.

calibration = SignalCalibration(oscillator=oscillator, amplitude=amplitude, port_delay=port_delay, delay_signal=delay_signal, mixer_calibration=mixer_calibration, precompensation=precompensation, local_oscillator=local_oscillator, range=range, port_mode=port_mode, threshold=threshold) instance-attribute

delay_signal property writable

The signal delay (in seconds) set on this signal, or None if none is set.

local_oscillator property writable

The local oscillator settings assigned to this signal or None if none is assigned.

mapped_logical_signal_path = None instance-attribute

mixer_calibration: MixerCalibration | None property writable

The mixer calibration assigned to this experiment signal or None if none is assigned.

oscillator: Oscillator | None property writable

The oscillator assigned to this experiment signal or None if none is assigned.

port_delay: float | None property writable

The port delay (in seconds) set on this signal, or None if none is set.

port_mode: PortMode | None property writable

The port mode for the signal if set or None if not set.

precompensation: Precompensation | None property writable

The calibration precompensation assigned to this experiment signal or None if none is assigned.

range: float | None property writable

The output or input range setting for the signal if set or None if not set.

threshold: float | list[float] | None property writable

The state discrimination threshold if set or None if not set.

Only supported for acquisition signals on the UHFQA, SHFQA and SHFQC.

uid = experiment_signal_id_generator() instance-attribute

voltage_offset: float | None property writable

The voltage offset set for this signal or None if none is set.

Only supported by HDAWG lines.

disconnect()

Disconnect the experiment signal from the logical signal.

is_calibrated()

True if calibration has been set for this experiment signal. False otherwise.

Returns:

Name Type Description
is_calibrated bool

True if the signal has calibration set. False otherwise.

is_mapped()

Return true if the signal is mapped to a logical signal path.

Returns:

Name Type Description
is_mapped bool

True if this experiment signal is mapped to a logical signal.

map(to)

Map this signal to a logical signal.

Parameters:

Name Type Description Default
to LogicalSignalRef

The logical signal to map this experiment signal to.

 required

reset_calibration(calibration=None)

Reset the calibration and apply the specified new calibration if provided.

Parameters:

Name Type Description Default
calibration SignalCalibration | None

The new calibration to apply or None if this signal is to be left uncalibrated after the reset.

 None

laboneq.dsl.experiment.pulse

Pulse

A pulse for playing during an experiment.

is_complex()

Return whether this pulse contains complex or real amplitudes.

Returns:

Name Type Description
is_complex bool

True if the amplitudes are complex. False if they are real.

laboneq.dsl.experiment.pulse_library

const(x, **_)

Create a constant pulse.

Parameters:

Name Type Description Default
**_ Any

All pulses accept the following keyword arguments: - uid (str): Unique identifier of the pulse - length (float): Length of the pulse in seconds - amplitude (float): Amplitude of the pulse

 {}

Returns:

Name Type Description
pulse Pulse

Constant pulse.

cos2(x, **_)

Create a raised cosine pulse.

Parameters:

Name Type Description Default
**_ Any

All pulses accept the following keyword arguments: - uid (str): Unique identifier of the pulse - length (float): Length of the pulse in seconds - amplitude (float): Amplitude of the pulse

 {}

Returns:

Name Type Description
pulse Pulse

Raised cosine pulse.

drag(x, sigma=1 / 3, beta=0.2, zero_boundaries=False, **_)

Create a DRAG pulse.

Parameters:

Name Type Description Default
**_ Any

All pulses accept the following keyword arguments: - uid (str): Unique identifier of the pulse - length (float): Length of the pulse in seconds - amplitude (float): Amplitude of the pulse

 {}
sigma float

Std. deviation, relative to pulse length

 1 / 3
beta float

Relative amplitude of the quadrature component

 0.2
zero_boundaries bool

Whether to zero the pulse at the boundaries

 False

Returns:

Name Type Description
pulse Pulse

DRAG pulse.

gaussian(x, sigma=1 / 3, order=2, zero_boundaries=False, **_)

Create a Gaussian pulse.

Parameters:

Name Type Description Default
**_ Any

All pulses accept the following keyword arguments: - uid (str): Unique identifier of the pulse - length (float): Length of the pulse in seconds - amplitude (float): Amplitude of the pulse

 {}
sigma float

Std. deviation, relative to pulse length, default is 1/3

 1 / 3
order int

Order of the Gaussian pulse, must be even and positive, default is 2

 2
zero_boundaries bool

Whether to zero the pulse at the boundaries, default is False

 False

Returns:

Name Type Description
pulse Pulse

Gaussian pulse.

gaussian_square(x, sigma=1 / 3, width=9e-08, zero_boundaries=False, length=1e-07, **_)

Create a gaussian square waveform with a square portion of length width and Gaussian shaped sides.

Parameters:

Name Type Description Default
**_ Any

All pulses accept the following keyword arguments: - uid (str): Unique identifier of the pulse - length (float): Length of the pulse in seconds - amplitude (float): Amplitude of the pulse

 {}
width float

Width of the flat portion of the pulse in seconds

 9e-08
sigma float

Std. deviation of the Gaussian rise/fall portion of the pulse

 1 / 3
zero_boundaries bool

Whether to zero the pulse at the boundaries

 False

Returns:

Name Type Description
pulse Pulse

Gaussian square pulse.

register_pulse_functional(sampler, name=None)

Build & register a new pulse type from a sampler function.

The sampler function must have the following signature:

    def sampler(x: ndarray, **pulse_params: Dict[str, Any]) -> ndarray:
        pass

The vector x marks the points where the pulse function is to be evaluated. The values of x range from -1 to +1. The argument pulse_params contains all the sweep parameters, evaluated for the current iteration. In addition, pulse_params also contains the following keys:

  • length: the true length of the pulse
  • amplitude: the true amplitude of the pulse
  • sampling_rate: the sampling rate

Typically, the sampler function should discard length and amplitude, and instead assume that the pulse extends from -1 to 1, and that it has unit amplitude. LabOne Q will automatically rescale the sampler's output to the correct amplitude and length.

Parameters:

Name Type Description Default
sampler Callable

the function used for sampling the pulse

 required
name str

the name used internally for referring to this pulse type

 None

Returns:

Name Type Description
pulse_factory function

A factory function for new Pulse objects. The return value has the following signature: 

    def <name>(
        uid: str = None,
        length: float = 100e-9,
        amplitude: float = 1.0,
        **pulse_parameters: Dict[str, Any],
    ):
        pass

sampled_pulse_complex(samples, uid=None, can_compress=False)

Create a pulse based on a array of complex values.

Parameters:

Name Type Description Default
samples numpy.ndarray

Complex valued data.

 required
uid str

Unique identifier of the created pulse.

 None

Returns:

Name Type Description
pulse Pulse

Pulse based on the provided sample values.

sampled_pulse_real(samples, uid=None, can_compress=False)

Create a pulse based on a array of real values.

Parameters:

Name Type Description Default
samples numpy.ndarray

Real valued data.

 required
uid str

Unique identifier of the created pulse.

 None

Returns:

Name Type Description
pulse Pulse

Pulse based on the provided sample values.

sawtooth(x, **_)

Create a sawtooth pulse.

Parameters:

Name Type Description Default
**_ Any

All pulses accept the following keyword arguments: - uid (str): Unique identifier of the pulse - length (float): Length of the pulse in seconds - amplitude (float): Amplitude of the pulse

 {}

Returns:

Name Type Description
pulse Pulse

Sawtooth pulse.

triangle(x, **_)

Create a triangle pulse.

A triangle pulse varies linearly from a starting amplitude of zero, to a maximum amplitude of one in the middle of the pulse, and then back to a final amplitude of zero.

Parameters:

Name Type Description Default
**_ Any

All pulses accept the following keyword arguments: - uid (str): Unique identifier of the pulse - length (float): Length of the pulse in seconds - amplitude (float): Amplitude of the pulse

 {}

Returns:

Name Type Description
pulse Pulse

Triangle pulse.