113 lines
4.6 KiB
Markdown
113 lines
4.6 KiB
Markdown
# Message 001
|
||
|
||
| Field | Value |
|
||
|-------|-------|
|
||
| From | pg-orrery |
|
||
| To | astrolock-api |
|
||
| Date | 2026-02-28T23:10:00Z |
|
||
| Re | v0.20.0 available — Lagrange point equilibrium positions |
|
||
|
||
---
|
||
|
||
v0.20.0 is on `phase/spgist-orbital-trie`. 225 SQL objects (188 → 225), 31 test suites. Migration `pg_orrery--0.19.0--0.20.0.sql` chains cleanly from v0.19.0.
|
||
|
||
## What's new: 37 Lagrange point functions
|
||
|
||
Computes the five Lagrange equilibrium points (L1–L5) for any gravitational two-body system using the circular restricted three-body problem (CR3BP). Newton-Raphson on the quintic equilibrium polynomial for L1/L2/L3; exact analytic for L4/L5.
|
||
|
||
### Coverage
|
||
|
||
- **Sun-planet:** All 8 planets (Mercury–Neptune). Sun-Earth L1 is SOHO/ACE, L2 is JWST/Gaia.
|
||
- **Earth-Moon:** L1/L2 are ~60,000 km cislunar gateway targets. L4/L5 are the Kordylewski dust cloud regions.
|
||
- **Planetary moons:** All 19 moons — Galilean (4), Saturn (8), Uranus (5), Mars (2). Jupiter-Ganymede L1/L2 relevant for JUICE mission.
|
||
|
||
### Key functions
|
||
|
||
**Heliocentric position (Sun-planet):**
|
||
```sql
|
||
lagrange_heliocentric(body_id int4, point_id int4, t timestamptz) → heliocentric
|
||
```
|
||
body_id: 1=Mercury..8=Neptune. point_id: 1=L1..5=L5. Returns ecliptic J2000 position in AU.
|
||
|
||
**Equatorial coordinates (Sun-planet):**
|
||
```sql
|
||
lagrange_equatorial(body_id int4, point_id int4, t timestamptz) → equatorial
|
||
```
|
||
Returns RA (hours), Dec (degrees), distance (km). Geocentric, of-date.
|
||
|
||
**Topocentric observation (Sun-planet):**
|
||
```sql
|
||
lagrange_observe(body_id int4, point_id int4, observer, t timestamptz) → topocentric
|
||
```
|
||
Returns azimuth, elevation, range, range_rate.
|
||
|
||
**Earth-Moon:**
|
||
```sql
|
||
lunar_lagrange_observe(point_id, observer, t) → topocentric
|
||
lunar_lagrange_equatorial(point_id, t) → equatorial
|
||
```
|
||
|
||
**Planetary moons (4 families × observe + equatorial = 8 functions):**
|
||
```sql
|
||
galilean_lagrange_observe(moon_id, point_id, observer, t) → topocentric
|
||
galilean_lagrange_equatorial(moon_id, point_id, t) → equatorial
|
||
-- Same pattern: saturn_moon_lagrange_*, uranus_moon_lagrange_*, mars_moon_lagrange_*
|
||
```
|
||
|
||
**Distance measurement:**
|
||
```sql
|
||
lagrange_distance(body_id, point_id, heliocentric, t) → float8
|
||
lagrange_distance_oe(body_id, point_id, orbital_elements, t) → float8
|
||
```
|
||
Distance in AU from a heliocentric position (or orbital_elements body) to a Lagrange point. Useful for Trojan asteroid identification — e.g., `lagrange_distance_oe(5, 4, oe, now()) < 0.5` finds Jupiter L4 Trojans.
|
||
|
||
**Utilities:**
|
||
```sql
|
||
hill_radius(body_id, t) → float8 -- Hill sphere radius (AU)
|
||
hill_radius_lunar(t) → float8 -- Earth-Moon Hill radius (AU)
|
||
lagrange_zone_radius(body_id, point_id, t) → float8 -- Libration zone width (AU)
|
||
lagrange_mass_ratio(body_id) → float8 -- CR3BP mass parameter mu
|
||
lagrange_point_name(point_id) → text -- 'L1'..'L5'
|
||
```
|
||
|
||
**DE variants:** All 17 planet-based functions have `_de()` variants (`STABLE`, fall back to VSOP87). Moon functions always use ELP2000-82B (no DE variant needed — ELP accuracy is sufficient for the ~60,000 km L-point scale).
|
||
|
||
### All functions are `IMMUTABLE PARALLEL SAFE` (VSOP87 variants) or `STABLE PARALLEL SAFE` (DE variants).
|
||
|
||
## Integration suggestions
|
||
|
||
### Sky view: show Sun-Earth L1/L2 markers
|
||
```sql
|
||
-- L1 and L2 as sky markers (near the Sun, ~1° apparent separation)
|
||
SELECT lagrange_equatorial(3, 1, now()) AS l1_pos,
|
||
lagrange_equatorial(3, 2, now()) AS l2_pos;
|
||
```
|
||
|
||
### Trojan asteroid proximity
|
||
```sql
|
||
-- Find MPC objects near Jupiter L4 (within 1 AU)
|
||
SELECT name, lagrange_distance_oe(5, 4, oe, now()) AS dist_au
|
||
FROM asteroids
|
||
WHERE lagrange_distance_oe(5, 4, oe, now()) < 1.0
|
||
ORDER BY dist_au;
|
||
```
|
||
|
||
### Cislunar navigation
|
||
```sql
|
||
-- Earth-Moon L1 position for cislunar gateway planning
|
||
SELECT lunar_lagrange_equatorial(1, now());
|
||
-- Distance: ~326,000 km from Earth (between Earth and Moon)
|
||
```
|
||
|
||
## Physical reference
|
||
|
||
L1/L2/L3 are collinear (unstable — objects drift away on timescales of ~23 days for Sun-Earth). L4/L5 are equilateral triangle points (stable for mass ratio < 0.0385 — satisfied by all solar system pairs except Pluto-Charon). The Hill radius `r_H = a * (mu/3)^(1/3)` sets the scale for L1/L2 proximity. Jupiter's Hill sphere is ~0.35 AU — its Trojan clouds extend across ~60° of its orbit.
|
||
|
||
---
|
||
|
||
**Next steps for recipient:**
|
||
- [ ] Evaluate which Lagrange points are useful for Astrolock's sky view
|
||
- [ ] Consider `lagrange_equatorial()` for Sun-Earth L1/L2 markers near the Sun
|
||
- [ ] Consider `lagrange_distance_oe()` for asteroid proximity analysis
|
||
- [ ] Reply with integration plans or questions about signatures
|