Class: Engine

Constructors

Constructor

new Engine(data): Engine;

Parameters

Parameter	Type
`data`	`EngineData`

Returns

Engine

Properties

Property	Modifier	Type
<a id="data"></a> `data`	`readonly`	`EngineData`

Methods

bodies()

bodies(): BodyId[];

The body ids this engine can compute, given the data pack it was constructed with. The core set is always present; extra asteroids and hypotheticals appear only when their Chebyshev or Kepler packs are loaded.

Returns

BodyId[]

Body ids accepted by Engine.position, Engine.longitude, and Engine.chart.

Example

engine.bodies().includes("ceres"); // true only if the Ceres pack is loaded

chart()

chart(
   y, 
   mo, 
   d, 
   h, 
   mi, 
   s, 
   lat, 
   lonEast, 
   opts?): Chart;

Full natal chart: body positions, house cusps, angles, and aspects for one instant and place.

The first six arguments are calendar fields in UT — not local civil time, and not a Julian Day. Passing a JD in y builds an absurd instant and throws RangeError; use Engine.chartAt for a chart from a JD. For a birth time given in a local time zone, resolve it to UT first (see the caelus-birth package).

Parameters

Parameter	Type	Default value	Description
`y`	`number`	`undefined`	Year in UT, e.g. `1990` — a calendar year, not a Julian Day.
`mo`	`number`	`undefined`	Month, `1`–`12`.
`d`	`number`	`undefined`	Day of month, `1`–`31`.
`h`	`number`	`undefined`	Hour in UT, `0`–`23`.
`mi`	`number`	`undefined`	Minute, `0`–`59`.
`s`	`number`	`undefined`	Second, `0`–`59`.
`lat`	`number`	`undefined`	Geographic latitude in degrees, north positive.
`lonEast`	`number`	`undefined`	Geographic longitude in degrees, east positive (so 82.46° W is `-82.46`).
`opts`	\| `HouseSystem` \| `ChartOptions`	`"placidus"`	A house-system name (e.g. `"placidus"`) or a ChartOptions bag for zodiac, topocentric mode, extra bodies, and custom orbs. Defaults to Placidus houses in the tropical zodiac.

Returns

Chart

A Chart: bodies, cusps, angles, and aspects, plus jdUt and the house system actually used (Placidus and Koch fall back to whole-sign above the polar circles). A body outside its fitted range (e.g. Chiron before ~1850) is omitted from bodies and listed in unavailable rather than failing the whole chart.

Throws

RangeError only if the instant itself is absurd — far outside any supported epoch — which almost always means a Julian Day was passed where calendar fields belong.

Example

// 1990-06-10 14:30 UT at Tampa, FL (27.95° N, 82.46° W), Placidus houses
const chart = engine.chart(1990, 6, 10, 14, 30, 0, 27.95, -82.46, "placidus");
chart.bodies.sun.lon; // Sun's ecliptic longitude, degrees
chart.angles.asc;     // Ascendant, degrees

See

Engine.chartAt to build the same chart from a Julian Day.

chartAt()

chartAt(
   jdUt, 
   lat, 
   lonEast, 
   opts?): Chart;

Full natal chart from a Julian Day (UT) — identical output to Engine.chart, without the calendar round-trip. Reach for this when you already hold a JD: transit and event scans, rankMoments winners, or position/longitude workflows.

Parameters

Parameter	Type	Default value	Description
`jdUt`	`number`	`undefined`	Julian Day in UT, e.g. from julianDay or a scan.
`lat`	`number`	`undefined`	Geographic latitude in degrees, north positive.
`lonEast`	`number`	`undefined`	Geographic longitude in degrees, east positive.
`opts`	\| `HouseSystem` \| `ChartOptions`	`"placidus"`	A house-system name or a ChartOptions bag. Defaults to Placidus houses in the tropical zodiac.

Returns

Chart

The same Chart shape returned by Engine.chart.

Example

const jd = julianDay(1990, 6, 10, 14, 30, 0);
const chart = engine.chartAt(jd, 27.95, -82.46, "placidus");

See

Engine.chart for the calendar-field entry point.

