harmonic-constituents

Purpose

Astronomical helper functions, Doodson coefficient tables, and per-constituent angular-speed tables consumed by the harmonic tide-prediction engine. This module is split out of harmonic.ts so that the prediction algorithm and its lookup data each stay below the 300-line file budget while remaining colocated under src/harmonic/. Every export is a pure, stateless utility — no I/O, no shared state.

Features

julianDate(date) and J2000-relative century parameter helpers feeding mean-longitude polynomials.
Mean longitude functions for Moon (s), Sun (h), lunar perigee (p), ascending lunar node (N), and solar perigee (pp).
astronomicalArgument(name, time) — Doodson-coefficient combination yielding V₀ + u for a named constituent.
nodeFactor(name, time) — Schureman-approximation f factor for amplitude modulation.
DOODSON_NUMBERS table covering 30+ constituents (M2, S2, N2, K2, K1, O1, P1, Q1, M4, MS4, MN4, M6, …).
CONSTITUENT_SPEEDS angular-speed table in degrees per hour.

Usage: Basic Example

import { CONSTITUENT_SPEEDS } from "@suaveplan/tides";

const m2Speed = CONSTITUENT_SPEEDS.M2; // 28.984104 deg/hr

Usage: Advanced Example

import {
    astronomicalArgument,
    DOODSON_NUMBERS,
    nodeFactor,
} from "@suaveplan/tides";

const time = new Date("2024-06-15T12:00:00Z");
for (const name of Object.keys(DOODSON_NUMBERS)) {
    const v0 = astronomicalArgument(name, time);
    const f = nodeFactor(name, time);
    console.log(name, v0.toFixed(2), f.toFixed(4));
}

API Reference

toRad(deg: number): number — degrees to radians.
julianDate(date: Date): number — Julian Day Number including fractional day.
normalize(deg: number): number — wrap angle into [0, 360).
meanLongitudeMoon|Sun|LunarPerigee|LunarNode|SolarPerigee(T: number): number — mean longitudes evaluated at Julian centuries since J2000.
astronomicalArgument(name: string, time: Date): number — V₀ + u in degrees, returns 0 for unknown names.
nodeFactor(name: string, time: Date): number — f in [~0.7, ~1.3], returns 1.0 for unrecognised constituents.
DOODSON_NUMBERS: Record<string, readonly [number, number, number, number, number, number]> — six-tuple (τ, s, h, p, N, pp) coefficients.
CONSTITUENT_SPEEDS: Record<string, number> — angular speed in degrees per hour.

Implementation Notes

Mean-longitude polynomials are truncated to the linear term in T (Julian centuries since J2000.0). This is adequate for short-range tide prediction but not for high-precision astronomical work — for centennial accuracy, quadratic and cubic terms from Meeus' Astronomical Algorithms are required. Node factors are simplified Schureman approximations: full-rigour evaluation requires lunar node N and lunar-perigee p together, but for engineering work the dominant cos N/cos 2N terms suffice. The Doodson and speed tables are intentionally exposed as plain Record<string, …> to keep registry extension a one-liner for callers shipping additional shallow-water or compound constituents.

3.1 KiB Raw Blame History