Mission scenarios

SimulateScenario is the heaviest tool. It runs a full mission simulation in one call:

1. Build a spacecraft from the supplied initial state, mass, engine, optional instruments
2. Optionally chain maneuvers (apogee/perigee/plane/phasing/combined burns, attitude pointings)
3. Numerically propagate under a configurable force model
4. Sample the trajectory at the requested cadence
5. Evaluate geometry constraints against the propagated trajectory
6. Return samples, per-maneuver report, constraint windows, and final state and mass

Nothing is persisted — every call is independent.

See Scenario simulation for the field-by-field reference.

Minimal example — simple LEO propagation

A spacecraft in a 200 km circular LEO, no maneuvers, gravity from Earth, Sun and Moon, one day of propagation:

{
  "window": {
    "start": { "dateTime": "2024-01-01T00:00:00", "kind": "UTC" },
    "end":   { "dateTime": "2024-01-02T00:00:00", "kind": "UTC" }
  },
  "integratorStepSizeSeconds": 10,
  "outputStepSizeSeconds": 60,
  "spacecraft": {
    "initialState": {
      "centerOfMotion": "EARTH",
      "epoch": { "dateTime": "2024-01-01T00:00:00", "kind": "UTC" },
      "frame": "ICRF",
      "position": { "x": 6578000, "y": 0, "z": 0 },
      "velocity": { "x": 0, "y": 7784, "z": 0 }
    },
    "mass": 1000,
    "engine": { "isp": 300, "thrust": 400 },
    "fuelTank": { "capacity": 200, "fuelMass": 200 }
  },
  "forceModel": {
    "perturbingBodies": ["SUN", "MOON"],
    "includeAtmosphericDrag": false,
    "includeSolarRadiationPressure": false
  }
}

The centralBody is taken from spacecraft.initialState.centerOfMotion. perturbingBodies are added on top.

With drag, SRP, and a geopotential model

Add the high-fidelity Earth perturbations:

{
  "forceModel": {
    "perturbingBodies": ["SUN", "MOON"],
    "includeAtmosphericDrag": true,
    "includeSolarRadiationPressure": true,
    "geopotentialDegree": 20
  }
}

The Earth geopotential model EGM2008_to70_TideFree is resolved by the server.

Adding maneuvers

maneuverPlan is an ordered list of maneuver specs. The supported kinds are listed in the Scenario reference — apogee, perigee, plane alignment, apsidal alignment, phasing, combined, plus attitude modes (zenith, nadir, prograde, retrograde, normal, anti-normal).

Each maneuver fires when the spacecraft is in the right geometry, modifies the trajectory, and the simulator carries on.

Evaluating geometry constraints inline

Pass a list of geometryConstraints (with id fields) and the response will include, per id, the windows on the propagated trajectory where the constraint holds. This is the right place to evaluate constraints that depend on the spacecraft trajectory — the Find*Constraint tools operate on SPICE-backed items only, not on a propagated spacecraft.

Reading the response

• trajectorySamples — list of state vectors at outputStepSizeSeconds cadence (ICRF, observer = central body)
• maneuverReport — for each maneuver: kind, maneuver window, thrust window, Δv vector, fuel burned
• constraintWindows — dictionary keyed by ConstraintSpec.id
• finalState — state at window.end
• finalMass — total mass at window.end

Performance hints

• The integrator step (integratorStepSizeSeconds) controls accuracy and cost. For LEO, 10 s is reasonable; for GEO, 60 s; for cislunar, 300 s.
• outputStepSizeSeconds only controls the sampling cadence of the returned trajectory — it does not affect the integrator. Pick the coarsest one that still gives you the shape you need.
• A long window with many perturbations and many sampling points produces a large response. If you only care about the endpoint, set outputStepSizeSeconds close to the full window length.