Functions: DE Ephemeris

Optional high-precision function variants that use JPL DE440/441 ephemeris files when configured via the pg_orrery.ephemeris_path GUC. Each function mirrors an existing VSOP87/ELP2000-82B counterpart with identical parameters and return types.

All DE functions are STABLE STRICT PARALLEL SAFE (except pg_orrery_ephemeris_info which is STABLE PARALLEL SAFE, not STRICT). When DE is unavailable, they fall back to their VSOP87/ELP2000-82B equivalents.

See the DE Ephemeris guide for setup and configuration.

---

planet_heliocentric_de

Computes the heliocentric ecliptic J2000 position of a planet using DE positions when available, falling back to VSOP87.

Signature

planet_heliocentric_de(body_id int4, t timestamptz) → heliocentric

Parameters

Parameter	Type	Description
body_id	int4	Planet identifier: 0 (Sun), 1-8 (Mercury through Neptune)
t	timestamptz	Evaluation time

Returns

A heliocentric position in AU (ecliptic J2000 frame). Identical return type to planet_heliocentric().

Example

-- Compare DE vs VSOP87 heliocentric distances
SELECT body_id,
       round(helio_distance(planet_heliocentric(body_id, '2024-06-21 12:00:00+00'))::numeric, 10) AS vsop87,
       round(helio_distance(planet_heliocentric_de(body_id, '2024-06-21 12:00:00+00'))::numeric, 10) AS de
FROM generate_series(1, 8) AS body_id;

---

planet_observe_de

Computes the topocentric position of a planet using DE ephemeris for both the target and Earth positions.

Signature

planet_observe_de(body_id int4, obs observer, t timestamptz) → topocentric

Parameters

Parameter	Type	Description
body_id	int4	Planet identifier (1-8, excluding 3/Earth)
obs	observer	Observer location on Earth
t	timestamptz	Observation time

Caution

Body IDs 0 (Sun) and 3 (Earth) are not valid. Use sun_observe_de() for the Sun. Observing Earth from Earth raises an error.

Returns

A topocentric with azimuth, elevation, range (km), and range rate (km/s).

Example

-- Mars position from Boulder using DE
SELECT round(topo_azimuth(t)::numeric, 4) AS az,
       round(topo_elevation(t)::numeric, 4) AS el,
       round(topo_range(t)::numeric, 0) AS range_km
FROM planet_observe_de(4, '40.0N 105.3W 1655m'::observer, now()) AS t;

---

sun_observe_de

Computes the topocentric position of the Sun using DE positions.

Signature

sun_observe_de(obs observer, t timestamptz) → topocentric

Parameters

Parameter	Type	Description
obs	observer	Observer location on Earth
t	timestamptz	Observation time

Returns

A topocentric with azimuth, elevation, range (km), and range rate (km/s).

Example

SELECT round(topo_azimuth(t)::numeric, 2) AS az,
       round(topo_elevation(t)::numeric, 2) AS el
FROM sun_observe_de('40.0N 105.3W 1655m'::observer, now()) AS t;

---

moon_observe_de

Computes the topocentric position of the Moon using DE positions. Falls back to ELP2000-82B when DE is unavailable.

Signature

moon_observe_de(obs observer, t timestamptz) → topocentric

Parameters

Parameter	Type	Description
obs	observer	Observer location on Earth
t	timestamptz	Observation time

Returns

A topocentric with azimuth, elevation, range (km), and range rate (km/s).

Example

SELECT round(topo_azimuth(t)::numeric, 2) AS az,
       round(topo_elevation(t)::numeric, 2) AS el,
       round(topo_range(t)::numeric, 0) AS range_km
FROM moon_observe_de('40.0N 105.3W 1655m'::observer, now()) AS t;

---

lambert_transfer_de

Computes a Lambert transfer orbit using DE-precision planet positions.

Signature

lambert_transfer_de(
    dep_body_id int4,
    arr_body_id int4,
    dep_time timestamptz,
    arr_time timestamptz
) → RECORD(c3_departure float8, c3_arrival float8, v_inf_dep float8, v_inf_arr float8, tof_days float8)

Parameters

Parameter	Type	Description
dep_body_id	int4	Departure planet (1-8)
arr_body_id	int4	Arrival planet (1-8, different from departure)
dep_time	timestamptz	Departure epoch
arr_time	timestamptz	Arrival epoch (must be after departure)

Returns

Transfer orbit parameters including departure and arrival C3 (km^2/s^2), v-infinity magnitudes, and time of flight.

