Three indicators, one conservative verdict¶
Stability cannot be proven for more than two planets, so exostab asks the question in three different ways and reports all three answers side by side. When they disagree, it says so instead of picking the most comfortable answer.
-
Hill spacing
The Gladman (1993) criterion for two planets, in its form for eccentric orbits, and for three or more the spacing heuristic of Chambers et al. (1996) with the eccentricity-dependent requirement of Pu & Wu (2015).
-
Angular momentum deficit
Is there enough AMD for two orbits to cross? Laskar & Petit (2017), with the resonance-overlap and Hill refinements of Petit, Laskar & Boué (2017, 2018).
-
N-body integration and MEGNO
Direct integration with REBOUND's WHFast, repeated with IAS15 as a check, and the MEGNO chaos indicator to tell regular from chaotic motion.
-
SPOCK, optional
The machine-learned classifier of Tamayo et al. (2020) for systems of three or more planets, run in its own environment with
--spock. It can make the verdict marginal, never unstable on its own.
Built to be traced and reproduced¶
-
Every assumption shown
Gaps in the archive are filled by explicit rules. Every value carries its provenance, and every rule that fires is printed on the report card and stored in
report.json. -
Uncertainties propagated
Seeded Monte Carlo draws within the published error bars. An indicator's verdict stands only if at least 95% of the draws agree with the nominal one.
-
A conservative verdict
Stable only if every indicator agrees and no N-body draw has a close encounter; unstable only if the integration shows close encounters or escapes for the nominal values and at least 95% of the draws, no input is only an upper limit, and the system has a single star. Mixed evidence is reported as marginal, with the reason.
-
Reproducible
The same seed gives the same draws.
report.jsonrecords the seed, the software versions, the integrator settings and the archive download date. -
Validated
Energy conservation, the Hill limit, TRAPPIST-1, GJ 876, Kepler-11 and a reproduction of the HD 127195 Research Note run nightly in continuous integration.
-
Command line, web app, catalog
exostab checkfor one system andexostab sweepfor "what if" scans, a Streamlit app with sliders, and a weekly catalog of every multi-planet system in the archive.
Get started¶
pip install "exostab @ git+https://github.com/mimitoz62/exostab@v1.0.0"
exostab check "TRAPPIST-1"
exostab list --min-planets 4 --max-period-days 200
Python 3.10 or newer. The first check downloads the archive's multi-planet table once (about 2,700 rows)
and caches it; --offline uses a bundled snapshot of 22 well-known systems. A package on PyPI is planned;
until then, install from GitHub.
Then open http://localhost:8501. Search a system, edit its parameters, try "what if" changes with sliders, choose a time budget, and download the report or a shareable link to the run. The app runs on your own computer; there is no hosted version yet. More in Web app.
exostab check --from-file examples/two_planet.yaml
exostab sweep "HD 127195" --planet b --param e --range 0 0.6 --steps 25
A YAML file describes a system the archive does not have, or a published solution you want to test; the
repository's examples/ folder has two to start from. sweep varies one parameter of one planet and records
every indicator.
What a check gives you¶
A report card in the terminal, like the one in the recording above, and three files: report.json, orbits.png
and megno.png. The excerpt below is from exostab check "TRAPPIST-1" --offline (bundled archive snapshot of
2026-09-28, default settings).
report.json, selected keys
{
"schema_version": "1.3",
"data": {
"source": "snapshot",
"table": "pscomppars",
"retrieved_utc": "2026-09-28T13:57:30+00:00"
},
"system": {
"planets": [
{
"name": "TRAPPIST-1 b",
"eccentricity": {
"value": 0.00622,
"err_plus": 0.00304,
"err_minus": 0.00304,
"provenance": "measured",
"reference": "Grimm et al. 2018",
"reference_url": "https://ui.adsabs.harvard.edu/abs/2018A&A...613A..68G/abstract"
}
}
],
"flags": [
{
"planet": "TRAPPIST-1 b",
"parameter": "pl_tranmid",
"rule": "phase_from_transit",
"message": "Orbital phase set from the transit mid-time, propagated with the period (transit time and period come from different publications)."
}
]
},
"settings": {
"seed": 0,
"orbits": 10000.0,
"draws": 20,
"integrator": "whfast",
"check_integrator": "ias15",
"megno_threshold": 2.2,
"energy_error_max": 1e-05
},
"software": {
"exostab": "1.0.0",
"rebound": "5.2.0",
"numpy": "2.5.3",
"python": "3.12.11"
},
"overall": {
"verdict": "marginal",
"reasons": [
"Hill spacing: marginal",
"N-body + MEGNO: marginal"
]
}
}
How it works¶
Fetch
The NASA Exoplanet Archive's composite table (pscomppars), downloaded once and cached; a bundled snapshot of
22 systems offline; or your own YAML file.
Complete
Explicit rules fill the gaps. Each value is tagged measured, derived, assumed, estimated, randomized or upper limit, and each rule adds a flag.
Sample and integrate
The nominal parameters and seeded Monte Carlo draws go through the Hill, AMD and N-body indicators, in parallel worker processes.
Report
A conservative overall verdict, the report card, report.json, orbits.png and megno.png.
What the verdicts mean¶
stable
The indicator's condition for stability holds for the nominal parameters and for at least 95% of the draws.
marginal
Borderline, or the draws within the uncertainties disagree with the nominal parameters.
unstable
The indicator predicts instability for the nominal parameters and for at least 95% of the draws.
inconclusive
The indicator could not be evaluated reliably, for example because the integration's energy error was too large.
The Hill and AMD criteria are sufficient conditions: failing them means stability is not guaranteed, not that the system falls apart. With the published four-planet solution of Rivera et al. (2010), GJ 876 is unstable by Hill spacing and marginal by AMD, yet every N-body draw is regular, because its planets are locked in a resonance.
Validated against physics and reference results¶
1.44 × 10⁻⁹ Relative energy error of the inner Solar System over 10,000 years with WHFast (test limit 10⁻⁷).
3.4624 Mutual Hill radii: the Gladman limit for two planets of 10⁻⁵ M☉ on circular orbits around a solar-mass star (it tends to 2√3 = 3.4641 for small masses).
20 / 20 Regular N-body draws for GJ 876 with the published four-planet solution of Rivera et al. (2010).
133 / 200 Regular draws for HD 127195 with the inputs of the Research Note (submitted, not yet published), which found 134 / 200.
These numbers come from python scripts/validation_summary.py (13 October 2026, macOS). The suite runs nightly in
continuous integration.
Full validation, with tolerances and versions
Know the limits¶
What a verdict does not tell you
- Finite horizon. The default run is 10,000 orbits of the innermost planet (41.4 years for TRAPPIST-1, 14,634 years for HD 127195). "No chaos detected" over that span is not proof of stability over billions of years.
- Coplanar orbits. Mutual inclinations are almost never measured, so all orbits are placed in one plane.
- Independent draws. Parameters are drawn independently from their error bars, ignoring the correlations in the published posteriors.
- Not modelled. Tides, general relativity, stellar evolution and companion stars. Circumbinary systems are rejected.
Cite exostab¶
If exostab helps your work, please cite the software, the methods behind the indicators you report and the NASA Exoplanet Archive. Citing exostab has a BibTeX entry and the list of references. What changed in each release is in the changelog.