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 BCE | 6.3 days |
| 16 April 410 BCE | 24.5 days |
| 23 March 173 BCE | 19.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:
| Constraint | Meaning |
|---|---|
{ 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).
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:
| Constraint | Windows left | Days left |
|---|---|---|
| Saturn in Capricorn | 432 | 269,787 |
| Jupiter in Aquarius | 150 | 29,603 |
| Sun in Aquarius | 134 | 4,427 |
| Mars in Pisces | 34 | 768 |
| Venus in Pisces | 19 | 292 |
| Mercury in Capricorn | 11 | 121 |
| Moon in Aquarius | 4 | 10 |
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:
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.
| Preset | Files | Download | Search, full packs | Search, embedded |
|---|---|---|---|---|
| Babylonian tablet, 800 years | 5 | 4.2 MB | 0.1 s | 0.6 s |
| Horoscope of Hadrian, 5,997 years | 14 | 27.2 MB | 1.1 s | 4.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 packs | Embedded tier opens | Embedded tier closes |
|---|---|---|
| 4 March 2485 BCE, 07:55 UT | 13 minutes earlier | 27 minutes earlier |
| 23 February 2248 BCE, 16:10 UT | 11 minutes earlier | 10 minutes earlier |
| 3 February 1394 BCE, 12:22 UT | 6 minutes earlier | 6 minutes earlier |
| 24 January 76 CE, 00:49 UT | 1 minute earlier | 1 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
loadNodeDatain Node.js orloadPacksin the browser; the embedded tier omits them. UseengineCapabilitiesto inspect per-body spans. - Chiron and the asteroids have no packs before 1600 CE and cannot be constrained in searches earlier than that.
dateSkysupports 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, usewhen(), which scans at a uniform time step (too slow for multi-millennium ranges).- A
visibilityconstraint 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.