Example

-- Earth-Mars transfer window with DE positions
SELECT round(c3_departure::numeric, 2) AS c3_dep,
       round(c3_arrival::numeric, 2) AS c3_arr,
       round(tof_days::numeric, 1) AS tof
FROM lambert_transfer_de(3, 4, '2026-05-01 00:00:00+00', '2027-01-15 00:00:00+00');

---

lambert_c3_de

Returns only the departure C3 (km^2/s^2) from a Lambert transfer computation using DE positions. A convenience wrapper around lambert_transfer_de().

Signature

lambert_c3_de(dep_body_id int4, arr_body_id int4, dep_time timestamptz, arr_time timestamptz) → float8

Example

-- Pork chop grid with DE accuracy
SELECT dep::date AS departure,
       arr::date AS arrival,
       round(lambert_c3_de(3, 4, dep, arr)::numeric, 2) AS c3
FROM generate_series('2026-04-01'::timestamptz, '2026-08-01'::timestamptz, '14 days') dep,
     generate_series('2026-12-01'::timestamptz, '2027-04-01'::timestamptz, '14 days') arr
WHERE arr > dep + interval '90 days';

---

galilean_observe_de

Computes the topocentric position of a Galilean moon of Jupiter. Uses DE for Jupiter’s heliocentric position and L1.2 theory for the moon’s offset.

Signature

galilean_observe_de(moon_id int4, obs observer, t timestamptz) → topocentric

Parameters

Parameter	Type	Description
moon_id	int4	0=Io, 1=Europa, 2=Ganymede, 3=Callisto
obs	observer	Observer location
t	timestamptz	Observation time

Example

-- All four Galilean moons with DE-precision Jupiter
SELECT moon_id,
       CASE moon_id WHEN 0 THEN 'Io' WHEN 1 THEN 'Europa'
                    WHEN 2 THEN 'Ganymede' WHEN 3 THEN 'Callisto' END AS moon,
       round(topo_elevation(galilean_observe_de(moon_id, '40.0N 105.3W 1655m'::observer, now()))::numeric, 2) AS el
FROM generate_series(0, 3) AS moon_id;

---

saturn_moon_observe_de

Computes the topocentric position of a Saturn moon. Uses DE for Saturn’s heliocentric position and TASS17 theory for the moon’s offset.

Signature

saturn_moon_observe_de(moon_id int4, obs observer, t timestamptz) → topocentric

Parameters

Parameter	Type	Description
moon_id	int4	0=Mimas, 1=Enceladus, 2=Tethys, 3=Dione, 4=Rhea, 5=Titan, 6=Iapetus, 7=Hyperion
obs	observer	Observer location
t	timestamptz	Observation time

---

uranus_moon_observe_de

Computes the topocentric position of a Uranus moon. Uses DE for Uranus’s heliocentric position and GUST86 theory for the moon’s offset.

Signature

uranus_moon_observe_de(moon_id int4, obs observer, t timestamptz) → topocentric

Parameters

Parameter	Type	Description
moon_id	int4	0=Miranda, 1=Ariel, 2=Umbriel, 3=Titania, 4=Oberon
obs	observer	Observer location
t	timestamptz	Observation time

---

mars_moon_observe_de

Computes the topocentric position of a Mars moon. Uses DE for Mars’s heliocentric position and MarsSat theory for the moon’s offset.

Signature

mars_moon_observe_de(moon_id int4, obs observer, t timestamptz) → topocentric

Parameters

Parameter	Type	Description
moon_id	int4	0=Phobos, 1=Deimos
obs	observer	Observer location
t	timestamptz	Observation time

---

pg_orrery_ephemeris_info

Returns diagnostic information about the current ephemeris provider.

Signature

pg_orrery_ephemeris_info() → RECORD(provider text, file_path text, start_jd float8, end_jd float8, version int4, au_km float8)

Note

This function is STABLE PARALLEL SAFE but not STRICT --- it takes no arguments and always returns a row.

Returns

Column	Type	Description
provider	text	'VSOP87' or 'JPL_DE'
file_path	text	Path to the DE file (empty string if no DE)
start_jd	float8	First Julian Date covered by the DE file
end_jd	float8	Last Julian Date covered by the DE file
version	int4	DE version number (440, 441, etc.)
au_km	float8	Astronomical Unit in km from the DE header

Example

-- Check current provider
SELECT (pg_orrery_ephemeris_info()).provider;

-- Full diagnostic
SELECT * FROM pg_orrery_ephemeris_info();