pg_orrery/sql/pg_orbit--0.1.0--0.2.0.sql

-- pg_orbit 0.1.0 -> 0.2.0 migration
--
-- Phase 1: Stars, comets, and Keplerian propagation.
-- Adds heliocentric type, star observation, and two-body propagation.


-- ============================================================
-- Heliocentric type: ecliptic J2000 position in AU
-- ============================================================

CREATE TYPE heliocentric;

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

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

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

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

CREATE TYPE heliocentric (
    INPUT = heliocentric_in,
    OUTPUT = heliocentric_out,
    RECEIVE = heliocentric_recv,
    SEND = heliocentric_send,
    INTERNALLENGTH = 24,
    ALIGNMENT = double,
    STORAGE = plain
);

COMMENT ON TYPE heliocentric IS 'Heliocentric position in ecliptic J2000 frame (x, y, z in AU)';

CREATE FUNCTION helio_x(heliocentric) RETURNS float8
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION helio_x(heliocentric) IS 'X component in AU (ecliptic J2000, vernal equinox direction)';

CREATE FUNCTION helio_y(heliocentric) RETURNS float8
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION helio_y(heliocentric) IS 'Y component in AU (ecliptic J2000)';

CREATE FUNCTION helio_z(heliocentric) RETURNS float8
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION helio_z(heliocentric) IS 'Z component in AU (ecliptic J2000, north ecliptic pole)';

CREATE FUNCTION helio_distance(heliocentric) RETURNS float8
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION helio_distance(heliocentric) IS 'Heliocentric distance in AU';


-- ============================================================
-- Star observation functions
-- ============================================================

CREATE FUNCTION star_observe(float8, float8, observer, timestamptz) RETURNS topocentric
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION star_observe(float8, float8, observer, timestamptz) IS
    'Observe a star from (ra_hours J2000, dec_degrees J2000, observer, time). Returns topocentric az/el. Range is 0 (infinite distance).';

CREATE FUNCTION star_observe_safe(float8, float8, observer, timestamptz) RETURNS topocentric
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE PARALLEL SAFE;
COMMENT ON FUNCTION star_observe_safe(float8, float8, observer, timestamptz) IS
    'Like star_observe but returns NULL on invalid inputs. For batch queries over star catalogs.';


-- ============================================================
-- Keplerian propagation functions
-- ============================================================

CREATE FUNCTION kepler_propagate(
    q_au float8, eccentricity float8,
    inclination_deg float8, arg_perihelion_deg float8,
    long_asc_node_deg float8, perihelion_jd float8,
    t timestamptz
) RETURNS heliocentric
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION kepler_propagate(float8, float8, float8, float8, float8, float8, timestamptz) IS
    'Two-body Keplerian propagation from classical orbital elements. Returns heliocentric ecliptic J2000 position in AU. Handles elliptic, parabolic, and hyperbolic orbits.';


-- ============================================================
-- Comet observation
-- ============================================================

CREATE FUNCTION comet_observe(
    q_au float8, eccentricity float8,
    inclination_deg float8, arg_perihelion_deg float8,
    long_asc_node_deg float8, perihelion_jd float8,
    earth_x_au float8, earth_y_au float8, earth_z_au float8,
    obs observer, t timestamptz
) RETURNS topocentric
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION comet_observe(float8, float8, float8, float8, float8, float8, float8, float8, float8, observer, timestamptz) IS
    'Observe a comet/asteroid from orbital elements. Requires Earth heliocentric ecliptic J2000 position (AU). Returns topocentric az/el with geocentric range in km.';


-- ============================================================
-- Phase 2: VSOP87 planets, ELP82B Moon, Sun observation
-- ============================================================

CREATE FUNCTION planet_heliocentric(int4, timestamptz) RETURNS heliocentric
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION planet_heliocentric(int4, timestamptz) IS
    'VSOP87 heliocentric ecliptic J2000 position (AU). Body IDs: 0=Sun, 1=Mercury, ..., 8=Neptune.';

CREATE FUNCTION planet_observe(int4, observer, timestamptz) RETURNS topocentric
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION planet_observe(int4, observer, timestamptz) IS
    'Observe a planet from (body_id 1-8, observer, time). Returns topocentric az/el with geocentric range in km.';

CREATE FUNCTION sun_observe(observer, timestamptz) RETURNS topocentric
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION sun_observe(observer, timestamptz) IS
    'Observe the Sun from (observer, time). Returns topocentric az/el with geocentric range in km.';

CREATE FUNCTION moon_observe(observer, timestamptz) RETURNS topocentric
    AS 'MODULE_PATHNAME' LANGUAGE C IMMUTABLE STRICT PARALLEL SAFE;
COMMENT ON FUNCTION moon_observe(observer, timestamptz) IS
    'Observe the Moon via ELP2000-82B from (observer, time). Returns topocentric az/el with geocentric range in km.';