RunSpec Reference¶
runspec_v8 is the supported input contract for one core simulation. YAML
is the normal authoring format; JSON is also accepted. Astraeus resolves imports
and profiles, validates the result, and writes the canonical expanded input into
the run bundle.
Required Shape¶
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
The required top-level fields are schema_version, execution, simulation,
and constellation.
Top-Level Blocks¶
| Block | Required | Purpose |
|---|---|---|
schema_version |
Yes | Contract selector; must be runspec_v8 |
simulation |
Yes | Time window, cadence, propagator, and state frame |
execution |
Yes | Requested public engineering stages |
constellation |
Yes | One synthesized design, explicit population, or multiple shells |
ground |
No | Ground sites and terminal infrastructure |
geography |
No | Coverage grids, regions, areas, and spatial selection |
mission |
No | Service or observation intent |
transport |
No | Links, gateways, beams, scheduling, routing, and ISLs |
adcs |
No | Commanded attitude and finite-slew realization |
power |
No | Generation, storage, loads, coupling, and sizing variants |
mass |
No | Spacecraft mass assumptions used by applicable models |
propulsion |
No | Burn definitions and propulsion configuration |
imports |
No | Layered YAML inputs |
component_profiles |
No | Reusable typed profile definitions, normally imported |
profiles |
No | Shared model profiles such as ADCS mobility envelopes |
artifacts |
No | Artifact detail and model-specific output controls |
runtime |
No | Reproducibility, output, preflight, and execution controls |
sweep |
No | Related variants derived from this base RunSpec |
extensions |
No | Reserved configuration for internal compatibility; stable user plug-ins are planned for a later release |
Unknown fields or incompatible combinations fail schema or semantic validation. Start from the closest copied example so dependent blocks remain coherent.
Simulation And Execution¶
simulation requires:
| Field | Contract |
|---|---|
start_utc |
ISO-8601 timestamp with an explicit time zone |
duration_s |
Positive integer duration |
step_s |
Positive integer sampling step |
propagator |
Optional auto or sgp4; both select the supported SGP4 path |
frame |
Optional; current propagated-state frame is TEME |
execution.stages accepts:
propagation, ground_access, coverage, attitude,
mission, transport, propulsion, power
Astraeus resolves the required upstream stage closure and records requested and resolved stages in the manifest. Only configuration blocks owned by stages in the resolved plan participate in execution.
execution.variant accepts baseline, validation, dual_antenna, or
steered. Prefer explicit model configuration over relying on a variant label
for a substantive study.
Runtime Controls¶
Common runtime fields are:
| Field | Values or purpose |
|---|---|
run_id |
Output directory identifier |
output_root |
Core-run root override |
seed |
Deterministic seed |
strict |
Fail on warnings when true |
profiling_level |
basic or detailed |
execution_profile |
default or large_sparse_exact |
memory_preflight_policy |
off, warn, or fail |
population_preflight_policy |
off, warn, or fail |
max_memory_fraction_of_available |
Fractional memory threshold in (0, 1] |
max_memory_gb |
Absolute memory threshold |
population_preflight_max_* |
Explicit population/cell/point-step limits |
transport_execution_mode |
dense_full, windowed, auto_adapt, or streaming_exact |
transport_window_steps |
Positive window size for applicable transport modes |
large_sparse_exact is intended for large exact routed-ISL studies. It applies
sparse/streaming-oriented defaults and rejects unsafe dense or materialized
combinations. Runtime and memory preflight estimates are safeguards, not
guaranteed peak-memory predictions.
Constellation¶
The normal single-shell form uses constellation.design:
| Field | Supported values |
|---|---|
design.kind |
walker, streets_of_coverage, explicit |
design.orbit.kind |
circular_altitude, keplerian |
design.layout |
Kind-specific plane, slot, phasing, and spacing controls |
Walker layouts normally define n_planes and n_sats_per_plane, with optional
RAAN spread, Walker factor, anomaly behavior, and seed. Streets-of-Coverage
layouts additionally define the requested geometric coverage_fold and
minimum elevation. Explicit layouts define planes and their satellite counts,
RAANs, and initial anomaly.
Use constellation.shells for a multi-shell population. Each entry has a unique
shell_id, an independent design, and an optional shell-local satellite cap.
The single-shell design form and multi-shell shells form are mutually
exclusive.
The canonical materialized population and shell metadata are written to:
config/resolved_constellation_layout.json
See Geometry And Coverage for orbit, constellation-synthesis, frame, and aggregation semantics.
Ground And Geography¶
ground defines sites, gateways, and applicable elevation settings.
geography defines grids, area selections, inline regions, coverage scope, and
spatial aggregation controls.
geography.coverage_folds requests the sampled fraction with at least each
listed number of geometrically visible satellites. It is distinct from
constellation.design.layout.coverage_fold, which helps synthesize a
Streets-of-Coverage design.
Geographic grids, masks, cadence, and aggregation choices materially affect the result. Record them as engineering assumptions rather than treating defaults as universal truth.
Mission And Transport¶
mission.kind is service or observe:
| Kind | Primary configuration |
|---|---|
service |
service points or population cohorts, demand, terminal profiles, and service KPIs |
observe |
target areas, sensor profiles, collection rules, products, and delivery |
transport holds the shared data-movement model. Its main areas are scheduler
and capacity policy, user and gateway links, beams and targeting, Earth-fixed
cells and beam hopping, inter-satellite links, and routing.
These blocks have intentionally deep model-specific contracts. Use their engineering pages rather than copying isolated fields from an unrelated case:
- Communications And Service
- Protocol-Informed Beam Hopping
- Native Earth-Fixed-Cell Grids
- Inter-Satellite Links
- Mission Types
Spacecraft Blocks¶
| Block | Scope |
|---|---|
adcs |
default pointing mode, optional finite-slew envelope, and coupling into communications, payload, and power |
power |
panels, battery, static and activity-driven loads, RF-derived equipment, and bounded sizing variants |
propulsion |
finite or impulsive burn definitions, state changes, mass and propellant accounting |
mass |
supporting mass assumptions used by applicable propulsion or spacecraft calculations |
Model-specific assumptions and outputs are documented under Attitude, Power, and Propulsion.
Imports And Component Profiles¶
Imports are resolved relative to the authored RunSpec unless --profile-root
selects another stable root:
imports:
- profiles/communications.yaml
- profiles/spacecraft.yaml
Imported mappings are layered before final validation. A local field overrides an imported scalar or mapping value; lists replace as complete values.
Selected blocks may use a typed component_profile reference. Current profile
kinds cover user terminals, gateways, schedulers, ISLs, beams, batteries,
payload power, and non-link activity coupling. The profile payload supplies the
base block and inline fields override it.
The canonical runspec.json contains expanded concrete values. Profile
selection and provenance are recorded separately in:
config/component_profile_resolution.json
Unknown profiles, kind/path mismatches, and duplicate definitions fail validation.
Sweep Declaration¶
A top-level sweep turns one base RunSpec into a grouped study:
sweep:
mode: cartesian
dimensions:
- path: constellation.design.orbit.altitude_km
values: [500, 550, 600]
summary:
fields: [coverage.global_mean_coverage_fraction]
write_csv: true
| Field | Contract |
|---|---|
mode |
cartesian or cases |
dimensions |
Ordered path plus non-empty values entries for cartesian expansion |
cases |
Ordered explicit override mappings for sparse case mode |
summary.fields |
Requested comparison fields |
summary.write_csv |
Optional CSV companion |
The expander cannot override contract and workflow identity fields such as
schema_version, imports, the sweep declaration, stage selection, mission
kind, run id, or output root. Execute a sweep with astraeus sweep, not
astraeus run.
Artifact Controls¶
artifacts.detail accepts summary, standard, or full_debug. Individual
models also expose focused output flags for raw samples or additional tables.
Use summary or standard output first; detailed transport, state, and spatial
artifacts can dominate runtime and storage at large scale.
Validation And Canonicalization¶
astraeus run <runspec.yaml> --dry-run
Validation covers schema, import and profile resolution, semantic constraints,
stage compatibility, execution planning, and configured preflight policies.
--strict converts warnings into failures.
After execution, review these forms:
| Artifact | Meaning |
|---|---|
runspec.json |
Canonical expanded input associated with the run |
runspec/runspec_execution.json |
Execution-normalized form |
run_manifest.json |
Product version, hashes, stages, warnings, and artifact inventory |
For a runnable baseline for each major capability, use Examples.
Schema-version support across supplied product releases is defined under Compatibility And Upgrades.