access-experiment-generator

About

The ACCESS Experiment Generator is a tool for creating ensembles of model experiments from a single control configuration. Instead of manually editing multiple files, you describe changes in one YAML plan, and the generator:

• Clones the configuration repository from GitHub.
• Creates a control branch (with optional edits).
• Creates one new branch per perturbation experiment.
• Applies the parameter changes and commits them.

Each generated branch is immediately Payu-ready — you can step into the branch directory and launch runs on Gadi, NCI using Payu.

Documentation

The ACCESS experient generator documentation can be found at: https://access-experiment-generator.hive-docs.org.au/

Key features

• YAML-driven configuration: define edits once, apply them across many experiments.
• Git-branch workflow: each variant is a branch, making experiments traceable.
• Reproducibility: given the same repo + YAML, identical branches are regenerated.
• Payu integration: generated branches are ready to run on Payu.

Documentation

Full documentation is available at https://access-experiment-generator.access-hive.org.au/

Installation

User setup

The experiment-generator is installed in the payu-dev conda environment:

module use /g/data/vk83/prerelease/modules && module load payu/dev

Alternatively, create a Python virtual environment and install via pip:

python3 -m venv <path/to/venv> --system-site-packages
source <path/to/venv>/bin/activate

pip install experiment-generator

Development setup

For contributors and developers, setup a development environment,

git clone https://github.com/ACCESS-NRI/access-experiment-generator.git
cd access-experiment-generator

# under a virtual environment
pip install -e .

Usage

$ experiment-generator --help

usage: experiment-generator [-h] [-i INPUT_YAML_FILE]

Manage ACCESS experiments using configurable YAML input.
If no YAML file is specified, the tool will look for 'Experiment_generator.yaml' in the current directory.
If that file is missing, you must specify one with -i / --input-yaml-file.

options:
  -h, --help            show this help message and exit
  -i INPUT_YAML_FILE, --input-yaml-file INPUT_YAML_FILE
                        Path to the YAML file specifying parameter values for experiment runs.
                        Defaults to 'Experiment_generator.yaml' if present in the current directory.

Example YAML

An exmaple plan (examples/Experiment_generator_example.yaml)

model_type: access-om2 # Specify the model ("access-om2", "access-om3", "access-esm1.5", or "access-esm1.6")
repository_url: git@github.com:ACCESS-NRI/access-om2-configs.git
start_point: "fce24e3" # Control commit hash for new branches
test_path: prototype-0.1.0 # All control and perturbation experiment repositories will be created here; can be relative, absolute or ~ (user-defined)
repository_directory: 1deg_jra55_ryf # Local directory name for the central repository (user-defined)

control_branch_name: ctrl
keep_uuid: false # Keep a pre-existing UUID. If true, this overrides new_uuid.
new_uuid: false # Generate a fresh UUID for an existing branch. Equivalent to Payu's --new-uuid.

Control_Experiment:
  accessom2.nml:
    date_manager_nml:
      restart_period: "0,0,86400"

  config.yaml:
    queue: express
    walltime: 5:00:00

  ice/cice_in.nml:
    shortwave_nml:
      albicei: 0.05
      albicev: 0.08
    thermo_nml:
      chio: 0.001

Perturbation_Experiment:
  Parameter_block1:
    branches:
      - perturb_1
      - perturb_2

    ice/cice_in.nml:
      shortwave_nml:
        albicei:
          - 0.06
          - 0.07
        albicev:
          - 0.78
          - 0.81
      thermo_nml:
        chio:
          - 0.007
          - 0.008

    ocean/input.nml:
      ocean_nphysics_util_nml:
        agm_closure_length:
          - 25000.0
          - 75000.0

Workflow example

1. Run the generator

experiment-generator -i examples/Experiment_generator_example.yaml

2. Inspect branches

cd my-experiment/1deg_jra55_ryf
git branch
# ctrl
# main
# perturb_1
# perturb_2

3. Check changes

git checkout perturb_1
git diff ctrl -- ice/cice_in.nml