Experiment

class caqtus.extension.Experiment(

storage_config: PostgreSQLConfig | SQLiteConfig | None = None,

)

Bases: object

Configure parameters and register extensions for a specific experiment.

There should be only a single instance of this class in the entire application. It is used to configure the experiment and knows how to launch the different components of the application after it has been configured.

Parameters:

storage_config – The configuration of the storage backend to be used to store the data of the experiment.

setup_default_extensions() → None

Register some commonly used extensions to this experiment.

This method registers the following extensions:

• digital time lanes

• analog time lanes

• camera time lanes

configure_storage(

storage_config: PostgreSQLConfig | SQLiteConfig,

) → None

Configure the storage backend to be used by the application.

After this method is called, the application will read and write data and configurations to the storage specified.

It is necessary to call this method before launching the application.

Warning

Calling this method multiple times will overwrite the previous configuration.

configure_shot_retry(

shot_retry_config: ShotRetryConfig | None,

) → None

Configure the shot retry policy to be used when running sequences.

After this method is called, shots that raise errors will be retried according to the policy specified.

It is necessary to call this method before launching the experiment manager.

Warning

Calling this method multiple times will overwrite the previous configuration.

configure_experiment_manager(

location: LocalExperimentManagerConfiguration | RemoteExperimentManagerConfiguration,

) → None

Configure the location of the experiment manager with respect to Condetrol.

The ExperimentManager is responsible for running sequences on the experiment.

It can be either running in the same process as the Condetrol application or in a separate process.

This is configured by passing an instance of either LocalExperimentManagerConfiguration or RemoteExperimentManagerConfiguration.

If this method is not called, the experiment manager will be assumed to be running in the same local process as the Condetrol application.

If the experiment manager is configured to run in the same process, it will be created when the Condetrol application is launched. An issue with this approach is that if the Condetrol application crashes, the experiment manager will also stop abruptly, potentially leaving the experiment in an undesired state.

If the experiment manager is configured to run in a separate process, it will be necessary to have an experiment manager server running before launching the Condetrol application. The Condetrol application will then connect to the server and transmit the commands to the other process. If the Condetrol application crashes, the experiment manager will be unaffected.

Warning

Calling this method multiple times will overwrite the previous configuration.

register_device_extension(

device_extension: DeviceExtension,

) → None

Register a new device extension.

After this method is called, the device extension will be available to the application, both in the device editor tab in Condetrol and while running the experiment.

register_time_lane_extension(

time_lane_extension: TimeLaneExtension,

) → None

Register a new time lane extension.

After this method is called, the time lane extension will be available to the application, both in the time lane editor tab in Condetrol and while running the experiment.

register_device_server(

name: DeviceServerName,

config: InsecureRPCConfiguration,

) → None

Register a new device server.

After this method is called, the device server will be available to the application to connect to devices.

get_storage_manager() → StorageManager

Get the storage manager to be used by the application.

The storage manager is responsible for interacting with the storage of the experiment.

build_storage_manager(

backend_type: Callable[[Concatenate[SerializerProtocol, P]], T],

*args: P,

**kwargs: P,

) → T

Create and set up a storage manager with the current registered extensions.

Parameters:

• backend_type – Defines how the data will be stored.

• *args – The arguments to pass to the storage backend constructor.

• **kwargs – The keyword arguments to pass to the storage backend constructor.

connect_to_experiment_manager() → ExperimentManager

Connect to the experiment manager.

get_local_experiment_manager() → LocalExperimentManager

Return the local experiment manager.

This method is used to create an instance of the experiment manager that runs in the local process.

The first time this method is called, the experiment manager will be created. If it is called again, the instance previously created will be returned.

launch_condetrol() → None

Launch the Condetrol application.

The Condetrol application is the main user interface to the experiment. It allows to edit and launch sequences, as well as edit the device configurations.

launch_experiment_server() → None

Launch the experiment server.

The experiment server is used to run procedures on the experiment manager from a remote process.

If the environment variable CAQTUS_BLOCKING_TASK_DURATION_WARNING is set to a float duration in seconds, a warning will be logged if a task doesn’t yield to the event loop for that duration during the execution of a sequence.

static launch_device_server(

config: InsecureRPCConfiguration,

name: str = 'device_server',

) → None

Launch a device server in the current process.

This method will block until the server is stopped.

Parameters:

• config – The configuration of the server.

• name – The name of the server. It is used to create the log file.

storage_session() → AbstractContextManager[ExperimentSession]

Return a context manager that provides a session to the storage backend.

A session can be used to access the data stored in the experiment.

upgrade_database() → None

Upgrade the database schema of the experiment to the latest version.

Warning

If the database contains important data, it is strongly recommended to back it up before running this function in case something goes wrong.