# 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.