Skip to content

Running your first ado experiment campaign

New to ado?

This walkthrough introduces the key concepts — custom experiments, discovery spaces, and operations — as we go. If you'd prefer a full overview first, the Concepts page has you covered.

This walkthrough takes you end-to-end through the full ado workflow using a deliberately simple example — computing density from mass and volume — so you can focus on the concepts rather than the domain.

We will:

  1. Run a pre-built custom experiment that computes density
  2. Test it on a single point
  3. Describe a discovery space over a grid of mass and volume values
  4. Run an operation to sample the space and collect results

Prerequisites

  • ado-core installed (pip install ado-core)
  • The example package cloned from GitHub (the wheel is not published to PyPI)

Clone the repository if you have not already done so:

git clone https://github.com/ibm/ado.git
cd ado

Then install the example package into your environment:

pip install -e examples/density_example/

All commands in this walkthrough are run from the repository root (ado/).

TL;DR

Once the package is installed:

run_experiment examples/density_example/point.yaml
ado create space -f examples/density_example/space.yaml
ado create operation -f examples/density_example/operation.yaml --use-latest space
ado show measurements operation --use-latest

Step 1 — The custom experiment

A custom experiment is a Python function that ado can call as part of a discovery workflow. In this example, the experiment is calculate_density: it takes mass and volume as inputs and returns density = mass / volume.

Once the prerequisites above are met, confirm ado can see the experiment:

ado get experiments

You should see calculate_density listed under custom_experiments:

Available experiments:
  actuator: custom_experiments
    - calculate_density

Step 2 — Test on a single point

Before running a full experiment campaign, it is useful to verify it works on a single point. The file examples/density_example/point.yaml defines one:

# Copyright IBM Corporation 2025, 2026
# SPDX-License-Identifier: MIT
entity:
  mass: 8
  volume: 4
experiments:
  - actuatorIdentifier: custom_experiments
    experimentIdentifier: calculate_density

Run it with:

run_experiment examples/density_example/point.yaml

You should see output similar to:

Point: {'mass': 8, 'volume': 4}
Result:
[
  ...
  density 2.0
]

Tip

run_experiment is a lightweight testing tool — results are not tracked or stored anywhere. It is purely for quick feedback during development. See Running experiments on single entities for details.

Step 3 — Define a discovery space

A discovery space brings together two things:

  • an entity space — the set of points (entities) to measure
  • a measurement space — the experiments to apply to them

The file examples/density_example/space.yaml defines a grid of ten masses and ten volumes:

# Copyright IBM Corporation 2025, 2026
# SPDX-License-Identifier: MIT
sampleStoreIdentifier: default
entitySpace:
  - identifier: mass
    propertyDomain:
      variableType: DISCRETE_VARIABLE_TYPE
      values: [1.0, 2.5, 5.0, 10.0, 25.0, 50.0, 100.0, 250.0, 500.0, 1000.0]
  - identifier: volume
    propertyDomain:
      variableType: DISCRETE_VARIABLE_TYPE
      values: [0.5, 1.0, 2.0, 5.0, 10.0, 20.0, 50.0, 100.0, 250.0, 500.0]
experiments:
  - actuatorIdentifier: custom_experiments
    experimentIdentifier: calculate_density
metadata:
  name: density_space
  description: Entity space over mass and volume for density calculation.

The entity space is 10 × 10 = 100 entities (every combination of mass and volume). The measurement space contains a single experiment: calculate_density.

Create the discovery space:

ado create space -f examples/density_example/space.yaml

Success! Created space with identifier: $DISCOVERY_SPACE_IDENTIFIER

Inspect it to confirm everything looks right:

ado describe space --use-latest

The output shows the entity space dimensions and the experiment interface:

Entity Space:

   Number of entities: 100

   Discrete properties:

      name   ┃ range ┃ interval ┃ values
     ━━━━━━━━╋━━━━━━━╋━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
      mass   ┃ None  ┃ None     ┃ [1.0, 2.5, 5.0, 10.0, 25.0, 50.0, ...]
      volume ┃ None  ┃ None     ┃ [0.5, 1.0, 2.0, 5.0, 10.0, 20.0, ...]


Measurement Space:

   Experiments:

      base identifier                         ┃ required major version ┃ parameterization
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━
      custom_experiments.calculate_density    ┃ None                   ┃ None

Step 4 — Run an operation

An operation drives an operator over the discovery space. The operator decides which entities to visit and in what order. Here we use random_walk, which samples entities at random.

The file examples/density_example/operation.yaml configures a random walk that visits 10 of the 100 entities:

# Copyright IBM Corporation 2025, 2026
# SPDX-License-Identifier: MIT
spaces:
  - space-0dac6d-default
operation:
  module:
    operatorName: random_walk
    operationType: explore
  parameters:
    numberEntities: 10
    batchSize: 5
    samplerConfig:
      samplerType: generator
      mode: random
actuatorConfigurationIdentifiers: []
metadata:
  name: density_operation
  description: Random walk exploration of the density space.

Create the operation:

ado create operation -f examples/density_example/operation.yaml --use-latest space

Tip

The spaces: field contains a real space identifier used during development of this example. The --use-latest space flag replaces it with the identifier of the discovery space you just created.

ado samples and measures entities, printing a line for each one as it completes. When finished you will see a summary like:

identifier: random_walk@2.0.0-a1b2c3
kind: operation
metadata:
  entities_submitted: 10
  experiments_requested: 10
status:
  - event: finished
    exit_state: success
    recorded_at: "2026-01-01T12:00:00.000000Z"

Step 5 — View the results

ado show measurements operation --use-latest

This prints every entity sampled in the operation alongside its measured density (some columns have been hidden for simplicity):

┌───────────────┬──────────────┬──────────────────────────┬──────────┬────────┬────────────────────┬───────┐
│ request_index │ result_index │ identifier               │ mass     │ volume │ density            │ valid │
├───────────────┼──────────────┼──────────────────────────┼──────────┼────────┼────────────────────┼───────┤
│ 0             │ 0            │ mass.1.0-volume.0.5      │ 1.0      │ 0.5    │ 2.0                │ True  │
│ 1             │ 0            │ mass.50.0-volume.5.0     │ 50.0     │ 5.0    │ 10.0               │ True  │
│ ...           │ ...          │ ...                      │ ...      │ ...    │ ...                │ ...   │
└───────────────┴──────────────┴──────────────────────────┴──────────┴────────┴────────────────────┴───────┘

To see measured results aggregated back onto the full space (not just the entities visited in this operation):

ado show measurements space --use-latest

Try it again

Run the operation a second time. Because ado memoizes results, measurements already in the sample store are reused automatically — no duplicate computation.

Summary

Step What you did ado concept
1 Ran a pre-built custom experiment that computes density Custom experiment
2 Verified it on one point with run_experiment Point testing
3 Described the space of things to measure in space.yaml Discovery space
4 Ran a random walk over 10 of the 100 entities Operation / operator
5 Retrieved the measured results ado show measurements

What's next