Python API#

cloudai.api lets a Python program validate or run a scenario and find its saved results. Prepare the Fio environment from Run your first experiment first. For integration patterns, see Automate experiments. Pass configuration file paths as pathlib.Path objects:

from pathlib import Path

import cloudai.api

system = Path("standalone.toml")
scenario = Path("conf/experimental/quickstart/fio.toml")

cloudai.api.validate_scenario(scenario, system)
experiment = cloudai.api.run_experiment(scenario, system)
print(experiment.status, experiment.path)

Validate a scenario#

validate_scenario(scenario, system) performs the same configuration loading checks as execution.

  • Returns None on success; raises configuration errors on failure.

  • Creates no runner, installs no dependencies, and submits no jobs.

  • Accepts tests_dir for referenced definitions and hook_dir for custom hooks.

  • Does not check cluster availability or guarantee workload success.

Run an experiment#

run_experiment(scenario, system) waits for completion and returns an Experiment with the data saved in experiment.json.

  • Workload failures appear in the experiment status.

  • Configuration and setup errors raise exceptions.

  • on_start receives the initial experiment and cancellation function after the result file is created, before execution begins.

  • Execution remains synchronous after the callback.

Option

Use

mode="dry-run"

Generate commands without running workloads.

single_sbatch=True

Execute through one Slurm allocation.

hook_dir

Select a custom hook directory.

on_start

Connect experiment startup and cancellation to your application.

Find saved experiments#

Call

Result

Errors or omissions

list_experiments(system)

(experiment_id, result_directory) pairs in the configured output directory.

Skips directories without experiment.json; a missing output directory returns an empty list. File contents are not parsed.

get_experiment(experiment_id, system)

An Experiment loaded from the system output directory.

Invalid IDs and missing, unreadable, or malformed files raise ValueError.

get_experiment(Path(...))

An Experiment loaded directly from a result directory.

The same file validation applies.