Run Experiment

Running an experiment on a single point

run_experiment is a separate CLI entry point, not an ado subcommand. There is no ado run_experiment. It runs one entity through one or more experiments and prints the result — nothing is written to the metastore.

Use it for:

• Smoke testing an actuator or custom experiment after installing a plugin
• Debugging experiment execution or entity validation
• Taking a single measurement when tracking is not needed

For measuring multiple entities, create a discoveryspace and an operation instead — see define-experiment-campaign.

Usage

uv run run_experiment PATH_TO_POINT_YAML

Ray is started locally and shut down automatically; no metastore or remote cluster is required.

Point YAML

The point.yaml has two top level fields:

• entity is a map of constitutive property name/value pairs. These are the input parameter name/value combinations to the experiment.
• experiments is a list of experiment references to run on that entity.

entity:
  mass: 8
  volume: 4
experiments:
  - actuatorIdentifier: custom_experiments
    experimentIdentifier: calculate_density
    experimentVersion: 1.0.0 # Omit if the experiment has no version

Get the identifiers to use with:

# Actuators and the experiments they provide
uv run ado get actuators --details

# Required and optional consitutive properties of one experiment
uv run ado describe experiment ACTUATOR_ID.EXPERIMENT_ID

Options

Verify with uv run run_experiment --help before writing a command.

Interpreting the output

run_experiment prints the point, whether the entity validated, and then the result as a pandas Series holding the request and entity identifiers, the entity's constitutive property values, and the experiment's target output properties.

• "Entity is not valid": the entity is missing a required constitutive property, or a value is outside the property's domain. Check the requirements with uv run ado describe experiment ACTUATOR_ID.EXPERIMENT_ID.
• "Failed to initialize actuator": the actuator raised during startup — usually a missing dependency or bad actuator configuration.
• "Measurement request failed unexpectedly": the experiment itself raised. Re-run with LOGLEVEL=10 set to see the actuator traceback.

Related Resources

• define-experiment-campaign — running experiments over many entities with a discoveryspace and operation
• using-ado-cli — the ado CLI: syntax, flags, and shortcuts
• plugin-development — plugin testing checklist, where run_experiment is the experiment execution check
• docs/user-guide/advanced/run-experiment.md — user documentation for this tool