Calculation Reference

Zodiac framework

The current web profile is Western modern v1: tropical zodiac, True Node, Standard (`modern-major-v1`) aspects, Chiron enabled 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.

The web chart output displays the profile-selected True North Node and Chiron as additional chart points. They retain the engine's sign, longitude, degree, minute and motion state; house placement is shown only when the birth time supports houses.

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 may use the start of the supplied local date as an internal reference datetime for body calculation, emits `UNKNOWN_BIRTH_TIME`, and does not present that midnight as the actual birth time. The engine’s `unknownTimeAssessment` is authoritative for sign, motion and aspect stability across the allowed local-day interval.

Stable signs can be shown without exact degree. If a fact is uncertain, or the assessment is incomplete or capped, the web product withholds it or labels it as uncertain. Houses, angles, Rising, Vertex and Part of Fortune remain unavailable. `anchorLongitude` is not an exact birth longitude, and the frontend does not use an end-of-day approximation.

Version reference

Current web pin: v1.13.0. Package/runtime: 1.13.0. Calculation engine: 1.13.0. Natal schema: 1.9.0. See the open-source engine (opens in a new tab), PyPI package (opens in a new tab), Zenodo concept citation (opens in a new tab) and version 1.13.0 record (opens in a new tab).