Stellium v0.12.0: Electional Astrology and Various Fixes

0.12.0 - The Electional Astrology Release

A complete electional astrology toolkit for finding auspicious times. Search date ranges with 30+ astrological conditions, interval-based optimization for 100x+ speedups, and planetary hours calculation.

Highlights

ElectionalSearch - Find Auspicious Times

New fluent API for searching date ranges with astrological conditions:

from stellium.electional import (
    ElectionalSearch, is_waxing, not_voc, sign_not_in,
    on_angle, no_hard_aspect, not_retrograde
)

# Find auspicious election windows
results = (ElectionalSearch("2025-01-01", "2025-06-30", "San Francisco, CA")
    .where(is_waxing())
    .where(not_voc())
    .where(sign_not_in("Moon", ["Scorpio", "Capricorn"]))
    .where(on_angle("Jupiter"))
    .where(no_hard_aspect("Moon"))
    .where(not_retrograde("Mercury"))
    .find_windows())

for window in results:
    print(f"{window.start} - {window.end} ({window.duration})")

30+ Helper Predicates covering:

• Moon phase (is_waxing(), is_waning())
• Void of Course (is_voc(), not_voc())
• Sign placement (sign_in(), sign_not_in())
• House placement (in_house(), on_angle(), succedent(), cadent())
• Retrograde (is_retrograde(), not_retrograde())
• Dignity (is_dignified(), is_debilitated())
• Aspects (has_aspect(), no_aspect(), aspect_applying(), no_hard_aspect())
• Combust & OOB (is_combust(), is_out_of_bounds())
• Planetary hours (in_planetary_hour())
• And more!

Interval-Based Optimization

Pre-compute time windows for 100x+ speedups on long date ranges:

  from stellium.electional.intervals import (
      waxing_windows, voc_windows, moon_sign_windows,
      intersect_windows, union_windows, invert_windows
  )

  # Get all waxing moon periods in 2025
  windows = waxing_windows(datetime(2025, 1, 1), datetime(2025, 12, 31))

Planetary Hours

Complete planetary hours calculation with variable-length hours based on actual sunrise/sunset:

  from stellium.electional import get_planetary_hour, get_planetary_hours_for_day

  # Get current planetary hour
  hour = get_planetary_hour(datetime.now(), latitude=37.7, longitude=-122.4)
  print(f"Current hour: {hour.ruler}")

  # Get all 24 hours for a day
  hours = get_planetary_hours_for_day(datetime(2025, 1, 15), 37.7, -122.4)

Aspect Exactitude Search

Find exact aspect times with sub-arcsecond precision:

  from stellium.engines.search import find_aspect_exact, find_all_aspect_exacts

  # Find all New Moons in 2025
  new_moons = find_all_aspect_exacts("Sun", "Moon", 0.0,
      datetime(2025, 1, 1), datetime(2025, 12, 31))

Angle Crossing Search

Find when ASC, MC, DSC, or IC reach specific longitudes:

  from stellium.engines.search import find_angle_crossing

  # Find when 0° Aries rises
  crossing = find_angle_crossing(0.0, latitude=40.7, longitude=-74.0,
      angle="ASC", start=datetime(2025, 1, 1))

Bug Fixes

• Conjunction detection: Fixed find_aspect_exact() for 0° aspects (conjunctions) using golden section search
• Timezone handling: Fixed timezone conversion in ElectionalSearch for correct UTC-based window calculations
• Planetary hours date: Fixed get_sunrise_sunset() to interpret dates as local time
• Moon phase: Fixed is_waxing attribute that was incorrectly always returning true
• VOC window accuracy: Improved binary search precision from 5 minutes to 1 minute tolerance
• Waxing window coverage: Fixed edge cases where Full Moon occurred after search end date
• Window endpoints: Fixed off-by-one errors in interval boundary comparisons
• RAMC display: Excluded technical calculation values from chart wheel rendering
• CI geocoding: Fixed test fixtures to apply geocoding mocks before fixture initialization

