Skip to content

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 laboneq.laboneq_logging.

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, Session.run will return a Results object with the deprecated .experiment, and .device_setup attributes populated. Otherwise, it will return a Results object with these attributes not populated.

False
server_log bool

If True, the data server log - including device firmware logs - will be forwarded to the LabOneQ log under the logger named server.log.<server_uid>. Additionally, it will be written to the file server.log alongside the regular LabOneQ log, assuming the standard logging configuration is used.

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 False (default), the following checks are made for compatibility:

  • Check LabOne and LabOne Q version compatibility.
  • Check LabOne and Zurich Instruments' devices firmware version compatibility.

The following states raise an exception:

  • Device firmware requires an update
  • Device firmware requires an downgrade
  • Device update is in progress

It is suggested to keep the versions aligned and up-to-date to avoid any unexpected behaviour.

Changed in version 2.4

Renamed ignore_lab_one_version_error to ignore_version_mismatch and include LabOne and device firmware version compatibility check.

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 True.

None
disable_runtime_checks bool

Disable the runtime checks performed by device firmware. Defaults to True.

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 call operation to refer to this function. If not provided, function name will be used.

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 call operation to refer to this function. If not provided, function name will be used.

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 Results object with the deprecated .experiment, and .device_setup attributes populated. If false, return a Results object with these attributes not populated. If None, the setting falls back to that passed to include_results_metadata when this session was created.

None

Returns:

Name Type Description
results Results

A Results object.

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. queue must be callable with the signature (name: str, experiment: CompiledExperiment | None, device_setup: DeviceSetup) which returns an object with which users can query results.

None

Returns:

Name Type Description
results Results

An object with which users can query results. Details depend on the implementation of the queue.