Skip to content

Stellium 0.3.0

Choose a tag to compare

View all tags
@katelouie katelouie released this 27 Nov 23:51
· 241 commits to main since this release
v0.3.0
e776f92

Stellium v0.3.0 - Progressions, Returns & Sidereal Support

I've released Stellium 0.3.0, bringing three major astrological systems to the Python toolkit: Secondary Progressions, Planetary Returns, and Sidereal Zodiac calculations!

What's New

Secondary Progressions Made Easy

Calculate progressed charts automatically - just provide an age or target date, and Stellium handles the rest.

from stellium import ChartBuilder, ComparisonBuilder

natal = ChartBuilder.from_notable("Albert Einstein").calculate()

# Progressions for age 30
prog = ComparisonBuilder.progression(natal, age=30).calculate()

# Or progress to a specific date
prog = ComparisonBuilder.progression(natal, target_date="2025-06-15").calculate()

# Access progressed aspects
for aspect in prog.cross_aspects:
    print(f"Progressed {aspect.object2.name} {aspect.aspect_name} Natal {aspect.object1.name}")

Three angle progression methods give you flexibility:

  • Quotidian (default): Actual daily motion from Swiss Ephemeris - most accurate
  • Solar Arc: Angles progress at the rate of the progressed Sun
  • Naibod: Angles progress at mean Sun rate (59'08"/year)
# Use solar arc angles
prog = ComparisonBuilder.progression(
    natal, age=30, angle_method="solar_arc"
).calculate()

Planetary Returns System

New ReturnBuilder makes calculating solar returns, lunar returns, and planetary returns simple and intuitive.

from stellium import ReturnBuilder

natal = ChartBuilder.from_notable("Albert Einstein").calculate()

# 2025 Solar Return
sr = ReturnBuilder.solar(natal, 2025).calculate()

# Lunar Return nearest to a specific date
lr = ReturnBuilder.lunar(natal, near_date="2025-03-15").calculate()

# First Saturn Return (~age 29)
saturn = ReturnBuilder.planetary(natal, "Saturn", occurrence=1).calculate()

# Relocated Solar Return to Tokyo
sr_tokyo = ReturnBuilder.solar(natal, 2025, location="Tokyo, Japan").calculate()

High-precision calculations use binary search algorithms with sub-arcsecond accuracy (~0.0001°), and properly handle retrograde motion.

Sidereal Zodiac Support

Stellium now supports both Western (tropical) and Vedic (sidereal) astrology with nine different ayanamsa systems.

from stellium import ChartBuilder

# Calculate with Lahiri ayanamsa (default for sidereal)
chart = (ChartBuilder
    .from_notable("Albert Einstein")
    .with_sidereal("lahiri")
    .calculate())

# Try other systems
chart = (ChartBuilder
    .from_notable("Albert Einstein")
    .with_sidereal("fagan_bradley")
    .calculate())

Supported ayanamsa systems: Lahiri, Fagan-Bradley, Raman, Krishnamurti, Yukteshwar, J.N. Bhasin, True Chitrapaksha, True Revati, and De Luce.

Chart metadata automatically tracks which zodiac system was used, making it easy to compare tropical and sidereal charts.

Fixed Stars Integration

Calculate and display 26 fixed stars in your charts, including the four Royal Stars of Persia.

from stellium import ChartBuilder
from stellium.components import FixedStarsComponent

# Add all 26 stars
chart = (ChartBuilder
    .from_notable("Albert Einstein")
    .with_component(FixedStarsComponent())
    .calculate())

# Or just the Royal Stars
chart = (ChartBuilder
    .from_notable("Albert Einstein")
    .with_component(FixedStarsComponent(royal_only=True))
    .calculate())

# Display in reports
from stellium import ReportBuilder

report = (ReportBuilder
    .from_chart(chart)
    .with_fixed_stars(tier=1)  # Royal Stars only
    .render(format="terminal", show=True))

Declination & Out-of-Bounds Planets

Every celestial position now includes both ecliptic AND equatorial coordinates.

chart = ChartBuilder.from_notable("Albert Einstein").calculate()

for planet in chart.positions.values():
    if planet.is_out_of_bounds:
        print(f"{planet.name} is out of bounds: {planet.declination:.2f}°")

Midpoint Aspects

New report section shows which planets aspect your midpoints - one of the most powerful midpoint techniques.

report = (ReportBuilder
    .from_chart(chart)
    .with_midpoint_aspects(mode="conjunction", orb=1.5)
    .render(format="terminal", show=True))

Enhancements

  • 21 new tests for progressions covering all angle methods and edge cases
  • 20 new tests for returns including solar, lunar, and planetary
  • Returns cookbook with 14 comprehensive examples
  • Enhanced report sections with graceful error handling
  • Improved metadata tracking for all chart types
  • Better visualization of multi-wheel charts

Fixes

  • Fixed PDF table header colors for better visual hierarchy
  • Fixed protocol mismatches in MockEphemerisEngine
  • Fixed aspect filtering in report sections
  • Performance improvements by removing redundant cache calls

Documentation

  • Complete API documentation for all three new systems
  • Comprehensive test coverage (60+ new tests)
  • Example code in changelog and cookbooks
  • Detailed docstrings with usage examples

Full Changelog: https://github.com/[your-repo]/stellium/blob/main/CHANGELOG.md

Assets 2
Loading