ecliptic()

ecliptic(body, jde): [number, number, number | null];

Low-level apparent geocentric ecliptic coordinates at a TT Julian Day, in radians. This is the engine's internal building block for the events module; it takes TT (not UT) and does no zodiac shift. Most callers want Engine.position (full Position in degrees) or Engine.longitude (longitude in degrees) instead.

Parameters

Parameter	Type	Description
`body`	`BodyId`	A body id from Engine.bodies.
`jde`	`number`	Julian Day in TT (Terrestrial Time), e.g. `jdTT(jdUt)`.

Returns

[number, number, number | null]

[lon, lat, dist] — longitude and latitude in radians (true equinox of date), distance in AU, or null distance for nodes and Lilith points.

Throws

Error if no data is loaded for body.

fixedStar()

fixedStar(
   name, 
   jdUt, 
   opts?): {
  dec: number;
  lat: number;
  lon: number;
  mag: number;
  ra: number;
  sign: string;
  signDeg: number;
};

Apparent place of a catalog fixed star at a Julian Day (UT). Requires the fixed-star catalog to be present in the data pack; see Engine.starNames for the available names.

Parameters

Parameter	Type	Description
`name`	`string`	Catalog star name, e.g. `"Regulus"` (see Engine.starNames).
`jdUt`	`number`	Julian Day in UT.
`opts`	`CalcOptions`	Calculation options; only `zodiac` is meaningful here (tropical by default, or a sidereal ayanamsa).

Returns

{
  dec: number;
  lat: number;
  lon: number;
  mag: number;
  ra: number;
  sign: string;
  signDeg: number;
}

Ecliptic lon/lat, equatorial ra/dec (all degrees), the zodiac sign and signDeg, and the star's visual magnitude mag.

Name	Type
`dec`	`number`
`lat`	`number`
`lon`	`number`
`mag`	`number`
`ra`	`number`
`sign`	`string`
`signDeg`	`number`

Throws

Error if name is not in the loaded catalog.

Example

const regulus = engine.fixedStar("Regulus", julianDay(2025, 1, 1));
regulus.sign;  // e.g. "Leo"
regulus.mag;   // apparent magnitude

heliocentric()

heliocentric(body, jdUt): {
  dist: number;
  lat: number;
  lon: number;
};

Geometric heliocentric ecliptic position (Sun-centred) at a Julian Day (UT), referred to the ecliptic of date. Unlike Engine.position, this is a geometric place — no light-time, aberration, or nutation — and is undefined for the Sun, the Moon, and the lunar nodes.

Parameters

Parameter	Type	Description
`body`	`BodyId`	A Sun-orbiting body (planet or asteroid) from Engine.bodies.
`jdUt`	`number`	Julian Day in UT.

Returns

{
  dist: number;
  lat: number;
  lon: number;
}

Heliocentric lon/lat in degrees and dist in AU.

Name	Type
`dist`	`number`
`lat`	`number`
`lon`	`number`

Throws

Error if body has no heliocentric solution (e.g. the Moon).

longitude()

longitude(
   body, 
   jdUt, 
   opts?): number;

Apparent geocentric ecliptic longitude of a body, in degrees [0, 360), at a Julian Day (UT). The fast path when you need only a longitude — a transit position, an aspect angle, a sign — without the full Position. In the tropical zodiac this is referred to the true equinox of date; sidereal subtracts the ayanamsa.

Parameters

Parameter	Type	Description
`body`	`BodyId`	A body id from Engine.bodies.
`jdUt`	`number`	Julian Day in UT.
`opts`	`CalcOptions`	Calculation options: `zodiac` (tropical or a sidereal ayanamsa), and `topocentric` with an `observer` for a parallax-corrected place.

Returns

number

Ecliptic longitude in degrees, [0, 360).

Example

engine.longitude("mars", julianDay(2025, 6, 1));               // tropical
engine.longitude("mars", julianDay(2025, 6, 1), { zodiac: "sidereal:lahiri" });

See

Engine.position for speed, retrograde, latitude, and distance.

lots()

