`laboneq.dsl.session` ¶

`Session(device_setup=None, log_level=None, performance_log=False, configure_logging=True, _last_results=None, compiled_experiment=None, experiment=None)` ¶

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`	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`

Changed in version 2.0

Removed pass_v3_to_compiler argument.
Removed max_simulation_time instance variable.

`compiled_experiment: CompiledExperiment | None` `property` ¶

Access to the compiled experiment.

The compiled experiment can be assigned to a different session if the device setup is matching.

`connection_state: ConnectionState` `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: ToolkitDevices` `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: int` `property` `writable` ¶

The current log level.

`logger` `property` `writable` ¶

The current logger instance used by the session.

`results: 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.

Changed 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)` ¶

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 raises 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`

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.

`load(filename)` `staticmethod` ¶

Loads the session from a serialized file. A restored session from a loaded file will end up in the same state of the session that saved the file in the first place.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename (full path) of the file that should be loaded into the session.	required

Returns:

Name	Type	Description
`session`	`Session`	A new session loaded from the file.

`load_compiled_experiment(filename)` ¶

Loads a compiled experiment from a given file into the session.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename (full path) of the experiment should be loaded into the session.	required

`load_device_calibration(filename)` ¶

Loads a device calibration from a given file into the session.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename (full path) of the calibration should be loaded into the session.	required

`load_device_setup(filename)` ¶

Loads a device setup from a given file into the session.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename (full path) of the setup should be loaded into the session.	required

`load_experiment(filename)` ¶

Loads an experiment from a given file into the session.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename (full path) of the experiment should be loaded into the session.	required

`load_experiment_calibration(filename)` ¶

Loads a experiment calibration from a given file into the session.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename (full path) of the calibration should be loaded into the session.	required

`load_signal_map(filename)` ¶

Loads a signal map from a given file and sets it to the experiment in the session.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename (full path) of the mapping that should be loaded into the session.	required

`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)` ¶

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`

Returns:

Name	Type	Description
`results`	`Results`	A `Results` object.

Changed in version 2.4

Raises error if session is not connected.

`save(filename)` ¶

Stores the session from a serialized file. A restored session from a loaded file will end up in the same state of the session that saved the file in the first place.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename (full path) of the file where the session should be stored in.	required

`save_compiled_experiment(filename)` ¶

Saves the compiled experiment from the session into a given file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename (full path) of the file where the experiment should be stored in.	required

`save_device_calibration(filename)` ¶

Saves the device calibration from the session into a given file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename (full path) of the file where the calibration should be stored in.	required

`save_device_setup(filename)` ¶

Saves the device setup from the session into a given file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename (full path) of the file where the setup should be stored in.	required

`save_experiment(filename)` ¶

Saves the experiment from the session into a given file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename (full path) of the file where the experiment should be stored in.	required

`save_experiment_calibration(filename)` ¶

Saves the experiment calibration from the session into a given file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename (full path) of the file where the calibration should be stored in.	required

`save_results(filename)` ¶

Saves the result from the session into a given file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename (full path) of the file where the result should be stored in.	required

`save_signal_map(filename)` ¶

Saves the signal mapping from experiment in the session into a given file.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Filename (full path) of the file where the mapping should be stored in.	required

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

laboneq.dsl.session ¶

Session(device_setup=None, log_level=None, performance_log=False, configure_logging=True, _last_results=None, compiled_experiment=None, experiment=None) ¶

compiled_experiment: CompiledExperiment | None property ¶

connection_state: ConnectionState property ¶

device_calibration property writable ¶

device_setup property ¶

devices: ToolkitDevices property ¶

experiment property ¶

experiment_calibration property writable ¶

log_level: int property writable ¶

logger property writable ¶

results: Results property ¶

signal_map property writable ¶

abort_execution() ¶

compile(experiment, compiler_settings=None) ¶

connect(do_emulation=False, ignore_version_mismatch=False, reset_devices=False, use_async_api=None) ¶

disable_outputs(devices=None, signals=None, unused_only=False) ¶

disconnect() ¶

get_results() ¶

load(filename) staticmethod ¶

load_compiled_experiment(filename) ¶

load_device_calibration(filename) ¶

load_device_setup(filename) ¶

load_experiment(filename) ¶

load_experiment_calibration(filename) ¶

load_signal_map(filename) ¶

register_neartime_callback(func, name=None) ¶

register_user_function(func, name=None) ¶

replace_phase_increment(parameter_uid, new_value) ¶

replace_pulse(pulse_uid, pulse_or_array) ¶

run(experiment=None) ¶

save(filename) ¶

save_compiled_experiment(filename) ¶

save_device_calibration(filename) ¶

save_device_setup(filename) ¶

save_experiment(filename) ¶

save_experiment_calibration(filename) ¶

save_results(filename) ¶

save_signal_map(filename) ¶

submit(experiment=None, queue=None) ¶

`laboneq.dsl.session` ¶

`Session(device_setup=None, log_level=None, performance_log=False, configure_logging=True, _last_results=None, compiled_experiment=None, experiment=None)` ¶

`compiled_experiment: CompiledExperiment | None` `property` ¶

`connection_state: ConnectionState` `property` ¶

`device_calibration` `property` `writable` ¶

`device_setup` `property` ¶

`devices: ToolkitDevices` `property` ¶

`experiment` `property` ¶

`experiment_calibration` `property` `writable` ¶

`log_level: int` `property` `writable` ¶

`logger` `property` `writable` ¶

`results: Results` `property` ¶

`signal_map` `property` `writable` ¶

`abort_execution()` ¶

`compile(experiment, compiler_settings=None)` ¶

`connect(do_emulation=False, ignore_version_mismatch=False, reset_devices=False, use_async_api=None)` ¶

`disable_outputs(devices=None, signals=None, unused_only=False)` ¶

`disconnect()` ¶

`get_results()` ¶

`load(filename)` `staticmethod` ¶

`load_compiled_experiment(filename)` ¶

`load_device_calibration(filename)` ¶

`load_device_setup(filename)` ¶

`load_experiment(filename)` ¶

`load_experiment_calibration(filename)` ¶

`load_signal_map(filename)` ¶

`register_neartime_callback(func, name=None)` ¶

`register_user_function(func, name=None)` ¶

`replace_phase_increment(parameter_uid, new_value)` ¶

`replace_pulse(pulse_uid, pulse_or_array)` ¶

`run(experiment=None)` ¶

`save(filename)` ¶

`save_compiled_experiment(filename)` ¶

`save_device_calibration(filename)` ¶

`save_device_setup(filename)` ¶

`save_experiment(filename)` ¶

`save_experiment_calibration(filename)` ¶

`save_results(filename)` ¶

`save_signal_map(filename)` ¶

`submit(experiment=None, queue=None)` ¶