Caelus3,462 checksGitHubv0.25.0MIT
Guides

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 } }
BodyEmbedded tier, validatedNode loader, validated
Sun, Moon, Mercury, Venus, Mars1000 to 3000−2998 to 3000
Jupiter1000 to 3000−3000 to 3000
Saturn1000 to 3000−3003 to 3000
Uranus, Neptune1000 to 3000−2999 to 3000
Pluto1885 to 2099−2999 to 3000
Chiron1600 to 24841600 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 packRecorded error
Mercury3.3e-6 AU
Venus3.1e-7 AU
Mars2.9e-8 AU
Jupiter2.8e-6 AU
Saturn5.7e-6 AU
Uranus, Neptune, Pluto8.2e-7 AU each
Earth (the Sun)5.7e-6 AU
Moon7.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"]
BodyLongitude
Sun2°41′ Aquarius
Moon27°16′ Capricorn
Mercury6°54′ Capricorn
Venus14°01′ Pisces
Mars19°13′ Pisces
Jupiter26°33′ Capricorn
Saturn29°57′ Sagittarius
Uranus23°41′ Aquarius
Neptune2°00′ Taurus
Pluto19°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)AnglesMoon
−299875,2783,59814.99°32.98′
−100025,3101,4406.00°13.20′
−50016,9391500.62°1.38′
010,4411290.54°1.18′
5005,586400.17°0.37′
10001,6501800.75°1.65′
1600109190.08°0.17′
18001810.00°0.01′
2000640.060.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.

Start building

Quickstart →