Run a simulation
What you will accomplish
A propagated timeline and the exports that follow from it, with a step size chosen for the question rather than left at its default.
Prerequisites
- A constellation.
Steps
Propagate
orbitforge simulate \
--constellation ph1.json \
--duration-hours 24 --step-seconds 300 \
--model j2Simulated 60 satellites over 24.0 h at 300 s steps (289 samples each) using j2.289 samples is 288 steps of 300 seconds across 24 hours, plus the closing endpoint.
Export what the recipient needs
orbitforge simulate \
--constellation ph1.json \
--duration-hours 24 --step-seconds 300 --model j2 \
--czml view.czml \
--oem trajectory.oemChoosing the step
The step is not a quality setting. It is a statement about what you intend to resolve.
| Question | Step |
|---|---|
| Watch it move on a globe | 60 to 300 s. The viewer interpolates; the eye cannot tell |
| Coverage gaps of minutes | Well below the shortest gap that matters |
| Pass boundaries for scheduling | 10 s or finer; LEO passes are minutes long |
| Hand a trajectory to another tool | Match what their interpolation needs |
A step too coarse does not produce a visibly worse answer. It produces a confidently wrong one: a gap shorter than the step is invisible, and a pass shorter than the step may never appear at all.
Every downstream analysis inherits this. Coverage, access, and eclipse intervals are all resolved no better than the step you propagated at.
File size scales linearly with step count, and CZML in particular becomes awkward for a browser at fine steps over long windows on a large constellation. Propagate finely for the analysis and export coarsely for the picture.
Choosing the export
| Flag | Format | Send it to |
|---|---|---|
--czml | CZML | The globe viewer, and nothing else |
--oem | CCSDS OEM | Another flight-dynamics tool |
--json | JSON | Your own tooling |
Do not hand CZML to another organization as a trajectory. It is a scene
description: positions in meters, a coarse INERTIAL frame label, and no
time-system declaration.
CCSDS OEM is the interchange format, and the reason is its metadata:
REF_FRAME, TIME_SYSTEM, and span are declared in the file, so the recipient
can reproduce your trajectory rather than approximate it.
Model selection in one line
| Situation | Model |
|---|---|
| Imported from TLE | sgp4, and nothing else is valid |
| Imported from OEM or SP3 | ephemeris, within the table span |
| Designed, quick look | two-body |
| Designed, plane layout over days | j2 |
| Designed, quantitative result | numerical |
Selecting sgp4 or ephemeris on a constellation that lacks the required data
fails immediately and names the satellite, rather than substituting a different
model silently. That is the behavior you want.
Verifying the run
The summary line is the first check. It states the satellite count, window, step, sample count, and model:
Simulated 60 satellites over 24.0 h at 300 s steps (289 samples each) using j2.Confirm the model is the one you asked for. On a numerical run the line expands
to name every active force term, for example
numerical (zonal4+drag+srp+sun+moon, dp54), which is the provenance to record
alongside any number you quote.
Next steps
- High-fidelity runs for force models.
- Coverage and revisit for the analysis this feeds.
- CCSDS OEM and CZML.
main (pre-release)