RunSpec Basics

A RunSpec is the authoritative user input for one Astraeus simulation. YAML is normally easiest to author; JSON is also accepted. The current supported contract is runspec_v8.

Minimum Useful RunSpec

schema_version: runspec_v8
execution:
  stages: [propagation]
simulation:
  start_utc: "2026-03-01T00:00:00+00:00"
  duration_s: 5400
  step_s: 60
constellation:
  base_name: FIRST-ORBIT
  base_norad_id: 81000
  design:
    kind: walker
    orbit:
      kind: circular_altitude
      altitude_km: 550
      inclination_deg: 53
    layout:
      n_planes: 2
      n_sats_per_plane: 3
runtime:
  seed: 101

Main Blocks

Block	Role
schema_version	Selects the input contract.
execution	Requests the public engineering stages.
simulation	Defines time window, cadence, and propagation settings.
constellation	Defines one or more orbital shells or explicit satellites.
ground and geography	Defines sites, regions, grids, and target geometry.
mission	Defines service or observation intent.
transport	Defines links, gateways, scheduling, beams, routing, and ISLs.
adcs, power, propulsion	Configures spacecraft engineering models.
imports and component_profiles	Reuses shared configuration.
artifacts	Requests optional detailed outputs.
runtime	Sets reproducibility and output controls.
sweep	Expands the base input into a bounded related study.

The public stages are:

• propagation
• ground_access
• coverage
• attitude
• mission
• transport
• propulsion
• power

Astraeus resolves dependencies between requested stages and records the executed plan in the run manifest. Configuration blocks that are irrelevant to the active plan may produce warnings. Prefer the smallest coherent stage set that answers the question.

Constellation Forms

constellation.design defines one synthesized constellation. Its key choices are:

• design.kind: walker, streets_of_coverage, or explicit
• design.orbit: circular-altitude or Keplerian orbit definition
• design.layout: plane, phasing, and kind-specific layout controls

Use constellation.shells for a multi-shell design. Each shell has a shell_id and its own design. The resolved materialized population is written to config/resolved_constellation_layout.json.

Mission And Model Composition

mission.kind is either service or observe. Mission configuration normally works with transport, geography, ground infrastructure, and optional spacecraft models. See Mission types before composing these blocks.

Engineering pages define model-specific inputs and assumptions:

• Geometry and coverage
• Communications and service
• Inter-satellite links
• Attitude
• Power
• Propulsion

Reuse And Expansion

imports layer shared YAML into the RunSpec. Component profiles provide reusable, typed defaults for selected mission, transport, and power blocks. Inline values override the chosen component profile; Astraeus writes the expanded canonical input and profile-resolution provenance to the run bundle.

A top-level sweep keeps one base RunSpec while declaring related parameter variants. Run it through astraeus sweep, not astraeus run.

Validate Before Execution

astraeus run <runspec.yaml> --dry-run

Use --strict when warnings should fail the command. Validation checks the schema, imported configuration, stage compatibility, and execution plan without performing the requested engineering calculations.

For exact fields and constraints, use the RunSpec reference. Next, read Authoring RunSpecs.