laboneq.dsl.session
¶
Session(device_setup=None, log_level=None, performance_log=False, configure_logging=True, _last_results=None, compiled_experiment=None, experiment=None, include_results_metadata=False, server_log=False)
¶
This Session class represents the main endpoint for the user interaction with the QCCS system.
The session holds:
- the wiring definition of the devices
- the experiment definition that should be run on the devices
- the calibration of the devices for experiment
- the compiled experiment
- the result of the executed experiment
The Session is a stateful object that hold all of the above. The expected steps to interact with the session are:
- initial state (construction)
- setting the device setup (optionally during construction)
- (optional) setting the calibration of the devices
- connecting to the devices (or the emulator)
- compiling the experiment
- running the experiment
- accessing the results of the last run experiment
The session is serializable in every state.
Constructor of the session.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
device_setup
|
DeviceSetup | None
|
Device setup that should be used for this session. The device setup can also be passed to the session after the construction of the object. |
None
|
log_level
|
int | str | None
|
Log level of the session.
If no log level is specified, the session will use the logging.INFO level.
Other possible levels refer to the logging python package and
|
None
|
performance_log
|
bool
|
Flag to enable performance logging. When True, the system creates a separate logfile containing logs aimed to analyze system performance. |
False
|
configure_logging
|
bool
|
Whether to configure logger. Can be disabled for custom logging use cases. |
True
|
compiled_experiment
|
CompiledExperiment | None
|
If specified, set the current compiled experiment. |
None
|
experiment
|
Experiment | None
|
If specified, set the current experiment. |
None
|
include_results_metadata
|
bool
|
If True, |
False
|
server_log
|
bool
|
If |
False
|
Changed in version 2.55.0
The deprecated .compiled_experiment
attribute was removed from Results
. The
include_results_metadata
argument thus no longer populates this attribute on Results
.
Track the compiled experiment separately instead.
Changed in version 2.54.0
The following deprecated methods for saving and loading were removed:
- load
- save
- save_signal_map
- load_signal_map
- save_results
- save_experiment
- load_experiment
- save_device_setup
- load_device_setup
- save_device_calibration
- load_device_calibration
- save_compiled_experiment
- load_compiled_experiment
- save_experiment_calibration
- load_experiment_calibration
Use the load
and save
functions from the laboneq.simple
module instead.
Added in version 2.52.0
Added the include_results_metadata
argument.
Changed in version 2.0
- Removed
pass_v3_to_compiler
argument. - Removed
max_simulation_time
instance variable.
compiled_experiment
property
¶
Access to the compiled experiment.
The compiled experiment can be assigned to a different session if the device setup is matching.
connection_state
property
¶
Session connection state.
device_calibration
property
writable
¶
Object holding the calibration of the device setup.
device_setup
property
¶
Object holding the device setup of the QCCS system.
devices
property
¶
Connected devices included in the system setup.
Allows the modification/inspection of the state of the device and its nodes.
Devices exist once the session is connected. After disconnecting, devices are empty.
Usage:
>>> session.connect()
>>> session.devices["device_hdawg"].awgs[0].outputs[0].amplitude(1)
>>> session.devices["DEV1234"].awgs[0].outputs[0].amplitude()
1
experiment
property
¶
Object holding the experiment definition.
experiment_calibration
property
writable
¶
Object holding the calibration of the experiment.
log_level
property
writable
¶
The current log level.
logger
property
writable
¶
The current logger instance used by the session.
results
property
¶
Object holding the result of the last experiment execution.
Attention
This accessor is provided for better
performance, unlike get_result
it doesn't make a copy, but instead returns the reference to the live
result object being updated during the session run. Care must be taken for not modifying this object from
the user code, otherwise behavior is undefined.
signal_map
property
writable
¶
Dict holding the signal mapping.
abort_execution()
¶
Abort the execution of an experiment.
Note
This currently exclusively works when called from within a near-time callback. The function does not return, and instead passes control directly back to the LabOne Q runtime.
compile(experiment, compiler_settings=None)
¶
Compiles the specified experiment and stores it in the compiled_experiment property.
Requires connected LabOne Q session (session.connect()
) either with or without emulation mode.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
experiment
|
Experiment
|
Experiment instance that should be compiled. |
required |
compiler_settings
|
Dict | None
|
Extra options passed to the compiler. |
None
|
Changed in version 2.4
Raises error if Session
is not connected.
Removed in version 2.0
Removed do_simulation
argument.
Use OutputSimulator instead.
connect(do_emulation=False, ignore_version_mismatch=False, reset_devices=False, use_async_api=None, disable_runtime_checks=True, timeout=None)
¶
Connects the session to the QCCS system.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
do_emulation
|
bool
|
Specifies if the session should connect to a emulator (in the case of 'True') or the real system (in the case of 'False'). |
False
|
ignore_version_mismatch
|
bool
|
Ignore version mismatches.
If set to
The following states raise an exception:
It is suggested to keep the versions aligned and up-to-date to avoid any unexpected behaviour. Changed in version 2.4 Renamed |
False
|
reset_devices
|
bool
|
Load the factory preset after connecting for device which support it. |
False
|
use_async_api
|
bool
|
Enable the async backend of LabOne Q controller. Defaults to |
None
|
disable_runtime_checks
|
bool
|
Disable the runtime checks performed
by device firmware. Defaults to |
True
|
timeout
|
float
|
Specifies the timeout for the initial connection to the instrument in seconds. |
None
|
Returns:
Name | Type | Description |
---|---|---|
connection_state |
ConnectionState
|
The connection state of the session. |
disable_outputs(devices=None, signals=None, unused_only=False)
¶
Turns off / disables the device outputs.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
devices
|
str | list[str] | None
|
Optional. Device or list of devices, if not specified - all devices. All or unused (see 'unused_only') outputs of these devices will be disabled. Can't be used together with 'signals'. |
None
|
signals
|
LogicalSignalRef | list[LogicalSignalRef] | None
|
Optional. Logical signal or a list of logical signals. Outputs mapped by these logical signals will be disabled. Can't be used together with 'devices' or 'unused_only'. |
None
|
unused_only
|
bool
|
Optional. If set to True, only outputs not mapped by any logical signals will be disabled. Can't be used together with 'signals'. |
False
|
disconnect()
¶
Disconnects instruments from the data server and closes the connection for this session.
Returns:
Name | Type | Description |
---|---|---|
connection_state |
ConnectionState
|
The connection state of the session. |
get_results()
¶
Returns a deep copy of the result of the last experiment execution.
Raises an exception if no experiment results are available.
Returns:
Name | Type | Description |
---|---|---|
results |
Results
|
A deep copy of the results of the last experiment. |
register_neartime_callback(func, name=None)
¶
Registers a near-time callback to be referred from the experiment's call
operation.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
func
|
function
|
Near-time callback that is registered. |
required |
name
|
str
|
Optional name to use as the argument to experiment's |
None
|
register_user_function(func, name=None)
¶
Registers a near-time callback to be referred from the experiment's call
operation.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
func
|
function
|
Near-time callback that is registered. |
required |
name
|
str
|
Optional name to use as the argument to experiment's |
None
|
Deprecated in version 2.19.0
The register_user_function
method was deprecated in version 2.19.0.
Use register_neartime_callback
instead.
replace_phase_increment(parameter_uid, new_value)
¶
Replace the value of a parameter that drives phase increments value.
If the parameter spans multiple iterations of a loop, it will replace the parameter by the same value in all the iterations.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
parameter_uid
|
str
|
The name of the parameter to replace. |
required |
new_value
|
int | float
|
The new replacement value. |
required |
replace_pulse(pulse_uid, pulse_or_array)
¶
Replaces a specific pulse with new sample data on the device.
This is useful when called from within a near-time callback, and allows fast waveform replacement within near-time loops without recompilation of the experiment.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
pulse_uid
|
str | Pulse
|
Pulse to replace, can be a Pulse object or the UID of the pulse. |
required |
pulse_or_array
|
ArrayLike | Pulse
|
Replacement pulse, can be a Pulse object or array of values. Needs to have the same length as the pulse it replaces. |
required |
run(experiment=None, include_results_metadata=None)
¶
Executes the compiled experiment.
Requires connected LabOne Q session (session.connect()
) either with or without emulation mode.
If no experiment is specified, the last compiled experiment is run. If an experiment is specified, the provided experiment is assigned to the internal experiment of the session.
Changed in version 2.0
Removed do_simulation
argument.
Use OutputSimulator instead.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
experiment
|
Union[Experiment, CompiledExperiment] | None
|
Optional. Experiment instance that should be run. The experiment will be compiled if it has not been yet. If no experiment is specified the previously assigned and compiled experiment is used. |
None
|
include_results_metadata
|
bool | None
|
If true, return a |
None
|
Returns:
Name | Type | Description |
---|---|---|
results |
Results
|
A |
Changed in version 2.55.0
The deprecated .compiled_experiment
attribute was removed from Results
. The
include_results_metadata
argument thus no longer populates this attribute on Results
.
Track the compiled experiment separately instead.
Changed in version 2.52.0
Replaced the include_metadata
argument with include_results_metadata
.
Added in version 2.51.0
Added the include_metadata
argument to control whether to include experiment and
device setup in the results.
Changed in version 2.4
Raises error if session is not connected.
submit(experiment=None, queue=None)
¶
Asynchronously submit experiment to the given queue.
If no experiment is specified, the last compiled experiment is run. If an experiment is specified, the provided experiment is assigned to the internal experiment of the session.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
experiment
|
Experiment | CompiledExperiment | None
|
Optional. Experiment instance that should be run. The experiment will be compiled if it has not been yet. If no experiment is specified the previously assigned and compiled experiment is used. |
None
|
queue
|
Callable[[str, CompiledExperiment | None, DeviceSetup], Any] | None
|
The name of connector to a queueing system which should do the actual
run on a setup. |
None
|
Returns:
Name | Type | Description |
---|---|---|
results |
Results
|
An object with which users can query results. Details depend on the implementation of the queue. |