New Examples

• examples/electional_cookbook.py - 43 comprehensive examples covering all electional features

Stelliium v0.11.1 - Notables Data Quality Fix

Notes

Fixed

Fixed missing required fields in several notable entries that caused them to be skipped during registry loading:

• Added missing hour/minute fields to 9 birth entries (using 12:00 noon for unknown birth times)
• Added missing category fields to 5 historical events

The registry now loads all 196 entries (175 births, 21 events) without warnings.

Stellium v0.11.0: Graphic Ephemeris, Prose, and PyPI Data Fix

Highlights

Critical Fix: Package Data Now Works from PyPI

Fixed an issue where the notables registry returned 0 entries when installed via pip install stellium. Ephemeris and notables data are now properly bundled with the package.

• Ephemeris files are automatically copied to ~/.stellium/ephe/ on first use
• Downloaded asteroid files persist across upgrades
• No more "registry has 0 entries" errors!

New: Graphic Ephemeris Visualization

Visualize planetary positions over time with the new GraphicEphemeris class.

• Three harmonic modes: 360°, 90° (hard aspects), 45° (8th harmonic)
• Station markers for retrograde/direct points
• Natal chart overlay for transit analysis

  from stellium.visualization import GraphicEphemeris

  eph = GraphicEphemeris(
      start_date="2025-01-01",
      end_date="2025-12-31",
      harmonic=90,
  )
  eph.draw("ephemeris_2025.svg")

New: ProseRenderer for Natural Language Output

Export chart data as clean, readable prose—perfect for sharing or pasting into conversations.

  report = ReportBuilder().from_chart(chart).with_planet_positions()
  report.render(format='prose', file='my_chart.txt')

New: AAF File Import

Import birth data from astro.com exports with stellium.io.parse_aaf().

Stellium v0.10.0: The Data Analysis Release - Batch Calculation, pandas DataFrames & Statistical Tools

Data Analysis Module

Stellium 0.10.0 introduces a comprehensive data analysis package for large-scale astrological research. Calculate hundreds of charts, export to pandas
DataFrames, filter by astrological criteria, and compute aggregate statistics.

Requires optional dependency: pip install stellium[analysis]

New Features

BatchCalculator

Efficiently calculate many charts at once:

from stellium.analysis import BatchCalculator

# Calculate all scientists from the notables database
charts = (BatchCalculator
    .from_registry(category="scientist", verified=True)
    .with_aspects()
    .calculate_all())

DataFrame Export

Convert charts to pandas DataFrames in three schemas:

from stellium.analysis import charts_to_dataframe, positions_to_dataframe

df = charts_to_dataframe(charts)  # One row per chart
positions_df = positions_to_dataframe(charts)  # One row per position

ChartQuery

Filter chart collections by astrological criteria:

from stellium.analysis import ChartQuery

fire_suns = (ChartQuery(charts)
    .where_sun(sign=["Aries", "Leo", "Sagittarius"])
    .where_pattern("Grand Trine")
    .results())

ChartStats

Statistical aggregation across chart collections:

from stellium.analysis import ChartStats

stats = ChartStats(charts)
print(stats.element_distribution())
print(stats.sign_distribution("Sun"))
print(stats.cross_tab("sun_sign", "moon_sign"))

Export Utilities

Save to CSV, JSON, or Parquet:

from stellium.analysis import export_csv, export_json

export_csv(charts, "scientists.csv", schema="charts")
export_json(charts, "scientists.json")

Interactive Cookbook

New Jupyter notebook cookbook at examples/analysis_cookbook.ipynb with:

• Batch calculation patterns
• DataFrame conversion examples
• Query filtering demonstrations
• Statistical analysis workflows
• Full research examples (element distribution by profession, retrograde frequencies, etc.)

Installation

# Core stellium
pip install stellium

# With data analysis support
pip install stellium[analysis]

Testing

36 new tests covering all analysis functionality.

Stellium v0.9.0: The MultiChart Release

