Caelus3,462 checksGitHubv0.25.0MIT
Guides

Sky dating

Chart functions compute planetary positions from a known timestamp. The dateSky function works in reverse: given a set of observed positions, it searches a date range and returns every time window where those positions occur together. Historians and researchers use this to date ancient horoscopes or texts that preserve planetary placements without a calendar year.

You can run the same search interactively in the browser on the Sky Dating instrument, which plots the pruning funnel as a timeline.

import { Engine, dateSky, julianDay, calendarDate } from "caelus";
import { loadNodeData } from "caelus/node";

const engine = new Engine(loadNodeData("node_modules/caelus/data"));

const { windows, funnel } = dateSky(engine, [
  { body: "jupiter", sign: "Pisces" },
  { body: "venus", sign: "Taurus" },
  { body: "saturn", sign: "Cancer" },
  { body: "mars", sign: "Gemini" },
], julianDay(-800, 1, 1, 0, 0, 0, "julian"), julianDay(0, 1, 1, 0, 0, 0, "julian"));

windows.map((w) => calendarDate(w.start, "julian"));

These four signs correspond to the positions commonly quoted for the oldest surviving Babylonian horoscope, dated by Abraham Sachs to 29 April 410 BCE ("Babylonian Horoscopes", Journal of Cuneiform Studies 6, 1952). Searching across 800 years yields three matching windows:

Window opens (Julian calendar)Length
25 June 529 BCE6.3 days
16 April 410 BCE24.5 days
23 March 173 BCE19.9 days

The second window matches Sachs's date. While four planetary signs narrow eight centuries down to three candidates, adding another recorded clue such as the Moon's sign or lunar month typically isolates a single date. Because the signs above are taken from secondary summaries rather than re-collated against the tablet edition, treat this snippet strictly as a code demonstration.

Years and calendars

Returned windows use UT Julian Days. Passing "julian" as the seventh argument to julianDay interprets input dates in the Julian calendar, which is standard for historical dates prior to 15 October 1582; calendarDate(jd, "julian") converts timestamps back into calendar fields. Years follow astronomical numbering, where year 0 equals 1 BCE and year -409 equals 410 BCE.

Constraints

Each constraint specifies a celestial target or elongation and the zodiacal arc it must lie within:

ConstraintMeaning
{ body: "saturn", sign: "Libra" }Body inside a zodiac sign (by name or index 0–11)
{ body: "mars", lon: 112.5, orb: 2 }Body within orb degrees of a target longitude
{ body: "venus", from: 350, to: 15 }Body inside the forward ecliptic arc from from to to
{ elongation: ["moon", "sun"], from: 180, to: 360 }Angular separation (Moon minus Sun), matching a waning Moon here

Add pad to an individual constraint (or globally in the options object) to widen bounds symmetrically by that many degrees. Pass zodiac in options (such as "sidereal:fagan_bradley") to evaluate longitudes in any supported zodiac frame.

First and last visibility constraints

Historical records often report a discrete sighting, such as Venus first appearing in the evening or Sirius rising before dawn, rather than a zodiac position. You can express that event as a visibility constraint using the same parameters as heliacal: a target body or star, an event kind, and the observer's coordinates (lat and lonEast).

TypeScript
import { Engine, dateSky, julianDay, calendarDate } from "caelus";
import { embeddedData } from "caelus/data-embedded";

const engine = new Engine(embeddedData);

// "Venus was first seen in the evening, and Jupiter was in Leo", at Babylon.
const found = dateSky(engine, [
  { body: "jupiter", sign: "Leo" },
  { visibility: { target: "venus", kind: "evening_first", lat: 32.54, lonEast: 44.42 } },
], julianDay(-650, 1, 1, 0, 0, 0, "julian"), julianDay(-600, 1, 1, 0, 0, 0, "julian"));

found.windows.map((w) => calendarDate(w.start, "julian"));

Over those 50 years, four windows match: June 642 BCE, late August 631 BCE, June 618 BCE, and late August 607 BCE. Each returned window spans the local calendar days from the event's earliest date (clearer sky) through its latest date (hazier sky), which runs 7 to 14 days for Venus. Add within on the constraint to widen each window by that many days on both sides when a text indicates the event occurred a few days earlier or later.

The visibility object also accepts extinction, spread, altM, method, and arcusVisionis, with the same semantics as heliacal.

Because visibility events are discrete sightings rather than continuous curves that can be bracket-scanned, dateSky always evaluates them last. Inside each candidate window left by the positional constraints, the solver locates matching visibility events sequentially. Combined with a planetary sign constraint, the 50-year query above finishes in about half a second; running a visibility constraint on its own executes one event search per occurrence (roughly 40 milliseconds each, or around 30 seconds for 800 years of Sirius risings).

Handling zodiac offsets in historical sources

The horoscope of Emperor Hadrian, preserved by Hephaestio of Thebes via Antigonus of Nicaea, places the Sun, Moon, and Jupiter in Aquarius, Saturn and Mercury in Capricorn, and Venus and Mars in Pisces. Neugebauer and Van Hoesen (Greek Horoscopes, 1959, no. L 76) date this chart to 24 January 76 CE.

For that morning, tropical longitudes place the Moon at 26° Capricorn, Jupiter at 26.5° Capricorn, and Saturn at 29.9° Sagittarius. Each falls a few degrees behind the sign recorded in the Greek text because Hellenistic horoscopes of that era referenced sidereal-like longitudes offset from the tropical equinox. Setting pad: 6 absorbs that offset:

