Operation manual

1What this is, and its three limits

GTRE is a trajectory and results explorer that runs entirely in a browser tab. It loads a Monte Carlo ensemble or a results table, plays a long arc back at a rate you can think in, lets you inject a disturbance and solve the correction for it, and lets you write the whole exercise down as a plan and run it.

Three limits govern everything below. None of them is a temporary gap.

2Quick start — first run

You do not need a file. The fastest way to see the tool work is to let it build an ensemble and run the plan it ships with.

1. Open the sandbox. Nothing is loaded; the viewport reads NO ENSEMBLE LOADED.
2. Scroll to Plan console at the bottom. It opens with the CAM rehearsal example already in the editor.
3. Press Run plan (or Ctrl+Enter in the editor).
4. Watch the panels above move while it runs — the plan drives the same controls you would click. It takes about twenty seconds.
5. Read the verdict bar under the transcript. A clean run reports PASS · 8 checks · 8 passed · 0 failed and the time it took.
6. Press Save transcript to write the plan and its output to your disk as one text file.
7. Press Download results — the example records a row per case, so you get a CSV of Δv against burn cost and before/after dispersion. Drop that file back on the page and it plots, because it is written in the same shape the reader parses. See §7.

If you would rather drive it by hand, press Generate ensemble in the Synthesise panel instead, then follow §6.

3The console, panel by panel

Three columns. Data and configuration on the left, the viewport and transport in the middle, operations and readouts on the right. Below them, the plan console. On a narrow screen the columns stack in that order.

Source — left column

Synthesise — build an ensemble with no file

Force model

• J2 oblateness — on by default. It is the dominant perturbation in LEO by two orders of magnitude; a long arc without it is not worth looking at.
• Atmospheric drag — off by default. When on, uses a static piecewise-exponential atmosphere with no solar-activity term. Density at 400 km moves by more than an order of magnitude across a solar cycle, so this gives a plausible shape, not a prediction.
• Ballistic coeff — Cd·A/m in m²/kg. Only active with drag on. Default 0.02.
• Integration step — the step used for disturbance and correction arcs, separately from the synthesis step. Default 20 s.

Disturbance — right column

Correction

Readout and Event log

Readout shows the reference run at the playhead — elapsed time, sample index, altitude, radius, speed, its position vector, and the ensemble’s |Δr| median, p95 and max against the plan. Full arc plays in tells you how long the current rate will take end to end.

Event log is the running commentary: what was loaded, what was measured, and every warning. It is worth reading rather than dismissing — most of the traps in §10 announce themselves here first.

4Loading a file

Drop a CSV on the Source panel. The reader inspects the header and takes one of two shapes. It does not go by the file extension, which says nothing. Columns are matched by name, not position, because every tool orders them differently and reading a velocity into a position slot produces a plausible-looking wrong answer rather than an error.

Shape A — ephemeris

Recognised when x, y, z and a time column are all present.

run,t,x,y,z,vx,vy,vz
0,0.0,6878.000,0.000,0.000,0.000000,7.6127,0.000000
0,3600.0,-6683.4,1560.2,0.0,-1.72808,-7.39942,0.0
1,0.0,6878.140,0.062,-0.031,0.000021,7.6126,0.000004
...

• Time — t, time, time_s, seconds, elapsed, or an ISO-8601 epoch / utc column converted to seconds from the first row.
• Position — x,y,z, rx,ry,rz, pos_x…, with or without a _km / _m suffix. Without one the magnitude decides: an Earth orbit is either ~6.8e3 or ~6.8e6 and there is no third possibility.
• Velocity — vx,vy,vz or x_dot,y_dot,z_dot (the OPM spelling). Optional; if absent it is recovered by central difference and the manifest says so.
• Run — run, case, trial, mc, member. Absent means a single trajectory.

Rows may be grouped by run or by epoch. Runs with a different sample count are linearly resampled onto the longest run’s grid, and the count that needed it appears in the log.

Shape B — series

Anything else. An x column plus any number of named numeric channels — which is what a verification run emits.

step_s,err_rk4,err_order8
600,5.000000e-03,5.000000e-03
300,3.125000e-04,1.953125e-05
150,1.953125e-05,7.629395e-08
...

• The x axis is a time-like column if one is named, otherwise the first column. It may ascend or descend — a convergence sweep is conventionally written with the step size falling.
• A column that is not ordered at all is demoted to the row index, and the log says so.
• A blank or non-numeric cell becomes a break in the line, not a zero. A missing measurement must never read as a measurement of zero.

HDF5

Not readable in this build, and it says so rather than half working. A browser-side HDF5 reader means shipping a ~700 KB WebAssembly build of the C library and adding 'wasm-unsafe-eval' to this page’s script policy — a real weakening of the guarantee in §12. One line converts the file and it stays on your machine:

# pandas, from an HDF5 table to the CSV above
import pandas as pd
pd.read_hdf("ensemble.h5").to_csv("ensemble.csv", index=False)

