Other Subsystems (Pointers)

🤖 Primarily for coding agents. Hello, Claude! Read this before re-deriving the API from source. If it disagrees with the code, the code wins — please update the doc.

Part of the developer docs. These are lighter pointers — entry points + the file to read. For deep coverage of the core path see CHART_BUILDING, ENGINES, VISUALIZATION_INTERNALS, PRESENTATION_INTERNALS.

---

Multi-chart: comparison / synastry / transits / synthesis

Source: core/comparison.py, core/multichart.py, core/multiwheel.py, core/synthesis.py.

• MultiChartBuilder (preferred) builds a frozen MultiChart of 2–4 charts with relationships, cross-aspects, and house overlays. Access via mc[0]/mc.inner/mc.outer/mc.natal, get_cross_aspects(i, j), calculate_compatibility_score(), draw().

• Comparison/ComparisonBuilder and MultiWheel/MultiWheelBuilder are the older two-chart / biwheel APIs — deprecated in favor of MultiChart but still exported. Prefer MultiChart in new code.

• SynthesisBuilder → SynthesisChart computes composite (midpoint) and Davison (midpoint time+place) charts; SynthesisChart subclasses CalculatedChart, so all chart methods work.

Returns (solar / lunar / planetary)

Source: returns/builder.py. ReturnBuilder factories: ReturnBuilder.solar(natal, year=, location=), ReturnBuilder.lunar(natal, near_date=|occurrence=), ReturnBuilder.planetary(natal, "Saturn", occurrence=|near_date=). Delegates configuration to an internal ChartBuilder; .calculate() → CalculatedChart with return metadata (return_jd, return_datetime, natal_longitude, return_number).

Electional (time search)

Source: electional/ + engines/search.py. ElectionalSearch (exported) finds times satisfying conditions. Building blocks:

• electional/predicates.py — composable Condition factories (is_waxing(), moon_phase([...]), not_voc(), sign_in(...), is_retrograde(...), is_dignified(...), aspect_applying(...), in_planetary_hour(...), …). Predicates can carry speed hints + window generators for fast hierarchical search.

• electional/intervals.py — TimeWindow + window generators (waxing_windows, moon_sign_windows, retrograde_windows, voc_windows, aspect_exact_windows, …) with set ops (intersect/union/invert_windows).

• electional/planetary_hours.py — Chaldean-order planetary hours (get_planetary_hours_for_day, get_planetary_hour).

Planner (personalized PDF)

Source: planner/. PlannerBuilder.for_native(native) → .year(...)/.date_range(...), front matter (with_natal_chart(), with_solar_return(), with_profections(), with_zr_timeline(...), with_graphic_ephemeris(...)), daily content (include_natal_transits(...), include_moon_phases(), include_voc(...), include_ingresses(...), include_stations(...)), layout (page_size(...), week_starts_on(...)), then .generate("planner.pdf") (Typst). Events gathered by planner/events.py::DailyEventCollector.

Chinese astrology (BaZi / Four Pillars)

Source: chinese/. Reach it via chart.bazi() or ChartBuilder...bazi(), or directly with BaZiEngine(timezone_offset_hours) .calculate(birth_datetime) -> BaZiChart.

• Primitives (chinese/core.py): Polarity, Element (Wu Xing + generation/ control cycles), HeavenlyStem (10), EarthlyBranch (12, with hidden stems).

• Models (chinese/bazi/models.py): Pillar, BaZiChart (year/month/day/hour, day_master, element_counts(include_hidden=), to_dict(), display()).

• Analysis: chinese/bazi/analysis.py (TenGod, analyze_ten_gods), chinese/bazi/strength.py (DayMasterStrength).

• Calendar (chinese/calendar.py): SolarTerm, SolarTermEngine (BaZi year starts at Li Chun 315°, not Jan 1).

• Render: chinese/bazi/renderers.py::BaziRichRenderer.

• Zi Wei Dou Shu (chinese/ziwei/) is planned / not yet implemented.

BaZi gotcha: BaZiEngine takes local birth time and applies the timezone offset as a negative value (PST = −8). Month is determined by solar term, not the lunar month; hidden stems drive strength analysis.

CLI

Source: cli/. Entry point stellium = "stellium.cli:cli" (pyproject.toml).

• stellium chart from-registry NAME [--output PATH --house-system ... --format svg|terminal|json]

• stellium ephemeris download [--years START-END --force --quiet]; stellium ephemeris download-asteroid <ids>|--tnos [--list --force]

• stellium cache ... (cache management; see COMPONENTS_AND_ANALYSIS)

Progressions & directions

• Secondary/tertiary/minor progressions: utils/progressions.py (+ chart helpers). Arc directions: engines/directions.py. Zodiacal releasing: engines/releasing.py via chart.zodiacal_releasing(...).