Deep time
The bundled embedded tier is validated from 1000 to 3000 CE. To reach back to 3000 BCE for ten bodies, load the binary era packs in Node.js or fetch them on demand in the browser. Historical astronomy also requires switching to the Julian calendar, modeling Earth's rotational drift (ΔT), and checking which bodies are excluded before their ephemeris spans begin. This guide covers all four.
import {
Engine, julianDay, calendarDate, deltaT, deltaTSigma,
engineCapabilities, chartStability, solarEclipses,
} from "caelus";
import { loadNodeData } from "caelus/node";
const engine = new Engine(loadNodeData("node_modules/caelus/data"));
What the era packs cover
An era pack stores a Chebyshev polynomial fit to JPL Horizons (DE441) for a
single body from 3000 BCE to 1000 CE. Stored alongside modern data files as
{body}_cheb.classical.json, each era pack joins the modern pack continuously at
1000 CE. Ten bodies have era packs: the Sun (via the Earth pack), the Moon, and
the planets from Mercury through Pluto.
Call engineCapabilities to inspect the active source, validated span, and
fitted span (in astronomical years) for each body loaded into an Engine
instance:
engineCapabilities(engine).bodies.find((b) => b.body === "saturn");
// { body: "saturn", source: "chebyshev_pack",
// validated: { from: -3003, to: 3000 }, fitted: { from: -3003, to: 3001 } }
| Body | Embedded tier, validated | Node loader, validated |
|---|---|---|
| Sun, Moon, Mercury, Venus, Mars | 1000 to 3000 | −2998 to 3000 |
| Jupiter | 1000 to 3000 | −3000 to 3000 |
| Saturn | 1000 to 3000 | −3003 to 3000 |
| Uranus, Neptune | 1000 to 3000 | −2999 to 3000 |
| Pluto | 1885 to 2099 | −2999 to 3000 |
| Chiron | 1600 to 2484 | 1600 to 2484 |
Astronomical years count a year 0 (1 BCE), so −2998 equals 2999 BCE.
Jupiter and Saturn packs begin a few years earlier because their fits are cut
into longer multi-year segments aligned to finish exactly where the modern pack
starts.
Each era pack records its maximum residual error against the JPL Horizons samples used to generate it:
engine.data.eraPacks.saturn[0].provenance.true_error_au; // 0.0000057
| Era pack | Recorded error |
|---|---|
| Mercury | 3.3e-6 AU |
| Venus | 3.1e-7 AU |
| Mars | 2.9e-8 AU |
| Jupiter | 2.8e-6 AU |
| Saturn | 5.7e-6 AU |
| Uranus, Neptune, Pluto | 8.2e-7 AU each |
| Earth (the Sun) | 5.7e-6 AU |
| Moon | 7.9 km |
Embedded tier vs. Node.js loader
Passing the package data folder to loadNodeData loads the modern Horizons
packs (planets, Earth, Pluto, Moon), the pre-1000 CE era packs, and the
asteroid, Uranian, and fixed-star catalogs. caelus/data-embedded
replaces the large planetary packs with compact trigonometric series and omits
all era packs.
When given a pre-1000 CE date, the embedded tier still computes coordinates
from its compact series while attaching an outside_validated_range warning
for affected bodies, because those series were never calibrated prior to
1000 CE. On 24 January 76 CE, the two tiers differ by 47″ on the Moon, 40″ on
Saturn, 13″ on Jupiter, and up to 5″ on the Sun, Mercury, Venus, and Mars.
The hosted MCP endpoint and initial browser views run on the embedded tier,
while local caelus-mcp instances use the Node.js loader.
Loading full packs in the browser
While the compact embedded tier ships inside client bundles, the full ephemeris
packs total 27.4 MB across 17 files, which is too large for an upfront bundle.
Browser apps can fetch only the required slices on demand via loadPacks,
passing a pack manifest and a fetch callback to overlay downloaded packs onto
embeddedData:
import { Engine, loadPacks, selectPacks } from "caelus";
import { embeddedData } from "caelus/data-embedded";
const base = "/data/packs/";
const manifest = await (await fetch(base + "manifest.json")).json();
const packs = selectPacks(manifest, {
bodies: ["saturn", "jupiter", "mars", "venus"], fromYear: -800, toYear: 0,
});
const data = await loadPacks(embeddedData, manifest, packs,
async (file) => (await fetch(base + file)).arrayBuffer());
const engine = new Engine(data);
selectPacks picks only the files required by your query: the requested
planetary packs, the Earth pack (needed both for the Sun and to transform
heliocentric planetary positions into geocentric coordinates), and the era files
spanning the target years. The call above selects five files totaling 4.2 MB;
loading both eras for all seven classical bodies takes 14 files totaling
27.2 MB.
The manifest records every file's byte length and SHA-256 hash. Before decoding
any buffer, loadPacks checks both values and throws PackIntegrityError on
any mismatch. It fetches only the files passed in packs that appear in the
manifest.
Once decoded, the overlaid browser engine produces bitwise-identical results to
loadNodeData (verified across 28 positions from 2500 BCE to 1990 CE with
===). The loader works in browsers, Node.js, and Cloudflare Workers via Web
Crypto, which browsers enable on HTTPS and localhost. Keep memory usage in
mind: loading all 14 classical pack files adds roughly 135 MB to a Chromium tab.
This site hosts its pack files at /data/packs/, and the
Sky Dating instrument fetches them automatically when
switched to full packs. See
docs/binary-packs.md
for the binary specification and publishing workflow.
A chart in 76 CE
const jd = julianDay(76, 1, 24, 6, 0, 0, "julian");
const chart = engine.chartAt(jd, 41.9, 12.5, "whole_sign"); // Rome
chart.unavailable; // ["chiron"]
| Body | Longitude |
|---|---|
| Sun | 2°41′ Aquarius |
| Moon | 27°16′ Capricorn |
| Mercury | 6°54′ Capricorn |
| Venus | 14°01′ Pisces |
| Mars | 19°13′ Pisces |
| Jupiter | 26°33′ Capricorn |
| Saturn | 29°57′ Sagittarius |
| Uranus | 23°41′ Aquarius |
| Neptune | 2°00′ Taurus |
| Pluto | 19°03′ Aquarius |
The Ascendant sits at 20°26′ Capricorn, matching the 76 CE chart recovered in the Sky Dating guide from seven zodiac signs alone.
Bodies whose ephemeris packs do not cover the target timestamp are listed in
chart.unavailable and omitted from chart.bodies, ensuring uncalibrated
extrapolations do not leak into output. Calling engine.position("chiron", jd)
for the same date throws a RangeError, so application code handling historical
charts should inspect chart.unavailable before accessing small bodies.
Julian calendar dates
Historical dates prior to 15 October 1582 are recorded in the Julian calendar.
julianDay interprets dates as Gregorian by default unless "julian" is
passed as the seventh argument, and calendarDate accepts the same option to
format Julian Days in either calendar:
julianDay(76, 1, 24, 6, 0, 0, "julian"); // 1748839.75
julianDay(76, 1, 24, 6, 0, 0); // 1748841.75, two days later
calendarDate(1748839.75, "julian"); // { year: 76, month: 1, day: 24, hour: 6 }
calendarDate(1748839.75); // { year: 76, month: 1, day: 22, hour: 6 }
The calendars differ by two days in the 1st century CE and ten days at the
1582 Gregorian reform: 4 October 1582 Julian (Julian Day 2299159.5) was
followed immediately by 15 October 1582 Gregorian (Julian Day 2299160.5). Using
astronomical years, the total solar eclipse of 28 May 585 BCE occurs in year
−584:
const [eclipse] = solarEclipses(engine,
julianDay(-584, 5, 1, 0, 0, 0, "julian"), julianDay(-584, 6, 30, 0, 0, 0, "julian"));
eclipse.type; // "total"
calendarDate(eclipse.tMax, "julian"); // 28 May, hour 14.44, which is 14:26 UT
ΔT (Earth rotation offset)
Ephemeris packs advance in Terrestrial Time (TT), a uniform astronomical
timescale, whereas calendar dates and civil clocks run in Universal Time (UT),
which follows Earth's slightly irregular rotation. ΔT is the offset in seconds
between those two timescales. Caelus applies ΔT automatically across chart and
event functions and exposes it via deltaT.
The built-in ΔT curve splices standard published datasets across time: IERS observations from 1955 to 2025, the Espenak and Meeus polynomial from 1948 to 1955, the Morrison, Stephenson, Hohenkerk, and Zawilski (2021) spline fitted to historical eclipses and occultations from −720 to 1948, and their long-term parabolic fit before −1520. Between −1520 and −720, Caelus interpolates between the parabola and the spline using a custom Hermite transition bridge not found in the published tables. Values beyond 2025 are extrapolated.
deltaTSigma estimates the one-sigma uncertainty of ΔT in seconds for any
year. Prior to 1700, it returns the larger of two published metrics: the
standard error from Stephenson, Morrison, and Hohenkerk (2016) or the magnitude
by which their 2020 revision moved the curve. Around 1000 CE, the 2020 revision
shifted ΔT by 180 seconds where the 2016 table had listed 15 seconds, so
deltaTSigma reports 180 seconds. Before −720 the source figures rely on
extrapolation, and before −2000 Caelus extends the published uncertainty table
linearly at its boundary slope.
deltaT(julianDay(76, 1, 1, 0, 0, 0, "julian")); // 9647.4
deltaTSigma(76); // 148.8
| Year | ΔT (s) | Sigma (s) | Angles | Moon |
|---|---|---|---|---|
| −2998 | 75,278 | 3,598 | 14.99° | 32.98′ |
| −1000 | 25,310 | 1,440 | 6.00° | 13.20′ |
| −500 | 16,939 | 150 | 0.62° | 1.38′ |
| 0 | 10,441 | 129 | 0.54° | 1.18′ |
| 500 | 5,586 | 40 | 0.17° | 0.37′ |
| 1000 | 1,650 | 180 | 0.75° | 1.65′ |
| 1600 | 109 | 19 | 0.08° | 0.17′ |
| 1800 | 18 | 1 | 0.00° | 0.01′ |
| 2000 | 64 | 0.06 | 0.00° | 0.00′ |
Each row samples January 1 of the given year and translates clock sigma into sky uncertainty: the Ascendant and Midheaven rotate roughly 0.25° per minute of clock error, while the Moon moves 0.55″ per second. By 2999 BCE, the total ΔT offset reaches 20.9 hours with a one-sigma uncertainty of roughly one hour (3,598 seconds).
What the warning means
Whenever a chart is calculated at an epoch with ΔT sigma of 10 seconds or
more, Caelus attaches a delta_t_uncertain warning. That threshold applies to
every year up to 1666 CE and resumes from 2137 CE onward as future extrapolations
diverge.
chart.warnings;
// [{ kind: "delta_t_uncertain", sigmaSeconds: 245,
// angleSmearDeg: 1.02, moonSmearArcmin: 2.24, text: "..." }]
In the 76 CE chart, a four-minute clock uncertainty translates to roughly 1° on the Ascendant and Midheaven and around two arcminutes on the Moon, while slower planets barely move.
To check whether that clock uncertainty alters any discrete astrological
placements, call chartStability, which defaults to the epoch's ΔT sigma when
no explicit window is supplied:
chartStability(engine, jd, { lat: 41.9, lonEast: 12.5 }).summary;
// { facts: 31, stable: 31 }
In this Rome chart, all 31 chart facts (signs, houses, aspects, retrograde
status, sect, and angle signs) hold across the uncertainty band. See
Uncertain Times for chartStability options, or
Sky Dating when you need to recover an unknown historical
date from planetary placements.
Limits
- Chiron and the asteroids have no pre-1600 CE era packs because JPL Horizons serves small bodies starting around 1600 CE, so they are unavailable before then.
- Published arcsecond validation bounds cover 1000 to 3000 CE on the Validation page; pre-1000 CE era packs only report the polynomial fit residuals tabulated above.
- ΔT sigma estimates before −2000 extrapolate the published table linearly past its lower boundary. At 3000 BCE, the one-sigma clock error reaches an hour (15° in longitude on the angles), so planetary positions remain well constrained while house cusps and angles cannot be determined reliably.
- Binary era packs account for about 16 MB of the npm package tarball. Client
bundles exclude them by default and fetch subsets on demand with
loadPacks.