Module madsci.experiment_application.experiment_application

Provides an ExperimentApplication class that manages the execution of an experiment.

.. deprecated:: 0.7.0 ExperimentApplication is deprecated. Use ExperimentScript, ExperimentNotebook, ExperimentTUI, or ExperimentNode instead depending on your use case. ExperimentApplication will be removed in v0.8.0.

Migration guide:
- For simple scripts: Use ExperimentScript
- For Jupyter notebooks: Use ExperimentNotebook
- For interactive terminal: Use ExperimentTUI
- For server mode: Use ExperimentNode

See https://ad-sdl.github.io/MADSci/running-experiments for details.

Classes¶

An experiment application that helps manage the execution of an experiment.

You can either use this class as a base class for your own application class, or create an instance of it to manage the execution of an experiment.

This class extends AbstractNode (via RestNode) and inherits client management from MadsciClientMixin. In addition to the standard node clients (event, resource, data), it also uses experiment, workcell, location, and optionally lab clients.

Initialize the experiment application.

.. deprecated:: 0.7.0 ExperimentApplication is deprecated. Use ExperimentScript, ExperimentNotebook, ExperimentTUI, or ExperimentNode instead.

You can provide an experiment design to use for creating new experiments, or an existing experiment to continue.

Note: Client initialization is handled by the parent AbstractNode class via MadsciClientMixin. All manager clients (experiment, workcell, location, data, resource) are available as properties and will be lazily initialized when first accessed.

Ancestors (in MRO)¶

madsci.node_module.rest_node_module.RestNode
madsci.node_module.abstract_node_module.AbstractNode
madsci.client.client_mixin.MadsciClientMixin

Class variables¶

OPTIONAL_CLIENTS: ClassVar[list[str]] :

experiment: madsci.common.types.experiment_types.Experiment | None: The current experiment being run.
experiment_design: madsci.common.types.experiment_types.ExperimentDesign | str | pathlib.Path | None: The design of the experiment.

Static methods¶

continue_experiment(experiment: madsci.common.types.experiment_types.Experiment, lab_server_url: str | pydantic.networks.AnyUrl | None = None) ‑> madsci.experiment_application.experiment_application.ExperimentApplication: Create a new experiment application with an existing experiment.
start_new(lab_server_url: str | pydantic.networks.AnyUrl | None = None, experiment_design: madsci.common.types.experiment_types.ExperimentDesign | None = None) ‑> madsci.experiment_application.experiment_application.ExperimentApplication: Create a new experiment application with a new experiment.

Methods¶

add_experiment_management(self, func: Callable[~P, ~R]) ‑> Callable[~P, ~R]

wraps the run experiment function while preserving arguments

cancel_experiment(self) ‑> None

Cancel the experiment.

check_experiment_status(self) ‑> None

Update and check the status of the current experiment.

Raises an exception if the experiment has been cancelled or failed. If the experiment has been paused, this function will wait until the experiment is resumed.

Raises: ExperimentCancelledError: If the experiment has been cancelled. ExperimentFailedError: If the experiment has failed.

check_resource_field(self, resource: madsci.common.types.resource_types.Resource, condition: madsci.common.types.condition_types.Condition) ‑> bool

check if a resource meets a condition

end_experiment(self, status: madsci.common.types.experiment_types.ExperimentStatus | None = None) ‑> None

End the experiment.

evaluate_condition(self, condition: madsci.common.types.condition_types.Condition) ‑> bool

evaluate a condition

fail_experiment(self) ‑> None

Mark an experiment as failed.

get_location_from_condition(self, condition: madsci.common.types.condition_types.Condition) ‑> madsci.common.types.location_types.Location

get the location referenced by a condition

get_resource_from_condition(self, condition: madsci.common.types.condition_types.Condition) ‑> madsci.common.types.resource_types.Resource | None

gets a resource from a condition

handle_exception(self, exception: Exception) ‑> None

Exception handler that makes experiment fail by default, can be overwritten

loop(self) ‑> None

Function that runs the experimental loop. This should be overridden by subclasses.

manage_experiment(self, run_name: str | None = None, run_description: str | None = None) ‑> Generator[None, None, None]

Context manager to start and end an experiment with full context propagation.

All logging within this experiment run will include the experiment context, enabling hierarchical log filtering and analysis.

pause_experiment(self) ‑> None

Pause the experiment.

resource_at_key(self, resource: madsci.common.types.resource_types.Resource, condition: madsci.common.types.condition_types.Condition) ‑> bool

return if a resource is in a location at condition.key

run_experiment(self, *args: Any, **kwargs: Any) ‑> Any

The main experiment function, overwrite for each app

start_app(self) ‑> None

Starts the application, either as a node or in single run mode

start_experiment_run(self, run_name: str | None = None, run_description: str | None = None) ‑> None

Sends the ExperimentDesign to the server to register a new experimental run.

ExperimentApplicationConfig(**kwargs: Any)

Configuration for the ExperimentApplication.

This class is used to define the configuration for the ExperimentApplication node. It can be extended to add custom configurations.

Initialize settings with walk-up file discovery.

Configuration file paths (YAML, JSON, TOML, .env) are resolved via walk-up discovery from a starting directory. Each filename walks up independently, so node.settings.yaml can resolve in the node dir while settings.yaml resolves in the lab root.

The starting directory is determined by (in priority order):

_settings_dir keyword argument
MADSCI_SETTINGS_DIR environment variable
Current working directory (default)

Args: _settings_dir: Starting directory for walk-up file discovery. **kwargs: Forwarded to BaseSettings.__init__.

Ancestors (in MRO)¶

madsci.common.types.node_types.RestNodeConfig
madsci.common.types.node_types.NodeConfig
madsci.common.types.base_types.MadsciBaseSettings
pydantic_settings.main.BaseSettings
pydantic.main.BaseModel

Class variables¶

lab_server_url: str | pydantic.networks.AnyUrl | None: The URL of the lab server to connect to.
run_args: list[typing.Any]: Arguments to pass to the run_experiment function when not running in server mode.
run_kwargs: dict[str, typing.Any]: Keyword arguments to pass to the run_experiment function when not running in server mode.
server_mode: bool: Whether the application should start a REST Server acting as a MADSci node or not.