Four features, 10 new SQL functions (174 → 184 objects), 29 test suites:
Saturn ring tilt: saturn_ring_tilt() exposes sub-observer latitude B'.
planet_magnitude() for Saturn now includes Mallama & Hilton Eq. 10
ring correction (-2.60|sin B'| + 1.25 sin²B'), removing the ~1.5 mag
globe-only caveat. IAU 2000 pole direction, ecliptic J2000 projection.
Conical shadow model: Replaces cylindrical shadow with umbra/penumbra
cones using Sun's finite angular size. Four new functions:
satellite_in_penumbra(), satellite_shadow_state(),
satellite_next_penumbra_entry/exit(). Existing eclipse functions are
backward compatible via narrower (more accurate) umbra boundary.
Rise/set event windows: Three SRFs returning TABLE(event_time, event_type)
for all rise/set events within a time window — planet_rise_set_events(),
sun_rise_set_events(), moon_rise_set_events(). Follows predict_passes()
SRF pattern. Optional refracted parameter, 366-day window limit.
Angular separation rate: Vincenty formula extracted to reusable helper.
eq_angular_rate() for generic finite-difference rate, planet_angular_rate()
for solar system body convenience (1-minute dt, handles Sun/planets/Moon).
Three-tier plan: elongation+phase+eclipse in existing SQL (immediate),
observing_night_quality as secondary signal (next), lunar libration in
new Moon detail section (later). Questions on TLE CTE reuse and eclipse
fraction compute cost.
162 → 174 SQL objects, 27 → 28 test suites, 3 new C source files.
Features:
- solar_elongation(body_id, ts): Sun-Earth-Planet angle [0,180] degrees
- planet_phase(body_id, ts): illuminated disk fraction [0,1]
- satellite_is_eclipsed/next_eclipse_entry/exit/eclipse_fraction:
cylindrical shadow model (Vallado §5.3) for Earth shadow prediction
- observing_night_quality(observer, ts): composite PL/pgSQL scoring
based on astronomical darkness duration and Moon interference
- moon_libration_longitude/latitude/position_angle/libration/subsolar_longitude:
optical libration from Meeus (1998) Ch. 53
Refactored magnitude_funcs.c to extract shared compute_planet_geometry()
used by magnitude, elongation, and phase — single VSOP87 evaluation per call.
All 28 regression suites pass. Zero compiler warnings.
The original implementation only used c1+c2 coefficients from the
simplified model. Mercury's 6th-order polynomial diverges badly
beyond ~60 deg phase angle with only 2 terms — returning -23 mag
at 130 deg (should be +1.1).
Now uses the complete piecewise models from the paper:
- Mercury: full 6th-order polynomial (Eq. 1)
- Venus: piecewise at 163.7 deg (Eq. 2/3)
- Mars: piecewise at 50 deg (Eq. 5/6)
- Jupiter: piecewise at 12 deg with log term (Eq. 7/8)
- Saturn: globe-only model (Eq. 11/12), ring tilt still not modeled
- Uranus: phase threshold at 3.1 deg (Eq. 14)
- Neptune: phase threshold at 1.9 deg (Eq. 17)
Bug found by astrolock: Mercury at superior conjunction (i=130.6 deg)
returned -23.3 mag instead of +1.1.
Twilight: 6 functions (civil/nautical/astronomical × dawn/dusk) reusing
the existing find_next_crossing() bisection search with Sun depression
angle thresholds (-6°, -12°, -18°). Returns NULL for polar regions
where the threshold is never reached.
Lunar phase: 4 functions computing Sun-Earth-Moon geometry from VSOP87
+ ELP2000-82B. Phase angle [0,360) via elongation + cross product
z-component for waxing/waning discrimination. 8 named phases in 45°
bins. Moon age approximated from phase angle and mean synodic month.
Planet magnitude: Mallama & Hilton (2018) polynomial model with VSOP87
heliocentric distances and phase angle via law of cosines. All 7
planets (Mercury-Neptune, excluding Earth). Saturn ring tilt not
modeled.
151 → 162 SQL objects. 26 → 27 test suites, all passing.
constellation_full_name(text) returns full IAU name from 3-letter
abbreviation (88-entry static table, IMMUTABLE). Returns NULL for
invalid input — composable with constellation() in queries.
Three rise_set_status functions classify body visibility as
'rises_and_sets', 'circumpolar', or 'never_rises' by sampling
elevation at 48 points across 24h. Separate diagnostic path —
called only when rise/set returns NULL, zero cost in normal case.
147 → 151 SQL objects. 25 → 26 regression suites. All pass.
Add 4 refracted rise/set functions completing the rise/set feature set:
- planet_next_rise/set_refracted: -0.569 deg threshold (refraction only,
point source — even Jupiter at opposition is only 24 arcsec)
- moon_next_rise/set_refracted: -0.833 deg threshold (refraction +
mean semidiameter, same as Sun)
Add IAU constellation identification from Roman (1987) CDS VI/42:
- 357 boundary segments covering all 88 constellations
- Precesses J2000 coordinates to B1875.0 epoch for lookup
- Two overloads: constellation(equatorial) and constellation(float8, float8)
- IMMUTABLE (compiled-in static data)
141 -> 147 SQL objects. 24 -> 25 regression suites. All 25 pass.
Integrate IAU 2000B nutation (~9 arcsec) into the solar system observation
pipeline via precess_and_nutate_j2000_to_date(). Affects all planet, star,
moon, and small body RA/Dec and az/el values. Satellite SGP4/TEME pipeline
unchanged.
Add make_equatorial(ra_hours, dec_deg, distance_km) constructor to replace
error-prone text literal casts.
Add 8 rise/set prediction functions (planet_next_rise/set, sun_next_rise/set,
moon_next_rise/set, sun_next_rise/set_refracted) using bisection algorithm
adapted from satellite pass prediction. Returns NULL for circumpolar and
polar night edge cases.
Fix DE fallback test fragility: replace exact float equality with tolerance
comparisons to handle GCC LTO inlining divergence across translation units.
132 -> 141 SQL objects. 22 -> 24 regression suites. All 24 passing.
CLAUDE.md: bump version to 0.12.0, function count to 132, test count
to 22, add v0.10-0.12 SQL files to layout, add gist_equatorial.c,
update function domains table, add DE moon equatorial to DE variants.
Docs: add equatorial GiST operator class section to operators-gist.mdx
(KNN queries, cone search, RA wrapping, polar behavior). Add 4 DE moon
equatorial functions to functions-de.mdx (galilean, saturn, uranus, mars).
- Add validate_orbital_elements_args() with isnan/isinf checks for all
7 propagation parameters (epoch, q, e, inc, omega, node, tp); h_mag
and g_slope exempt (NaN is valid sentinel for "unknown magnitude")
- Deduplicate validation between make_orbital_elements() and _deg()
- Update SQL COMMENTs to clarify geometric vs apparent coordinates
- Add NaN/Inf rejection tests (q, e, epoch, Inf inclination)
- Add NaN H/G acceptance test (sentinel value)
- Expand error path coverage to all 4 moon families + negative body_id
- All 20 regression suites pass
6 new SQL functions (114 -> 120):
- make_orbital_elements(): construct from 9 floats, angles in radians
- make_orbital_elements_deg(): same with angles in degrees, matches
text I/O convention and typical catalog column layouts
- galilean_equatorial(): geocentric RA/Dec for Io/Europa/Ganymede/Callisto
- saturn_moon_equatorial(): geocentric RA/Dec for Mimas through Hyperion
- uranus_moon_equatorial(): geocentric RA/Dec for Miranda through Oberon
- mars_moon_equatorial(): geocentric RA/Dec for Phobos/Deimos
Constructors requested by astrolock-api to replace fragile
format(9 args)::orbital_elements cast pattern. Moon equatorial
functions fill the last NULL RA/Dec gaps in their unified sky query.
All 20 regression suites pass.
- Add timing numbers for equatorial, aberration, angular distance,
refraction, and star proper motion+parallax to benchmarks page
- Update From Skyfield page: v0.10.0 now has light-time + aberration
parity; remaining gap narrowed to nutation (~9 arcsec) and polar motion
- Update llms.txt and llms-full.txt for 114 functions, new DE apparent
variants, equatorial spatial operators, and aberration/parallax notes
Annual stellar aberration (~20 arcsec) added to all 6 existing _apparent()
functions via classical first-order v/c projection (Ron & Vondrak). Earth
velocity sourced from VSOP87 xyz[3..5] (analytic) or DE numerical
differentiation.
New functions (106 -> 114):
- eq_angular_distance(): Vincenty formula, stable at 0 and 180 deg
- eq_within_cone(): cosine shortcut for fast cone-search predicate
- <-> operator on equatorial type
- 6 DE apparent variants with VSOP87 fallback:
planet/sun/moon_observe_apparent_de(),
planet/moon_equatorial_apparent_de(),
small_body_observe_apparent_de()
Stellar parallax now functional in star_observe_pm() and
star_equatorial_pm() — Green (1985) Eq. 11.3 displacement using
Earth heliocentric position from VSOP87.
All 19 regression suites pass (18 existing + new aberration suite).
