pg_orrery/sql/pg_orrery--0.8.0--0.9.0.sql

-- pg_orrery 0.8.0 -> 0.9.0 migration
--
-- Adds equatorial type (apparent RA/Dec of date), atmospheric refraction,
-- stellar proper motion, and light-time corrected _apparent() functions.

-- ============================================================
-- equatorial type — apparent RA/Dec of date
-- ============================================================

CREATE TYPE equatorial;

CREATE FUNCTION equatorial_in(cstring) RETURNS equatorial
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;

CREATE FUNCTION equatorial_out(equatorial) RETURNS cstring
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;

CREATE FUNCTION equatorial_recv(internal) RETURNS equatorial
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;

CREATE FUNCTION equatorial_send(equatorial) RETURNS bytea
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;

CREATE TYPE equatorial (
    INPUT = equatorial_in,
    OUTPUT = equatorial_out,
    RECEIVE = equatorial_recv,
    SEND = equatorial_send,
    INTERNALLENGTH = 24,
    ALIGNMENT = double,
    STORAGE = plain
);

COMMENT ON TYPE equatorial IS
    'Apparent equatorial coordinates of date: RA (hours), Dec (degrees), distance (km). Solar system: J2000 precessed via IAU 1976. Satellites: TEME frame (~of-date to ~arcsecond). 24 bytes, fixed-size.';


-- ============================================================
-- Equatorial accessor functions
-- ============================================================

CREATE FUNCTION eq_ra(equatorial) RETURNS float8
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION eq_ra(equatorial) IS 'Right ascension in hours [0, 24)';

CREATE FUNCTION eq_dec(equatorial) RETURNS float8
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION eq_dec(equatorial) IS 'Declination in degrees [-90, 90]';

CREATE FUNCTION eq_distance(equatorial) RETURNS float8
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION eq_distance(equatorial) IS 'Distance in km (0 for stars without parallax)';


-- ============================================================
-- Satellite RA/Dec functions
-- ============================================================

CREATE FUNCTION eci_to_equatorial(eci_position, observer, timestamptz) RETURNS equatorial
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION eci_to_equatorial(eci_position, observer, timestamptz) IS
    'Topocentric apparent RA/Dec from ECI position. Observer parallax-corrected — LEO parallax is ~1 degree.';

CREATE FUNCTION eci_to_equatorial_geo(eci_position, timestamptz) RETURNS equatorial
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION eci_to_equatorial_geo(eci_position, timestamptz) IS
    'Geocentric apparent RA/Dec from ECI position. Observer-independent — the direction of the TEME position vector.';


-- ============================================================
-- Solar system equatorial functions (VSOP87)
-- ============================================================

CREATE FUNCTION planet_equatorial(int4, timestamptz) RETURNS equatorial
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION planet_equatorial(int4, timestamptz) IS
    'Geocentric apparent RA/Dec of a planet via VSOP87. Body IDs: 1=Mercury through 8=Neptune.';

CREATE FUNCTION sun_equatorial(timestamptz) RETURNS equatorial
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION sun_equatorial(timestamptz) IS
    'Geocentric apparent RA/Dec of the Sun via VSOP87.';

CREATE FUNCTION moon_equatorial(timestamptz) RETURNS equatorial
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION moon_equatorial(timestamptz) IS
    'Geocentric apparent RA/Dec of the Moon via ELP2000-82B.';

CREATE FUNCTION small_body_equatorial(orbital_elements, timestamptz) RETURNS equatorial
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION small_body_equatorial(orbital_elements, timestamptz) IS
    'Geocentric apparent RA/Dec of a comet/asteroid from orbital elements. Earth via VSOP87.';

CREATE FUNCTION star_equatorial(float8, float8, timestamptz) RETURNS equatorial
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION star_equatorial(float8, float8, timestamptz) IS
    'Apparent RA/Dec of a star at a given time. Precesses J2000 catalog coordinates (RA hours, Dec degrees) to date via IAU 1976.';


-- ============================================================
-- Atmospheric refraction (Bennett 1982)
-- ============================================================

CREATE FUNCTION atmospheric_refraction(float8) RETURNS float8
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION atmospheric_refraction(float8) IS
    'Atmospheric refraction correction in degrees for a given geometric elevation (degrees). Standard atmosphere: P=1010 mbar, T=10C. Bennett (1982) formula with domain guard at -1 degree.';

CREATE FUNCTION atmospheric_refraction_ext(float8, float8, float8) RETURNS float8
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION atmospheric_refraction_ext(float8, float8, float8) IS
    'Atmospheric refraction with pressure/temperature correction. Args: elevation_deg, pressure_mbar, temperature_celsius. Meeus P/T factor applied to Bennett formula.';

