Authoring RunSpecs¶

Start from the closest bundled example and change one engineering assumption at a time. This is faster to review than assembling a large RunSpec from unrelated snippets.

Copy The Supported Baselines¶

astraeus resources copy astraeus-resources

The curated example catalog is under astraeus-resources/examples/user/. Relevant starting points include:

Question	Example
Orbit evolution	`first-orbit.yaml`
Ground contact windows	`ground-access.yaml`
Regional point and area-weighted coverage	`regional-coverage.yaml`
Service through gateways	`service-downlink.yaml`
Steered beams or beam hopping	`steered-multibeam.yaml` or `beam-hopping-capacity.yaml`
ISL-routed service	`isl-routed-network.yaml`
Observation through delivery	`observation-to-delivery.yaml`
Spacecraft power or sizing	`spacecraft-power-balance.yaml` or `power-sizing.yaml`
Coupled multi-model study	`integrated-constellation-study.yaml`
Related design variants	`altitude-trade-sweep.yaml`
Independent architecture comparison	`architecture-comparison-batch.yaml`

Examples describes the complete catalog and runtime classes.

Recommended Authoring Order¶

flowchart LR Q["Engineering question"] --> STAGES["Smallest stage set"] STAGES --> TIME["Time window and cadence"] TIME --> CONST["Constellation"] CONST --> MODELS["Relevant model blocks"] MODELS --> CHECK["Dry run and inspect"]

1. State The Question¶

Write down the quantity or decision the study must support. A focused question makes the stage set, duration, cadence, output metrics, and comparison cases much clearer.

2. Select The Stages¶

Keep only the stages needed to answer the question. For example, orbit evolution needs propagation; regional service normally needs geometry, mission, and transport; spacecraft energy balance adds power and its required activity drivers.

3. Choose Time And Scale Deliberately¶

Use a short duration, coarse cadence, and smaller constellation while checking the model chain. Refine cadence and increase scale only after the RunSpec and artifact families are correct. A coarse cadence can miss short access or operational events, so the final value must follow the relevant model guidance.

4. Change Inputs In The Owning Block¶

Keep orbit and layout choices under constellation, geographic questions under ground or geography, service or observation intent under mission, network choices under transport, and spacecraft assumptions under their subsystem blocks. This makes provenance and later review much clearer.

5. Request Detailed Artifacts Intentionally¶

Summary artifacts are always the best first inspection point. Enable optional raw samples only when the analysis needs them; detailed timelines and samples can dominate output size for large constellations.

Imports¶

Use imports for shared profiles or layered configuration:

imports:
  - profiles/communications.yaml
  - profiles/spacecraft.yaml

Paths normally resolve relative to the authored RunSpec. When a stable external root is required:

astraeus run study.yaml --profile-root <profile-root>

The run bundle preserves the canonical expanded RunSpec and the relevant source provenance.

Component Profiles¶

Selected blocks can reference a typed component profile:

transport:
  scheduler:
    component_profile: scheduler.gateway_greedy_capacity
    default_offered_load_bps: 12000

power:
  battery:
    component_profile: battery.small_520wh
    soc_init_pct: 72

The profile supplies defaults; fields written beside the reference override them. References fail closed when the profile is missing, has the wrong kind, or is applied to an unsupported block. The executed RunSpec contains concrete expanded fields, while config/component_profile_resolution.json records which profiles supplied them.

Validate, Run, Review¶

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

After execution, inspect run_manifest.json, metrics_summary.json, and the canonical runspec.json before tuning detailed outputs.

Common Mistakes¶

beginning with more stages or scale than the question requires
changing cadence without checking short-event sensitivity
retaining configuration blocks after removing their stage
defining service or observation intent without the required transport and geography context
referencing a component profile without copying or importing its catalog
assuming the Console exposes every advanced RunSpec field
comparing cases that changed several assumptions without recording why

For field-level constraints use the RunSpec reference. Next, read Running simulations.