A showcase for rakupp --target=js

Eclipses are arithmetic

No telescope, no ephemeris file, no table of past eclipses. A few hundred sine terms, one integer — the number of New Moons since January 2000 — and every eclipse for four thousand years falls out, with its type, its magnitude and its 1,300-year family.

Everything on this page is computed in your browser by Raku code. The engine is lib/Eclipse.rakumod; the same file drives a command-line program in a terminal and this book in a browser, because rakupp --target=js turns it into JavaScript. Nothing was precomputed and no server is involved: when you move a control below, Raku runs.

The next eclipses, from today

Times are Universal Time, at the instant of greatest eclipse. A solar eclipse is visible only from the track its shadow draws; a lunar one from the whole night side of the Earth at once, which is why you have seen more of those.

Chapter 1

Two clocks that almost agree

The Moon passes between us and the Sun every month. Almost every month, nothing happens. The reason is a five-degree tilt, and the whole of eclipse prediction is bookkeeping about it.

Two different months matter. The synodic month — New Moon to New Moon — is 29.530589 days. The draconic month — the Moon's return to the same crossing point of its tilted orbit, its node — is 27.212221 days. An eclipse needs both clocks to strike at once: the Moon must be new (or full) and near a node.

synodic month 29.530589 d New Moon to New Moon draconic month 27.212221 d node to node anomalistic 27.554550 d perigee to perigee (this one sets total vs annular)

One number does the bookkeeping: F, the Moon's angular distance from a node, and it enters every formula below as sin F. The Sun is half a degree wide, the Moon likewise, the orbit is tilted 5.1°, so the shadows can still touch when the Moon is up to about 21° from the node. In sines: an eclipse is possible when |sin F| < 0.36, and impossible otherwise. That one line rejects five sixths of all New Moons in a single comparison.

sin F at every syzygyengine: moon-args, eclipse-at

no eclipse an eclipse a total one shaded band: |sin F| < 0.36

The curve is not a wave in time — it is one dot per month, and the months are 29.5 days apart while the nodes come round every 27.2. The band is entered twice a year, for about 34 days each time: an eclipse season. Because the nodes themselves drift backwards, a season arrives about 19 days earlier each year, and the whole pattern repeats after 18.6 years.

Chapter 2

Counting from one New Moon

Fix an origin — the New Moon of 6 January 2000 — and number every New Moon after it. That integer, called k, is the only input the rest of this book needs.

A first guess at the instant is a straight line: the origin plus k synodic months. That guess is wrong by up to fourteen hours, because the Moon does not move at a constant speed — it is nearer and faster at perigee, further and slower at apogee, and the Sun's pull on the whole system varies through the year.

JDE = 2451550.09766 + 29.530588861 k + 0.00015437 T² - ... T = k / 1236.85 - 0.40720 sin M' the Moon's own elliptical orbit (up to +/-9.8 hours) + 0.17241 E sin M the Sun's (up to +/-4.1 hours) + 0.01608 sin 2M' the second harmonic of the first + 0.01039 sin 2F the tilt + ... 20 more terms, then 14 planetary ones (Venus and Jupiter, ~30 seconds)

The pattern is worth recognising, because it is how almost all of classical celestial mechanics is written: a linear mean motion, plus a sum of sines of angles that are themselves linear in time. Each term is one physical effect, and you can switch them off one at a time and watch the answer get worse.

One phase, term by termengine: mean-phase, phase-jde

lunation k
–
mean phase alone
–
the straight line
your series
–
full series
–
your error
–
minutes off the full answer

Switch a term off and watch the prediction drift. The bars are signed: the tick in each track is zero, gold runs to the term's value in minutes. With nothing on, the answer is the straight line — ten hours out. The two ellipses in the problem, the Moon's around the Earth and the Earth's around the Sun, recover all but twenty minutes of that between them, and the last dozen terms are worth seconds. That is what a convergent series looks like from the inside.

Chapter 3

Gamma: where the shadow points

One number decides everything about a solar eclipse: how far the Moon's shadow axis misses the centre of the Earth, measured in Earth radii. It is called gamma.

Picture the plane through the centre of the Earth, perpendicular to the shadow axis — the fundamental plane. The Earth projects onto it as a disc of radius 1. The axis of the Moon's shadow pierces that plane at some point, and sweeps across it as the Moon moves. Gamma is the closest that point ever comes to the centre.