CREATE FUNCTION topo_elevation_apparent(topocentric) RETURNS float8
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION topo_elevation_apparent(topocentric) IS
    'Apparent elevation in degrees — geometric elevation plus atmospheric refraction correction.';


-- ============================================================
-- Refracted pass prediction
-- ============================================================

CREATE FUNCTION predict_passes_refracted(
    tle, observer, timestamptz, timestamptz, float8 DEFAULT 0.0
) RETURNS SETOF pass_event
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE
    ROWS 20;
COMMENT ON FUNCTION predict_passes_refracted(tle, observer, timestamptz, timestamptz, float8) IS
    'Predict satellite passes using a refracted horizon threshold (-0.569 deg geometric). Atmospheric refraction makes satellites visible ~35 seconds earlier at AOS and later at LOS.';


-- ============================================================
-- Stellar proper motion
-- ============================================================

CREATE FUNCTION star_observe_pm(
    float8, float8, float8, float8, float8, float8, observer, timestamptz
) RETURNS topocentric
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION star_observe_pm(float8, float8, float8, float8, float8, float8, observer, timestamptz) IS
    'Observe a star with proper motion. Args: ra_hours, dec_deg, pm_ra_masyr (mu_alpha*cos(delta)), pm_dec_masyr, parallax_mas, rv_kms, observer, time. Hipparcos/Gaia convention for pm_ra.';

CREATE FUNCTION star_equatorial_pm(
    float8, float8, float8, float8, float8, float8, timestamptz
) RETURNS equatorial
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION star_equatorial_pm(float8, float8, float8, float8, float8, float8, timestamptz) IS
    'Apparent RA/Dec of a star with proper motion. Args: ra_hours, dec_deg, pm_ra_masyr, pm_dec_masyr, parallax_mas, rv_kms, time. Distance from parallax if > 0.';


-- ============================================================
-- Light-time corrected observation functions
-- ============================================================

CREATE FUNCTION planet_observe_apparent(int4, observer, timestamptz) RETURNS topocentric
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION planet_observe_apparent(int4, observer, timestamptz) IS
    'Observe a planet with single-iteration light-time correction. Body at retarded time, Earth at observation time. VSOP87.';

CREATE FUNCTION sun_observe_apparent(observer, timestamptz) RETURNS topocentric
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION sun_observe_apparent(observer, timestamptz) IS
    'Observe the Sun with light-time correction (~8.3 min). VSOP87.';

CREATE FUNCTION small_body_observe_apparent(orbital_elements, observer, timestamptz) RETURNS topocentric
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION small_body_observe_apparent(orbital_elements, observer, timestamptz) IS
    'Observe a comet/asteroid with single-iteration light-time correction. Kepler propagation at retarded time, Earth via VSOP87 at observation time.';


-- ============================================================
-- Light-time corrected equatorial functions
-- ============================================================

CREATE FUNCTION planet_equatorial_apparent(int4, timestamptz) RETURNS equatorial
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION planet_equatorial_apparent(int4, timestamptz) IS
    'Geocentric apparent RA/Dec of a planet with light-time correction. VSOP87.';

CREATE FUNCTION moon_equatorial_apparent(timestamptz) RETURNS equatorial
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION moon_equatorial_apparent(timestamptz) IS
    'Geocentric apparent RA/Dec of the Moon with light-time correction (~1.3 sec). ELP2000-82B.';

CREATE FUNCTION small_body_equatorial_apparent(orbital_elements, timestamptz) RETURNS equatorial
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION small_body_equatorial_apparent(orbital_elements, timestamptz) IS
    'Geocentric apparent RA/Dec of a comet/asteroid with light-time correction.';


-- ============================================================
-- DE ephemeris equatorial variants (STABLE)
-- ============================================================

CREATE FUNCTION planet_equatorial_de(int4, timestamptz) RETURNS equatorial
    AS 'MODULE_PATHNAME' LANGUAGE C STABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION planet_equatorial_de(int4, timestamptz) IS
    'Geocentric apparent RA/Dec of a planet via JPL DE ephemeris (falls back to VSOP87 + equatorial).';

CREATE FUNCTION moon_equatorial_de(timestamptz) RETURNS equatorial
    AS 'MODULE_PATHNAME' LANGUAGE C STABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION moon_equatorial_de(timestamptz) IS
    'Geocentric apparent RA/Dec of the Moon via JPL DE ephemeris (falls back to ELP2000-82B + equatorial).';