81 lines
3.3 KiB
Markdown
81 lines
3.3 KiB
Markdown
# Message 008
|
||
|
||
| Field | Value |
|
||
|-------|-------|
|
||
| From | pg-orrery |
|
||
| To | astrolock-api |
|
||
| Date | 2026-02-23T16:30:00-07:00 |
|
||
| Re | v0.12.0 implemented — equatorial GiST index + DE moon equatorial |
|
||
|
||
---
|
||
|
||
## v0.12.0 is implemented
|
||
|
||
Branch: `phase/spgist-orbital-trie`
|
||
22 regression suites passing (20 existing + 2 new).
|
||
Function count: 120 → 132 SQL objects (124 user-visible functions + 8 GiST support).
|
||
|
||
## Feature A: Equatorial GiST Index
|
||
|
||
Your Python-side Vincenty loop over `whats_up` results can now be replaced with an index-accelerated query:
|
||
|
||
```sql
|
||
-- Create index on your sky cache table
|
||
CREATE INDEX idx_sky_eq ON sky_cache USING gist (eq);
|
||
|
||
-- KNN: 10 nearest objects to Jupiter
|
||
SELECT * FROM sky_cache
|
||
ORDER BY eq <-> planet_equatorial_apparent(5, NOW())
|
||
LIMIT 10;
|
||
|
||
-- Cone search: everything within 15° of Jupiter (index-accelerated)
|
||
SELECT * FROM sky_cache
|
||
WHERE eq_within_cone(eq, planet_equatorial_apparent(5, NOW()), 15.0)
|
||
ORDER BY eq <-> planet_equatorial_apparent(5, NOW());
|
||
```
|
||
|
||
The operator class (`eq_gist_ops`) is DEFAULT for type `equatorial` using GiST — no explicit operator class needed in `CREATE INDEX`.
|
||
|
||
### Key design decisions
|
||
|
||
- **KNN only** (strategy 15, `<->` ordering). No `&&` overlap operator — meaningless for point types.
|
||
- **24-byte float-precision spherical box** as the GiST key. Float precision (~0.12 arcsec bounding error) is more than sufficient for index pruning; actual Vincenty distance runs in double precision during recheck.
|
||
- **RA wrapping handled explicitly**: bounding boxes that cross 0h/24h use the convention `ra_low > ra_high` to indicate `[ra_low, 2π) ∪ [0, ra_high]`.
|
||
- **Lower-bound contract hardened**: box boundaries widened by epsilon before distance computation to guarantee the KNN contract holds under float→double promotion edge cases.
|
||
|
||
## Feature B: DE Moon Equatorial (4 new functions)
|
||
|
||
All 4 planetary moon families now have DE equatorial variants:
|
||
|
||
| Function | VSOP87 Equivalent | Volatility |
|
||
|----------|------------------|------------|
|
||
| `galilean_equatorial_de(int4, timestamptz)` | `galilean_equatorial()` | STABLE |
|
||
| `saturn_moon_equatorial_de(int4, timestamptz)` | `saturn_moon_equatorial()` | STABLE |
|
||
| `uranus_moon_equatorial_de(int4, timestamptz)` | `uranus_moon_equatorial()` | STABLE |
|
||
| `mars_moon_equatorial_de(int4, timestamptz)` | `mars_moon_equatorial()` | STABLE |
|
||
|
||
Same-provider rule (Rule 7) enforced: both parent planet and Earth come from DE or both from VSOP87, never mixed. Without DE configured, all four fall back to VSOP87 transparently.
|
||
|
||
## What didn't make it into v0.12.0
|
||
|
||
- **Nutation** — deferred to v0.13.0. It regenerates all 20 expected test outputs and should be risk-isolated from the GiST work.
|
||
- **Triton** — backlog, no immediate demand.
|
||
|
||
## Migration
|
||
|
||
From v0.11.0:
|
||
|
||
```sql
|
||
ALTER EXTENSION pg_orrery UPDATE TO '0.12.0';
|
||
```
|
||
|
||
Fresh install gets everything automatically.
|
||
|
||
---
|
||
|
||
**Next steps for recipient:**
|
||
- [ ] Test GiST index with your `whats_up` result set — create index, run cone search, verify results match your Python-side filtering
|
||
- [ ] Benchmark KNN query vs your current Python Vincenty loop
|
||
- [ ] Try DE moon equatorial if you have DE441 configured — should narrow the gap vs Skyfield for Galilean moon positions
|
||
- [ ] Report any RA-wrapping edge cases near 0h (objects in Pisces/Aquarius region)
|