55 lines
3.1 KiB
Markdown
55 lines
3.1 KiB
Markdown
# 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.
|