5Views and transport

Views

• Inertial — Earth, the planned trace and the ensemble at the playhead. Drag to rotate, wheel to zoom. Only about three revolutions of trace are drawn: a 400-day arc is ~6,100 revolutions and the trace would be a solid annulus.
• RIC dispersion — the ensemble in the reference’s rotating frame, in-track horizontal and radial vertical, with 1σ and 3σ ellipses computed from the runs on screen. If the cloud is not Gaussian the ellipse will visibly fail to contain it, which is information.
• Channels — replaces the orbital views when a series file is loaded. Hover anywhere to read every selected channel at that x.

The timeline is the scrub bar

One strip, not two. The question you ask while dragging a playhead across 400 days is how big the error is at that point, so the dispersion envelope (p05–p95 band, median, max, on a log axis) is drawn under the cursor. Injection and correction epochs are marked. Click or drag anywhere on it to seek.

Rate

Expressed as sim-time per wall-second. The slider is continuous; the presets are 1 min : 1 s, 1 hr : 1 s, 1 day : 10 s (the default), 1 day : 1 s and 10 d : 1 s. At the default a 400-day arc plays in 66 minutes, which the full arc plays in readout tells you before you start.

Keyboard

6Running a test by hand

The full disturbance-and-correction exercise, from an empty console. Every step here has a plan-console equivalent in §9.

1. Set the seed before anything else. Everything dispersed downstream derives from it, so changing it later invalidates the comparison you were making.
2. Choose the force model. Leave J2 on. Leave drag off unless you specifically want decay behaviour — with drag off, any orbit decay you then observe is the integrator, which is a useful thing to be able to say.
3. Press Generate ensemble (or drop a CSV). Wait for the manifest. A 400-day, 32-run set takes about six seconds and reports its own throughput.
4. Read the integrator line in the manifest before going further. It should be green. If it is red, stop and fix it — see §10. Every number downstream inherits this.
5. Set the disturbance. Frame, the three components, and the per-axis execution error. Set Inject at day early enough that there is arc left to watch afterwards.
6. Press Inject and propagate. The view switches to RIC dispersion at the injection epoch and the timeline fills with the envelope.
7. Scrub forward and watch the cloud grow. For an in-track disturbance it stretches along track and keeps stretching — that is the physics, not a drawing artefact.
8. Set the correction epoch and horizon, then press Solve correction. Read the status pill: SOLVED, OUT OF REGIME or SINGULAR. Nothing has changed yet.
9. Press Fly it. Both burns are flown if the second-burn box is ticked. The playhead moves to the burn epoch.
10. Compare the |Δr| readouts at the same late epoch, before and after. The honest comparison is at one fixed day, not at whatever the playhead happens to be showing.

7The plan console

Clicking through the panels is fine for one case. A rehearsal is not one case — it is a sweep, run the same way twice, with the outcome written down. The whole plan goes in the editor and runs in one press.

A plan is a document: seeded so it reproduces, asserted so it has a verdict rather than a wall of numbers, and saveable so the plan and its transcript land on disk together. A result without the plan that produced it is not evidence of anything.

Controls

• Example — loads one of three ready plans. This replaces the editor contents.
• Run plan / Ctrl+Enter — executes from the top. Disabled while running.
• Stop — halts at the next statement. A verb already in flight finishes first.
• Download results — writes the rows collected by record() as a CSV. Disabled until a plan records something; the label shows the row count.
• Save transcript — writes the plan, the transcript and the verdict to your disk as one text file.

Recording results

record() collects one row per call, with columns you name. Put it at the end of a sweep iteration and each case adds a row.

for dv in [0.01, 0.05, 0.20]:
    inject(ric_ms=[0, dv, 0], at_day=20)
    before = dispersion(at_day=115)
    s = solve(at_day=22, horizon_rev=0.75, two_burn=True)
    fly()
    after = dispersion(at_day=115)

    record(dv_ms=dv, burn_ms=s.burn_ms,
           before_km=before.median_km, after_km=after.median_km)

Press Download results and you get:

# GTRE Sandbox — plan results
# build 2026-08-11
# sandbox arithmetic, not the GDS Physics engine, no execution certificate
# 8 checks, 8 passed, 0 failed
dv_ms,burn_ms,before_km,after_km
0.01,0.06601634992336892,14.48779888692292,18.71241722069512
0.05,0.28284001744899867,16.625360960017577,17.769083317217667

Reading the transcript

Every line is stamped with elapsed seconds. PASS and FAIL lines come from check(). A failure at the end names the line number. The verdict bar summarises: state, check count, passes, failures, and total time.

8Plan language reference

The plan language uses Python’s syntax for the part a test plan is made of. It is not CPython, and the page says so rather than letting you find out.

Supported

