Primary Directions #

The PrimaryDirectionsFactory implements Placidus semi-arc primary directions – the most widely used method in classical/traditional astrology for predicting life events.

Algorithm #

1. Convert each planet’s ecliptic position to equatorial (RA, Dec)
2. Compute the semi-arc (diurnal or nocturnal) for each planet
3. Compute the meridian distance (RA - RAMC)
4. Compute the pole of the significator (Placidus house latitude)
5. Compute oblique ascension of promissor under the significator’s pole
6. The arc of direction = OA(promissor under sig’s pole) - OA(significator)
7. Convert arc to years using the rate key

Basic Usage #

from kerykeion import AstrologicalSubjectFactory, PrimaryDirectionsFactory

subject = AstrologicalSubjectFactory.from_birth_data(
    "John", 1940, 10, 9, 18, 30,
    lng=-2.9833, lat=53.4, tz_str="Europe/London", online=False,
)

directions = PrimaryDirectionsFactory.compute(subject, max_years=80)

for d in directions[:10]:
    print(f"Year {d.direction_years:.1f}: {d.promissor} {d.aspect} {d.significator}")

Methods #

compute(subject, *, max_years, rate_key, aspects) #

Compute primary directions for a natal chart.

Returns: List[PrimaryDirectionModel] sorted by direction_years. Only directions whose direction_years is above 0.1 and not greater than max_years are kept: an arc that resolves to 0.1 years or less is dropped.

compute_speculum(subject) #

Compute the Placidian coordinate table independently of the direction list:

speculum = PrimaryDirectionsFactory.compute_speculum(subject)
for entry in speculum:
    print(entry.name, entry.right_ascension, entry.declination, entry.semi_arc)

Returns: List[SpeculumEntryModel]. The subject must represent one real instant with valid chart geometry; midpoint composites are not supported. Equatorial coordinates follow the subject’s configured perspective: planetocentric charts use that center body’s frame, and Topocentric charts use the observer coordinates including subject.altitude (sea level when None).

Rate Keys #

• Ptolemy: 1 degree of arc = 1 year of life (the classical rate)
• Naibod: 0.98564 degrees = 1 year (the mean daily motion of the Sun)

Data Models #

PrimaryDirectionModel #

Note: compute() returns both direct (is_converse=False) and converse (is_converse=True) entries interleaved, so each aspect point yields two arcs. Sextile, square and trine are directed to both the dexter and the sinister aspect point (longitude - aspect and longitude + aspect), while conjunction and opposition have a single one: the same promissor/significator/aspect combination therefore appears up to four times for the former and twice for the latter. The converse arc is an explicit sign-flip approximation of the classical technique — filter on is_converse if you only want the traditional direct directions.

SpeculumEntryModel #

The speculum (coordinate table) for each point can be retrieved separately:

Direction Points #

By default, the factory computes directions between: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Ascendant, Medium Coeli.

Aspect Types #

Default major aspects: conjunction, sextile, square, trine, opposition.

---