Calculation Reference

Zodiac framework

The current web profile is Western modern v1: tropical zodiac, true node and Placidus houses by default. Zodiac sign boundaries are the twelve 30-degree tropical sectors starting at 0° Aries.

Ephemeris and coordinates

Planetary, lunar, node, Chiron, house and angle calculations use Swiss Ephemeris through the `pyswisseph` binding. The package declares `pyswisseph>=2.10.3.2`; the web source does not claim a tighter runtime binding version here.

The engine accepts geographic latitude in [-90, 90], longitude in [-180, 180], an IANA timezone and an optional altitude. Altitude is stored but is not applied to positions or houses. Place names are resolved by the website before coordinates reach the package.

Supported bodies and points

The natal body set contains the following IDs. Derived points are separate outputs and are only present when their required geometry is available.

House systems

The engine library contains more house-system implementations than the public web natal API exposes. The current website selector exposes Placidus, Whole Sign and Equal. Placidus and Koch are undefined beyond the polar circles; the engine raises an explicit error instead of silently changing systems.

Aspect types and orbs

Natal aspects use the versioned `modern-major-v1` profile. An aspect is included when the shortest angular separation falls within the configured orb. Applying/separating phase is derived from relative motion; it is not a user-entered label.

Synastry and relationship calculations

Synastry compares two already-calculated natal charts. It can produce directional cross-chart aspects, house overlays when the receiving chart has houses, and body-to-angle interactions when the target chart has angles. A missing birth time removes the corresponding house and angle facts rather than adding substitutes.

Synastry uses a separate `synastry-major-v1` profile: conjunction 7°, sextile 3°, square 6°, trine 6° and opposition 7°. Cross-chart phase is indeterminate by default because two natal charts do not share a physical timeline. Composite charts use the natal aspect profile.

Timezone and local time

The engine requires an IANA timezone and converts a local date/time with the runtime's `zoneinfo` data. Historical offsets and daylight-saving rules are applied for that date. Spring-forward gaps raise `NONEXISTENT_LOCAL_TIME`; fall-back overlaps raise `AMBIGUOUS_LOCAL_TIME` unless an explicit fold is supplied.

Unknown birth time

Unknown time must be explicit. The engine resolves the start of the supplied local date for body calculation, emits `UNKNOWN_BIRTH_TIME`, and does not present that midnight as the actual birth time.

Version reference

Current web pin: v1.12.1. Calculation engine: 1.12.1. Installable package: 1.12.2. Chart schema: 1.3.0. See the open-source engine (opens in a new tab), PyPI package (opens in a new tab) and archived release (opens in a new tab).