Orbit determination runs¶
A run fits the orbit to the fixes of an arc and predicts it for the day after.
run = client.runs.request(satellite, "2026-10-01T00:00:00Z", "2026-10-02T00:00:00Z")
run = run.wait() # RunFailed if it failed, WaitTimeout if it takes too long
client.runs.list(satellite) # newest first
client.runs.get(run.id)
The arc is between 3 and 72 hours; a day is a good choice. A run is queued, then
running, then succeeded or failed; a day of data takes about ten seconds.
Reading a run¶
print(run.status, run.accepted, run.weighted_rms, run.flags)
print(run.arc_start, run.arc_end, run.mass_kg)
run.download("oem", "orbits/") # oem, uncertainty, residuals, result
run.report("reports/") # the run as one HTML page with its charts
run.raw["fixes"] # anything of the API's answer not modelled
accepted tells you whether the run can be trusted without a closer look. It compares
figures of the run with fixed limits of its profile: how well the orbit fits the fixes, how
many fixes were left out as outliers, how many iterations were needed and the longest gap
in the data. A run that is not accepted still has its products. Look at its residuals
before you use its orbit: an unreported manoeuvre or wrong spacecraft properties are the
usual causes.
weighted_rms is the fit’s residuals over the sigma the fixes were weighted with: near
1 is right.
flags list what deserves a look in a run that passed:
possible_unmodelled_manoeuvre: the small accelerations the service estimates every half hour, to take up what its force model lacks, came out many times larger than expected somewhere in the arc. Something pushed the satellite that the model does not know: most often a burn nobody reported, sometimes a geomagnetic storm. The flag (inrun.raw) gives its span andequivalent_delta_v_m_s, the size of the push as a velocity change. The orbit is usable; report the burn (Manoeuvres and plans) so that later runs model it.prediction_outside_uncertainty: the run’s orbit lies more than three standard deviations from what the run before predicted for the same hours, radially or along the track. The prediction did not foresee something: a burn, a change in the atmosphere. On healthy arcs about one run in eight raises it by chance; a burn raises it by far more.
The run before. A run that shares time with the accepted run before it compares the two
(run.raw["self_check"]): how far that run’s prediction lay from this run’s fitted orbit
1, 6, 12 and 24 hours after its arc, and how far the two fitted orbits lie apart where they
overlap. The diagnostics have the same every five minutes (Diagnostics and trends).
A failed run raises RunFailed from wait(), with the API’s error
code:
Code |
Meaning |
What to do |
|---|---|---|
|
The fixes inside the arc could not be used |
Check the file and the arc |
|
No orbit could be fitted to the fixes |
Check the spacecraft properties and that the arc holds no manoeuvre; try a shorter arc |
|
The fault is ours |
Nothing; we are told. Contact us with the run’s |
A request that cannot be accepted is refused at once (InvalidRequest),
for example when the arc holds no tracking data or the satellite has no properties yet.
Profiles and settings¶
A run is made by a profile, the kind of determination on offer. The default,
leo-gnss-v4, suits most satellites in low orbit as it is: the drag coefficient estimated
in steps over the arc, small empirical accelerations every half hour, and a predicted
uncertainty that holds the atmosphere’s error (measured against ESA’s precise orbits of
Swarm: about two thirds of the prediction’s errors within one standard deviation, all but a
few within three).
for profile in client.profiles():
print(profile.name, profile.default, profile.description)
print(" settings:", ", ".join(profile.settings))
Each profile offers named settings: the same determination with one thing changed, such
as segments-60min (the empirical accelerations per hour, not per half hour), sigma-2m
(the fixes trusted to 2 m, not 1 m) or no-empirical. Name one in a run or a schedule:
client.runs.request(satellite, arc_start, arc_end, setting="segments-60min")
client.runs.request(satellite, arc_start, arc_end, profile="leo-gnss-v3")
To find out whether a setting suits your satellite better, compare them over the same arc (Comparing settings).
Custom settings¶
Where a named setting is not enough, an expert chooses the estimation’s figures, in place of
a setting. It is a feature of your tier (od_custom_settings in client.me().features;
without it FeatureNotIncluded). What is left out stays the profile’s.
default = next(p for p in client.profiles() if p.default)
for setting in default.custom_settings:
print(setting.name, setting.value, setting.minimum, setting.maximum)
run = client.runs.request(
satellite,
arc_start,
arc_end,
custom={"segment_minutes": 45, "along_track_sigma_m_s2": 5e-9, "gravity_degree": 90},
).wait()
print(run.setting, run.custom) # "custom", the settings given
Setting |
Meaning |
|---|---|
|
Length of the segments of the empirical accelerations (5 to 720) |
|
Standard deviation the fixes are weighted with, per axis |
|
One fix is used per this many seconds (1 to 600) |
|
Whether along-track and cross-track empirical accelerations are estimated |
|
Their a priori standard deviations |
|
A priori standard deviation of the drag coefficient, around your properties’ value; left out: free |
|
The drag coefficient estimated in steps of this length (1 to 72 hours) instead of once for the arc; steps shorter than about two orbits predict worse |
|
Which components of the antenna offset are refined: |
|
Editing threshold k; 0: no fix is left out |
|
Length of the predicted ephemeris (1 to 72) |
|
Uncertainty of the drag coefficient added to the predicted covariance |
|
The same as a share of the predicted drag coefficient (0.075 in |
|
k: the ephemeris’s formal standard deviations are multiplied by it |
|
Degree and order of the gravity field (2 to 120) |
A value outside a setting’s limits is refused. A run made this way shows "custom" as its
setting and is judged by the profile’s acceptance limits like any other.