gamma = (P cos F1 + Q sin F1) (1 - 0.0048 |cos F1|) |gamma| < 0.9972 the axis lands on the Earth: an eclipse is central somewhere 0.9972 .. 1.5433 + u the axis misses, but the penumbra still catches a pole: partial > 1.5433 + u nothing at all — the Moon's shadow passes above or below us

The companion number is u, the radius of the Moon's umbral cone where it crosses that same plane. The cone is the full shadow, and it is only just long enough to reach us: about 375,000 km, against a Moon that orbits between 356,000 and 407,000 km away. When the Moon is near, the cone still has length to spare and u is negative — the shadow lands, and the eclipse is total. When the Moon is far, the cone runs out above our heads, u is positive, and what reaches the ground is the widening cone beyond the tip: the Sun shows as a ring, an annular eclipse.

The fundamental planeengine: eclipse-at

gamma
–
u
–
verdict
–

The blue disc is the Earth as the Sun sees it; the dashed circle is the limit 1.5433 + u, beyond which the penumbra misses us entirely. The gold line is the path of the shadow axis, and the gold dot the moment of greatest eclipse. Clear the checkbox and drive the two numbers by hand — the verdict comes from classify-solar, the same function every real eclipse goes through. Hunt for the hybrid sliver: it is only 0 < u < 0.0047 wide, two or three eclipses a century.

Chapter 4

Total, annular, hybrid

Two numbers, one plane, four verdicts. Plot every eclipse of a century as a point and the taxonomy draws itself.

The horizontal axis is gamma, the vertical one is u. The vertical lines at ±0.9972 are the edge of the Earth; the horizontal line at u = 0 is the tip of the umbral cone landing exactly on the fundamental plane. That is the whole classification:

Where the point landsWhat you seeHow often
|gamma| < 0.9972, u < 0total — the cone reaches the ground~27%
|gamma| < 0.9972, u > 0.0047annular — a ring of Sun around the Moon~33%
|gamma| < 0.9972, 0 < u < 0.0047hybrid — annular at the ends of the track, total in the middle, because the Earth curves away under it~5%
|gamma| > 0.9972partial — only the penumbra arrives~35%

The hybrid case is the prettiest piece of geometry in the subject. The cone's tip falls within a few kilometres of the surface; where the observer stands on the bulge of the Earth directly under it, the tip has already passed and the eclipse is total, and a thousand kilometres along the track, where the ground has curved away, the same cone falls short and the same eclipse is annular. Two or three per century.

Every solar eclipse of a spanengine: eclipses

eclipses
–
total
–
annular
–
hybrid
–
partial
–

Chapter 5

The Moon in the Earth's shadow

Reverse the geometry and the arithmetic barely changes — but now the shadow is ours, it is enormous, and everyone on the night side sees the same thing at the same moment.

At the Moon's distance the Earth's umbra is about 4,600 km across — two and a half times the Moon's diameter — surrounded by a penumbra half again as wide. Meeus's numbers, in the same Earth-radius units as before:

umbra radius 0.7403 - u penumbra radius 1.2848 + u Moon's radius 0.2725 first contact with the penumbra |gamma| = 1.5573 + u first contact with the umbra |gamma| = 1.0128 - u totality begins |gamma| = 0.4678 - u umbral magnitude = (1.0128 - u - |gamma|) / 0.5450 >= 1 -> total penumbral magnitude = (1.5573 + u - |gamma|) / 0.5450 > 0 -> something happens

The magnitude is the fraction of the Moon's diameter buried in the shadow. Duration follows from a chord: the Moon crosses at 0.5458 + 0.0400 cos M' Earth radii per hour, so each phase lasts twice the half-chord divided by that speed. A totality of 100 minutes means the Moon passed almost through the centre.

The Earth's shadow, and the Moon's path through itengine: eclipse-at

verdict
–
umbral magnitude
–
gamma
–
totality
–
minutes
partial
–
minutes
penumbral
–
minutes

Ghost discs mark the contacts: outer penumbra, umbra, totality, then the same in reverse. Slide gamma to zero and the Moon goes through the middle of the umbra, which is where the long totalities come from — over an hour and a half, and the record is about 107 minutes. Slide it past 1.0128 − u and the umbra is missed entirely: a penumbral eclipse, a slight dimming that most people looking straight at it fail to notice.

