Features

What the engine computes, in one place. The counts are exact, and each links to the accuracy row or guide behind it. Positions are checked against Swiss Ephemeris and JPL Horizons; see Methods.

Bodies

Thirteen in the default chart: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, Chiron, and the mean and true lunar node. On request: mean and true Lilith (lunar apogee), five asteroids (Ceres, Pallas, Juno, Vesta, Pholus), the Uranian/Hamburg points, and a 318-star fixed catalog.

Houses, angles, and zodiacs

Twelve house systems: Placidus, Koch, Porphyry, Equal, Whole-sign, Regiomontanus, Campanus, Alcabitius, Morinus, Meridian, Polich-Page, and Vehlow, with a whole-sign fallback above the polar circles. Angles: Ascendant, Midheaven, vertex, and east point. Zodiac: tropical and seven sidereal ayanamsas (Lahiri, Fagan/Bradley, Krishnamurti, Raman, Yukteshwar, Galactic Center, and Spica). See Houses & Zodiacs.

Aspects and frames

Major aspects (conjunction, sextile, square, trine, opposition) with configurable orbs. Apparent geocentric or topocentric positions, in ecliptic longitude and latitude or right ascension and declination, with light-time, annual aberration, IAU 1980 nutation, and Vondrák 2011 precession.

Events

Rise, set, and meridian transit; longitude crossings; lunar phases; stations; Gauquelin sectors; and solar and lunar eclipses (global circumstances, with types and times). Timing bounds are on Validation.

Derived charts

Solar and lunar returns, secondary progressions, solar arc directions, composite and Davison charts, harmonics, antiscia and contra-antiscia, declination aspects and parallels, out-of-bounds, essential dignities, and sect. See Derived Charts.

Electional

Applying and separating aspects, solar phase (cazimi, combust, under the beams), planetary hours, the void-of-course Moon, and house placement with angularity. These read off the validated positions, pinned to the Python reference.

Query, turbo, and search

A declarative when() query language finds the intervals where celestial predicates hold. Predicates combine with allOf, anyOf, and notOf, and the solver locates the boundaries by bisection. For bulk scans, the turbo tier evaluates segmented Chebyshev longitude packs fit to the engine. For ranked time searches, rankMoments scores every instant in a range and returns the best, with a non-blocking variant for the browser. See Recipes.

Matching and synthesis

A chart reduces to a feature vector, each body's longitude as a weighted point on the unit circle, so two configurations compare by cosine similarity and searchConfigurations ranks a time range by how closely the sky resembles a target form. The geometric compiler runs the other way: give compileForm weighted constraints (an aspect between two bodies, a sign or a degree placement) and it finds the longitudes that best satisfy them, reports the residual, and flags a form as impossible when even the best fit falls short. Both are pure and pinned to the Python reference. See Recipes.

Visualization

The chart as a flat wheel, as a tilted celestial sphere with planets at their true ecliptic latitude, or as an astrocartography world map of the planetary angle lines, plus a graphic ephemeris of any value over time. The 3D aspect angle accounts for latitude rather than longitude alone. Every view renders to SSR-safe SVG with no runtime dependencies. See Visualizations.

Packages

Four npm packages: caelus (the engine, zero runtime dependencies), caelus-birth (timezone and local-time resolution), caelus-wheel (server-rendered SVG charts), and caelus-mcp (the MCP server). The Python reference ships on PyPI as caelus-engine.

Integration

The MCP server exposes nine chart tools over stdio and Streamable HTTP at /api/mcp; a REST endpoint answers at /api/chart. The engine does no file or network I/O, ships an embedded data tier and a Node loader, and runs in the browser, on edge runtimes, and in Node. See MCP Setup and Data Tiers.

Range and license

Supported range 1800–2149, with the precise Moon and Chiron fits spanning 1850–2150. MIT licensed, with no AGPL and no ephemeris files on disk. Provenance for every coefficient is on Provenance.