Python API
cloudai.api lets a Python program validate or run a scenario and find its saved results. Pass configuration file paths as pathlib.Path objects:
validate_scenario performs the same configuration loading checks as run_experiment. It returns None on success and raises configuration errors on failure, without creating a runner, installing dependencies, or submitting jobs. Pass tests_dir for referenced test definitions and hook_dir for custom hooks, as with run_experiment. Validation does not check cluster availability or whether a workload will run successfully.
run_experiment waits for the scenario to finish and returns an Experiment model with the same data saved in experiment.json. Workload failures appear in its status. Configuration and setup errors raise exceptions. Use mode="dry-run" to generate commands without running workloads. Use single_sbatch=True for a single Slurm allocation. Pass hook_dir to use a custom hook directory. Pass an on_start callback to receive the initial Experiment and a cancellation function after experiment.json is created and before execution begins. The function remains synchronous after calling the callback.
list_experiments(system) returns (experiment_id, result_directory) pairs from the system’s configured output directory. Directories without experiment.json are skipped. A missing output directory gives an empty list; experiment file contents are not parsed.
get_experiment(experiment_id, system) loads an Experiment from that system’s output directory. Pass a Path to a result directory to load it directly. Invalid IDs and missing, unreadable, or malformed experiment files raise ValueError.