lots(chart): {
  house: number;
  lon: number;
  lot: string;
  sign: string;
  signDeg: number;
}[];

The seven Hermetic lots of a chart, each placed by sign and house. Sect is read from the Sun (above the horizon -> a day chart). Feed the result to interpretationContext as lots to project lot fact atoms.

Parameters

Parameter	Type	Description
`chart`	`Chart`	A chart from Engine.chart / Engine.chartAt; it must carry the seven classical planets.

Returns

{ house: number; lon: number; lot: string; sign: string; signDeg: number; }[]

One entry per lot with its longitude, sign, signDeg, and house, or an empty array if a required planet is absent.

position()

position(
   body, 
   jdUt, 
   opts?): Position;

Full apparent position of a body at a Julian Day (UT): ecliptic longitude and daily speed (with a retrograde flag), the zodiac sign, ecliptic latitude, geocentric distance, and equatorial right ascension and declination. The general-purpose single-body call; use Engine.longitude when you need only the longitude.

Parameters

Parameter	Type	Description
`body`	`BodyId`	A body id from Engine.bodies.
`jdUt`	`number`	Julian Day in UT.
`opts`	`CalcOptions`	Calculation options: `zodiac` (tropical or a sidereal ayanamsa), and `topocentric` with an `observer` for a parallax-corrected place.

Returns

Position

A Position: lon, speed, retrograde, sign, signDeg, lat, dist (AU; null for nodes and Lilith), ra, dec.

Example

const mars = engine.position("mars", julianDay(2025, 6, 1));
mars.retrograde; // boolean
mars.speed;      // degrees/day (negative when retrograde)

registerRender()

registerRender(id, render): this;

Author how a runtime body should look in SkyView (size, magnitude, colour). Position still comes from registerSource; this owns appearance only.

Parameters

Parameter	Type
`id`	`string`
`render`	`SyntheticRender`

Returns

this

registerSource()

registerSource(id, source): this;

Register a runtime XyzSource under a body id, so it resolves through Engine.position, Engine.longitude, Engine.chartAt, and everything built on them (transits, returns, retrograde, SkyView) with no special-casing — exactly like a baked-in Chebyshev or Kepler pack. The source yields heliocentric ecliptic-J2000 xyz in AU at a TT Julian Day, the same contract Chiron and the Uranian bodies satisfy; the engine applies light-time, aberration, precession and nutation to it like any real body.

This is the seam the synthetic module plugs imaginary bodies into (see registerSyntheticSystem). A registered id shadows a baked-in pack of the same name and persists for the engine's lifetime.

Parameters

Parameter	Type	Description
`id`	`string`	The body id to register (any string).
`source`	`XyzSource`	A heliocentric xyz source; see XyzSource.

Returns

this

This engine, for chaining.

renderFor()

renderFor(id): SyntheticRender | undefined;

SkyView appearance for a registered body, if any.

Parameters

Parameter	Type
`id`	`string`

Returns

SyntheticRender | undefined

starConjunctions()

starConjunctions(chart, opts?): {
  body: string;
  orb: number;
  star: string;
}[];

Fixed-star conjunctions in a chart: each body within orb of a catalog star, in the chart's own zodiac. Feed the result to interpretationContext as stars to project star fact atoms (the Chart itself carries no star catalog).

Parameters

Parameter	Type	Description
`chart`	`Chart`	A chart from Engine.chart / Engine.chartAt.
`opts`	{ `maxMag?`: `number`; `orb?`: `number`; `stars?`: `string`[]; }	`orb` (default 1°); `stars` to restrict to named stars (then no magnitude filter); else `maxMag` keeps only stars brighter than it (default 2.5) so obscure catalog entries do not flood the result.
`opts.maxMag?`	`number`	-
`opts.orb?`	`number`	-
`opts.stars?`	`string`[]	-

Returns

{ body: string; orb: number; star: string; }[]

Conjunctions sorted by increasing orb.

starNames()

starNames(): string[];

The names in the loaded fixed-star catalog, sorted. Empty if no catalog is present in the data pack. Pass any of these to Engine.fixedStar.

Returns

string[]

Sorted catalog star names.

Start building

Quickstart →