Caelus3,462 checksGitHubv0.25.0MIT
Guides

Rise, set, and sky events

While chart functions calculate planetary positions for a known timestamp, event functions solve for when specific sky events occur: rising, setting, meridian culmination, principal lunar phases, planetary stations, and longitude crossings. All returned timestamps are UT Julian Days.

TypeScript
import {
  Engine, julianDay, riseSet, lunarPhases, stations, crossings,
} from "caelus";
import { embeddedData } from "caelus/data-embedded";

const engine = new Engine(embeddedData);

// Reads a Julian Day as a UTC timestamp.
const utc = (jd) => new Date((jd - 2440587.5) * 86400000).toISOString();

Rise, set, and culmination

riseSet locates the next horizon or meridian crossing after a start timestamp for a given body and observer location, accepting "rise", "set", "mtransit" (upper culmination), or "itransit" (lower culmination):

TypeScript
const day = julianDay(2025, 6, 21);
utc(riseSet(engine, "sun", day, 51.5, -0.13, "rise"));      // London
Event, London, 21 June 2025UT
Sun rises03:43:16
Sun culminates12:02:22
Sun sets20:21:27
Moon rises00:34:46

Longitudes are east-positive. By default, rising and setting track the upper limb under standard atmospheric refraction; pass { discCenter: true } to solve for the disc center, or pass altM, pressure, and tempC to adjust elevation and atmospheric conditions.

When the requested event does not occur within the search window, riseSet returns null. Inside polar circles, that is expected behavior during the midnight sun or polar night (in Tromsø on 21 June, the Sun neither rises nor sets).

Lunar phases

lunarPhases returns the timestamps and names of all four principal lunar phases falling between two Julian Days:

TypeScript
lunarPhases(engine, julianDay(2025, 6, 1), julianDay(2025, 7, 1))
  .map(([jd, phase]) => [utc(jd), phase]);

In June 2025, those phases occur on 3 June at 03:41 UT (first quarter), 11 June at 07:43 UT (full Moon), 18 June at 19:19 UT (last quarter), and 25 June at 10:31 UT (new Moon).

Stations

stations finds every timestamp in a range where a planet reverses its longitudinal direction of motion, paired with whether it turns "retrograde" or "direct":

TypeScript
stations(engine, "mercury", julianDay(2025, 1, 1), julianDay(2026, 1, 1))
  .map(([jd, turns]) => [utc(jd), turns]);
Mercury, 2025Turns
15 March, 06:46 UTretrograde
7 April, 11:08 UTdirect
18 July, 04:44 UTretrograde
11 August, 07:29 UTdirect
9 November, 19:00 UTretrograde
29 November, 17:39 UTdirect

Because apparent velocity drops near zero around a station, small numerical differences amplify timing variance: two ephemerides matching to within an arcsecond can differ by around a minute on the exact station timestamp.

Crossings

crossings returns every timestamp when a body's longitude hits a target degree. Because retrograde motion can bring a planet across the same degree three times, all crossings in the interval are returned in chronological order:

TypeScript
crossings(engine, "sun", 0, julianDay(2025, 1, 1), julianDay(2026, 1, 1)).map(utc);
// one instant: 2025-03-20 09:01:30 UT, the March equinox

To search for conditions that remain true across intervals of time (such as aspects within orb or planets occupying a sign), use when(). To work backward from a full planetary configuration to candidate historical dates, use dateSky.

Start building

Quickstart →