Engine Configuration Models¶
These are the typed Pydantic models that live at the GUI/engine boundary. They're the validated shape of every scan request — the GUI builds them, the engine consumes them. If you're scripting a scan, writing a custom evaluator, or building an alternate UI, these are the models you'll construct or read.
Scan execution¶
The top-level configuration for a scan run.
Bases: BaseModel
Complete, validated specification for one scan run.
This is what the GUI produces and what the engine consumes. Replaces
the raw config_dictionary dict that previously carried device config,
options, and action sequences in an untyped bag.
Attributes:
| Name | Type | Description |
|---|---|---|
scan_config |
ScanConfig
|
Scan parameters — variable, start/stop/step, scan mode. |
options |
ScanOptions
|
Engine-level execution options (rep rate, time sync, TDMS, etc.). |
save_config |
SaveDeviceConfig
|
Device saving configuration including setup/closeout action sequences. |
Methods:
| Name | Description |
|---|---|
from_gui_dict |
Construct from the dict the GUI currently builds. |
to_device_manager_dict |
Return the dict format DeviceManager.load_from_dictionary() expects. |
Attributes¶
model_config
class-attribute
instance-attribute
¶
model_config = ConfigDict(arbitrary_types_allowed=True)
options
class-attribute
instance-attribute
¶
options: ScanOptions = Field(default_factory=ScanOptions)
save_config
class-attribute
instance-attribute
¶
save_config: SaveDeviceConfig = Field(default_factory=SaveDeviceConfig)
Functions¶
from_gui_dict
classmethod
¶
from_gui_dict(config_dict: dict, scan_config: ScanConfig, options: Optional[ScanOptions] = None) -> 'ScanExecutionConfig'
Construct from the dict the GUI currently builds.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config_dict
|
dict
|
Raw |
required |
scan_config
|
ScanConfig
|
Scan parameters. |
required |
options
|
ScanOptions
|
Execution options. Overrides any |
None
|
to_device_manager_dict ¶
to_device_manager_dict() -> dict
Return the dict format DeviceManager.load_from_dictionary() expects.
Scan options¶
Engine-level execution options (rep rate, time-sync settings, file-save destination).
Bases: BaseModel
Engine-level options that affect how a scan is executed.
Constructed by the GUI from its menu-bar settings and passed through
RunControl to ScanManager. User-interface-only preferences
(sound theme, dark mode, window layout) are not included here.
Attributes:
| Name | Type | Description |
|---|---|---|
rep_rate_hz |
float
|
Shot repetition rate in Hz. Must be positive. |
enable_global_time_sync |
bool
|
When True, use cross-device timestamp comparison to synchronise devices before each scan step instead of the fixed timeout method. |
global_time_tolerance_ms |
int
|
Tolerance window (milliseconds) for global time synchronisation. Clamped to [0, 60000]. |
master_control_ip |
str
|
IP address of the Master Control server for ECS live dump. Empty string disables the dump. |
on_shot_tdms |
bool
|
When True, write an incremental TDMS update after each shot. |
save_direct_on_network |
bool
|
When True, save device data directly to the scan folder on the network share instead of staging locally first. |
randomized_beeps |
bool
|
When True, vary the beep pitch between shots. |
Attributes¶
Save device configuration¶
The schema that backs the save-element YAML files. Documented narratively at Save Elements; this is the formal model.
Bases: BaseModel
Comprehensive configuration schema for experimental device saving and workflow management.
This model provides a complete framework for defining device configurations, data saving strategies, and pre/post-scan actions during experimental workflows.
Attributes:
| Name | Type | Description |
|---|---|---|
Devices |
(Dict[str, DeviceConfig], optional)
|
Mapping of device names to their specific configuration. Allows granular control over individual device data collection. |
scan_info |
(Dict[str, str], optional)
|
Additional metadata or descriptive information about the scan. |
setup_action |
(ActionSequence, optional)
|
Sequence of actions to perform before initiating the scan. Enables complex pre-scan device preparation and system configuration. |
closeout_action |
(ActionSequence, optional)
|
Sequence of actions to perform after completing the scan. Supports systematic device shutdown, data processing, or system reset. |
Notes
SaveDeviceConfig provides: - Comprehensive device configuration management - Flexible pre and post-scan action sequences - Extensible scan metadata tracking - Modular experimental workflow definition
Examples:
>>> save_config = SaveDeviceConfig(
... Devices={
... 'Laser': DeviceConfig(synchronous=True),
... 'Spectrometer': DeviceConfig(save_nonscalar_data=True)
... },
... scan_info={'experiment': 'beam_characterization'},
... setup_action=ActionSequence(steps=[...]),
... closeout_action=ActionSequence(steps=[...])
... )
>>> # Creates a comprehensive device saving configuration
See Also
DeviceConfig : Individual device configuration ActionSequence : Define pre/post-scan action sequences geecs_scanner.engine.device_manager : Device management system
Attributes¶
Devices
class-attribute
instance-attribute
¶
Devices: Optional[Dict[str, DeviceConfig]] = Field(None, description='Mapping of device names to their specific configuration.')
scan_info
class-attribute
instance-attribute
¶
scan_info: Optional[Dict[str, str]] = Field(None, description='Additional metadata or descriptive information about the scan.')
setup_action
class-attribute
instance-attribute
¶
setup_action: Optional[ActionSequence] = Field(None, description='Sequence of actions to perform before initiating the scan.')
closeout_action
class-attribute
instance-attribute
¶
closeout_action: Optional[ActionSequence] = Field(None, description='Sequence of actions to perform after completing the scan.')
Bases: BaseModel
Comprehensive configuration for a single device during scan acquisition and data saving.
This model provides granular control over device data collection, logging strategies, and variable tracking during experimental workflows.
Attributes:
| Name | Type | Description |
|---|---|---|
synchronous |
(bool, optional)
|
If True, device is treated as synchronous with step-by-step logging. Defaults to False, enabling more flexible asynchronous data collection. |
save_nonscalar_data |
(bool, optional)
|
Controls whether non-scalar data (e.g., images) should be saved. Defaults to False, focusing on scalar measurements. |
variable_list |
(List[str], optional)
|
Explicit list of variables to acquire from the device. If None, defaults to device-specific or system-wide variable tracking. |
post_analysis_class |
(str, optional)
|
DEPRECATED. Previously used for post-acquisition data processing. |
scan_setup |
(Dict[str, List[str]], optional)
|
Configures device-specific setup and teardown values. Each key maps to a two-element list: [pre-scan value, post-scan value]. |
Notes
DeviceConfig enables: - Flexible logging mode selection - Granular data saving control - Explicit variable tracking - Device-specific pre/post-scan configuration
Examples:
>>> laser_config = DeviceConfig(
... synchronous=True,
... save_nonscalar_data=False,
... variable_list=['power', 'wavelength'],
... scan_setup={'mode': ['standby', 'off']}
... )
>>> # Configures laser device for synchronous, scalar data collection
See Also
SaveDeviceConfig : Overall device saving configuration ActionSequence : Define pre/post-scan actions
Attributes¶
synchronous
class-attribute
instance-attribute
¶
synchronous: Optional[bool] = Field(False, description='If True, device is treated as synchronous (step-by-step logging).')
save_nonscalar_data
class-attribute
instance-attribute
¶
save_nonscalar_data: Optional[bool] = Field(False, description='Whether to save non-scalar data such as images.')
variable_list
class-attribute
instance-attribute
¶
variable_list: Optional[List[str]] = Field(None, description='List of variables to acquire from the device.')
add_all_variables
class-attribute
instance-attribute
¶
add_all_variables: Optional[bool] = Field(False, description='If True, include all device variables (overridden by variable_list if provided).')
post_analysis_class
class-attribute
instance-attribute
¶
post_analysis_class: Optional[str] = Field(None, description='Deprecated post-analysis processing class.')
scan_setup
class-attribute
instance-attribute
¶
scan_setup: Optional[Dict[str, List[str]]] = Field(None, description='Optional dictionary mapping setup variables to pre-scan and post-scan values. Each entry is a two-element list: [pre-scan value, post-scan value].')
Action steps¶
The five step types that make up setup_action and closeout_action sequences. Documented narratively at Save Elements — Action Sequences.
Bases: BaseModel
A step that pauses execution for a specified duration in experimental workflows.
This action step provides precise timing control during experimental sequences, allowing for controlled delays between device operations, data acquisition phases, or system stabilization periods.
Attributes:
| Name | Type | Description |
|---|---|---|
action |
Literal['wait']
|
The action type identifier for wait operations. |
wait |
float
|
Duration to pause in seconds. Must be greater than 0. |
Notes
Wait steps are commonly used for: - Allowing devices to stabilize after configuration changes - Introducing delays between measurement phases - Synchronizing with external experimental timing
Examples:
>>> wait_step = WaitStep(action="wait", wait=2.5)
>>> # Creates a 2.5 second pause in the action sequence
See Also
ExecuteStep : Execute nested action sequences SetStep : Configure device variables
Bases: BaseModel
A step that configures device variables with precise control and optional execution waiting.
This step enables dynamic device configuration within experimental workflows, supporting various data types and optional synchronous execution.
Attributes:
| Name | Type | Description |
|---|---|---|
action |
Literal['set']
|
The action type identifier for device variable configuration. |
device |
str
|
Name of the device to configure (must be known to the system). |
variable |
str
|
Specific variable on the device to set. |
value |
Union[str, float, int]
|
Value to assign to the device variable. |
wait_for_execution |
(bool, optional)
|
Whether to wait for the command to complete before proceeding. Defaults to True. |
Notes
Set steps provide: - Flexible device configuration - Support for multiple value types - Optional synchronous execution - Precise device state management
Examples:
>>> set_step = SetStep(
... action="set",
... device="LaserController",
... variable="power",
... value=5.0,
... wait_for_execution=True
... )
>>> # Sets laser power to 5.0, waiting for confirmation
See Also
GetStep : Query device variable values WaitStep : Introduce delays in action sequences
Attributes¶
device
instance-attribute
¶
device: Annotated[str, Field(description='Device name (must be known to the system)')]
variable
instance-attribute
¶
variable: Annotated[str, Field(description='Variable on the device to set')]
value
instance-attribute
¶
value: Annotated[Union[str, float, int], Field(description='Value to assign to the variable')]
wait_for_execution
class-attribute
instance-attribute
¶
wait_for_execution: Optional[bool] = Field(True, description='Whether to wait for the command to complete before proceeding.')
Bases: BaseModel
A step that queries device variables and optionally validates their values.
This step enables dynamic data retrieval and optional value verification within experimental workflows, supporting various data types.
Attributes:
| Name | Type | Description |
|---|---|---|
action |
Literal['get']
|
The action type identifier for device variable querying. |
device |
str
|
Name of the device to query (must be known to the system). |
variable |
str
|
Specific variable to read from the device. |
expected_value |
Union[str, float, int]
|
Optional expected value for validation purposes. |
Notes
Get steps support: - Dynamic device variable retrieval - Optional value validation - Flexible data type handling - Experimental state verification
Examples:
>>> get_step = GetStep(
... action="get",
... device="Thermometer",
... variable="temperature",
... expected_value=25.0
... )
>>> # Retrieves temperature, optionally validating against 25.0
See Also
SetStep : Configure device variables ActionSequence : Define sequences of action steps
Attributes¶
device
instance-attribute
¶
device: Annotated[str, Field(description='Device name (must be known to the system)')]
variable
instance-attribute
¶
variable: Annotated[str, Field(description='Variable to read from the device')]
expected_value
instance-attribute
¶
expected_value: Annotated[Union[str, float, int], Field(description='Expected value for validation')]
Bases: BaseModel
A step that invokes another named action, enabling reusable and nested procedural workflows.
This step allows for complex, modular action sequences by referencing pre-defined actions from the action library. It supports hierarchical and recursive action composition.
Attributes:
| Name | Type | Description |
|---|---|---|
action |
Literal['execute']
|
The action type identifier for action execution. |
action_name |
str
|
Name of the action to execute, as defined in the action library. |
Notes
Execute steps enable: - Modular action design - Reusable procedure templates - Complex workflow composition - Hierarchical action nesting
Examples:
>>> execute_step = ExecuteStep(action="execute", action_name="laser_calibration")
>>> # Executes a pre-defined "laser_calibration" action sequence
See Also
ActionLibrary : Collection of named action sequences WaitStep : Introduce delays in action sequences
Bases: BaseModel
A step that executes external scripts or classes within the experimental workflow.
This step provides flexibility in running custom Python scripts or instantiating specific classes as part of the action sequence.
Attributes:
| Name | Type | Description |
|---|---|---|
action |
Literal['run']
|
The action type identifier for script/class execution. |
file_name |
str
|
Name of the Python file containing the script or class to run. |
class_name |
str
|
Name of the class to instantiate or method to execute. |
Notes
Run steps support: - Dynamic script execution - Custom class instantiation - Flexible integration of external logic - Extensible experimental workflows
Examples:
>>> run_step = RunStep(
... action="run",
... file_name="beam_analysis.py",
... class_name="BeamProfiler"
... )
>>> # Runs BeamProfiler class from beam_analysis.py
See Also
ExecuteStep : Execute predefined action sequences SetStep : Configure device variables
Bases: BaseModel
A comprehensive, ordered sequence of action steps defining an executable experimental procedure.
This model represents a complete, structured workflow composed of multiple action steps, enabling complex, modular experimental protocols.
Attributes:
| Name | Type | Description |
|---|---|---|
steps |
List[ActionStep]
|
An ordered list of action steps to perform in sequence. Supports various step types: Wait, Execute, Run, Set, Get. |
Notes
ActionSequence provides: - Ordered execution of multiple action steps - Support for diverse step types - Flexible experimental workflow definition - Comprehensive validation of step sequences
Examples:
>>> sequence = ActionSequence(steps=[
... WaitStep(action="wait", wait=1.0),
... SetStep(action="set", device="Laser", variable="power", value=5.0),
... GetStep(action="get", device="Laser", variable="status")
... ])
>>> # Creates a sequence with wait, set, and get steps
See Also
ActionLibrary : Collection of named action sequences ActionStep : Individual step types supported in sequences