Manoeuvres and plans

Reporting a burn

Tell the service about every burn, before or after it happens:

client.manoeuvres.report(satellite, "2026-10-05T12:12:00Z", along_track_m_s=0.02)
client.manoeuvres.list(satellite)
client.manoeuvres.delete(manoeuvre)  # to correct a report: delete it, then report again

The velocity change is in metres per second along the orbit’s axes: radial_m_s (away from the Earth), along_track_m_s (near the direction of flight) and cross_track_m_s (the orbit’s normal). Give a burn of some length at its middle. sigma_m_s says how well you know each component; without it the service takes 10 % of the burn’s size, at least 1 mm/s.

  • A run whose arc holds the burn determines it. Your report is where the estimate starts; the run’s manoeuvres give the velocity change it found, with its uncertainty.

  • A predicted ephemeris includes a burn you have planned. A burn reported for a time after the arc is applied in the prediction as you reported it, and the predicted uncertainty grows after it by the burn’s sigma_m_s. The run lists it with planned == True. Report planned burns as soon as you know them.

  • Without a report, a burn above about 1.5 cm/s makes the run fail (estimation_failed), and a smaller one shows as a flag (Orbit determination runs).

The mass a burn spends

A satellite that has spent propellant is lighter, so drag and radiation pressure move it more. Say what a burn spent in one of two ways:

# The propellant spent, as your bookkeeping has it (negative: a mass change):
client.manoeuvres.report(
    satellite, "2026-11-18T06:00:00Z", along_track_m_s=0.02, delta_mass_kg=-0.004
)
# Or the thruster's specific impulse: the mass change follows from the velocity change.
client.manoeuvres.report(
    satellite, "2026-11-19T06:00:00Z", along_track_m_s=0.02, specific_impulse_s=220
)

run = client.runs.request(satellite, arc_start, arc_end).wait()
print(run.mass_kg)  # the mass at the arc's start
for burn in run.manoeuvres:
    print(burn.epoch, burn.along_track_m_s, burn.planned, burn.delta_mass_kg, burn.mass_kg)

The mass counts down from the spacecraft properties: a version gives the mass from its valid_from on, and the burns reported after that lower it. If you would rather give the mass yourself, leave the burns’ mass changes out and add new properties after a burn; do not do both for the same burn. A report with neither leaves the mass as it is.

Planning a burn

Ask for the burns that bring the satellite’s mean orbit to a target, from its current orbit, under the same force model as its orbit determination:

plan = client.plans.request(
    satellite,
    semi_major_axis={"delta_m": 150},
    window_start="2026-10-06T00:00:00Z",
    window_end="2026-10-06T12:00:00Z",
).wait()
for burn in plan.burns:
    print(burn.epoch, burn.along_track_m_s)
for target in plan.targets:
    print(target.name, target.before, target.wanted, target.after, target.met, target.sigma)
  • Targets: semi_major_axis (delta_m, a change from the present mean value, or value_m; met within tolerance_m, 1 m by default), eccentricity_vector (ex, ey, or delta_ex, delta_ey: e cos ω and e sin ω of the mean orbit), inclination (delta_deg or value_deg), node and phase (the mean right ascension of the ascending node and the mean argument of latitude at an epoch, in ICRF), ground_track (the geographic longitude of a later ascending node). Mean elements are averaged over a nodal period (elements="analytical": the Eckstein–Ustinov theory instead).

  • Burns: strategy="along_track" (one burn, at the first ascending node in the window, or at argument_of_latitude_deg), "along_track_pair" (two, half a revolution apart; for the eccentricity vector) or "cross_track" (one burn out of the orbit’s plane). The window must begin inside your orbit’s ephemeris; by default it starts at the orbit’s arc end or now, whichever is later, and lasts twelve hours.

  • Uncertainty: each target’s standard deviation after the burns, from your orbit’s at the start, the drag coefficient’s and the burns’ execution.

A plan is advice: your orbit is unchanged by it. To adopt it, report its burns as planned manoeuvres when you command them:

burn = plan.burns[0]
client.manoeuvres.report(satellite, burn.epoch, along_track_m_s=burn.along_track_m_s)