Stellium v0.9.0 - The Unified MultiChart Release

This release introduces the unified MultiChart architecture that consolidates Comparison and MultiWheel into a single, more powerful API. Plus:
eclipse search, transit calendar presets, and ingress reporting.

Highlights

Unified MultiChart Architecture

The new MultiChart class replaces both Comparison (2-chart) and MultiWheel (2-4 chart) with a single, flexible API:

from stellium import MultiChartBuilder

# Synastry (replaces ComparisonBuilder.synastry)
mc = MultiChartBuilder.synastry(chart1, chart2, label1="Kate", label2="Partner").calculate()

# Triwheel: Natal + Progressed + Transit
mc = (MultiChartBuilder.from_chart(natal, "Natal")
    .add_progression(age=30, label="Progressed")
    .add_transit("2025-06-15", label="Transit")
    .calculate())

# Access charts multiple ways
mc[0]        # Indexed
mc.chart1    # Named property
mc.natal     # Semantic alias

Key features:

• Support for 2-4 charts (biwheels, triwheels, quadwheels)
• Dual access pattern: indexed AND named properties
• Per-pair relationship types (synastry, transit, progression)
• Configurable cross-aspect calculation ("to_primary", "all", or explicit pairs)
• House overlay analysis
• Compatibility scoring for synastry
• Full visualization and report support

Eclipse Search

Find solar and lunar eclipses with new search functions:

from stellium.engines import find_eclipse, find_all_eclipses

# Find next eclipse
eclipse = find_eclipse(datetime(2024, 1, 1))
print(eclipse)  # Total solar eclipse at 19°24' Aries (NN) on 2024-04-08

# All eclipses in a year
eclipses = find_all_eclipses(datetime(2024, 1, 1), datetime(2024, 12, 31))

Transit Calendar Preset

New convenience preset bundles stations, ingresses, and eclipses:

report = (ReportBuilder()
    .from_chart(chart)
    .preset_transit_calendar(end=datetime(2024, 12, 31))
    .render(format="rich_table"))

Ingress Section

Report section showing when planets enter new zodiac signs:

report = (ReportBuilder()
    .from_chart(chart)
    .with_ingresses(end=datetime(2024, 12, 31), include_moon=True)
    .render())

Breaking Changes

None - existing Comparison and MultiWheel APIs continue to work but emit deprecation warnings.

Deprecations

• Comparison → Use MultiChart
• ComparisonBuilder → Use MultiChartBuilder
• MultiWheel → Use MultiChart
• MultiWheelBuilder → Use MultiChartBuilder

See the examples/multichart_cookbook.py#example_18_migration for details.

What's Changed

Added

• MultiChart and MultiChartBuilder unified multi-chart classes
• find_eclipse() and find_all_eclipses() search functions
• Eclipse dataclass with type, classification, and node info
• EclipseSection for reports
• IngressSection for reports
• ReportBuilder.preset_transit_calendar() convenience preset
• 51 new tests for MultiChart

Changed

• Visualization layers now accept MultiChart
• Report sections now accept MultiChart
• CrossChartAspectSection handles dict-based cross_aspects

Deprecated

• Comparison, ComparisonBuilder, MultiWheel, MultiWheelBuilder

Installation

pip install stellium==0.9.0

Full Changelog

See CHANGELOG.md for complete details.

Stellium v.0.8.0: Directions, Dragons, and Voids

This is a major feature release focused on deep calculation engines. v0.8.0 introduces Primary Directions (one of the most mathematically complex techniques in traditional astrology), Draconic charts for karmic analysis, and precise Void of Course Moon calculations for electional timing.

New Features

Primary Directions Engine

I have added a complete engine for Primary Directions, allowing for 3D celestial sphere analysis and predictive timing.

