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.
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):
const day = julianDay(2025, 6, 21);
utc(riseSet(engine, "sun", day, 51.5, -0.13, "rise")); // London| Event, London, 21 June 2025 | UT |
|---|---|
| Sun rises | 03:43:16 |
| Sun culminates | 12:02:22 |
| Sun sets | 20:21:27 |
| Moon rises | 00: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:
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":
stations(engine, "mercury", julianDay(2025, 1, 1), julianDay(2026, 1, 1))
.map(([jd, turns]) => [utc(jd), turns]);| Mercury, 2025 | Turns |
|---|---|
| 15 March, 06:46 UT | retrograde |
| 7 April, 11:08 UT | direct |
| 18 July, 04:44 UT | retrograde |
| 11 August, 07:29 UT | direct |
| 9 November, 19:00 UT | retrograde |
| 29 November, 17:39 UT | direct |
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:
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 equinoxTo 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.