Sweeps

A sweep expands one base runspec_v8 input into related parameter variants. Use it when the engineering question is comparative and every case should share the same model structure.

Use a batch instead when the cases are independently authored RunSpecs.

Define The Variants

The top-level sweep block supports:

• cartesian: the product of ordered value lists
• cases: an explicit sparse list of override patches

sweep:
  mode: cartesian
  dimensions:
    - path: constellation.design.orbit.altitude_km
      values: [500, 550, 600]
    - path: runtime.seed
      values: [11, 22]
  summary:
    fields:
      - coverage.union_coverage_fraction
    write_csv: true

Override paths address fields in the base RunSpec. Review the fully expanded plan before executing a large matrix. astraeus run rejects an active sweep block so that a multi-case input cannot accidentally run as one case.

Plan, Then Run

The curated altitude study is a useful baseline:

astraeus sweep plan astraeus-resources/examples/user/altitude-trade-sweep.yaml

Planning validates every expansion, materializes canonical child RunSpecs, and prints the path to sweep_plan.json without executing cases.

Execute it with bounded local workers:

astraeus sweep run astraeus-resources/examples/user/altitude-trade-sweep.yaml --workers 2

Serial execution is the default. Increase --workers only after considering the per-case memory footprint; workers run isolated child processes.

Useful planning and execution options are:

Option	Purpose
--sweep-id <id>	Choose the grouped bundle name.
--output-root <path>	Change the default runs/sweeps root.
--profile-root <path>	Resolve imported profiles from a stable root.
--max-cases <n>	Record and print a soft warning above the chosen case count.
--workers <n>	Set bounded local concurrency.
--write-summary-csv	Add a tabular export beside the JSON summary.

--max-cases sets a warning threshold; execution may continue above it.

Results And Exit Behavior

The grouped bundle contains:

runs/sweeps/<sweep_id>/
|-- base_runspec.json
|-- sweep_plan.json
|-- sweep_attempts.json
|-- sweep_results.json
|-- sweep_summary.json
|-- sweep_summary.csv
`-- cases/<case_id>/
    |-- runspec.json
    `-- attempts/<attempt_id>/
        `-- <standard run artifacts>

The CSV is optional; the JSON summary is the contract. Read the plan first, then current results, attempt history, comparison summary, and only then individual child bundles.

Successful child attempts are preserved when a sibling fails. Mixed outcomes produce grouped artifacts with partial_success and command exit code 4; exit code 0 means every current case succeeded.

Resume And Rerun

Recovery operates on the existing grouped bundle, not the original RunSpec:

astraeus sweep resume runs/sweeps/<sweep_id>
astraeus sweep resume runs/sweeps/<sweep_id> --retry-failed
astraeus sweep rerun runs/sweeps/<sweep_id> --failed
astraeus sweep rerun runs/sweeps/<sweep_id> --case <case_id>
astraeus sweep rerun runs/sweeps/<sweep_id> --all

resume selects incomplete current cases. --retry-failed includes failed cases. rerun deliberately creates a new attempt for the selected failed, named, or complete case set. --workers is available on recovery commands too.

Always compare the current/latest result view with attempt history when a case has been rerun.

See Understanding outputs for the common child-run contract.