• Two Direction Methods: Switch between "zodiacal" (2D ecliptic projection) and "mundane" (3D Placidus semi-arc proportions).
• Two Time Keys: Support for "naibod" (mean solar motion) and "ptolemy" (1 degree = 1 year).
• Life Chapters (Distributions): A new DistributionsCalculator tracks the directed Ascendant through Egyptian bounds/terms to generate "Time Lord" periods for the native's life.

from stellium.engines.directions import DirectionsEngine, DistributionsCalculator

# Calculate direction: Sun directed to Ascendant
result = DirectionsEngine(chart).direct("Sun", "ASC")
print(f"Sun to ASC: age {result.age:.1f}")

# Calculate Life Chapters (Distributions)
periods = DistributionsCalculator(chart).calculate(years=80)

Draconic Charts

You can now transform any chart into its Draconic equivalent (where the North Node is locked to 0° Aries). This introduces a new chart_tags architecture to track coordinate transformations.

# Create a draconic chart (returns a new CalculatedChart)
draconic = chart.draconic()
print(draconic.get_object("Sun").sign) 
print(draconic.chart_tags)  # ('draconic',)

Void of Course Moon

A precise timing engine to detect when the Moon is Void of Course (VOC).

• Calculates exact end times and next ingress.
• Supports Traditional mode (visible planets only) and Modern mode (includes outer planets).

voc = chart.voc_moon(aspects="traditional")
if voc.is_void:
    print(f"Moon is VOC until {voc.void_until} (enters {voc.next_sign})")

Changes & Fixes

• Core Architecture: House system engines now return RAMC (Right Ascension of the Meridian) as the 6th angle, which is essential for the new primary directions calculations.
• Progressions: Fixed timezone handling in calculate_progressed_datetime to gracefully handle comparisons between timezone-aware and timezone-naive datetimes.

Stellium v0.7.0: MultiWheel Visualization & Transit Search

[0.7.0] - 2025-12-03

The MultiWheel Release: Complete multi-wheel visualization for bi/tri/quad charts, Arabic Parts in reports, and a new longitude search engine for transit timing.

Highlights

MultiWheel Visualization Improvements

The multi-wheel system is now production-ready for professional chart comparisons:

• Automatic canvas scaling: Tri-wheels 15% larger, quad-wheels 30% larger for readability
• Ring boundary lines: Clear visual separation between chart layers
• Cross-chart aspects for biwheels: Aspect lines drawn between inner/outer chart planets
• Angles on all rings: Each chart displays its own ASC/MC/DSC/IC with degree positions
• Smart glyph scaling: Glyphs automatically shrink for outer rings (85% tri, 75% quad)
• New info_mode="no_sign": Compact degree display without sign glyph redundancy
• Improved headers: Detailed side-by-side layout for biwheels, compact columns for tri/quad

Arabic Parts Report Section

Full support for displaying Lots in PDF/terminal reports:

• Filtering modes: "all", "core" (7 Hermetic), "family", "life", "planetary"
• Formula column: Shows calculation with * indicator for sect-aware parts
• Description column: Optional interpretive text
• Multi-house system support: Abbreviated column headers when multiple systems calculated

ReportBuilder.from_chart(chart).with_arabic_parts(mode="core", show_formula=True).render()

Longitude Search Engine

New precision engine for finding when planets reach specific degrees:

• find_longitude_crossing(): Hybrid Newton-Raphson/bisection algorithm
• find_all_longitude_crossings(): Find all crossings in a date range
• Sub-arcsecond precision with proper retrograde and station handling
• 360°/0° wraparound handled correctly

Use cases enabled:

• Persona charts (Sun reaching natal planet positions)
• Transit searches ("When does Mars hit my natal Venus?")
• Ingress calculations (equinoxes, solstices, sign entries)

from stellium.engines.search import find_longitude_crossing

# Find next time Mars crosses 15° Aries
crossing = find_longitude_crossing("Mars", 15.0, start_date, direction="forward")

Stellium v0.6.0: Dials, Time Lords, and Deep Space

Release Description

