Skip to content

Running Simulations

Execute one RunSpec with:

astraeus run <runspec.yaml>

Core runs default to runs/core/<run_id>/. Provide a deliberate run ID for human-reviewed studies; otherwise Astraeus derives a deterministic identifier from the normalized input.

flowchart LR EDIT["Edit RunSpec"] --> DRY["Dry run"] DRY --> RUN["Named execution"] RUN --> HEALTH["Manifest and metrics"] HEALTH --> DETAIL["Detailed artifacts and views"]

Validate without executing stages:

astraeus run study.yaml --dry-run

Execute after validation:

astraeus run study.yaml --run-id study-baseline

Treat dry-run success as input and plan validation, not scientific validation of the result. Full execution can still encounter resource limits or model-specific conditions.

For runs with memory or population preflight, the dry-run output also reports the projected peak, the configured threshold, the policy result, and practical recommendations. Compare that estimate with currently available memory and keep operating-system headroom. The estimate follows the resolved workload shape; worker concurrency and changes to duration, cadence, grids, output detail, or transport configuration can change the execution envelope. The large-scale showcases include measured examples of this comparison.

Common Options

Option Purpose
--dry-run Validate and resolve the RunSpec without executing stages.
--strict Convert otherwise nonfatal validation warnings into failures.
--run-id <id> Choose a stable run-directory name.
--output-root <path> Change the core run root from runs/core.
--profile-root <path> Supply a stable root for layered imports.
--seed <integer> Override the RunSpec seed for a controlled variant.

Examples:

astraeus run study.yaml --strict --run-id study-baseline
astraeus run study.yaml --output-root studies/project-a/runs --run-id baseline
astraeus run study.yaml --profile-root astraeus-resources/examples/user

Run Identity And Reproducibility

The bundle name is selected in this order:

  1. CLI --run-id
  2. runtime.run_id in the RunSpec
  3. a deterministic rs-<hash> identifier

Use names that encode the comparison role rather than every input value, such as service-baseline, higher-elevation-mask, or battery-600wh. The canonical RunSpec and manifest preserve the exact values.

For a defensible comparison:

  • begin from one reviewed baseline
  • change only the intended assumptions
  • control the runtime seed
  • keep output-detail settings consistent
  • compare canonical inputs as well as metrics

Grouped Studies

Use separate commands when the study contains more than one case:

Need Surface
Related variants derived from one RunSpec Sweep
Independently authored RunSpecs executed together Batch

Both surfaces preserve grouped plans, attempt history, current results, summaries, and child run bundles. Use them whenever grouped recovery and comparison provenance matter.

Optional Notifications

Core runs, sweeps, batches, and campaigns can send best-effort lifecycle notifications through an ntfy endpoint. Configure either a complete topic URL:

ASTRAEUS_NOTIFY_NTFY_URL=https://<server>/<topic>

or server and topic separately:

ASTRAEUS_NOTIFY_NTFY_SERVER=https://<server>
ASTRAEUS_NOTIFY_NTFY_TOPIC=<topic>

ASTRAEUS_NOTIFY_ON selects started, success, failure, all, or a comma-separated combination. ASTRAEUS_NOTIFY_NTFY_TOKEN supplies a bearer token for private topics. Notification delivery is best-effort and independent of the run result and command exit behavior.

When A Run Fails

  1. Read the CLI error and run_manifest.json when a bundle was created.
  2. Confirm the canonical RunSpec and resolved stage plan.
  3. Compare against the nearest bundled example.
  4. Reduce duration, cadence density, or constellation scale only to isolate the issue; retain the original-scale case as the engineering evidence.
  5. Use Run Monitor for long-running progress and resource context.

Import failures normally indicate a path relative to the wrong RunSpec or profile root. Model failures should be investigated through that model's summary and limitations rather than by suppressing warnings.

Next: Understanding outputs.