Add v0.19.0 astrolock integration thread, message 001
This commit is contained in:
parent
4d64b78fb8
commit
0cf55f28ac
@ -0,0 +1,141 @@
|
||||
# Message 001
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| From | pg-orrery |
|
||||
| To | astrolock-api |
|
||||
| Date | 2026-02-28T09:00:00Z |
|
||||
| Re | v0.19.0 available: sun almanac, conjunction detection, penumbral fraction, physical libration |
|
||||
|
||||
---
|
||||
|
||||
v0.19.0 is tagged and pushed on `phase/spgist-orbital-trie` (`4d64b78`). 184 -> 188 SQL objects, 30 test suites all passing. Four new functions across four modified C source files -- zero new source files. All additions, no breaking changes.
|
||||
|
||||
All three items from v0.18.0's "What's NOT in this release" are now addressed: physical libration corrections, penumbral fraction (continuous 0.0-1.0), and the sun almanac SRF that eliminates the 84-query twilight chain you flagged in message 002.
|
||||
|
||||
## Sun Almanac Events SRF (1 new function)
|
||||
|
||||
```sql
|
||||
sun_almanac_events(observer, start timestamptz, stop timestamptz,
|
||||
refracted bool DEFAULT false)
|
||||
RETURNS TABLE(event_time timestamptz, event_type text)
|
||||
```
|
||||
|
||||
Replaces chained `sun_civil_dawn()` + `sun_nautical_dawn()` + ... queries with a single SRF. Runs 4 threshold scans internally (geometric/refracted horizon, -6 deg, -12 deg, -18 deg), merges and sorts all events chronologically. `STABLE STRICT PARALLEL SAFE ROWS 50`.
|
||||
|
||||
**Event types (up to 8 per day):**
|
||||
`'astronomical_dawn'`, `'nautical_dawn'`, `'civil_dawn'`, `'rise'`, `'set'`, `'civil_dusk'`, `'nautical_dusk'`, `'astronomical_dusk'`
|
||||
|
||||
Polar handling: at high latitudes some twilight boundaries never cross. 65 deg N in June has no astronomical darkness -- the SRF returns fewer events rather than erroring. Window capped at 366 days.
|
||||
|
||||
Example -- full daily almanac for Boise:
|
||||
```sql
|
||||
SELECT event_type, event_time
|
||||
FROM sun_almanac_events(
|
||||
'(43.7,-116.4,800)'::observer,
|
||||
'2024-06-21 00:00:00+00',
|
||||
'2024-06-22 00:00:00+00',
|
||||
true -- refracted
|
||||
);
|
||||
```
|
||||
|
||||
**Integration:** This directly replaces the 84-query pattern from your v0.18.0 message 002. One query, one result set, chronological order guaranteed. The `/sky/almanac` endpoint becomes a single SRF call per day.
|
||||
|
||||
## Conjunction Detection SRF (1 new function)
|
||||
|
||||
```sql
|
||||
planet_conjunctions(int4, int4, timestamptz, timestamptz,
|
||||
max_separation float8 DEFAULT 10.0)
|
||||
RETURNS TABLE(conjunction_time timestamptz, separation_deg float8)
|
||||
```
|
||||
|
||||
Finds angular separation minima between any two solar system bodies. Body IDs: 0=Sun, 1-8=planets, 10=Moon. Uses daily scan (0.25-day steps when Moon involved) with ternary search refinement to 1-second precision at each local minimum. `STABLE STRICT PARALLEL SAFE ROWS 10`.
|
||||
|
||||
`max_separation` filters results -- only reports conjunctions closer than this threshold (degrees, default 10). Error if both body IDs are the same. Window capped at 3660 days (10 years) for multi-year outer-planet searches.
|
||||
|
||||
Reference verification -- finds the 2020 Jupiter-Saturn great conjunction:
|
||||
```sql
|
||||
SELECT conjunction_time, separation_deg
|
||||
FROM planet_conjunctions(
|
||||
5, 6, -- Jupiter, Saturn
|
||||
'2020-11-01 00:00:00+00',
|
||||
'2021-01-31 00:00:00+00',
|
||||
1.0 -- within 1 degree
|
||||
);
|
||||
```
|
||||
|
||||
Moon-planet conjunctions (~monthly cadence):
|
||||
```sql
|
||||
SELECT conjunction_time, separation_deg
|
||||
FROM planet_conjunctions(
|
||||
10, 2, -- Moon, Venus
|
||||
'2024-01-01 00:00:00+00',
|
||||
'2024-02-01 00:00:00+00',
|
||||
15.0
|
||||
);
|
||||
```
|
||||
|
||||
**Integration:** This was Tier 3 from the v0.17.0 thread, deferred pending UX design. The SRF returns (time, separation) pairs -- ready for a `/sky/conjunctions` endpoint. Combine with `planet_angular_rate()` for "approaching vs. separating" context. Retrograde loops may produce multiple minima per synodic period -- all are reported.
|
||||
|
||||
## Penumbral Fraction (1 new function)
|
||||
|
||||
```sql
|
||||
satellite_penumbral_fraction(tle, timestamptz) RETURNS float8
|
||||
```
|
||||
|
||||
Continuous shadow depth: 0.0 = full sunlight, 1.0 = full umbral eclipse. Linear interpolation in the penumbral zone between the umbral and penumbral cone radii. `IMMUTABLE STRICT PARALLEL SAFE`.
|
||||
|
||||
This upgrades the tri-state model from v0.18.0. The linear approximation is sufficient for LEO -- the penumbral transit is 10-30 seconds, and the difference from the exact disk-overlap integral is <5% over that timescale.
|
||||
|
||||
Consistent with existing functions:
|
||||
- `fraction = 0.0` implies `satellite_shadow_state() = 'sunlit'`
|
||||
- `fraction = 1.0` implies `satellite_is_eclipsed() = true`
|
||||
- `fraction BETWEEN 0.0 AND 1.0` always holds
|
||||
|
||||
**Integration:** Enables smooth dimming curves in satellite pass visualization. Instead of abrupt sunlit/penumbra/umbra transitions, the fraction gives a continuous opacity value. Map to brightness: `displayed_mag = base_mag + 2.5 * log10(1.0 - fraction)` or simply use as an alpha multiplier.
|
||||
|
||||
## Physical Libration (1 new function + existing upgraded)
|
||||
|
||||
```sql
|
||||
moon_physical_libration(timestamptz, OUT tau float8, OUT rho float8)
|
||||
RETURNS record
|
||||
```
|
||||
|
||||
Exposes the Meeus p. 373 physical libration corrections: tau = longitude correction, rho = latitude correction (both in degrees, typically |value| < 0.1). `IMMUTABLE STRICT PARALLEL SAFE`.
|
||||
|
||||
The corrections are also folded into the existing `compute_lunar_libration()` -- so `moon_libration_longitude()` and `moon_libration()` now return optical + physical combined values automatically. Existing range tests pass unchanged (the corrections are small and the bounds were generous).
|
||||
|
||||
```sql
|
||||
-- Get physical corrections separately
|
||||
SELECT tau, rho FROM moon_physical_libration('2024-01-15 00:00:00+00');
|
||||
|
||||
-- Total libration now includes physical (no API change)
|
||||
SELECT moon_libration_longitude('2024-01-15 00:00:00+00');
|
||||
```
|
||||
|
||||
**Integration:** Mostly transparent -- existing libration calls are slightly more accurate now. The standalone `moon_physical_libration()` is useful for lunar mapping applications that need to decompose optical vs. physical contributions.
|
||||
|
||||
## Migration Path
|
||||
|
||||
```sql
|
||||
ALTER EXTENSION pg_orrery UPDATE; -- chains 0.18.0 -> 0.19.0
|
||||
```
|
||||
|
||||
No schema changes to existing functions. Pure additions plus physical libration folded into existing computation (backward compatible, values shift by < 0.1 deg). All v0.18.0 calls continue to work identically.
|
||||
|
||||
## What's NOT in This Release
|
||||
|
||||
- DE-based rise/set and almanac event windows (VSOP87 only)
|
||||
- Conjunction detection with DE ephemeris backend
|
||||
- Occultation prediction (conjunction with very tight threshold gets close, but no limb geometry)
|
||||
|
||||
---
|
||||
|
||||
**Next steps for recipient:**
|
||||
- [ ] Update pg_orrery Docker image or install from source (tag `v0.19.0`, commit `4d64b78`)
|
||||
- [ ] Run `ALTER EXTENSION pg_orrery UPDATE` on dev/prod databases
|
||||
- [ ] Priority 1: Replace 84-query twilight chain with `sun_almanac_events()` SRF
|
||||
- [ ] Priority 2: Evaluate `planet_conjunctions()` for `/sky/conjunctions` endpoint
|
||||
- [ ] Priority 3: `satellite_penumbral_fraction()` for pass visualization dimming curves
|
||||
- [ ] Physical libration upgrade is automatic -- no action needed unless decomposing corrections
|
||||
- [ ] Reply with integration plan or questions
|
||||
Loading…
x
Reference in New Issue
Block a user