Chapter 6

The saros

223 synodic months are 6585.3213 days. 242 draconic months are 6585.3575 days. 239 anomalistic months are 6585.5375 days. Three clocks, three different periods, and they land within a few hours of each other.

That coincidence is the oldest result in the subject — the Babylonians had it — and it is why eclipses repeat. Wait 6585 ⅓ days after any eclipse and you get another one: the Moon is new again (synodic), it is at the same distance from the node (draconic), and it is at nearly the same distance from the Earth (anomalistic), so the new eclipse is of nearly the same kind and depth. The family of eclipses at that spacing is a saros series.

223 synodic = 6585.3213 d 242 draconic = 6585.3575 d differs by 51 minutes 239 anomalistic = 6585.5375 d differs by 5.2 hours 6585.32 d = 18 years 11 days 8 hours (10 or 11 days, depending on leap years)

The extra eight hours matter: the Earth turns 120° in that time, so each eclipse of a series lands a third of the way round the world from the last. Three saroses — an exeligmos, 54 years and about 33 days — bring the track back to roughly the same longitude.

The 51-minute mismatch with the draconic month matters too. It means the Moon is not quite at the same place relative to the node each time, so gamma drifts steadily in one direction. A series begins with a glancing partial eclipse at one pole, deepens through central eclipses over some seven hundred years, and dies with a partial eclipse at the other pole, twelve or thirteen centuries after it started. About forty series are running at any moment, which is why the numbers below are in the hundreds.

One family, beginning to endengine: saros-run

eclipses
–
first
–
last
–
span
–
years

Series numbers are not arbitrary and not random: consecutive numbers are one inex apart — 358 lunations, 28.9 years — so the engine recovers a series number from k with a single modular inverse: 38 × (k − anchor) mod 223. No lookup table anywhere in this book.

Chapter 7

Delta T, and the edge of prediction

The theory of the Moon runs on a uniform clock. The Earth does not keep one. The gap between them is the only part of this calculation that cannot be computed at all.

Everything above produces an instant in dynamical time — the time coordinate the equations of motion use. To say what a clock on the ground read, you must subtract ΔT = TD − UT, and ΔT is a measurement, not a formula. Tidal friction is slowing the Earth's rotation by about 2.3 milliseconds per century, but the mantle and core exchange angular momentum on decade scales in ways nobody can predict, so ΔT wanders.

It was about +17 seconds in 1900, +64 in 2000, and is near +75 today. Run backwards, the drift accumulates quadratically: about three hours by 1000 BC. Ancient ΔT is not derived — it is read off eclipses, from records of which city saw totality, which is a pleasing circularity: the same observations that test the theory supply the one constant the theory cannot produce.

TD − UT across four millenniaengine: delta-t

year
–
Delta T
–
Earth turns
–
degrees of longitude in that time

The last column is why ΔT is not an academic worry: an error of one hour in ΔT moves a totality track 15 degrees of longitude. Predicting the date of an eclipse in 2000 BC is easy; predicting which valley it was total over is not.

What this engine gets right, and where it stops

Checked against NASA's Five Millennium Canon, the engine reproduces the date, type and saros number of all 64 catalogued eclipses in reference/catalogue.tsv but one, and the instant of greatest eclipse to about a minute across the modern era. The exception is instructive: the lunar eclipse of 4 April 2015 was total by 0.0006 of a magnitude, with a totality of four minutes and 43 seconds. The truncated series here calls it partial by 0.004 of a magnitude. A series with a stated precision of minutes cannot adjudicate a four-minute totality, and it is more honest to say so than to add digits that are not there.

What is genuinely out of reach without a full ephemeris is where: the path of totality needs Besselian elements — the shadow axis in Earth-fixed coordinates, sampled through the event, corrected for the observer's height and the flattening of the Earth. This book answers when, and what kind. That is most of the question, and it fits in five hundred lines.

The engine is showcase/eclipse/lib/Eclipse.rakumod in the rakupp repository — 550 lines of Raku. eclipse.raku is the terminal version of this book; tools/build.raku bundles the engine with web/api.raku, transpiles it with rakupp --target=js --standalone, and inlines the result here. The page you are reading is one file with no dependencies.