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, spectroscopy, discrimination 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 |
reset_oscillator_phase |
bool
|
When true, reset all oscillators at the start of every step.
Default: |
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: |
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.
Unless matching a sweep parameter, a Case
may only contain PlayPulse
and Delay
operations and not other kinds of
operations or sections.
add(obj)
¶
Add a child to the Case section.
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 condition.
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. |
prng_sample |
PRNGSample | None
|
PRNG sample to match. |
sweep_parameter |
SweepParameter | None
|
Sweep parameter to match. |
local |
bool
|
Whether to fetch the codeword via the PQSC ( |
Match inherits all the attributes of Section.
Only subsections of type Case may be added to a Match section.
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: |
name |
str
|
A name for the section. The name need not be unique.
The name may, in future, be used as a prefix for
generating a |
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 |
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 |
play_after |
str | Section | list[str | Section] | None
|
A list of sections that must complete before this section
may be played.
If |
children |
list[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: |
Changed in version 2.0.0
Removed offset
member variable.
Added in version 2.26.0
Added name
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)
¶
call(func_name, **kwargs)
¶
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 |
float | Parameter
|
Duration of the delay. |
required |
precompensation_clear |
bool | None
|
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 |
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 kernels. |
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
|
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 |
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[str, Any] | None
|
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 |
Sweep
dataclass
¶
Bases: Section
Sweep loops.
Sweeps are used to sample through a range of parameter values.
Attributes:
Name | Type | Description |
---|---|---|
parameters |
list[Parameter] | Parameter
|
Parameters that should be swept.
Default: |
reset_oscillator_phase |
bool
|
When True, reset all oscillators at the start of every step.
Default: |
chunk_count |
int
|
Split the sweep into N chunks.
Default: |
Sweep inherits all the attributes of Section.
Changed in 2.24.0
parameters
now accepts a single Parameter
in addition to accepting a list.
laboneq.dsl.experiment.experiment
¶
Experiment
dataclass
¶
LabOne Q Experiment.
Attributes:
Name | Type | Description |
---|---|---|
uid |
str | None
|
Unique identifier for the experiment.
If not specified, it will remain |
name |
str
|
A name for the experiment. The name need not be unique.
Default: |
signals |
dict[str, ExperimentSignal] | list[ExperimentSignal | str]
|
Experiment signals.
Default: |
version |
DSLVersion
|
Used DSL version. Default: DSLVersion.V3_0_0 |
epsilon |
float
|
Epsilon. Not used.
Default: |
sections |
list[Section]
|
Sections defined in the experiment.
Default: |
Changed in version 2.27.0
The uid
attribute is not longer automatically generated and
will be left as None
if unspecified.
The name
attribute was added.
experiment_signals_uids: list[str]
property
¶
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:
|
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. |
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. |
CYCLIC
|
repetition_mode |
RepetitionMode
|
Defines the shot repetition mode. Defaults to RepetitionMode.FASTEST. Further options are RepetitionMode.CONSTANT and RepetitionMode.AUTO. |
FASTEST
|
repetition_time |
float | None
|
This is the shot repetition time in seconds. This
argument is only required and valid if |
None
|
acquisition_type |
AcquisitionType
|
This is the acquisition type. Defaults to AcquisitionType.INTEGRATION. Further options are AcquisitionType.SPECTROSCOPY, AcquisitionType.DISCRIMINATION and AcquisitionType.RAW. |
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 | None
|
The unique id of the new experiment signal (optional). |
None
|
connect_to |
LogicalSignalRef | None
|
The |
None
|
Returns:
Name | Type | Description |
---|---|---|
signal |
ExperimentSignal
|
The created and added signal. |
See also map_signal.
all_sections()
¶
call(func_name, **kwargs)
¶
Add a near-time callback function in the execution of the experiment.
The near-time 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 | Callable[..., Any]
|
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
Parameters:
Name | Type | Description | Default |
---|---|---|---|
uid |
str | None
|
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 |
float | Parameter
|
The delay time in seconds. The parameter can either be given as a float or as a sweep parameter. |
required |
precompensation_clear |
bool | None
|
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_rt_acquire_loop()
¶
Return the real-time acquire loop object.
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
|
|
list_calibratables()
¶
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, sweep_parameter=None, uid=None, play_after=None, local=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 determined by the local
argument.
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 | None
|
The unique ID for this section. |
None
|
handle |
str | None
|
A unique identifier string that allows to retrieve the acquired data. |
None
|
user_register |
int | None
|
The user register to use for the match. |
None
|
sweep_parameter |
Parameter | None
|
The sweep_parameter to use for the match. |
None
|
play_after |
str | Section | list[str | Section] | None
|
Play this section after the end of the section(s) with the given ID(s). Defaults to None. |
None
|
local |
bool | None
|
Selects whether the feedback path should be local
(exclusively on an SHFQC) or global via PQSC. Defaults to |
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 | None
|
The unique ID for this section. |
None
|
handle |
str
|
A unique identifier string that allows to retrieve the acquired data. |
required |
play_after |
str | Section | list[str | Section] | None
|
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 | None
|
The unique ID for this section. |
None
|
handle |
str
|
A unique identifier string that allows to retrieve the acquired data. |
required |
play_after |
str | Section | list[str | Section] | None
|
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 |
Pulse | list[Pulse] | None
|
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 |
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
|
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
|
length |
float | Parameter
|
Length for which the pulse shall be played. Defaults to
|
None
|
phase |
float
|
The desired baseband phase (baseband rotation) with which the
pulse shall be played. Given in radians, defaults to |
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
|
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
|
pulse_parameters |
dict
|
Dictionary with user pulse function parameters (re)binding. |
None
|
marker |
dict
|
Dictionary with markers to play. Example: |
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
|
reset_signal_map(signal_map=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
|
alignment |
SectionAlignment | None
|
Alignment of the operations in the section. Defaults to SectionAlignment.LEFT. |
None
|
play_after |
str | Section | list[str | Section] | None
|
Play this section after the end of the section(s) with the given ID(s). Defaults to None. |
None
|
trigger |
dict[str, dict[str, int]] | None
|
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_signal_map(signal_map)
¶
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 | None
|
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 |
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 |
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 |
None
|
port_delay |
float | None
|
The signal calibration port delay.
Ignored if the |
None
|
mixer_calibration |
MixerCalibration | None
|
The signal mixer calibration.
Ignored if the |
None
|
precompensation |
Precompensation | None
|
The signal calibration precompenstation settings.
Ignored if the |
None
|
local_oscillator |
Oscillator | None
|
The local oscillator assigned to the signal calibration.
Only supported by SHFSG, SHFQA and SHFQC signals.
Ignored if the |
None
|
range |
float | None
|
The output or input range setting for the signal calibration.
Ignored if the |
None
|
port_mode |
PortMode | None
|
The SHFSG, SHFQA and SHFQC port mode signal calibration.
Ignored if the |
None
|
threshold |
float | None
|
The sginal calibration state discrimation threshold.
Only supported for acquisition signals on the UHFQA, SHFQA
and SHFQC.
Ignored if the |
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 |
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. |
added_outputs
property
writable
¶
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
|
laboneq.dsl.experiment.pulse_library
¶
pulse_function_library = _pulse_samplers
module-attribute
¶
const(x, **_)
¶
Create a constant pulse.
Other Parameters:
Name | Type | Description |
---|---|---|
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.
Other Parameters:
Name | Type | Description |
---|---|---|
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 |
---|---|---|---|
sigma |
float
|
Standard deviation relative to the interval the pulse is sampled from, here [-1, 1]. Defaults |
1 / 3
|
beta |
float
|
Relative amplitude of the quadrature component |
0.2
|
zero_boundaries |
bool
|
Whether to zero the pulse at the boundaries |
False
|
Other Parameters:
Name | Type | Description |
---|---|---|
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
|
DRAG pulse. |
gaussian(x, sigma=1 / 3, order=2, zero_boundaries=False, **_)
¶
Create a Gaussian pulse.
Returns a generalised Gaussian pulse with order parameter \(n\), defined by:
$$ g(x, \sigma, n) = e^{-\left(\frac{x^2}{2\sigma^2}\right)^{\frac{n}{2}}} $$.
When the order \(n = 2\), the formula simplifies to the standard Gaussian:
For higher orders (\(n > 2\)), the value of \(\sigma\) is adjusted so that the pulse has the same near-zero values at the edges as the ordinary Gaussian.
In general, for \(x \in [-L, L]\), the adjusted \(\sigma\) can be written as:
Considering here \(x \in [-1, 1]\), the adjusted \(\sigma\) simplifies to:
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sigma |
float
|
Standard deviation relative to the interval the pulse is sampled from, here [-1, 1]. Defaults to 1/3. |
1 / 3
|
order |
int
|
Order of the Gaussian pulse, must be positive and even, default is 2 (standard Gaussian), order > 2 will create a super Gaussian pulse |
2
|
zero_boundaries |
bool
|
Whether to zero the pulse at the boundaries, default is False |
False
|
Other Parameters:
Name | Type | Description |
---|---|---|
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
|
Gaussian pulse. |
gaussian_square(x, sigma=1 / 3, width=None, zero_boundaries=False, *, length, **_)
¶
Create a gaussian square waveform with a square portion of length
width
and Gaussian shaped sides.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
length |
float
|
Length of the pulse in seconds |
required |
width |
float
|
Width of the flat portion of the pulse in seconds. Dynamically set to 90% of |
None
|
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
|
Other Parameters:
Name | Type | Description |
---|---|---|
uid |
[str][]
|
Unique identifier of the pulse |
amplitude |
[float][]
|
Amplitude of the pulse |
Returns:
Name | Type | Description |
---|---|---|
pulse |
Pulse
|
Gaussian square pulse. |
pulse_factory(name)
¶
Return the named pules factory.
The pulse factory returns the description of the pulse used to specify
a pulse when calling LabOne Q DSl commands such as .play(...)
and
.measure(...)
.
For example, in:
```python
@register_pulse_functional
def const(x, **_):
return numpy.ones_like(x)
```
the factory is the decorated function const
. Calling
pulse_factory("const")
will return this decorated function. This is
the same function one calls when calling pulse_library.const(...)
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
name |
str
|
The name of the factory to return. |
required |
Return
The factory function.
pulse_sampler(name)
¶
Return the named pulse sampler.
The sampler is the original function used to define the pulse.
For example in:
```python
@register_pulse_functional
def const(x, **_):
return numpy.ones_like(x)
```
the sampler is the undecorated function const
. Calling
pulse_sampler("const")
will return this undecorated function.
This undecorate function is called a "sampler" because it is used by the LabOne Q compiler to generate the samples played by a pulse.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
name |
str
|
The name of the sampler to return. |
required |
Return
The sampler function.
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 pulseamplitude
: the true amplitude of the pulsesampling_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 | None
|
the name used internally for referring to this pulse type |
None
|
Returns:
Name | Type | Description |
---|---|---|
pulse_factory |
function
|
A factory function for new
|
sampled_pulse(samples, uid=None, can_compress=False)
¶
sampled_pulse_complex(samples, uid=None, can_compress=False)
¶
sampled_pulse_real(samples, uid=None, can_compress=False)
¶
sawtooth(x, **_)
¶
Create a sawtooth pulse.
Other Parameters:
Name | Type | Description |
---|---|---|
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.
Other Parameters:
Name | Type | Description |
---|---|---|
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. |