Computing Eclipses and Occultations
Every event on this site is a body casting a shadow, and what matters is who stands in it. When the observer stands in the shadow, the source is hidden: an occultation, a transit or a solar eclipse. When another body stands in it, that body goes dark for everyone: a lunar eclipse or the eclipse of a planet's satellite. This site sets out how each event is computed, with the formulas, constants, datasets and validation evidence. Solar eclipses are covered in most depth. The primer explains the two cases with pictures and animations, and how they are named.
The solar eclipse pipeline gives the implementation stages, and extending the pipeline to other events sets out what each other event adds. The software comparison covers published calculators and open-source libraries. The topic map draws every topic and the links between them.
Research and website source on GitHub.
Published predictors can disagree at a path limit because they use different models and inputs 1 2. This site sets out what a developer needs to know to compute every product, from the list of eclipses in a century to the second totality begins on one hillside, and to know how good the result is: the algorithm, the constants and where each one came from, the datasets, the published implementations, and what is still unsettled.
The source policy prioritises primary documents and published code. Equations carry their constants, and substantive claims carry graded citations. Follow the cited artefact before relying on a number. Method and source policy defines the grades and the evidence each one provides.
- Hidden: the observer stands in the shadow. Occultations, transits and solar eclipses depend on where the observer stands. Their dominant inputs are the lunar limb, the star's and the body's positions, and the solar and planetary radii 3 4 5.
- Darkened: another body stands in the shadow. Lunar and satellite eclipses look the same from everywhere. Their dominant inputs are the enlargement of the Earth's shadow and the satellite ephemeris 6 7.
- Solar eclipses are covered in most depth. Bessel's method underlies classical eclipse tables and maps. Direct topocentric calculations and raster limb tests provide alternative routes. Predictors differ in their algorithms as well as their constants and data 8 9 10.
- Solar radius, lunar limb and terrain can move a path limit by hundreds of metres to kilometres. Their effects depend on the geometry and on which corrections the predictor includes 1 11.
- Wright and Young 2024 describe NASA SVS's terrain-aware raster method. It uses an 18,000-element lunar limb from LRO and Kaguya (SELENE) topography. The paper is open access, while the surveyed public releases contain data rather than the generating code 10 12.
- The adopted solar radius remains a modelling choice. Flash-spectrum and light-curve studies infer values around 959.95 to 960.01 arcseconds. At Stephenville in 2024, predictions of 24.5 s and 12.9 s bracketed the observed 13.7 s. That comparison changes several implementation inputs, so it does not isolate the radius contribution 13 14 2.
- The surveyed open implementations do not derive limb-corrected path limits. Stellarium and NASA's JavaScript provide smooth-Moon products. The repository survey also includes a LOLA-based bead construction for a single eclipse 15 16 17.
Start here
- Primer: start here if you have not computed an eclipse before.
- Executive summary: the findings that carry the most weight, for both cases and then for solar eclipses.
- Solar eclipse pipeline: nine stages with formulas, constants, outputs and validation cases.
- Extending the pipeline to other events: how the same geometry serves the other events, and what each one adds.
- Solar eclipse error budget: every input ranked in seconds and metres.
- Reading list: the papers, code and datasets for each research group, in order.
The research notes
Seventeen topics in five groups, each a folder of notes with quoted formulas, graded citations and the questions it could not close.
Shared geometry and inputs
What every event needs: the geometry, the Earth, time, the ephemerides and the software. Group overview.
| Topic | What it settles |
|---|---|
| Foundations | The eight Besselian elements, the equations from ephemeris to elements, the constants and their provenance |
| Earth model and time | The ellipsoid, terrain and geoid, ΔT models, refraction, frames |
| Lunar and solar model | The DE ephemerides, centre of mass against figure, , libration |
| Software and repositories | Four production lineages, the open libraries, thirty repositories, the datasets |
Solar eclipses and transits
The hidden case with the Sun as the source, covered in most depth. Group overview.
| Topic | What it settles |
|---|---|
| Catalogues and types | How eclipses are enumerated and classified, and which catalogues to use as fixtures |
| Global circumstances | Central line, limits, outlines, rise and set curves, durations, and the data products |
| Local circumstances | Contact times, magnitude, obscuration and position angles at one site, and the corrections |
| Lunar limb profile | Watts, Kaguya and LOLA, the DEM-to-profile geometry, and Baily's beads |
| Solar radius | Every value in circulation, what each measures, and the effect on products |
| Validation | Observed against predicted, predictor disagreements, the error budget and protocol |
| NASA SVS and Ernie Wright | The 2024 paper, the SVS products and data, and the comparison with other predictors |
| Transits of Mercury and Venus | Enumeration, transit elements, contacts and local reduction formulas, the black drop and the radii |
Lunar eclipses
The darkened case with the Moon in the Earth's shadow.
| Topic | What it settles |
|---|---|
| Lunar eclipses | The lunar elements and six contacts, the three shadow enlargement rules, crater timings and brightness |
Occultations
The hidden case with a star or a planet as the source. Group overview.
| Topic | What it settles |
|---|---|
| Lunar occultations | Occultations of stars and planets by the Moon, grazes, star catalogues and the reduction of timings |
| Occultations by planets and minor bodies | Asteroid and TNO occultation paths, Gaia astrometry, light curves and chords, and planet-planet occultations |
Planetary satellites
Both cases at Jupiter, Saturn and beyond. Group overview.
| Topic | What it settles |
|---|---|
| Jupiter's satellites | Eclipses, occultations, transits and shadow transits of the Galilean satellites, theories and mutual events |
| Saturn and the outer satellites | Saturn's ring geometry, satellite theories and phenomena, and mutual events at Uranus and Pluto |
Reference
- Glossary: the jargon, defined standalone, with the formula where a term is really a quantity.
- Open questions: what this corpus could not close, each naming the artefact that would close it.
- Method and source policy: the grades, and what each one is allowed to prove.
References
- 1peer-reviewed Quaglia, Irwin, Emmanouilidis & Pessi (2021), Estimation of the Eclipse Solar Radius by Flash Spectrum Video Analysis, ApJS 256:36 Full PDF read (var/downloads/quaglia2021_flash_spectrum_ApJS.txt). Flash-spectrum video from a site a few hundred metres inside the 2017 southern limit near Vale, Oregon. S = 959.95 +/- 0.05 arcsec. Gives sensitivity of duration and limit distance to solar radius, and compares Irwin's model with Occult and Solar Eclipse Maestro.
- 2trade Besselian Elements team, Experimentally Testing Eclipse Maps Accuracy (2024) Read via WebFetch summary. Stephenville, Texas, 2024 April 8. Observed totality 13.7 s (C2 18:39:06.6, C3 18:39:20.3 UTC) versus six predictions from 12.9 s (Irwin) to 65 s (timeanddate). Authors' own experiment, so trade grade.
- 3company Herald, D. (2016-11-20). Update to Occult and Observations Read (curl). States that a position-angle error of up to 0.2 deg in the traditional method corrupted the limb correction, and that with the LOLA lunar limb (Occult download #26) most occultation predictions are within 0.3 s of observation.
- 4peer-reviewed Ferreira, J. F., Tanga, P., Spoto, F., Machado, P. and Herald, D. (2022). Asteroid astrometry by stellar occultations: accuracy of the existing sample from orbital fitting. A&A 658, A73 (arXiv:2201.03892) Read from the arXiv text. Source of the pre-Gaia residual level of 30 to 50 mas, the Gaia EDR3 level near 10 mas, the factor of about 5 reduction, the 10 mas FWHM of the residual core, the 3 to 4 mas along-track error level, the RUWE analysis and the statement that 61 per cent of events are single-chord.
- 5primary IMCCE for ESO VT-2004, Extended InfoSheet B1: Predictions of the Venus transit of June 8, 2004 Read in full (curl). VSOP87, Lieske precession, Wahr nutation, Aoki sidereal time, IAU 1976 constants (solar semidiameter 15'59.63", Venus radius 6051.8 km, Earth radius 6378.140 km), flattening 1/298.257, TT - UTC 65.184 s, general and geocentric phases, the E, F, G coefficients and the Paris example. Formula (1) is an image; its form is reconstructed in the note from the Paris example.
- 6peer-reviewed Herald, D. and Sinnott, R. W. (2014). Analysis of lunar crater timings, 1842-2011. J. Br. Astron. Assoc. 124(5), 247-253 Read in full from the ADS scan (text extracted; Greek letters in the Symbol font are lost, so equation [4]'s angle is written theta here). Source of equations [1] to [4], the recommended rule with h = 0.0136, the NEL statistics (mean 86.9 +/- 0.2 km, mode 78, median 85), the per-eclipse heights, the ingress-egress and limb-contact biases, the shape result and the 1963 Dec 30 case.
- 7peer-reviewed Arlot, J.-E., Emelyanov, N. V., Lainey, V. et al. (2012). Astrometric results of observations of mutual occultations and eclipses of the Saturnian satellites in 2009. Astronomy and Astrophysics 544, A29 Read in full from the HAL PDF (CC BY 4.0). Source of the observation counts 14, 66 and 33 for 1980, 1995 and 2009, the photometric model E(t) = K S(X, Y), the O-C residuals against TASS 1.7, Lainey and SAT351, and the NOE-6-2011-MAIN accuracy statement.
- 8peer-reviewed Explanatory Supplement to the Astronomical Ephemeris and the American Ephemeris and Nautical Almanac (1961), section 9B Eclipses and Transits Read in full (OCR text). Definitive almanac formulation: fundamental plane, point Z, x y z, mu from ephemeris sidereal time, sin f1 sin f2 with tabulated numerators for k = 0.272274, 0.2724807, 0.272281 and 0.2724880, c1 c2 l1 l2, sign convention, observer coordinates, ephemeris meridian 1.002738 ΔT, worked example 1961 Feb 15.
- 9peer-reviewed Quaglia, L., Irwin, J., Emmanouilidis, K., Pessi, A., Estimation of the Eclipse Solar Radius by Flash Spectrum Video Analysis, ApJS 256, 36 (2021), arXiv:2107.09416 Downloaded PDF and read the introduction and computational model sections. States 959.63 arcsec (Auwers 1891) is used in all published predictions, IAU 2015 nominal 959.23 arcsec, result 959.95 ± 0.05 arcsec; model uses DE430, LOLA SLDEM-256 and LDEM-128 in the ME frame, IAU 2006 Earth orientation, light time, deflection and planetary aberration, and no Besselian elements.
- 10peer-reviewed Wright, E. and Young, C. A. 2024, A Raster-oriented Method for Creating Eclipse Maps, AJ 168, 163 Original publisher PDF preserved in Wayback snapshot 2024-11-19. Sections 4-6 and Appendix A checked 2026-09-30. 0.02 degree bins imply about 600 m along the Moon, not Earth edge accuracy. Printed broken-annular criterion needs common angular normalisation. PDF SHA256 5c07500302a852e21439b0cfe8b4a94c423fd92ca3315918818009d4cbf26447. CC BY 4.0.
- 11primary Wright (2017), 2017 Eclipse Shadow Cones and Umbra Shape, NASA SVS 4517 Full HTML read from a saved copy. Terrain shifts the 2017 umbra south-east by as much as 3 km in the western states. Explains the polygonal umbra and the move from Watts to LRO and Kaguya profiles.
- 12primary NASA SVS, 2024eclipse_shapefiles.zip (78.6 MB) Downloaded from Wayback capture 2025-02-12 and parsed: umbra_hi 6741 records at 1 s 17:56:00 to 19:48:20 UTC with 12 attributes; umbra_lo 1181 at 10 s; center, duration, ppath, ppath01, upath_hi, upath_lo; all .prj GCS_WGS_1984.
- 13peer-reviewed Quaglia, L., Irwin, J., Emmanouilidis, K. and Pessi, A. (2021) Estimation of the eclipse solar radius by flash spectrum video analysis. ApJS 256, 36 Full arXiv PDF read. Accepted-paper Figure 2 and conclusions checked 2026-09-30: 959.63-to-960.00 comparison gives 1.8 s central and 19.3 s Vale duration loss; fitted 959.95 +/-0.05 arcseconds gives 1.6 s central loss. Fit depends on limb and detection model. Accepted-paper PDF SHA256 dea52d9a88577023541769f62b3ddd41c601737d64ef7afdd64ab7fe31302e95.
- 14peer-reviewed Lamy, P., Prado, J.-Y., Floyd, O., Rocher, P., Faury, G. and Koutchmy, S. (2015) A novel technique for measuring the solar radius from eclipse light curves: results for 2010, 2012, 2013, and 2015. Solar Physics 290, 2617 Seventeen photometer light curves at 540 nm with Kaguya limb profiles: 959.99 ± 0.06 arcseconds (696,246 ± 45 km). Abstract read on the Springer page; full text paywalled.
- 15company Stellarium src/core/SolarEclipseComputer.cpp Source read at pinned commit 69888f4f47af2aa4d1c9d14ec3853e874e253c73. SHA256 6ea4ddfac3c2fc921adcb75c06fd6c0062d6e7716ce566c15976c16b2020cbd5. Lines 584-587 use a small-separation angular axis approximation; global limits and observer transformations inspected. Verified 2026-09-30.
- 16primary JSEX program.js (JavaScript source of the Solar Eclipse Explorer) Source read in full (36.8 KB, downloaded 2026-09-15). GPL v2+. Contains the local-circumstance algorithm, the observer geocentric constants and the crude refraction handling.
- 17company tomasrojasc/eclipse-2026 Read live. Skyfield with DE421, LOLA LDEM_16 limb profile, moon_pa_de421 orientation, Baily's beads per bead; 84 tests; no licence stated.