• Variables and assignment; numbers, strings, True, False, None
• Lists, and indexing including negative indices
• Arithmetic + - * / // % **, with ** right-associative and binding tighter than unary minus
• Comparisons == != < <= > >=
• and, or, not, with short-circuit evaluation
• for … in over a list or range(); break, continue, pass
• if / elif / else
• Calls with positional and keyword arguments; attribute access on results
• # comments, and line continuation inside brackets

Not supported

import, def, classes, while, dictionaries, tuples, slicing, f-strings, try/except, generators. The keywords are caught by name and say what to use instead; dictionaries, tuples, slicing and f-strings are rejected as a parse error rather than by name.

# what you get, rather than a puzzling syntax error
import numpy   -> "import" is not supported in a plan — there is nothing
                  to import; every verb is already in scope
while True:    -> "while" is not supported — use "for k in range(n)"
assert x == 1  -> "assert" is not supported — use check(label, condition)

9Verb reference

Setup

Data

Operations

Measurement

synthesize(), inject(), solve() and fly() all return the same object status() does, so you can read a result straight off the call.

Verdict and utilities

A complete plan

# Cross-track corrects cleanly; in-track does not. Show both.

seed(20260811)
forces(j2=True, drag=False, step_s=20)

ens = synthesize(runs=16, days=120, cadence_s=3600)
check("integrator adequate", ens.steps_per_rev > 100, ens.steps_per_rev)
check("no false decay", ens.sma_drift_km < 2, ens.sma_drift_km)

for axis in ["in-track", "cross-track"]:
    if axis == "in-track":
        inject(ric_ms=[0, 0.05, 0], at_day=20)
    else:
        inject(ric_ms=[0, 0, 0.05], at_day=20)

    before = dispersion(at_day=115)
    s = solve(at_day=22, horizon_rev=0.75, two_burn=True)
    fly()
    after = dispersion(at_day=115)

    print(axis, "burn", round(s.burn_ms, 3), "m/s |",
          round(before.median_km, 1), "->", round(after.median_km, 1), "km")
    check(axis + " solver converged", s.corr_status != "SINGULAR", s.corr_status)

report()

10Reading the diagnostics

This is the section worth reading twice. Most ways of getting a wrong answer here announce themselves, and this is what they mean.

The integrator line

The manifest reports N steps/rev · a drift X km. Green is fine, red is not. Both numbers are measured on the run you just made, not assumed.

• steps/rev — integration steps per orbital revolution. RK4 needs roughly 100 to hold energy. Below 50 the orbit spirals in from truncation error alone.
• a drift — the secular change in semi-major axis implied by the energy drift, measured over one whole orbit at each end of the arc so that J2’s short-period oscillation cancels.

Correction status

Log warnings you will actually see

• “velocity derived by central difference” — your file had no velocity columns. RIC orientation and the interpolation between samples both depend on it, so this is worth knowing.
• “run(s) had a different sample count and were linearly resampled” — a real approximation, reported rather than done quietly.
• “Horizon snapped from X to Y” — burns can only be placed where the ensemble has samples. The solve uses the snapped value so both burns agree with each other; a finer sample cadence places it closer.
• “the x column does not increase monotonically” — a series file whose x column is unordered. The row index is plotted instead.
• “most of the burn is radial” — you are nulling a phase error by brute force. Lengthen the horizon.

Linear (CW) versus RK4

The linear option is not a faster approximation to be preferred — it is there to be compared against. Run a small burn both ways over ten days and the two are indistinguishable; run a large one over two hundred days and the linear answer is wrong by hundreds of kilometres. Watching where the agreement fails is worth more than being told that it does.

11What it cannot tell you

GTRE cannot run any of the platform’s stress tests, and no amount of feature work would change that. A stress test verifies the GDS Physics engine against a known answer. This is a JavaScript reimplementation; running the same scenario here proves something about this page, not about the engine.

What it can do is let you explore the phenomenon behind several of them — convergence order and the round-off floor, the fact that conservative models cannot decay an orbit, that burning early and along-track is cheaper, and that execution error can make the cure worse than the disease.

And it can explore the output of a run you made elsewhere, which is what shape B exists for. That is a genuinely different thing from producing the output, and the distinction is the whole of limit 2.

The endpoints, the certificate format and the stress-test evidence are in the technical documentation.

12Where your data goes

Nowhere. Specifically, and checkably:

• The sandbox page is served with connect-src 'none'. The browser refuses every outbound request the page could attempt, before it is made. Open devtools and read the policy rather than taking our word.
• Parsing happens in a Web Worker in your tab. The file is read with File.stream(); the bytes go into typed arrays and nowhere else.
• No localStorage, sessionStorage, IndexedDB, cookie or cache write. A refresh, a tab close or Purge drops every array.
• Three controls write files, and they are the only three: Download format template, Save transcript and Download results. All go to your own disk through a blob: URL — a local write, not a send. Nothing is uploaded as a side effect of any of them.
• No API key is involved anywhere, because no request is made.

This manual page is ordinary site content and carries the site’s normal policy. The sandbox itself is the page with connect-src 'none', because it is the one that touches your files.