Data Tiers

The engine is given its ephemeris data explicitly. Two suppliers ship with the package: the embedded dataset for the browser and edge, and the Node loader for the extended packs. Hosted REST and hosted MCP use the embedded dataset. Stdio caelus-mcp uses the Node loader.

What runs where

Embedded (browser, edge)

caelus/data-embedded bundles a compact dataset: the eight planets, the Moon, Pluto, Chiron, the nodes, and the HYG fixed-star catalog (~13 KB gzipped of the ~153 KB total), with the core house systems and aspects. This is what runs client-side and on edge runtimes, with no files on disk.

import { Engine } from "caelus";
import { embeddedData } from "caelus/data-embedded";

const engine = new Engine(embeddedData);

Node loader (extended)

loadNodeData reads the larger JSON packs from disk: Horizons/DE441 Chebyshev packs for every planet plus Earth, Pluto, the Moon, Chiron, and the asteroids, which supersede the embedded VSOP87D / analytic series wherever they load. These are the packs that carry the validated 1000–3000 range (small bodies 1600–2484). The loader also picks up era slabs ({body}_cheb.classical.json beside each modern pack), which extend the classical seven (Sun via Earth's slab, Moon, Mercury, Venus, Mars, Jupiter, Saturn) from 3000 BCE to the modern packs' shared 1000 CE boundary, resolving each instant from whichever slab covers it. The Uranian points and fixed stars ship too; the Node loader reads the same fixed-star catalog from disk when you load extended packs. Use the Node tier when you need extended bodies, event search, or the wide range.

import { Engine } from "caelus";
import { loadNodeData } from "caelus/node";

const engine = new Engine(loadNodeData());
const star = engine.fixedStar("Aldebaran", jd);

Turbo (bulk longitude scans)

For century-scale work that evaluates a longitude tens of thousands of times (a long transit scan, a returns sweep), the Turbo tier trades generality for speed. A turbo pack is a segmented Chebyshev representation of the engine's own apparent longitude, fit to the engine itself, so one evaluation is a couple of dozen multiply-adds. The pack is data you mint for your range and bodies; the runtime evaluator does no I/O and needs no engine.

import { Turbo } from "caelus";

// pack: a TurboPack you minted for your range/bodies (python/fit_turbo.py).
const turbo = new Turbo(pack);
turbo.has("mars");            // is this body in the pack?
turbo.longitude("mars", jd);  // apparent longitude (degrees), within [jd0, jd1]

Bundle sizes

The choice between client-side and server-side computation comes down to one number: the embedded dataset. The engine code tree-shakes small (a chart-only import drops event search, eclipses, the query and turbo tiers, and the derived and electional layers); the weight a browser pays is the coefficient data it bundles.

So: ship caelus + caelus/data-embedded for full charts in the browser (the data dominates, the code is a small addition on top of your app), or compute server-side through the REST endpoint or the MCP server and ship only caelus-wheel to render the result.