Fixed Star Discovery #

The FixedStarDiscoveryFactory dynamically discovers fixed stars conjunct natal planets within a configurable orb. Unlike the per-subject stars requested via active_fixed_stars (none are computed by default), this factory scans the full star catalog provided by the ephemeris backend and returns only stars that are within orb of at least one active point.

Basic Usage #

from kerykeion import AstrologicalSubjectFactory, FixedStarDiscoveryFactory

subject = AstrologicalSubjectFactory.from_birth_data(
    "John", 1990, 6, 15, 14, 30,
    lng=12.5, lat=41.9, tz_str="Europe/Rome", online=False,
)

# Find fixed stars within 1 degree of any natal planet
stars = FixedStarDiscoveryFactory.find_prominent_stars(subject, orb=1.0)

for star in stars:
    print(f"{star.name}: {star.sign} {star.position:.2f} (mag: {star.magnitude})")
    print(f"  Conjunct: {star.near_point} (orb: {star.orb:.2f})")

Methods #

`find_prominent_stars(subject, orb)` #

Find fixed stars conjunct natal planets within the given orb.

Parameter	Type	Default	Description
`subject`	AstrologicalSubjectModel	–	A natal chart with a finite Julian Day
`orb`	float	1.0	Finite, non-negative maximum conjunction orb in degrees

Returns: List[KerykeionPointModel] sorted by magnitude (brightest first).

Return Fields #

Each returned KerykeionPointModel is enriched with discovery metadata:

Field	Type	Description
`name`	str	Star name from the catalog
`sign`	str	Zodiac sign
`position`	float	Position within the sign (0-30)
`degree`	float	Same value as `position`, under the generic point name
`abs_pos`	float	Absolute ecliptic longitude (0-360)
`longitude`	float	Same value as `abs_pos`
`latitude`	float	Ecliptic latitude of the star
`magnitude`	float	Apparent visual magnitude
`declination`	float	Equatorial declination
`speed`	float	Apparent longitudinal drift, dominated by precession
`retrograde`	bool	Always `False`: a fixed star never retrogrades
`house`	str or None	House placement (if house cusps are available)
`near_point`	str	Name of the nearest conjunct natal point
`orb`	float	Orb of the conjunction in degrees
`aspect`	str	Always `"conjunction"` – the only aspect this factory looks for
`source`	str	Which ephemeris source supplied the position
`precision_class`	str	Precision tier of that source

Catalog Source #

The catalog is sourced from libephemeris (the default backend). On the swisseph backend, the factory requires sefstars.txt to be present in the ephemeris data path (see Swiss Ephemeris Configuration for details); without it the scan logs a warning and returns whatever it could resolve, which is an incomplete list rather than an error.

Catalog enumeration uses immutable FixedStarMetadataModel entries containing name, canonical slug, optional Hipparcos number, nomenclature, visual magnitude, and constellation (the full IAU constellation name, e.g. "Orion", derived from the nomenclature suffix; None when the star has no standard constellation assignment). Discovery results remain enriched KerykeionPointModel objects as described above.

Wider Orb Example #

# Scan with a wider orb to find more stars
stars = FixedStarDiscoveryFactory.find_prominent_stars(subject, orb=2.0)
print(f"Found {len(stars)} stars within 2 degrees of natal planets")