const hadrian = dateSky(engine, [
  { body: "sun", sign: "Aquarius" },
  { body: "moon", sign: "Aquarius" },
  { body: "jupiter", sign: "Aquarius" },
  { body: "saturn", sign: "Capricorn" },
  { body: "mercury", sign: "Capricorn" },
  { body: "venus", sign: "Pisces" },
  { body: "mars", sign: "Pisces" },
], julianDay(-2990, 1, 1, 0, 0, 0, "julian"), julianDay(2990, 1, 1), { pad: 6 });

Across those 5,980 years, widening every sign boundary by 6° returns four matching windows: 4 March 2485 BCE, 23 February 2248 BCE, 3 February 1394 BCE, and 24 January 76 CE. The 76 CE window runs from 00:49 UT on 24 January to 20:30 UT on 26 January, and no other match appears within a thousand years of it. The search takes roughly 1.2 seconds in Node.js on a laptop.

Constraint funnel and diagnostics

To search multi-millennium ranges quickly, dateSky orders constraints from the slowest body to the fastest. It scans the slowest body across the entire span and evaluates each faster body only inside the candidate windows left standing. The returned funnel array records the surviving window count and day total after each stage. For the Hadrian search:

ConstraintWindows leftDays left
Saturn in Capricorn432269,787
Jupiter in Aquarius15029,603
Sun in Aquarius1344,427
Mars in Pisces34768
Venus in Pisces19292
Mercury in Capricorn11121
Moon in Aquarius410

The funnel shows both which constraints narrow the search most effectively and where an empty query dropped to zero windows, which often points directly to a transcription error or zodiac offset in one body of a historical text.

Running in the browser

Because the embedded tier covers 1000 to 3000 CE, searches inside that window require no external downloads and execute directly on the page. This query finds when all seven classical bodies occupied Aquarius between 1800 and 2200:

TypeScript
import { Engine, dateSky, julianDay, calendarDate } from "caelus";
import { embeddedData } from "caelus/data-embedded";

const engine = new Engine(embeddedData);

const { windows } = dateSky(engine, [
  { body: "sun", sign: "Aquarius" },
  { body: "moon", sign: "Aquarius" },
  { body: "mercury", sign: "Aquarius" },
  { body: "venus", sign: "Aquarius" },
  { body: "mars", sign: "Aquarius" },
  { body: "jupiter", sign: "Aquarius" },
  { body: "saturn", sign: "Aquarius" },
], julianDay(1800, 1, 1), julianDay(2200, 1, 1));

windows.map((w) => [calendarDate(w.start), calendarDate(w.end)]);

One window matches, from 22:56 UT on 3 February 1962 to 22:52 UT on 5 February (calendarDate returns UTC hours as decimals). Because the Moon crosses a sign in just over two days, lunar motion determines the window width. This 400-year search finishes in about half a second in Node.js and powers the Sky Dating instrument.

Using full ephemeris packs in the instrument

The instrument starts on the embedded tier, and its Data selector switches to the full ephemeris packs: it lists the pack files needed for the current search alongside their download size, fetches them when you run the query, and verifies each file against its SHA-256 hash before decoding. See Deep Time for details on the browser pack loader.

PresetFilesDownloadSearch, full packsSearch, embedded
Babylonian tablet, 800 years54.2 MB0.1 s0.6 s
Horoscope of Hadrian, 5,997 years1427.2 MB1.1 s4.5 s

Both data tiers locate the same historical events, though window boundaries shift slightly due to differences in polynomial fit accuracy: for the Babylonian preset the embedded tier's edges differ by up to ~6 minutes, while for Hadrian's horoscope they shift by up to ~27 minutes at the oldest match:

Window opens, full packsEmbedded tier opensEmbedded tier closes
4 March 2485 BCE, 07:55 UT13 minutes earlier27 minutes earlier
23 February 2248 BCE, 16:10 UT11 minutes earlier10 minutes earlier
3 February 1394 BCE, 12:22 UT6 minutes earlier6 minutes earlier
24 January 76 CE, 00:49 UT1 minute earlier1 minute earlier

Once loaded, the full Chebyshev packs are also faster to query than the compact trigonometric series in the embedded tier. (Timings above are measured on a single laptop.)

MCP integration

AI clients can invoke this search via the date_sky MCP tool, passing constraints alongside start_year and end_year in astronomical years. Each returned window includes formatted calendar dates (using the Julian calendar before 15 October 1582 and era labels such as 410 BCE). A local caelus-mcp installation loads era packs back to the classical era, whereas the hosted MCP server uses the embedded tier, covers 1000 to 3000 CE, and returns an error noting the supported range if given dates outside it. Setup instructions are in the MCP guide.

Limits

  • Queries must fall within the loaded engine's ephemeris span. Pre-1000 CE dates are validated only when era packs are loaded via loadNodeData in Node.js or loadPacks in the browser; the embedded tier omits them. Use engineCapabilities to inspect per-body spans.
  • Chiron and the asteroids have no packs before 1600 CE and cannot be constrained in searches earlier than that.
  • dateSky supports longitude, elongation, and first or last visibility constraints; it does not filter by Ascendant, house placement, or retrograde state. To search arbitrary predicates over years or decades, use when(), which scans at a uniform time step (too slow for multi-millennium ranges).
  • A visibility constraint requires ephemeris coverage extending roughly 250 days beyond both ends of the search range so events near the boundaries can be resolved cleanly.
  • Any search involving the Moon yields windows roughly two to three days wide. In antiquity, ΔT uncertainty of several minutes nudges the Moon by a few arcminutes and shifts window edges by a comparable number of minutes without moving matches to another date.

Start building

Quickstart →