Magnetic declination

sextant/magnetic answers the question every magnetic compass on board raises: how far is magnetic north from true north, here, today?

That difference is the magnetic declination — "variation" on a chart. It is not a constant. It depends on where the boat is, and it drifts year on year as the Earth's field moves. Off Brest it is currently around a degree; in parts of the Southern Ocean it exceeds 30°. Getting it wrong by 5° puts a 60-mile leg six miles off track.

The report carries three numbers:

Field	Unit	What it is
declination	degrees, positive = east	angle from true north to magnetic north
inclination	degrees	the "dip" — how far the field points into the ground; positive in the northern magnetic hemisphere
totalIntensity	nanotesla (nT)	the strength of the field, roughly 25 000–65 000 nT at the surface

{
  "data": {
    "declination": -1.23,
    "inclination": 64.5,
    "totalIntensity": 48250.0
  },
  "metadata": { "rxDate": "2026-08-16T10:31:02Z", "expireAfterSec": 3600 }
}

declination is the one anything else on the boat uses; inclination and totalIntensity are published because the model produces them and they are useful for diagnosing a magnetometer.

The model

The numbers come from the World Magnetic Model, the standard spherical-harmonic model of the Earth's main field. The daemon uses the reference implementation published by NOAA's National Centers for Environmental Information, compiled into the binary, and reads its coefficients from a plain text file:

/var/lib/muxen-sextant/WMM.COF

That file ships in the muxen-sextant-database package. Its first line is its own identity:

    2025.0            WMM-2025     11/13/2024

— epoch 2025.0, model WMM-2025, released 13 November 2024. The path is overridable with --wmm-cof-path; the default is {data-dir}/WMM.COF.

The file is parsed once and cached for the life of the process, keyed on its path. Changing the file on disk therefore has no effect until the service restarts.

Validity period — read this one

A magnetic model expires. WMM-2025 has a nominal validity of 2025.0 to 2030.0 — five years from its epoch. The daemon knows this and enforces it, in three bands:

Date	Behaviour
Before 2025.0	Refused. Nothing is published, one line per attempt on stderr.
2025.0 – 2030.0	Normal. The model is inside its validity window.
2030.0 – 2031.0	Computed, with a warning on stderr per attempt: WARNING - WMM model past nominal end date.
After 2031.0	Refused. Nothing is published.

In the refusal bands the daemon logs

Magnetic: WMM model expired (epoch 2025.0-2030.0, requested 2031.4)

and returns without publishing. The rest of the daemon is unaffected: the sun, moon, tide and sky map reports continue exactly as before.

What the crew sees when it expires

The declination on the screen stops updating, and then stops existing. Because sextant/magnetic is retained, the last payload published before expiry stays on the broker indefinitely — so the number on the page will look normal, will not change, and will slowly become wrong as the field drifts. Nothing raises an alarm.

That is the failure mode to plan for. From 2 January 2031 a Brain running an un-updated muxen-sextant-database will be showing a declination frozen at the end of 2030.

What to do about it

The fix is a new coefficient file, not new code: the WMM reference library reads the epoch and the model order from the file header, so dropping in the next model's .COF and restarting the service is the whole operation. NOAA publishes the successor model before the predecessor expires.

sudo systemctl restart muxen-sextant
journalctl -u muxen-sextant | grep Magnetic

The startup line names the file actually in use:

Magnetic: Report started (WMM: /var/lib/muxen-sextant/WMM.COF)

In MUXEN terms this arrives as an update of the muxen-sextant-database package. The daemon does not need rebuilding for it.

The end-date rule is derived by the reference library as epoch + 5 years, so it follows the file automatically: a WMM-2030 coefficient file moves both the warning and the refusal five years out with no change anywhere else.

Accuracy

Two error sources, and they are of very different sizes.

The model itself. The WMM is a model of the Earth's main field — the part generated in the core — and it is a smooth global fit, so it is least reliable where declination changes fastest, near the magnetic poles, where the horizontal field is weak. NOAA publishes uncertainty figures with each model release; consult those rather than assuming a figure. What MUXEN verifies is the implementation: the unit tests evaluate the shipped WMM.COF against the official WMM2025 test vectors and require declination and inclination within 0.1° and total intensity within 10 nT of the published values. That says the arithmetic is right, not that the model matches the field over your particular patch of seabed.

Local anomalies. The WMM does not model crustal magnetism, and cannot. Iron ore, volcanic rock, a wreck, or the boat's own engine and speakers produce local deviations that the model has no knowledge of. In some coastal areas the crustal contribution exceeds several degrees. This is why deviation cards exist, and the report is not a substitute for swinging a compass.

Two further limits specific to this implementation:

• The field is evaluated at sea level — 0 km above the WGS-84 ellipsoid — regardless of the altitude in nmea/navigation, which the daemon ignores. On a boat this is exactly right.
• The value is recomputed on the standard schedule, so it is up to fifteen minutes and one drift threshold old. Declination changes by well under a degree over 75 nautical miles in most of the world, so this is not a practical concern outside the polar regions.

Secular variation is applied

The model is time-adjusted before evaluation: the coefficients carry annual rates of change, and the daemon evaluates them at the current decimal year, computed as year + (day_of_year − 1) / days_in_year with leap years handled. So the published declination follows the real drift through the five-year window rather than being pinned to the epoch. That is also why the expiry matters: once past the window, the extrapolation is no longer supported by the model's fit.

When nothing is published

sextant/magnetic is silent, with the rest of the reports working, in exactly three cases:

Cause	Log line
The coefficient file is missing	Magnetic: WMM coefficient file not found: <path>
The file exists but cannot be parsed as a model	Magnetic: Failed to read WMM model from <path>
The date is outside the model's window	Magnetic: WMM model expired (epoch …)

The first two normally mean the muxen-sextant-database package is not installed, or --wmm-cof-path points somewhere wrong. The daemon does not exit in any of these cases; it publishes the other four reports and carries on.

The file-existence check is deliberate and load-bearing: the NOAA reference library does not tolerate a missing file, so the daemon tests for it before handing over the path.