run-scripts

Run script conventions

When creating or editing run_*.sh or run_*.py under any model's examples/ directory:

Required patterns

1. Env-var defaults — Every user-configurable parameter must be overridable via an environment variable with a sensible default:

   SC_STEPS="${SC_STEPS:-6}"
   

   steps = int(os.environ.get("SC_STEPS", "6"))
   

2. Config summary — Print all effective settings before the main run:

   echo "=== Configuration ==="
   echo "  Steps:  $SC_STEPS"
   echo "  Output: $SC_OUTPUT"
   

3. Fail on missing required inputs — If a variable is required (no default), exit with a clear message:

   : "${ORBIT2_ROOT:?Set ORBIT2_ROOT to the ORBIT-2 clone directory}"
   

4. No site-specific paths — including in defaults — Paths to checkpoints, data, and output directories must come from env vars. Critically, the default values for those env vars must also be free of site-specific paths (usernames, cluster-specific mount points like /shared/username, /scratch/...). This is the most common mistake: the logic is portable, but a site-specific path is baked into the default.

   Wrong:

   SC_OUTPUT="${SC_OUTPUT:-/shared/username/models/StormCast/outputs/pred.zarr}"
   

   Right — derive from a user-set base, or require the user to set it:

   # Option A: derive from AI4S_SHARED_DIR (user sets this for their site)
   SC_OUTPUT="${SC_OUTPUT:-${AI4S_SHARED_DIR:-}/models/StormCast/outputs/pred.zarr}"
   
   # Option B: no default — require it
   : "${SC_OUTPUT:?Set SC_OUTPUT to your desired output path}"
   

5. Shebang line — Shell scripts: #!/usr/bin/env bash with set -euo pipefail. Python scripts: #!/usr/bin/env python3.

6. chmod +x — All scripts must be executable.

Naming

• Use the model's env-var prefix consistently (e.g. SC_* for StormCast, ORBIT2_* for ORBIT-2, MG_* or bare names for MatterGen).
• Name scripts run_<task>.sh or run_<task>.py where task is inference, train, ensemble, generation, etc.