feat(magnetic): world 38, your compass does not point north

[Hotragn]

The geomagnetic field from IGRF-14, synthesised in the browser. NOAA supplies 195 Gauss coefficients per epoch and nothing else; the declination where you stand, the world map, all three poles, the century of pole drift, the dipole's decline and the South Atlantic Anomaly are all computed from them here.

What is on the page

• Declination, inclination, total and horizontal field at any place and any year from 1900 to 2030, with the annual rate and what an uncorrected bearing costs in kilometres.
• A world map of compass error at 28,800 sample points, including the two agonic lines where the error is exactly zero, drawn at the interpolated sign crossing rather than the sampled cell.
• The three north poles, computed: geographic, geomagnetic (3 coefficients, closed form) and the dip pole (all 195, iterative search), plus the southern dip pole that is 20 degrees from antipodal.
• The north dip pole's walk since 1900, with its speed: about 5 km/yr through the Canadian Arctic, 56 km/yr by 2005, and 40 km/yr by 2025. The acceleration is famous, the recent slowing is in the same data and quoted far less.
• The dipole moment, down 7.7% since 1900, and the South Atlantic Anomaly found by sweeping for the weakest total field.

How it is validated, in two independent ways
A spherical harmonic synthesis returns plausible five-figure numbers even when the Legendre recursion, the geodetic conversion or the frame rotation is wrong, so a range check proves nothing. The 48 tests compare against the frozen output of the official pyIGRF14 reference implementation at twelve places and dates, 1900 to 2029.9, sea level to 500 km, agreeing to 0.05 nT out of 50,000. On top of that, NOAA publishes its own pole positions: this code reproduces the 2025 geomagnetic pole at 80.79 N / 72.76 W and the 9.21 degree dipole tilt exactly, and lands 20 km from NOAA's dip pole, which is the honest gap between two current field models. The southern dip pole agrees to 0.01 degrees.

Three cross-module checks in lib/consistency.test.ts tie the computed pole to the constant lib/aurora was built on. They differ by 7 km, and the reason is worth keeping: WMM2020 was a prediction published in 2019, IGRF-14's 2020 column is a definitive retrospective fit. The oval is hundreds of km wide, so the constant stays, with a test to catch it if that ever changes.

A mirror with no cron, deliberately. Climate and carbon refresh monthly because an annual or monthly mean is a state that gets revised. A generation of IGRF is a frozen publication whose numbers will never change, so it is fetched once, committed and cited.

Stated on the page: degree 13 means the crustal field is absent, so over volcanic ground the real declination can be degrees away from this; the field wobbles daily and during storms while this is a quiet-day average; past 2025 the model is a straight line by construction and past 2030 it returns nothing; and the measured weakening is not a countdown to a reversal.

Three defects a screenshot caught and assertions did not: a moire lattice from alpha-composited overlapping cells (now one scaled image), a colour scale that blended through white and turned everything under 15 degrees into grey, and a "0% weaker than it was in 1900" comparison of the first epoch against itself.

Performance, measured rather than guessed: hoisting the coefficient interpolation out of the map loop was the obvious win and bought 15%. The real cost was 180 trig calls per point; computing cos and sin of m*lon once by angle addition took the whole-world pass from 1716 ms to about 550, and painting only the newly computed band per animation frame keeps the first render from freezing the page.

Verified: 1,423 tests pass, tsc clean, fresh production build, all 38 routes sweep clean, no console errors, no mobile overflow.

What & why

How to test

Checklist

• npm run build passes locally.
• npx vitest run passes (added or updated tests for new logic where it makes sense).
• No fake data. Every number this PR puts on screen traces to a data source or a documented calculation.
• Anything simulated is labeled as simulated in the UI, right where it appears.
• If this adds or changes a data source, its license and endpoint are logged in docs/DATA_SOURCES.md in this same PR.
• The project stays keyless — no new required API keys or .env config (a new source needing a key ships with a keyless fallback).
• Positioning still goes through lib/geo.ts; the globe mesh is not rotated (coordinate convention is locked).
• No new per-frame allocations in useFrame loops; heavy scenes stay dynamically imported (60fps budget on integrated graphics).

The honesty rule

This project's credibility rests on one rule: every number on screen traces to a real data source or a documented calculation, and anything simulated is labeled as simulated. By opening this PR you confirm your change respects it.

Screenshots / recording

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
h-o-t-earth	Ready	Preview	Aug 21, 2026 12:01am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hot-earth-docs	Ignored		Aug 21, 2026 12:01am