Eclipses
Caelus provides functions to answer three eclipse questions: when eclipses occur within a date range, where a solar eclipse path crosses Earth, and what a viewer at a specific location sees. Every eclipse helper runs on the embedded data tier using the same Sun and Moon calculations as charts.
import {
Engine, julianDay, solarEclipses, solarEclipseWhere, solarEclipseLimits,
solarEclipseLocal, lunarEclipses, lunarEclipseLocal,
} from "caelus";
import { embeddedData } from "caelus/data-embedded";
const engine = new Engine(embeddedData);
// Reads a Julian Day as a UTC timestamp.
const utc = (jd) => new Date((jd - 2440587.5) * 86400000).toISOString();Finding eclipses in a date range
solarEclipses and lunarEclipses return every eclipse occurring between two
Julian Days in chronological order:
solarEclipses(engine, julianDay(2024, 1, 1), julianDay(2027, 1, 1))
.map((e) => [utc(e.tMax), e.type, e.gamma]);| Greatest eclipse (UT) | Type | Gamma |
|---|---|---|
| 2024-04-08 18:17:23 | total | 0.3433 |
| 2024-10-02 18:45:00 | annular | 0.3506 |
| 2025-03-29 10:47:39 | partial | 1.0413 |
| 2025-09-21 19:41:49 | partial | 1.0650 |
| 2026-02-17 12:12:00 | annular | 0.9743 |
| 2026-08-12 17:45:46 | total | 0.8978 |
Each solar eclipse record includes tMax, type (total, annular, hybrid,
or partial), gamma, and the global begin and end timestamps. Gamma
measures the distance from the Moon's shadow axis to Earth's center in Earth
radii; when gamma exceeds roughly 1, the shadow axis misses Earth and the
eclipse is partial everywhere.
A lunar eclipse record provides tMax, type (total, partial, or
penumbral), umbral and penumbral magnitudes, and start/end times for every
phase reached. During the total lunar eclipse of 14 March 2025, tMax falls at
06:58:41 UT with an umbral magnitude of 1.178 and totality lasting from
06:25:58 to 07:31:21 UT.
Locating the solar eclipse path
For a solar eclipse, solarEclipseWhere returns the geographic coordinates
directly beneath the shadow axis at a given timestamp, while solarEclipseLimits
adds the northern and southern bounds of the central path alongside its width
in kilometers:
const [eclipse] = solarEclipses(engine, julianDay(2024, 4, 1), julianDay(2024, 5, 1));
solarEclipseWhere(engine, eclipse.tMax);
// { lat: 25.30, lonEast: -104.17 } in Mexico, near TorreónsolarEclipseLimits(engine, eclipse.tMax).widthKm;
// 198.98Sampling timestamps from begin to end traces the full path across Earth.
Both functions return null when no central eclipse touches the surface at
that timestamp.
Local circumstances for an observer
Pass observer coordinates to solarEclipseLocal to calculate the local eclipse
type, magnitude, solar disc obscuration, and four contact times:
solarEclipseLocal(engine, eclipse.tMax, 32.78, -96.80); // Dallas| Field | Dallas | New York |
|---|---|---|
type | total | partial |
magnitude | 1.056 | 0.910 |
obscuration | 1.000 | 0.898 |
c1, partial begins | 17:23:24 UT | |
c2, totality begins | 18:40:45 UT | |
maxTime | 18:42:43 UT | 19:25:40 UT |
c3, totality ends | 18:44:41 UT | |
c4, partial ends | 20:02:45 UT |
In Dallas, totality lasts 236 seconds. Outside the eclipse footprint, type
is "none" and the contact times are null.
Because a lunar eclipse happens simultaneously everywhere on Earth's night side,
the local question is simply whether the Moon is above the horizon.
lunarEclipseLocal returns the Moon's altitude and a visible boolean: at
greatest eclipse on 14 March 2025, the Moon stands 44° above the horizon in
New York and 5° below it in London.
Accuracy
Times of greatest eclipse match Swiss Ephemeris within 9 seconds, and all 92 lunar eclipses and 89 solar eclipses between 1990 and 2030 classify with zero type mismatches. Contact times typically agree within 15 seconds (widening to minutes during grazing eclipses), and sub-shadow ground coordinates stay within 10 km. Detailed benchmarks appear on Validation.
This accuracy reliably establishes whether a city sees totality and its duration within a few seconds, though observers situated right on the edge of a path should consult an official Besselian-element map where a single kilometer can decide totality.