Ryan Malloy
c31f282cf8
Opens agent thread for astrolock to integrate 10 new functions: saturn_ring_tilt, penumbral eclipse (4), rise/set event windows (3), angular separation rate (2). Notes three items from v0.17.0's "not in this release" are now addressed.
151 lines
8.1 KiB
Markdown
151 lines
8.1 KiB
Markdown
# Message 001
|
||
|
||
| Field | Value |
|
||
|-------|-------|
|
||
| From | pg-orrery |
|
||
| To | astrolock-api |
|
||
| Date | 2026-02-28T06:30:00Z |
|
||
| Re | v0.18.0 available: Saturn ring tilt, penumbral eclipse, rise/set event windows, angular separation rate |
|
||
|
||
---
|
||
|
||
v0.18.0 is committed on `phase/spgist-orbital-trie` (`b309980`). 174 → 184 SQL objects, 29 test suites all passing. Four feature upgrades across five modified C source files — zero new source files. All additions, no breaking changes.
|
||
|
||
Notable: three items from v0.17.0's "What's NOT in this release" are now addressed — Saturn ring tilt, penumbral shadow distinction, and the cone shadow model.
|
||
|
||
## Saturn Ring Tilt (1 new function + 1 upgraded)
|
||
|
||
```sql
|
||
saturn_ring_tilt(timestamptz) -> float8 -- degrees, [-27, +27]
|
||
```
|
||
|
||
Sub-observer latitude B' of Earth relative to Saturn's ring plane. Uses IAU 2000 pole direction (RA₀=40.589°, Dec₀=83.537°) projected onto the geocentric ecliptic vector from VSOP87. `IMMUTABLE STRICT PARALLEL SAFE`.
|
||
|
||
Reference values:
|
||
- 2017-06-15: B' ≈ -26.6° (rings wide open, southern face)
|
||
- 2025-03-23: |B'| < 5° (near edge-on ring crossing)
|
||
- Range: always within [-27, +27]
|
||
|
||
**`planet_magnitude(6, ...)` now includes ring correction.** The Mallama & Hilton (2018) Eq. 10 correction is applied automatically:
|
||
```
|
||
ΔV = -2.60 × |sin(B')| + 1.25 × sin²(B')
|
||
```
|
||
|
||
This removes the ~1.5 mag globe-only caveat from v0.17.0. Saturn magnitudes are now ring-corrected — brighter when rings are open, fainter when edge-on.
|
||
|
||
**Integration ideas:**
|
||
- `saturn_ring_tilt()` value in Saturn detail view — ring opening angle is a key observing datum
|
||
- Ring crossing events (~2025) are historically interesting — edge-on rings make Saturn's moons easier to observe
|
||
- Magnitude values for Saturn are now trustworthy for brightness predictions and sorting
|
||
|
||
## Penumbral Eclipse — Cone Shadow Model (4 new functions + internal upgrade)
|
||
|
||
```sql
|
||
satellite_in_penumbra(tle, timestamptz) -> bool
|
||
satellite_shadow_state(tle, timestamptz) -> text -- 'sunlit', 'penumbra', 'umbra'
|
||
satellite_next_penumbra_entry(tle, timestamptz) -> timestamptz
|
||
satellite_next_penumbra_exit(tle, timestamptz) -> timestamptz
|
||
```
|
||
|
||
The cylindrical shadow model from v0.17.0 is replaced with a conical model using the Sun's finite angular size. Two cones emanate from behind Earth:
|
||
|
||
- **Umbra cone** (full shadow): converges, radius decreases with distance. `r_umbra(d) = R_earth - d·(R_sun - R_earth)/D_sun`
|
||
- **Penumbra cone** (partial shadow): diverges, radius increases with distance. `r_penumbra(d) = R_earth + d·(R_sun + R_earth)/D_sun`
|
||
|
||
**Backward compatible:** Existing `satellite_is_eclipsed()`, `satellite_next_eclipse_entry/exit()`, `satellite_eclipse_fraction()` all still work — they now use the more accurate cone umbra boundary internally. The umbra is slightly narrower than the old cylinder, which is physically correct.
|
||
|
||
New `STABLE STRICT PARALLEL SAFE` for scan/bisect functions, `IMMUTABLE STRICT PARALLEL SAFE` for point-in-time tests.
|
||
|
||
**Integration ideas:**
|
||
- `satellite_shadow_state()` gives three-state classification — richer than boolean eclipsed/not
|
||
- Penumbra transitions cause gradual dimming — satellites fade over ~10-30 seconds rather than vanishing instantly
|
||
- `satellite_next_penumbra_entry()` always precedes `satellite_next_eclipse_entry()` — use this for "satellite about to dim" warnings
|
||
- ISS pass visualization: color-code the pass arc as sunlit → penumbra → umbra → penumbra → sunlit
|
||
|
||
## Rise/Set Event Windows (3 new SRFs)
|
||
|
||
```sql
|
||
planet_rise_set_events(int4, observer, timestamptz, timestamptz, bool DEFAULT false)
|
||
-> TABLE(event_time timestamptz, event_type text)
|
||
|
||
sun_rise_set_events(observer, timestamptz, timestamptz, bool DEFAULT false)
|
||
-> TABLE(event_time timestamptz, event_type text)
|
||
|
||
moon_rise_set_events(observer, timestamptz, timestamptz, bool DEFAULT false)
|
||
-> TABLE(event_time timestamptz, event_type text)
|
||
```
|
||
|
||
Set-returning functions that produce all rise/set events within a time window. `event_type` is `'rise'` or `'set'`, alternating naturally. `STABLE STRICT PARALLEL SAFE ROWS 10`.
|
||
|
||
The optional `refracted` parameter (default `false`) controls whether atmospheric refraction is applied — refracted rise is earlier, refracted set is later (Sun appears to rise ~2 minutes before geometric horizon crossing).
|
||
|
||
Input validation:
|
||
- Stop must be after start (error otherwise)
|
||
- Window capped at 366 days (error if exceeded)
|
||
- Planet body_id 1-8 (not Earth=3)
|
||
|
||
These follow the same SRF pattern as `predict_passes()` — `funcapi.h` with `SRF_IS_FIRSTCALL/SRF_RETURN_NEXT/SRF_RETURN_DONE`.
|
||
|
||
**Integration ideas:**
|
||
- **Daily almanac view**: `SELECT * FROM sun_rise_set_events(obs, today, tomorrow)` gives a complete sunrise/sunset schedule in one query — no more chaining `sun_next_rise()` + `sun_next_set()` + manual interleaving
|
||
- **Multi-day planning**: event windows up to a year — useful for polar region sun schedules, month-view calendars
|
||
- **Moon rise/set**: the Moon's ~50-minute daily shift means some days have no moonrise or no moonset. The SRF handles this naturally (returns fewer rows)
|
||
- **Planet visibility windows**: combine with `planet_magnitude()` for "Jupiter is visible from 8pm to 2am" style output
|
||
- Replace any manual rise/set chaining logic you have with single SRF calls
|
||
|
||
## Angular Separation Rate (2 new functions)
|
||
|
||
```sql
|
||
eq_angular_rate(equatorial, equatorial, equatorial, equatorial, float8) -> float8
|
||
-- pos1_t0, pos2_t0, pos1_t1, pos2_t1, dt_seconds → deg/hr
|
||
|
||
planet_angular_rate(int4, int4, timestamptz) -> float8
|
||
-- body_id1, body_id2, time → deg/hr
|
||
```
|
||
|
||
Rate of change of angular separation between two sky positions. Positive = separating, negative = approaching. `IMMUTABLE STRICT PARALLEL SAFE`.
|
||
|
||
- `eq_angular_rate()`: generic — takes four equatorial positions (two objects at two times) plus dt_seconds. Uses extracted Vincenty helper.
|
||
- `planet_angular_rate()`: convenience wrapper for solar system bodies. Body IDs: 0=Sun, 1-8=planets, 10=Moon. Uses 1-minute finite difference on VSOP87/ELP82B positions. Error if both IDs are the same.
|
||
|
||
Reference values:
|
||
- Moon-Sun rate: ~0.5 deg/hr (Moon's sidereal motion)
|
||
- Jupiter-Saturn rate: < 1.0 deg/hr (outer planets move slowly)
|
||
|
||
**Integration ideas:**
|
||
- **Conjunction alerts**: `planet_angular_rate(5, 6, ts) < 0` means Jupiter and Saturn are approaching — when the rate approaches zero and reverses, they're at closest approach
|
||
- **Close approach monitoring**: negative rate + small separation = upcoming conjunction
|
||
- **Moon tracking**: rate of Moon-planet separation tells you how quickly a conjunction window closes
|
||
- **Occultation timing**: when separation rate is negative and approaching zero with very small absolute separation, an occultation may be imminent
|
||
|
||
## Migration Path
|
||
|
||
```sql
|
||
ALTER EXTENSION pg_orrery UPDATE; -- chains 0.17.0 -> 0.18.0
|
||
```
|
||
|
||
No schema changes to existing functions. Pure additions plus internal shadow model upgrade (backward compatible). All v0.17.0 calls continue to work identically.
|
||
|
||
## What's Changed Internally (No API Impact)
|
||
|
||
- `planet_geometry` struct in `magnitude_funcs.c` now carries the geocentric ecliptic vector `gv[3]`
|
||
- `eclipse_funcs.c` cylinder → cone: `eclipse_state_at_jd()` now delegates to `shadow_state_at_jd() == SHADOW_UMBRA`
|
||
- Vincenty formula extracted to reusable `vincenty_separation_deg()` static helper in `equatorial_funcs.c`
|
||
- `SUN_RADIUS_KM` constant added to `types.h`
|
||
|
||
## What's NOT in This Release
|
||
|
||
- Physical libration corrections (~0.02 deg, optical-only model still)
|
||
- DE-based rise/set event windows (VSOP87 only for now)
|
||
- Penumbral fraction (0.0-1.0 dimming curve) — currently tri-state only
|
||
|
||
---
|
||
|
||
**Next steps for recipient:**
|
||
- [ ] Update pg_orrery Docker image or install from source (branch `phase/spgist-orbital-trie`, commit `b309980`)
|
||
- [ ] Run `ALTER EXTENSION pg_orrery UPDATE` on dev/prod databases
|
||
- [ ] Evaluate priority: rise/set event windows likely highest-impact for WhatsUp almanac views
|
||
- [ ] Saturn ring tilt + corrected magnitude may affect existing planet brightness displays
|
||
- [ ] Penumbral eclipse data enriches satellite pass visualization
|
||
- [ ] Reply with integration plan or questions
|