This release bridges the gap between ancient Hellenistic techniques and modern Uranian astrology. It introduces a completely new visualization engine for Uranian Dial Charts, a comprehensive Zodiacal Releasing engine (Valens method), and critical stability improvements for handling asteroid ephemeris files.

Headline Features

Uranian Dial Charts & Deep Space Objects

We have added full support for the Hamburg School of astrology.

• New Visualization: Generate 90°, 45°, and 360° dial charts using the new DialDrawBuilder.
• Features: Includes pointers, modality wheels, measurement scales, and collision detection for planetary glyphs.
• New Objects: Built-in support for 8 Trans-Neptunian Objects (Eris, Sedna, etc.) and 8 Uranian/Hypothetical planets (Cupido, Hades, etc.) plus the Aries Point.

# Generate a 90-degree dial with Uranian planets
chart.draw_dial("dial.svg", degrees=90)
     .with_uranian()
     .with_tnos()
     .with_midpoints()

Zodiacal Releasing (Valens Method)

A complete engine for the Hellenistic "Time Lord" technique, Zodiacal Releasing, is now available.

• Deep Calculation: Calculates periods from Level 1 (decades) down to Level 4 (hours).
• Qualitative Analysis: Automatically detects "Peak" periods, "Loosing of the Bond," and scores periods based on sect, benefic/malefic rulers, and chart tenants.
• Report Integration: Add timelines and snapshots directly to your PDF reports via .with_zodiacal_releasing().

Graceful Ephemeris Handling

Stellium is now much more robust when dealing with missing data.

• No More Crashes: If an asteroid ephemeris file is missing, the engine now gracefully warns you and skips the object instead of raising an error.
• New CLI Tool: Easily download missing files with the new CLI command: stellium ephemeris download-asteroid 136199 or --tnos for the full set.

Enhancements & API Changes

• MultiWheel Data Structures (Phase 1): We have laid the groundwork for bi-wheel, tri-wheel, and quad-wheel charts. The MultiWheel dataclass and builder are now available for backend calculations (visualization coming in v0.7.0).
• ReportBuilder API: Simplified PDF generation. You can now use .with_chart_image() to auto-generate and embed chart wheels, and .with_title("My Report") to customize the cover.
• Web App Code Preview: Every page on the web app (Natal, Relationships, Timing) now features a live Python code preview, making it easier to learn the API.
• Standalone Aspectarians: You can now generate standalone aspectarian SVGs (grids) without rendering a full chart wheel.
• PDF Rendering: Fixed rendering for compound sections (like Dispositor graphs and Aspectarians) in Typst-generated PDFs.

Database

• Added 78 notable births and 12 events to the Notables database.

Stellium 0.5.0

[0.5.0] - 2025-11-28

The Timing Techniques Release — Stellium gains serious traditional astrology capabilities with profections, arc directions, dispositor analysis, and declination aspects.

Added

Profections Engine

Complete Hellenistic timing technique implementation:

• Annual profections: Calculate activated house and Lord of Year for any age
• Monthly profections: Solar ingress method for subdividing the year
• Multi-point profections: Profect ASC, Sun, Moon, MC, or any point simultaneously
• Timeline generation: View sequence of Lords across a range of ages
• Traditional and modern rulership options
• Whole Sign default (traditional) with support for any house system

Chart convenience methods:

chart.profection(age=30)              # Annual profection
chart.profection(date="2025-06-15")   # Annual + monthly for specific date
chart.profections(age=30)             # Multi-point (ASC, Sun, Moon, MC)
chart.profection_timeline(25, 35)     # Timeline of Lords
chart.lord_of_year(30)                # Quick access

Arc Directions

Move all chart points by a unified arc — a key technique for timing life events:

• 7 arc types supported:

  • solar_arc — Progressed Sun motion (~1°/year)
  • naibod — Mean solar motion (0.9856°/year)
  • lunar — Progressed Moon motion (~12-13°/year)
  • chart_ruler — Uses planet ruling the Ascendant (personalized!)
  • sect — Solar arc for day charts, lunar arc for night charts
  • Any planet — "Mars", "Venus", "Jupiter", "Saturn", "Mercury"

