Reference · v0.23.0
API Reference
Generated from the caelus package with TypeDoc. Regenerate with npm run docs:api. The tiers below mark what to build against; the full alphabetical index follows. See Edge Cases & Stability for the versioning contract.
Recommended
The surface most applications build against. Start here.
Advanced
Stable but specialized: reach for these when the recommended surface does not cover the case. The Engine already calls most of them for you.
Internal / unstable
The engine's own astronomy machinery: series evaluators, apparent-position builders, and raw constants. Exported for inspection and tests; not a stable contract. Prefer the Engine over calling these directly.
The Engine
Construct one Engine from a data pack, then call these methods, the surface most code uses. Every method links straight to its signature and parameters.
Charts
chart()Full chart from calendar fields in UT (year, month, day, hour, minute, second).
chartAt()The same chart straight from a Julian Day (UT), no calendar round-trip.
Positions
position()Full Position at a JD: lon, speed, retrograde, sign, lat, distance, ra/dec.
longitude()Apparent geocentric ecliptic longitude (deg) at a JD.
heliocentric()Geometric heliocentric ecliptic (lon, lat, distance in AU).
ecliptic()Raw apparent [lon, lat, dist] building block; most callers want position().
Fixed stars & introspection
fixedStar()Apparent place of a catalog star: lon/lat/ra/dec, sign, magnitude.
starNames()Names in the loaded fixed-star catalog.
starConjunctions()A chart's bodies within orb of catalog stars; feeds star fact atoms.
lots()The seven Hermetic lots placed by sign and house; feeds lot fact atoms.
bodies()Body ids this engine can compute, given its data.
registerSource()Register a runtime heliocentric xyz source under any body id.
registerRender()Author SkyView appearance (size, magnitude, colour) for a registered body.
renderFor()SkyView render attrs for a registered body, if any.
Synthetic ephemeris
syntheticPositions()World-frame positions for every body in an authored system at one instant.
syntheticEphemeris()Reusable position source with speed, retrograde, and validation diagnosis.
registerSyntheticSystem()Drop authored bodies onto an Engine for returns, transits, SkyView.
validateSyntheticSystem()Flag ill-defined synthetic systems (impossible / problems).
Full index
caelus
Classes
| Class | Description |
|---|---|
| ChebSeries | - |
| Engine | - |
| KeplerOrbit | Constant-element two-body orbit with the same xyz(jde) interface as ChebSeries, so chironApparent takes either. |
| Turbo | Runtime evaluator for a turbo pack — a segmented Chebyshev fit of the engine's apparent longitude over a fixed range and body set. Evaluating a longitude costs a couple dozen multiply-adds, so a century-scale transit scan that calls it tens of thousands of times runs in milliseconds. Construct one from a pack you minted offline; it does no fitting, no I/O, and needs no Engine. |
Interfaces
| Interface | Description |
|---|---|
| AnchoredChart | A chart described by its realm and anchors, not a bare (instant, place). |
| AnchorRegistry | Lookups an anchor may need to resolve: prior instants/places for relative anchors, calendar resolvers for narrative times, a gazetteer for named places. All optional; an anchor that needs a missing one resolves to null. |
| AngleAtom | - |
| AngleChange | An angle whose sign changed. |
| AngleLines | - |
| AshtottariActive | - |
| AshtottariPeriod | - |
| AshtottariSub | - |
| AshtottariTimeline | - |
| Aspect | One aspect between two bodies in a Chart. |
| AspectAtom | - |
| AspectMatch | - |
| BodyChange | A body whose sign or house changed between two charts. |
| BodyPositionSource | A pluggable position-over-time source: the same shape every derived computation needs from a body. Returned by syntheticEphemeris. |
| Brief | A chart rendered as citable LLM input. |
| BriefFact | A salience-ranked fact in a Brief. |
| BriefOptions | - |
| CalcOptions | Options shared by the single-body calls (Engine.position, Engine.longitude) and by charts. |
| CelestialPole | The visible celestial pole: the fixed point the whole sky rotates about as time passes (north pole for northern observers, south for southern). Its altitude equals the observer's |
| Chart | A full natal chart, as returned by Engine.chart and Engine.chartAt. Longitudes are degrees in the chart's zodiac. |
| ChartBody | A Position enriched with chart-relative placement, as returned per body by Engine.chart and Engine.chartAt. |
| ChartDiff | What differs between two charts. |
| ChartLots | - |
| ChartOptions | Options for Engine.chart and Engine.chartAt, extending CalcOptions. |
| ChartPattern | One configuration found in a chart. |
| ChartSignature | - |
| CitationAudit | The result of auditCitations. |
| Claim | A model-produced statement and the fact ids it claims to rest on. |
| CompiledForm | - |
| CompileOptions | - |
| CompositeAtom | - |
| CompositePlacement | A composite-chart body placement (midpoint method). |
| ConstellationPack | Constellation figure lines and labels; vertices as ecliptic J2000 (lon, lat) degrees. Built by scripts/build-constellations.mjs from d3-celestial. |
| ContextOptions | - |
| Counterfactual | A counterfactual: a base chart and a perturbed variant, with the diff. |
| CounterfactualEdit | A perturbation of a resolved chart. |
| Dasha | - |
| DashaActive | - |
| DashaSub | - |
| DashaTimeline | - |
| DeclinationPair | - |
| DignityAtom | - |
| DignityScore | The essential-dignity breakdown of a planet at a longitude. |
| DirectionArcs | - |
| DispositorAtom | - |
| EclipsePath | The umbra/antumbra path of a solar eclipse at one instant. |
| EngineData | - |
| EnrichFlags | - |
| EnrichTarget | - |
| EphemerisOptions | - |
| EphemerisPoint | - |
| FeatureOptions | - |
| FirdariaPeriod | - |
| FirdariaSub | - |
| GeoPlace | Resolved coordinates a chart can be computed at. |
| GeoPoint | Geographic point on the Earth's surface (geodetic latitude, east longitude). |
| InterpretationContext | A chart as a flat, ranked list of FactAtoms. |
| InterpretationSource | A pluggable corpus of rules: a tradition, a house style, a third party. |
| Kemadruma | - |
| LordPairYoga | - |
| LotAtom | - |
| LunarEclipse | - |
| LunarLocal | Whether a lunar eclipse is up at a place, and how high the Moon stands. |
| Match | The result of a Selector: did it match, and on which atoms. |
| MilkyWay | The Milky Way band's appearance in the frame. Visible only in a dark sky (astronomical twilight or night) without a bright Moon or heavy light pollution. The band is the galactic equator; its bright bulge is the galactic center in Sagittarius. |
| MundaneDirection | - |
| Nakshatra | - |
| NakshatraAtom | - |
| Observer | - |
| OverlayLine | An in-frame polyline (the ecliptic, a constellation figure stroke). |
| OverlayMark | A labeled point projected into the frame (sign, house, constellation name). |
| Paran | One co-angular pair: bodies a and b on the named angles at ~the same time. |
| PatternAtom | - |
| PatternBody | A body's longitude (and house, for stelliums) for detectPatternsIn. |
| PatternOptions | - |
| Pheno | - |
| PlacementAtom | - |
| PlanetaryHour | - |
| Position | A body's full apparent position, as returned by Engine.position. |
| Predicate | Margin function (true where >= 0) carrying the bodies it depends on. |
| PrimaryDirection | - |
| ProfectedSign | - |
| Profection | - |
| RankedMoment | - |
| RankOptions | astroengine scan -- long-scan ergonomics over the engine: a batched scan with progress, and rankMoments to find the best instants by a score, synchronously or without blocking the event loop. |
| Reading | A resolved interpretation: ranked entries, each citing its facts. |
| ReadingEntry | One licensed statement in a Reading, with its provenance. |
| ReadingGroup | Entries about the same facts, gathered. |
| RealizedChart | The outcome of realize: how (or whether) a chart was produced. |
| ReceptionAtom | - |
| ReconcileOptions | - |
| RenderLayer | One layer of the hybrid render: what Caelus computes and the pipeline composites locally over the image-model background plate. |
| RenderPlan | A machine-readable render contract for a hybrid pipeline: ask an image model for a body-free background plate, then composite the computed layers (bodies, stars, the Milky Way, overlays) locally at their exact pixels. The image model supplies atmosphere; Caelus supplies the physically correct objects. This is the structured complement to prompt, which is for humans and image models. |
| ResolvedPlace | The outcome of resolving a SpatialAnchor. |
| ResolvedTime | The outcome of resolving a TemporalAnchor. |
| RiseSetOptions | - |
| Rule | One interpretation: a condition and the text it licenses. |
| SalienceWeights | Additive salience weights. Each contribution is documented at its use site; override any subset through ContextOptions.salience. |
| ScanOptions | astroengine scan -- long-scan ergonomics over the engine: a batched scan with progress, and rankMoments to find the best instants by a score, synchronously or without blocking the event loop. |
| SearchConfigOptions | - |
| SignatureAtom | - |
| SignatureBody | A body's longitude (and house) for chartSignatureOf. |
| SignatureOptions | - |
| SkyAim | - |
| SkyBody | - |
| SkyLens | A resolved lens: field of view and projection actually used. |
| SkyOffFrameBody | - |
| SkySummary | - |
| SkyViewOptions | - |
| SkyViewOverlays | Projected reference-frame overlays. Each is null when not requested; arrays hold only the in-frame parts. Pixels match the bodies' coordinate system. |
| SkyViewOverlaysRequest | Which reference frames to project. The ecliptic, the zodiac signs (its 30 degree divisions), the house cusps and angles, and the constellation figure lines. These are annotations: real reference frames drawn over the sky, not things a camera sees. |
| SkyViewResult | - |
| SkyViewSequence | - |
| SkyViewSequenceSpec | - |
| SkyViewSpec | - |
| SolarEclipse | - |
| SolarLocal | Local circumstances of a solar eclipse seen from one place. |
| SourceRegistrar | A type guard for the surface registerSyntheticSystem needs, so the synthetic module does not import the heavy Engine class. |
| StarAtom | - |
| StarEntry | - |
| StarfieldSummary | What the star field in bodies represents. A deep field is the complete naked-eye sky to limitingMag, pinned at exact pixels (animation-grade); a named field is the bright catalog, to be fleshed out by the model. |
| StarPack | - |
| StarParan | One star-to-body paran: a fixed star and a body on angles at ~the same time. |
| SynastryAspectHit | An inter-chart aspect between person A's body and person B's body. |
| SynastryAtom | - |
| SynastryOverlays | - |
| SyntheticDiagnosis | Why a system is unsatisfiable, if it is — the impossible/residual honesty pattern, mirroring CompiledForm. A system with problems still computes for the bodies that are individually valid, but flags the rest rather than silently producing garbage. |
| SyntheticPosition | A body's position at one instant, in degrees and system length units. |
| SyntheticRender | Render attributes for a synthetic body — how an imaginary body should look in a SkyView frame. The engine owns position; these own appearance, so a body stays visually consistent across skyViewSequence frames. |
| SyntheticSystem | An authored celestial system: a set of SyntheticBody that move together, an optional observer body that fixes the vantage point, and optional per-body SyntheticRender attributes. |
| TimelordAtom | - |
| TransitAtom | - |
| TransitHit | A transiting body aspecting a natal point. |
| TurboBody | - |
| TurboPack | - |
| Varga | - |
| VargaAtom | - |
| VoidOfCourse | - |
| WhenOptions | - |
| XyzSource | Anything that yields heliocentric ecliptic-J2000 xyz (AU) at a TT jd: ChebSeries (fitted small bodies) or KeplerOrbit (Uranian bodies). |
| Yoga | - |
| YogaAtom | - |
| YoginiActive | - |
| YoginiPeriod | - |
| YoginiSub | - |
| YoginiTimeline | - |
| ZrActive | - |
| ZrPeriod | - |
Type Aliases
| Type Alias | Description |
|---|---|
| AlwaysBody | Bodies guaranteed to be in every chart: the analytic Sun–Pluto and the lunar nodes, which resolve across all supported epochs. (Chiron is Chebyshev-packed and can fall outside its fitted range, so it is not guaranteed.) |
| AspectPhase | - |
| Ayanamsa | - |
| Body | - |
| BodyId | Core names keep autocomplete; any string id is accepted (data packs). |
| Certainty | How trustworthy a resolved instant/place is for computation. |
| ChartBodies | A chart's bodies, keyed by id. The analytic core (AlwaysBody) is always present and needs no presence check. PackedBody bodies (Chiron) and any opt-in extras requested via ChartOptions.bodies may be absent when the instant is outside their fitted range (see Chart.unavailable), so those accesses are typed `ChartBody |
| ChebData | - |
| Constraint | - |
| DeclinationKind | - |
| Element | - |
| EphemerisValue | - |
| FactAtom | - |
| FactKind | Atom kinds in an InterpretationContext. |
| HermeticLot | - |
| HouseSystem | - |
| Interval | - |
| KeplerElements | - |
| KeplerPack | - |
| LensSpec | - |
| Modality | - |
| MoonSeries | - |
| PackedBody | Default chart bodies that are Chebyshev-packed, so they can fall outside their fitted range (and be omitted from a chart). Opt-in asteroids are packed too, but arrive as arbitrary ids through the string index. |
| PhaseName | - |
| Realm | What a chart's subject is -- its epistemic / ontological status. |
| RiseKind | - |
| Sect | - |
| Selector | Tests a whole InterpretationContext and reports the matching atoms. |
| SkyProjection | - |
| SolarPhase | - |
| SpatialAnchor | How a chart's place is known -- the spatial twin of TemporalAnchor. |
| SyntheticBody | A single authored body. Its id is how every consumer (charts, transits, SkyView) refers to it. |
| TemporalAnchor | How a chart's time is known. |
| TwilightStage | - |
| Vec3 | - |
| VsopSeries | - |
| Zodiac | - |
Variables
| Variable | Description |
|---|---|
| ARCSEC | - |
| ASHTOTTARI_ORDER | - |
| ASHTOTTARI_YEARS | - |
| ASPECTS | - |
| AYANAMSA_J2000 | Mean ayanamsa at J2000.0 (degrees) per mode. Standard epoch anchors (matched to Swiss Ephemeris 2.10 to 1e-9 deg); propagation uses Vondrak 2011 ecliptic precession, the same model Swiss Ephemeris uses: agreement over 1900-2099 is <=0.005 arcsec. |
| BODIES | - |
| BRIEF_INSTRUCTIONS | Default instruction header prepended to Brief.prompt. |
| CAZIMI_DEG | - |
| COMBUST_DEG | - |
| DASHA_YEAR | - |
| DEFAULT_BODIES | - |
| DEFAULT_ORBS | - |
| DEFAULT_PARAN_BODIES | - |
| DEFAULT_SALIENCE | - |
| DEG | astroengine core -- clean-room ephemeris engine (TypeScript port). |
| DHANA_HOUSES | - |
| DIAMETER_KM | Equatorial diameters, km (IAU values, as used by Swiss Ephemeris). |
| DIGNITY_WEIGHTS | - |
| DOMICILE | - |
| DRISHTI | Graha drishti: the house-distances (1-based) each planet aspects. |
| EARTH_RADIUS_AU | - |
| ELEMENTS | - |
| EXALTATION | - |
| EXTRA_BODIES | Computable on request (not in the default chart set). |
| FACE_CYCLE | Faces (decans): Chaldean order from Mars at 0 Aries; floor(lon/10) selects. |
| FIRDARIA_ORDER | The firdaria cycle of the seven planets. |
| FIRDARIA_YEARS | Period length in years for each of the seven planets. |
| HERMETIC_LOTS | The seven Hermetic lots, in their conventional order. |
| HOUSE_SYSTEMS | The canonical house-system ids, in a stable order (also used for error text). |
| J2000 | - |
| KENDRAS | - |
| KEYS | Degrees of arc that equal one year of life, per time key. |
| LENS_NAMES | - |
| LEVEL_UNIT | Days per period unit at each level (each a twelfth of the one above). |
| LIGHT_TIME_AU | - |
| MODALITIES | - |
| NAK_SPAN | - |
| NAKSHATRAS | - |
| NODE_PERIODS | The two nodes close the sequence with no sub-periods (70 + 5 = 75 years). |
| NOT_ASPECTABLE | Points: excluded from aspect search by default. |
| PARAN_ANGLES | - |
| PATTERN_ANGLES | Pattern aspects, including the quincunx the default Ptolemaic set omits. |
| PATTERN_ORBS | Default orbs: DEFAULT_ORBS for the five Ptolemaic aspects, plus a tight quincunx. Override via PatternOptions.orbs. |
| PLANETS | - |
| QUERY_ASPECTS | - |
| SIGN_RULERS | Traditional (domicile) ruler of each sign, Aries..Pisces. |
| SIGNS | - |
| TERMS_EGYPTIAN | Egyptian terms (Ptolemy I.21): per sign, [ruler, upper-degree] segments. |
| TIME_ANCHORED_REALMS | Realms whose charts come from a time + place (the ephemeris path). The rest (archetypal, conceptual, mythic) are better generated from constraints via the compiler, since they have no instant to compute from. |
| TRADITIONAL | - |
| TRIKONAS | - |
| TRIPLICITY | Dorothean triplicity rulers by element (sign%4), as [day, night, participating]. |
| TROPICAL_YEAR | - |
| UNDER_BEAMS_DEG | - |
| VARGA_DIVISIONS | Supported divisions. |
| VIMSHOTTARI_ORDER | The Vimshottari order and each lord's period in years (totalling 120). |
| VIMSHOTTARI_YEARS | - |
| YOGA_PLANETS | - |
| YOGINI_LORDS | - |
| YOGINI_YEARS | Period in years by yogini index (Mangala..Sankata), totalling 36. |
| YOGINIS | - |
| ZR_PERIODS | Period length in 360-day years for each sign, Aries..Pisces. |
Functions
| Function | Description |
|---|---|
| allOf | True where every predicate is true (interval intersection). |
| almuten | The almuten of a degree: the classical planet with the greatest positive essential dignity (rulership + exaltation + triplicity + term + face) at lon. Ties broken by the canonical planet order. |
| angles | Ascendant, MC, ARMC, obliquity. East longitude positive. |
| angularity | angular / succedent / cadent for a 1-based house number. |
| angularSeparation3d | True great-circle angle (degrees) between two bodies from their ecliptic longitude and latitude. With both latitudes zero this is the unsigned longitude difference; latitude pulls the two apart in three dimensions. |
| antiscion | Reflection across the solstice (Cancer-Capricorn) axis. |
| anyOf | True where any predicate is true (interval union). |
| ashtottariActive | The maha and antar lord active at targetJd; null before the first period. |
| ashtottariAt | Ashtottari dasha active at targetJd, from the natal Moon's nakshatra. |
| ashtottariDashas | The Ashtottari dasha timeline from the Moon's sidereal longitude. |
| ashtottariLord | The Ashtottari dasha lord governing a nakshatra index (0-based). |
| aspect | A Predicate that holds while body is within orb degrees of an exact aspect to target. Feed it to when to find the time windows, or compose it with allOf/anyOf. |
| aspectBetween | The tightest major aspect between two bodies at jd, within orb, or null. orb is the signed distance from exact (degrees). |
| aspectPhase | Applying/separating/exact for the aspect (degrees) between body a and body b, from their longitudes and longitude speeds (deg/day). Applying = the orb to the exact aspect is closing. |
| aspectsSign | Whether planet at planetSign casts a graha drishti onto targetSign. |
| associationType | How two planets associate: "conjunction" |
| astrocartography | Angle lines for each body at jdUt: { body: AngleLines }. |
| auditCitations | Check that a model's claims cite only facts that exist in the context -- the accuracy half of "novel and accurate". A claim citing an id not in ctx fabricated its provenance, so ok is false and the id lands in unknown. |
| ayanamsa | Mean ayanamsa in degrees. Sidereal longitude = (tropical true-equinox longitude - nutation in longitude) - ayanamsa: the sidereal zodiac is anchored to the mean equinox. |
| azAlt | Apparent ecliptic position -> azimuth (deg, from true north, east- positive) and true altitude (deg). No refraction. |
| bodySource | The heliocentric xyz source for one authored body — the per-body engine behind every tier, and the exact object Engine.registerSource consumes. |
| chartBrief | Render an InterpretationContext as a compact, id-tagged Brief for an LLM to interpret and cite. |
| chartDiff | Diff two charts: body sign/house shifts, aspects gained/lost, angle sign changes. Bodies and angles that did not change sign/house are omitted. |
| chartFeatures | Encode the sky at an instant as a feature vector: each body's ecliptic longitude becomes a weighted unit-circle point. The deterministic substrate for matching and searching chart configurations — compare two with cosineSimilarity, or rank a time range against one with searchConfigurations. |
| chartSignature | The structural signature of a Chart: element / modality / angularity / quadrant / hemisphere distributions over its bodies, the dominant element, modality, and most-occupied sign, and the classical chart ruler. Counts only, no interpretation. Bodies absent from the chart (outside their fitted range) are skipped. |
| chartSignatureOf | Structural counts for a body map. Lower-level form of chartSignature: bodies maps a body id to { lon, house? }. |
| chironApparent | - |
| compileForm | Synthesize a chart form from geometric constraints — the inverse of (time, place) → chart. Given weighted Constraints (aspects between bodies, sign placements, exact degrees), find the body longitudes that best satisfy them via deterministic coordinate descent, and report how well they can be met. When even the best fit is poor, the form is flagged impossible — a valid, informative result. |
| compositeLongitudes | Midpoint-method composite: the shorter-arc midpoint of each body's two longitudes. Angles compose the same way via midpointLon on the two ASC/MC. |
| compositePlacements | Midpoint-composite placements for bodies from two birth instants. |
| configurationFit | Similarity between the sky at jdUt and a target feature vector — shorthand for cosineSimilarity(chartFeatures(engine, jdUt, opts), target). The scoring function searchConfigurations maximizes. |
| constraintLoss | Degrees by which a single Constraint is unmet for a set of body longitudes — 0 when satisfied. The pure building block of formLoss and compileForm. |
| contraAntiscion | Reflection across the equinox (Aries-Libra) axis. |
| cosineSimilarity | Cosine similarity of two feature vectors, in [-1, 1]. For vectors from chartFeatures this is a weighted mean of cos(Δlongitude) per body: 1 when the configurations coincide, falling off as bodies diverge. |
| counterfactual | Realize an AnchoredChart, then apply a CounterfactualEdit and diff the result -- "a real event, perturbed." A time/place edit recomputes the ephemeris; a setLongitudes edit splices the geometry. |
| crossings | UT JDs where the body's apparent longitude crosses targetLon (degrees) in [jdStart, jdEnd]. Retrograde bodies can cross a degree three times; every crossing is returned in time order. |
| davisonParams | Time and place for a Davison relationship chart: the temporal midpoint and the geographic midpoint (mean latitude, shorter-arc mean longitude). Compute a normal chart at these to get the Davison chart. Returns [jd, lat, lonEast]. |
| declinationAspect | Classify two declinations: parallel (same), contraparallel (opposite), null. |
| declinationAspects | Parallels and contraparallels among a set of bodies at an instant: pairs whose declinations are equal (parallel) or equal and opposite (contraparallel) within orb — the declination analogue of conjunction and opposition. |
| deltaT | ΔT (TT − UT1) in seconds at a given instant — the gap between Terrestrial Time and universal time. Observed IERS values 1955–2025, Espenak–Meeus polynomials before, and a gentle extrapolation after (Earth's rotation sped up post-2016). The engine applies this for you; call it directly only for timescale work. |
| detectPatterns | The aspect configurations present in a Chart: T-squares, grand trines, grand crosses, yods, kites, mystic rectangles, and stelliums by sign and by house. Bodies outside their fitted range (absent from the chart) are skipped. |
| detectPatternsIn | The configurations present among a body map. Lower-level form of detectPatterns: bodies maps a body id to { lon, house? }. |
| detectYogas | The placement yogas present in a chart. signs maps each of the seven classical planets to its 0-based sign index; ascSign is the Ascendant's sign index. |
| dhanaYogas | Dhana yogas: associations between two wealth-house (2/5/9/11) lords. |
| dhanaYogasAt | Dhana yogas of a natal chart. |
| dignities | Essential dignities a body holds in a sign: any of "domicile", "exaltation", "detriment", "fall" (the last two are the signs opposite domicile and exaltation). Empty when the body is peregrine there or has no classical rulership (the outer planets, Chiron, the nodes). |
| dignityOf | - |
| dignityScore | The weighted essential dignities of planet at ecliptic longitude lon (degrees) in a day or night chart. Only the seven classical planets score. |
| directedLongitude | - |
| directionArcs | Direct primary-direction arcs (degrees, [0, 360)) of a body at right ascension alpha and declination delta to the four angles, for latitude phi and right ascension of the MC ramc. asc/dsc are null when the body is circumpolar. |
| directionYears | Years of life corresponding to an arc of direction under a time key. |
| element | Triplicity (element) of a sign: "fire", "earth", "air", or "water". |
| enrichContextOptions | Build ContextOptions extras for a natal chart evaluated at target. Merge the result into interpretationContext(chart, { ...base, ...extras }). |
| enrichSynastryOptions | Synastry and composite atoms for two natal charts (A is the projection base). |
| ephemeris | Sample value for each body across [start, end], returning per-body series in time order. |
| equationOfTime | Apparent minus mean solar time, minutes (Meeus ch. 28). |
| equatorial | Ecliptic lon/lat -> right ascension, declination (all radians). |
| faceRuler | - |
| featureVector | Build a feature vector from explicit (longitude, weight) pairs: each pair contributes a weighted unit-circle point [w·cos(lon), w·sin(lon)]. The low-level primitive behind chartFeatures; most callers want that. |
| findAspects | - |
| firdaria | The full firdaria timeline from birth. |
| firdariaActive | The major and sub firdar lord active at targetJd; both null outside the 75-year span. |
| firdariaAt | The active firdar at targetJd, taking the chart's sect from the natal moment and place. |
| firdariaSequence | The nine major firdaria periods in order, as [lord, years] pairs. |
| fmtLon | - |
| formLoss | Total weighted loss for a set of body longitudes — the sum of each constraint's constraintLoss times its weight. The objective compileForm minimizes. |
| gast | Greenwich apparent sidereal time. |
| gauquelinSector | The Gauquelin sector of a body (1–36, fractional) from the rise/set times of the disc centre with refraction (Swiss Ephemeris method 3). Sectors run from rise: 1–18 above the horizon, 19–36 below. |
| gmst | Greenwich mean sidereal time, radians (IAU 1982 / Meeus 12.4). |
| harmonicChart | The nth-harmonic chart: each body's longitude multiplied by n and wrapped to [0, 360). The 5th harmonic surfaces quintiles, the 9th the navamsa, and so on. |
| harmonicLongitude | The nth-harmonic longitude of a point: lon * n, wrapped to 360. |
| hasAngle | Matches an angle atom by which angle and/or its sign. |
| hasAspect | Matches aspect atoms. between is an unordered pair; minStrength filters loose aspects; phase filters applying/separating. |
| hasComposite | Matches a composite midpoint placement. |
| hasDignityFine | Matches finer essential-dignity facts (term, face, triplicity, almuten). |
| hasDispositor | Matches dispositor atoms by body, its dispositor, and/or the final flag (a body in its own domicile that terminates a dispositor chain). |
| hasLot | Matches a Hermetic lot by name, and/or its sign or house. |
| hasNakshatra | Matches a nakshatra placement. |
| hasPattern | Matches configuration atoms by kind and/or a participating body. |
| hasPlacement | Matches placement atoms by any subset of body / sign / house / retrograde / a held dignity. |
| hasReception | Matches a mutual reception, optionally involving a given body. |
| hasSignature | Matches a structural-signature facet, e.g. ("element", "fire"). |
| hasStar | Matches a fixed-star conjunction by the catalog star and/or the body on it. |
| hasSynastry | Matches synastry aspect or house-overlay atoms. |
| hasTimelord | Matches an active time-lord period. |
| hasTransit | Matches transit-to-natal aspect atoms. |
| hasVarga | Matches a varga (divisional chart) placement. |
| hasYoga | Matches a classical yoga. |
| hermeticLots | The seven Hermetic lots from the Ascendant, sect, and the seven planets' longitudes (degrees). Pure arithmetic. |
| houseCusp | Ecliptic longitude where the house circle with pole pole crosses the ecliptic; ra measured like ARMC. The Ascendant is houseCusp(armc+90, phi); the MC is houseCusp(armc, 0). |
| houseFromAsc | The whole-sign house (1-12) a sign falls in from the Ascendant. |
| houseLord | The lord of the given whole-sign house from the Ascendant. |
| houseOf | 1-based house number for an ecliptic longitude (degrees) given the twelve cusps (degrees), wrapping across 0. |
| housesAlcabitius | Alcabitius: trisect the Ascendant degree's semi-arcs in right ascension; project cusps along meridians. |
| housesCampanus | Campanus: equal divisions of the prime vertical. House circles run through the horizon's north/south points; cusps are their ecliptic crossings, assigned in zodiacal order MC->ASC->IC. |
| housesEqual | - |
| houseSign | The sign on the given whole-sign house (1-12) from the Ascendant. |
| housesKoch | Koch (birthplace): cusps are ascendants at ARMC +/- k/3 of the MC degree's diurnal semi-arc. Throws where the MC degree is circumpolar ( |
| housesMeridian | Meridian (axial rotation): equal RA divisions projected along hour circles. Latitude-independent. |
| housesMorinus | Morinus: equal RA divisions projected onto the ecliptic by great circles through the ecliptic poles. Latitude-independent. |
| housesPlacidus | Placidus house cusps via the classic iterative semi-arc scheme: for all four intermediate cusps RA = ARMC + offset + f·AD with AD = asin(tan φ · tan δ); offsets 30/60/120/150, f = 1/3, 2/3, 2/3, 1/3. Undefined above the polar circles, as Placidus itself is. |
| housesPolichPage | Polich-Page ('topocentric'): cusp poles tan P = (k/3) tan(phi). |
| housesPorphyry | - |
| housesRegiomontanus | Regiomontanus: equal divisions of the celestial equator; cusp poles tan P = tan(phi) sin(H). |
| housesVehlow | Vehlow: equal houses with the ASC at the middle of house 1. |
| housesWholeSign | - |
| inSect | - |
| inSign | True while body is in sign (index 0=Aries..11=Pisces, or name). |
| interpret | Run interpretation sources against a fact projection and return a ranked Reading. Each rule whose selector matches emits an entry carrying the matched atom ids (provenance) and a salience = sum of those atoms' salience x the rule weight. The engine never ships the content: the sources are the caller's. |
| interpretationContext | Project a Chart into a ranked list of FactAtoms -- the substrate an interpretation layer consumes. Pure and deterministic; computes applying/separating and a normalized strength for each aspect that the bare Chart.aspects list omits. |
| isDayChart | Diurnal when the Sun is above the horizon at the given place. |
| isoToJd | ISO-8601 timestamp -> UT Julian Day, or null when unparseable. |
| isTimeAnchored | Whether a realm is normally grounded in an instant (ephemeris) rather than synthesized from symbolic constraints. |
| jdTT | - |
| julianDay | Convert a UT calendar date and time to a Julian Day (UT) — the time coordinate the engine consumes. Pass the result to Engine.position, Engine.longitude, Engine.chartAt, and the event/derived functions; Engine.chart takes the calendar fields directly instead. |
| kemadruma | Kemadruma yoga: the Moon is isolated -- no planet in the 2nd or 12th sign from it, nor conjunct it. The planet set is parameterized (texts vary): the default is the five tara grahas, includeSun adds the Sun, includeNodes adds Rahu/Ketu when present in signs. |
| kemadrumaAt | Kemadruma yoga of a natal chart, from the sidereal rasi positions. |
| lotFortune | Lot of Fortune: Asc + Moon - Sun by day, Asc + Sun - Moon by night. |
| lots | The seven Hermetic lots of a chart: compute the Ascendant and sect, then the lots from the seven planets' longitudes. |
| lotSpirit | Lot of Spirit (the reverse of Fortune): Asc + Sun - Moon by day. |
| lunarEclipseLocal | Local visibility of a lunar eclipse: a lunar eclipse happens at the same instant for the whole Earth, so "local circumstances" is simply whether the Moon is up. Pass a contact time (e.g. LunarEclipse.tMax or a phase boundary) to learn whether that phase is visible from a place. |
| lunarEclipses | Lunar eclipses in [jdStart, jdEnd] (UT JDs). |
| lunarPhases | Every principal lunar phase (new, first quarter, full, last quarter) within [jdStart, jdEnd], sorted by time. Found from the Sun–Moon elongation crossing 0°/90°/180°/270°. |
| lunarReturn | - |
| matchAll | Matches only when every selector matches; returns the union of their atoms. |
| matchAny | Matches when any selector matches; returns the atoms from those that did. |
| matchNone | Matches when the selector does NOT match (an absence test); no atoms. |
| meanLilith | Mean lunar apogee (Black Moon Lilith) on the inclined lunar orbit: apparent lon (true equinox) and orbital latitude, radians. |
| meanNode | - |
| meanObliquity | - |
| midpointLon | Shorter-arc midpoint of two longitudes (degrees). |
| mod | Python-style modulo: result has the sign of the divisor. |
| modality | Quadruplicity (modality) of a sign: "cardinal", "fixed", or "mutable". |
| moonApparentPrecise | - |
| moonApparentSeries | - |
| moonGeometric | Geocentric Moon, mean equinox of date (Meeus ch.47): lon, lat, dist km. |
| mundaneDirectionArc | Placidus semi-arc mundane directional arc (degrees) for promissor P to significator S: arc = MD_p - (MD_s / SA_s) * SA_p. null if either body is circumpolar. Reduces to the to-MC arc when S is on the meridian, and to 0 when P and S coincide. |
| mundaneDirections | Direct mundane (Placidus semi-arc) directions of each promissor to each other significator within maxYears, sorted by years. |
| nakshatra | The nakshatra of a sidereal longitude. |
| nakshatraAt | The nakshatra of a body (default the Moon) at jd, in a sidereal zodiac. |
| normalizeHouseSystem | Resolve a forgiving house-system string (any case, spaces or hyphens, or a known alias) to a canonical HouseSystem, or throw listing the valid ids. Lets MCP, share links, and hand-written calls pass "whole sign", "Whole_Sign", "whole", etc. without tripping the strict union. |
| notOf | True where pred is false (interval complement). |
| notRetrograde | True while body is direct or stationary. |
| nutation | IAU 1980 nutation: [dPsi, dEps] in radians. |
| oscApogeePrecise | Osculating lunar apogee (True Lilith) from the Chebyshev moon. |
| oscApogeeSeries | Series fallback outside the Chebyshev range (same finite-difference state as the true-node fallback). |
| outOfBounds | - |
| outOfBoundsMargin | |
| parans | Co-angular pairs over the 24 hours from jd (UT) at latitude lat: every pair of different bodies whose angle crossings fall within toleranceMin minutes. Ordered by (a, b, jd), with a < b by name. |
| parivartana | Sign exchange: a sits in b's sign and b sits in a's sign. |
| parseOffset | Parse a duration offset into days. Accepts a compact single unit ("3d", "-2h", "1.5y", "6mo", "90m") or an ISO-8601 duration ("P1Y2M10DT2H30M"). Calendar units use mean lengths (year 365.2425 d, month 30.436875 d). Returns NaN when unparseable. |
| pheno | Photometric and apparent-geometry quantities for a body at an instant: its phase angle, illuminated fraction, elongation from the Sun, apparent disc diameter, and apparent visual magnitude. |
| planetApparent | Apparent geocentric ecliptic lon/lat (true equinox of date), distance. |
| planetaryHour | The planetary hour containing jdUt at a place, or null at latitudes where the Sun does not rise or set on the day in question. |
| planetarySect | The sect a body belongs to: "diurnal" (Sun, Jupiter, Saturn), "nocturnal" (Moon, Venus, Mars), or null for Mercury and bodies without a fixed sect. Whether a chart is itself day or night — the Sun above or below the horizon — is a separate question. |
| planetLines | Angle lines for one body at right ascension/declination (degrees) and a Greenwich apparent sidereal time (degrees). |
| plutoApparent | - |
| plutoHeliocentric | Meeus ch.37 heliocentric Pluto, ecliptic J2000: [l rad, b rad, r AU]. |
| precessEcliptic | Precession of ecliptic coordinates between epochs (Vondrak 2011): ecliptic-of-from -> J2000 equatorial -> ecliptic-of-to. |
| primaryDirections | Direct primary directions of the bodies to the four angles within maxYears, by the given time key, sorted by years. |
| profectedSign | The whole-sign profection steps signs after the Ascendant sign. |
| profection | Annual and monthly profection at targetJd for a natal Ascendant sign. |
| profectionAt | Profection from a natal chart: take the Ascendant sign from the natal chart, then profect to targetJd. |
| progressedJd | The JD whose real positions are the secondary-progressed positions for the age (targetJd - natalJd): one day of motion per year of life. |
| progressedLongitude | Secondary-progressed longitude of a body for a given target date: the "day-for-a-year" method, where one day of real motion after birth maps to one year of life. Equivalent to taking the body's longitude at progressedJd. |
| quadrant | 1-based quadrant (I–IV) of a 1-based house number: houses 1–3 -> 1, etc. |
| rajaYogas | Raja yogas: associations between a kendra lord and a trikona lord. |
| rajaYogasAt | Raja yogas of a natal chart, with the chart's yogakarakas. |
| rankMoments | Score every sampled instant and return the best, highest score first. |
| rankMomentsAsync | rankMoments that yields to the event loop every chunk samples, so a long main-thread scan does not freeze the UI. Same result as rankMoments. |
| realize | Realize an AnchoredChart: resolve its anchors and run the appropriate generator. A resolvable instant always wins (the realm is then just framing); failing that, constraints synthesize a form; failing both, nothing computes. |
| realmFraming | A one-line framing for the realm and certainty, or "" when neither needs it. |
| reconcile | Group a Reading's entries by the facts they share, so statements about the same atoms surface together rather than scattered through a flat list -- the substrate for "everything said about this placement" and for spotting contention. Entries are connected when their cited atoms overlap; an entry citing nothing (an absence rule) stands alone. A group is contested when a declared conflicting tag-pair both appear in it. |
| refractApparentToTrue | Bennett refraction, degrees. |
| refractTrueToApparent | Saemundsson refraction, degrees. Returns the input unchanged when even the refracted altitude stays below the horizon (matches Swiss Ephemeris). |
| registerSyntheticSystem | Register a system's bodies on a real Engine so transits, returns, retrograde detection, skyView, relational — every computation built on Engine.position/Engine.longitude — consume them unchanged. The bodies are placed heliocentrically in the real solar system and viewed from real Earth, so the synthetic observer is not applied here (use syntheticPositions for the self-contained world frame). Each body's epoch is then interpreted as a TT Julian Day. |
| resolvePlace | Resolve a SpatialAnchor to coordinates, using registry for relative references and the gazetteer for named places. place is null when no coordinates can be derived (fictional, none, an unknown reference). |
| resolveTime | Resolve a TemporalAnchor to a usable instant, using registry for relative references and narrative calendars. The result always reports its Certainty; jd is null exactly when no instant can be derived (symbolic, none, an unknown reference, or an unmappable calendar). |
| retrograde | True while body is in apparent retrograde motion. |
| returns | UT JDs in [jdStart, jdEnd] when body returns to its natal longitude. Outer-planet returns can show three crossings around a retrograde loop. |
| riseSet | The next rise, set, or meridian transit of a body after jdStart, as a Julian Day (UT). Accounts for the body's apparent radius, atmospheric refraction, and observer altitude. |
| sampleCount | Number of samples a scan of these options visits. |
| scan | Evaluate fn at each sampled instant in [start, end], returning the results in time order. |
| searchConfigurations | Rank the instants in [start, end] by how closely the sky resembles a target feature vector, best first — a realization search over the feature space. Build target with chartFeatures (e.g. from a natal chart). |
| separation | Unsigned angular separation in [0, 180] degrees. |
| signedElongation | Signed shortest angle from b to a, in (-180, 180] degrees. |
| signLord | The traditional ruler of a sign index (0 = Aries). |
| signRuler | Traditional (domicile) ruler of a sign index (0 = Aries). |
| skyView | Project the visible sky into an image frame for a place, instant, aim, and lens. Returns each in-frame body's pixel position, apparent size, brightness, and (for the Moon) phase orientation, a sky-state summary, the bright bodies just outside the frame, and a serialized prompt. |
| skyViewSequence | A time sequence of skyView frames for the same place, aim, and lens: the keyframes for an accurate night-sky animation. Each frame is a complete, physically exact spec; across frames the sky rotates about the pole, the Moon drifts and changes phase, twilight evolves, and the Milky Way wheels. The geometry is continuous, so the frames are temporally coherent; supplying them as control images (or reprojecting one rendered plate by the per-frame rotation) is how to keep the rendered output coherent too. |
| solarArc | Solar-arc direction angle (degrees, forward): how far the secondary- progressed Sun has moved from the natal Sun. Add it to any natal longitude. |
| solarEclipseLimits | Ground path of a solar eclipse at a Julian Day (UT): the central point and the north/south limits of totality (or annularity), with the path width. Marches perpendicular to the shadow's ground track out to the umbra edge -- where the Moon just fully covers (or is covered by) the Sun. Sample across the eclipse to trace the full path of totality. |
| solarEclipseLocal | Local circumstances of a solar eclipse as seen from one place: contact times, magnitude, and obscuration. Topocentric Sun and Moon disks, so it accounts for lunar parallax (which is what makes the same eclipse total in one town and partial in the next). |
| solarEclipses | Solar eclipses in [jdStart, jdEnd], with global circumstances (not local visibility). Each new Moon in the window is tested for an eclipse and, when found, classified by the Moon's shadow geometry. |
| solarEclipseWhere | Sub-shadow geographic point where the eclipse axis meets the Earth at a Julian Day (UT): the centre line of totality/annularity at that instant. Sample it across the eclipse (e.g. between the SolarEclipse begin and end) to draw the ground track. |
| solarElongation | Ecliptic-longitude separation between a body and the Sun (degrees). |
| solarPhase | cazimi / combust / under_beams / null for a body's nearness to the Sun by ecliptic longitude. The Sun itself returns null. |
| solarReturn | Solar-return instants in [jdStart, jdEnd]: the times the Sun returns to its natal longitude (about once a year). Build a chart at each with Engine.chartAt for the solar-return chart. |
| starAngleTimes | The four angle crossings of a fixed star over the day from jd at latitude lat: the meridian transits always occur; rise/set are absent when the star is circumpolar or never rises. |
| starApparent | Apparent ecliptic [lon, lat] of date (rad) for a catalog entry. |
| starParans | Star-to-body parans over the day from jd (UT) at latitude lat: a fixed star and a moving body simultaneously on angles within toleranceMin minutes — Brady's fixed-star parans. Ordered by (star, body, jd). |
| startingYogini | 0-based starting yogini index from the Moon's nakshatra index (0-based): (nakshatra number + 3) mod 8, a remainder of 0 mapping to the 8th. |
| stations | Times the body stations (speed crosses zero): [jdUt, direction the body turns]. Sun and Moon never station. Station timing is ill-conditioned: expect minute-level differences between ephemerides. |
| sunApparent | - |
| synastryAspects | Inter-chart aspects between two natal charts (static snapshot; both speeds 0). |
| synastryOverlays | House overlays both ways between two charts. |
| syntheticEphemeris | A BodyPositionSource over an authored system: the world-frame view as a reusable object, with longitude speed and a retrograde flag so it satisfies the same contract real ephemeris bodies do. Carries the system's validateSyntheticSystem diagnosis (impossible/problems) — the honesty pattern — and still serves the bodies that are individually valid. |
| syntheticPositions | Positions of every body at one instant — the core position-over-time contract. Pure: a function of (sys, t) only. |
| syntheticRender | The SyntheticRender attributes for a body id, or undefined when none were authored. The accessor SkyView/skyViewSequence reads so an imaginary body keeps a consistent size, brightness and colour across frames — the engine owns position, this owns appearance. |
| syntheticSources | Build the heliocentric XyzSource for every body in a system, keyed by id — the raw material for both the world-frame contract and engine registration. |
| termRuler | - |
| topocentricEcl | Diurnal parallax in ecliptic coordinates (Meeus ch. 11/40). lst = local apparent sidereal time (rad). Returns [lon, lat, distAu]. |
| transitAspects | Transiting bodies aspecting a natal chart at transitJd. Natal longitudes are fixed; phase reflects the transiting body's motion toward the natal point. |
| trueNodePrecise | - |
| trueNodeSeries | Osculating node from the series moon (fallback outside Chebyshev range). |
| trueObliquity | - |
| unitVector | Unit vector on the sphere for an (ecliptic longitude, latitude) pair, in the ecliptic frame: x toward 0 Aries, z toward the north ecliptic pole. |
| validateSyntheticSystem | Check an authored system for the ways it can be ill-defined — duplicate ids, a dangling observer, non-positive periods, or out-of-range eccentricity — and report each, in the impossible/residual honesty style. Pure. |
| varga | The varga D-n placement of a sidereal longitude. |
| vargaAt | The varga D-n of a body (default the Moon) at jd, in a sidereal zodiac. |
| vargaChart | The full divisional chart D-n at jd: the varga sign of each body. |
| vertexEastPoint | Vertex (western crossing of prime vertical and ecliptic) and east point (equatorial ascendant). Radians in, radians out. |
| vimshottariActive | The mahadasha, antardasha, and pratyantardasha lords active at targetJd. |
| vimshottariAt | Vimshottari dasha active at targetJd, from the natal Moon's nakshatra. |
| vimshottariDashas | The Vimshottari dasha timeline from the Moon's sidereal longitude. |
| voidOfCourse | Void-of-course state of the Moon at jdUt: void from its last perfecting aspect to a traditional planet (Sun..Saturn) until it leaves the sign it occupies at jdUt. |
| vsopHeliocentric | - |
| when | Solve for the time intervals within [jdStart, jdEnd] (UT Julian Days) where a Predicate holds. Predicates compose from aspect, inSign, retrograde, notRetrograde, and the allOf/anyOf combinators, so one call answers questions like "when is Venus in Taurus while Mercury is direct?". |
| yogakarakas | Planets ruling both a pure kendra (4/7/10) and a pure trikona (5/9), sorted. |
| yogasAt | The placement yogas of a natal chart, from the sidereal rasi positions. |
| yoginiActive | The maha and antar yogini active at targetJd; null before the first period. |
| yoginiAt | Yogini dasha active at targetJd, from the natal Moon's nakshatra. |
| yoginiDashas | The Yogini dasha timeline from the Moon's sidereal longitude. |
| zrActive | The L1..L4 releasing signs active at targetJd; null outside the span. |
| zrAt | Zodiacal releasing active at targetJd, releasing from the Lot of Spirit (default) or Fortune of the natal chart. |
| zrRelease | Flat timeline of releasing periods down to maxLevel over horizonYears (360-day years) from birth. |