`orbitforge simulate`

Synopsis


orbitforge simulate --constellation <PATH> [OPTIONS]

Description

Advances every satellite in a constellation through time on a fixed step and writes the resulting timeline to the requested export formats.

This is the command that turns a static constellation definition into a trajectory. Coverage, link, and eclipse analysis all consume its output, so the propagation model chosen here determines the fidelity of everything downstream.

Options

Core options. Values shown are the shipped defaults.
Parameter	Type	Unit	Default	Required	Description
`--constellation`	path	n/a	—	Yes	Path to a constellation JSON file, from `constellation walker`, `import-tle`, `import-ephem`, or `design`.
`--start`	string	RFC 3339 UTC	`2026-01-01T00:00:00Z`	No	Scenario start epoch. When propagating imported TLEs, set this to the reference epoch the import reported.
`--duration-hours`	float	h	`6`	No	Length of the propagation window.
`--step-seconds`	float	s	`60`	No	Fixed output step. Sample count is duration divided by step, plus one for the closing endpoint.
`--model`	enum	n/a	`two-body`	No	Propagation model: `two-body`, `j2`, `sgp4`, `numerical`, or `ephemeris`. See the table below.
`--gravity`	string	n/a	`j4`	No	Gravity field for the numerical model: `two-body`, `j2`, `j3`, `j4`, or a spherical-harmonic field as `egm96:DxO`, for example `egm96:16x16`. Degree and order up to 36.
`--drag-cdam`	float	m^2/kg	—	No	Enables drag with this ballistic term, Cd times A over m. Omitted means no drag.
`--atmosphere`	enum	n/a	`exponential`	No	Density model for drag: `exponential`, or `harris-priester` for a table-driven profile with a diurnal bulge.
`--srp-cram`	float	m^2/kg	—	No	Enables cannonball solar radiation pressure with this radiation term, Cr times A over m.
`--third-body`	string	n/a	—	No	Comma-separated third bodies, a subset of `sun`, `moon`, and planet names such as `venus` or `jupiter`.
`--czml`	path	n/a	—	No	Write a CZML document for the 3D globe viewer.

Run orbitforge simulate --help for the complete list, including integrator selection and the remaining export paths.

Propagation models

`--model`	Forces included	Requires
`two-body`	Point-mass Earth only	Nothing
`j2`	Two-body plus secular J2: nodal regression and apsidal rotation	Nothing
`sgp4`	SGP4/SDP4 from each satellite’s source TLE	Satellites imported from TLE
`numerical`	Cowell integration with the configured gravity field, drag, solar radiation pressure, and third bodies	Nothing; force terms are opt-in
`ephemeris`	Interpolation of an imported ephemeris table	Satellites imported from OEM or SP3, and a window inside the table span

sgp4 is only valid for TLE-imported satellites, and ephemeris only within the span the imported table covers. Selecting either on a constellation produced by constellation walker fails rather than silently substituting a different model.

Worked examples

Baseline two-body run


orbitforge constellation walker \
  --name demo --planes 6 --sats-per-plane 10 \
  --altitude-km 550 --inclination-deg 53 --fov-deg 45 \
  --output demo.json
 
orbitforge simulate \
  --constellation demo.json --duration-hours 6 --step-seconds 60 \
  --czml demo.czml


Generated 'demo' with 60 satellites (6 planes x 10 per plane) -> demo.json
Simulated 60 satellites over 6.0 h at 60 s steps (361 samples each) using two_body.
Wrote CZML -> demo.czml

The sample count is 361, which is 360 steps of 60 seconds across 6 hours plus the closing endpoint.

High-fidelity numerical run


orbitforge simulate \
  --constellation demo.json --duration-hours 24 --step-seconds 60 \
  --model numerical --gravity j4 \
  --drag-cdam 0.02 --atmosphere harris-priester \
  --srp-cram 0.02 --third-body sun,moon \
  --czml demo-hifi.czml

Each added force term costs run time. Drag and solar radiation pressure also require a ballistic and a radiation term that describe the actual spacecraft; a guessed value produces a confidently wrong trajectory rather than a warning.

Model basis

Model basis: Numerical Cowell propagation

Assumptions: Cowell formulation integrating the full acceleration in an inertial frame; zonal gravity harmonics to the configured degree and order; cannonball solar radiation pressure with conical shadow scaling; point-mass third bodies from the built-in ephemerides.
Validity range: Earth-orbiting trajectories. Drag terms assume the configured atmosphere model is representative; the exponential profile carries no diurnal or solar-activity variation.
Accuracy: Dominated by force-model and initial-state error, not by integration error, for typical tolerances. Atmospheric density uncertainty of tens of percent maps directly to along-track error that grows with time in drag-dominated regimes.
Reference: Dormand and Prince, a family of embedded Runge-Kutta formulae, Journal of Computational and Applied Mathematics, 1980. EGM96 gravity field coefficients.

Exit behavior

The command exits non-zero and prints a diagnostic to standard error when the constellation file cannot be read or parsed, when a model is selected that the constellation cannot support, or when a requested export path cannot be written.

Partial output is not left behind on failure.

orbitforge simulate