Caelus3,462 checksGitHubv0.25.0MIT
Guides

Uncertain times

A chart is calculated for a single timestamp, yet birth records and historical sources rarely pin down the exact minute. Birth certificates often round to the quarter hour, biographies may record a date with no time, and ancient observations carry clock errors of several minutes. The chartStability function scans a time window around your target timestamp and reports which chart facts hold across the entire window and when any changing facts shift.

The Uncertain Time instrument runs the same scan interactively in your browser, plotting a timeline track for every fact that changes.

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

const engine = new Engine(embeddedData);

// Born 10 June 1990 in Tampa, "about 2:30 in the afternoon" (18:30 UT).
const jd = julianDay(1990, 6, 10, 18, 30);
const { facts, summary } = chartStability(engine, jd, {
  lat: 27.95, lonEast: -82.46,
  halfWidthSeconds: 900,
});

summary;                          // { facts: 61, stable: 60 }
facts.filter((f) => !f.stable);   // the true node's house, and nothing else

With a 15-minute window on either side of the nominal time, 60 of the chart's 61 facts stay fixed. Only the house placement of the true lunar node changes, shifting from the fifth house to the fourth at 18:43 UT.

Supported chart facts

In chartStability, a fact is a single discrete statement derived from a chart. The function tracks six kinds:

KindSubjectValue
angle_signasc or mcThe angle's zodiac sign
sectchart"day" or "night"
signA planet or pointThe body's zodiac sign
houseA planet or pointThe body's house number, 1 to 12
retrogradeA planettrue or false
aspectA pair, "sun-moon"The active aspect name, or null

Each returned fact includes its value at the nominal timestamp, a stable flag, the share of the window during which that value holds, and segments, which splits the window into contiguous intervals of each value. Every boundary between segments marks a transition timestamp resolved to roughly one-second precision.

Scanning an entire day without a birth time

Pass a half-width of twelve hours (43200 seconds) to test the full calendar day when only a date is known:

TypeScript
const day = chartStability(engine, jd, {
  lat: 27.95, lonEast: -82.46, halfWidthSeconds: 43200,
});

day.summary;   // { facts: 64, stable: 42 }

Across the full 24-hour span for this same chart, 42 of 64 facts remain constant: every body stays in the same sign, every planet keeps the same motion direction, and 20 of the 26 active aspects remain within orb. Both angles, the chart sect, and all thirteen house placements change over the day, which is why charts without a birth time are typically read without house cusps. This full-day scan takes roughly 1.6 seconds in Node.js.

If you omit lat and lonEast, chartStability skips location-dependent calculations (angles, houses, and sect) and evaluates only signs, retrograde states, and aspects.

Visualizing uncertainty on the chart wheel

ChartWheel in caelus-wheel can display the uncertainty range directly on a chart diagram. Its uncertainty prop accepts an array of charts sampled across the time window in chronological order and draws an arc showing how far each body and angle travels.

import { Engine, julianDay } from "caelus";
import { embeddedData } from "caelus/data-embedded";
import { ChartWheel } from "caelus-wheel";

const engine = new Engine(embeddedData);
const jd = julianDay(1990, 6, 10, 18, 30);
const at = (minutes: number) =>
  engine.chartAt(jd + minutes / 1440, 27.95, -82.46);

export default function Wheel() {
  // an hour either way, sampled every half hour
  const samples = [-60, -30, 0, 30, 60].map(at);
  return <ChartWheel chart={at(0)} uncertainty={{ samples }} />;
}
♈♉♊♋♌♍♎♏♐♑♒♓123456789101112ACMCDCIC☉19°36'☽15°19'☿28°05'♀13°13'♂7°37'♃14°52'♄24°17'℞♅8°20'℞♆13°49'℞♇15°30'℞⚷15°35'☊8°07'℞
The sample chart for 18:30 UT with a ±1 hour birth-time window. The Ascendant moves 27° and the Midheaven moves 28°, and both cross a sign boundary, so their arcs along the outer rim are drawn heavier with a square marker at the cusp. The Moon moves 1°, visible as a short arc beneath its tick mark, while the remaining planets move by at most 0.13°.

Planetary range arcs appear just inside the zodiac ring, while Ascendant and Midheaven arcs sit near the outer rim (with the Ascendant outermost). Arcs that cross a sign boundary render thicker and display a square marker at the boundary. Two boundary samples are usually enough for planets, whereas the angles rotate roughly 15° per hour and require samples every 30 minutes across multi-hour windows (closing into complete circles over a 24-hour day). The Uncertain Time instrument draws these arcs for any window you configure.

Ancient dates and ΔT uncertainty

When you omit halfWidthSeconds, chartStability defaults to a window radius equal to the one-sigma uncertainty of ΔT at the chart's epoch. For modern dates, that uncertainty is under a second, so all facts stay stable by default. For a chart in 100 CE, ΔT uncertainty reaches 155 seconds, enough to shift the Ascendant by two-thirds of a degree, and chartStability reports which facts that clock margin puts at risk. The same uncertainty triggers the delta_t_uncertain warning on standard charts and appears in the epochSigma block of canonical output.

Position uncertainty for a single body

To measure longitude uncertainty for an individual body rather than discrete chart facts, call positionUncertainty. It returns ephemeris model error and clock-induced error as separate numbers so they stay distinguishable:

import { positionUncertainty, julianDay } from "caelus";

positionUncertainty(engine, "moon", julianDay(1500, 6, 1, 12, 0, 0, "julian"));
// { modelBoundArcsec: 3, deltaTSigmaSeconds: 15.0, clockSigmaArcsec: 7.5, ... }

modelBoundArcsec is the body's worst-case error measured against JPL Horizons across the validated date range, or null when the timestamp falls outside that range (positions are still calculated outside the span, without a published accuracy guarantee). clockSigmaArcsec measures the one-sigma spread caused by ΔT uncertainty, equal to the body's angular speed multiplied by deltaTSigmaSeconds.

TimestampBodyModel boundΔT sigmaClock uncertainty
2000Moon3″0.06 s0.03″
1500Moon3″15 s7.5″
1500Saturn1″15 s0.08″
100Moonnone published155 s76″
100Saturnnone published155 s0.19″
1000 BCEMoonnone published1,440 s711″
1000 BCESaturnnone published1,440 s1.8″

In 1500 CE, the Moon's 3″ ephemeris model bound is already smaller than the 7.5″ spread caused by clock uncertainty. By 1000 BCE, the Moon's position varies by nearly twelve arcminutes while Saturn shifts by less than two arcseconds.

MCP integration

AI clients can run this same scan via the chart_stability tool. It accepts a timestamp, uncertainty_minutes, and optional coordinates, returning the list of stable facts alongside transition timestamps for any unstable ones. Setup instructions are in the MCP guide.

Options

OptionDefaultDescription
lat, lonEastnoneObserver coordinates in degrees (supply both or omit both).
halfWidthSecondsΔT one-sigmaHalf-width of the time window in seconds.
houseSystem"placidus"House system identifier, as in chartAt.
zodiac"tropical"Zodiac reference frame, as in chartAt.
orbsdefault orbsOptional per-aspect orb overrides.
stepSeconds120Initial sampling step in seconds before boundary bisection.

Limits

  • Because the scan samples every two minutes by default, a fact that flips and reverts within a single step can be missed (most likely when a body sits right on a quadrant house cusp at high latitudes).
  • Time windows do not account for uncertainty in geographic coordinates.
  • Aspects are tracked as binary states (in orb or out of orb); an aspect whose exactness tightens or loosens while remaining within orb is reported as stable.

Start building

Quickstart →