first commit

docs/geospatial/geo/tides/src/harmonic/harmonic-constituents.md

@@ -0,0 +1,54 @@
+# 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
+
+```ts
+import { CONSTITUENT_SPEEDS } from "@suaveplan/tides";
+
+const m2Speed = CONSTITUENT_SPEEDS.M2; // 28.984104 deg/hr
+```
+
+## Usage: Advanced Example
+
+```ts
+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.