• Full biwheel support with cross-chart aspects

• Traditional and modern rulership options for chart ruler arc

ComparisonBuilder.arc_direction(natal, age=30, arc_type="solar_arc").calculate()
ComparisonBuilder.arc_direction(natal, age=30, arc_type="chart_ruler", rulership_system="traditional").calculate()

Dispositor Graphs

Visualize how planets and houses flow into each other:

• Planetary dispositors: Traditional chain analysis — find the final dispositor, detect mutual receptions
• House-based dispositors: Kate's innovation — trace how life areas feed into each other
• Graphviz SVG rendering with Stellium's color palette
  • Gold highlighting for final dispositors
  • Purple tinting for mutual receptions
  • Bidirectional arrows for mutual reception pairs
  • Planet glyphs (☉♀♂♃♄) in planetary mode
• ReportBuilder integration: .with_dispositors(mode="both")

Declination Aspects

Support for parallel and contraparallel aspects:

• Parallel (∥): Same declination, same hemisphere — interpreted like conjunction
• Contraparallel (⋕): Equal declination, opposite hemispheres — interpreted like opposition
• Configurable orb (default 1.0°)
• ReportBuilder integration: .with_declination_aspects()

chart = ChartBuilder.from_details(...).with_declination_aspects(orb=1.0).calculate()
chart.get_parallels()
chart.get_contraparallels()

Test Coverage

109 new tests across the four features:

• Profections: 46 tests
• Arc Directions: 18 tests
• Dispositor Graphs: 26 tests
• Declination Aspects: 19 tests

Links

• Live App: https://stellium.up.railway.app
• GitHub: https://github.com/katelouie/stellium
• PyPI: https://pypi.org/project/stellium/

Stellium 0.4.0

[0.4.0] - 2025-11-28

The Web Application Release - Stellium goes online with a complete, production-ready web interface.

Added

Stellium Web Application

• Complete NiceGUI Web Application (web/ module, 5,600+ lines): Full-featured web interface at stellium.up.railway.app

• 5 Pages:

  • Home: Landing page with feature overview and navigation
  • Natal: Interactive birth chart builder with full visualization options
  • Relationships: Synastry, Composite, and Davison chart generation
  • Timing: Transits, Secondary Progressions, and Returns (Solar, Lunar, Planetary)
  • Explore: Browse and search 59 notable births with instant chart generation

• 11 Reusable Components: Birth input, chart display, chart options, code preview, header, location input, notable selector, PDF options, report options, time input, unified birth input

• Key Features:

  • "Enter / Famous" toggle to use notable births in any chart type
  • "View as Python" button shows equivalent library code for any chart
  • SVG and PDF download for all chart types
  • Full theme and palette customization
  • No login required, completely free

• Design: Beautiful editorial aesthetic with Cinzel Decorative and Crimson Pro typography, warm cream/purple color palette

Deployment Infrastructure

• Railway Deployment Configuration: Production-ready cloud deployment
  • Procfile for Railway/Heroku
  • railway.json with healthcheck and restart policy
  • Dynamic PORT binding for cloud environments
  • Production mode detection via RAILWAY_ENVIRONMENT

Extended Test Coverage

• 242 New Tests across 6 test files, bringing coverage to 62%:
  • CLI tests (46 tests): Commands, cache management, error handling
  • Visualization layers tests (29 tests): Headers, themes, palettes
  • Extended canvas tests (37 tests): Tables, aspectarian, filtering
  • ChartBuilder extended tests (38 tests): Factory methods, configuration
  • Comparison extended tests (55 tests): All comparison types, scoring
  • Returns builder tests (37 tests): All return types, edge cases

Changed

• Web application is now the recommended way to try Stellium without writing code

Links

• Live App: https://stellium.up.railway.app
• GitHub: https://github.com/katelouie/stellium
• Documentation: https://github.com/katelouie/stellium/blob/main/README.md