Epic polish: audit fixes (#316)

* Attribute degenerate-fit refusal to AMICA wrapper

Row 5 of the differences table credited the raw PyTorch backend with
refusing transform/get_*/save on a degenerate fit; that guard is the
AMICA wrapper's _check_usable contract. The raw AMICATorchNG backend
has no such guard of its own (tracked as issue #306).

* Document unmapped Fortran keywords

Add a section resolving the page's exhaustiveness contract: points to
fortran_params.py's FORTRAN_UNSUPPORTED_KEYS as the enumeration, names
filter_length/dft_length/decwindow as dead in the reference itself
(alongside the already-documented do_choose_pdfs/Spinv2 dead code),
and records the do_rho-vs-pdftype divergence: Fortran can freeze the
GG shape while keeping pdftype=0, but every pamica backend derives
the freeze from pdftype directly, making that combination unreachable.
Links issues #312/#314 for the live lifecycle/diagnostics gaps.

* Port variance_order to AMICAMLXNG

Adds the EEGLAB back-projected-variance component order (issue #92)
to the MLX backend, mirroring AMICATorchNG.variance_order with MLX's
model-major W layout ((n_models, n, n)) and the unfitted RuntimeError.
Closes the one accessor gap the epic's feature-parity audit found in
an otherwise-complete Phase 3; updates the module docstring's
ported-features claim to match.

Adds cross-backend parity coverage against a float64 AMICATorchNG
twin holding identical fitted parameters (order matches exactly on a
30-iteration multi-model fit with non-degenerate variance gaps, with
a gap-size assertion documenting the tie risk), plus MLX-only
unfitted/invalid-model_idx/permutation tests.

* Correct validation harness backend coverage claim

AGENTS.md claimed the harness runs "both implementations (NG +
NumPy)"; validate_implementations.py only exercises torch vs Fortran.
NumPy parity lives in pytest (test_sample_data_numpy_vs_fortran); MLX
validation lives in mlx_tests/ plus the cross-backend suites.
Extending the harness itself is tracked as issue #315.

* Fix unsupported-key comment for writestep/do_history

The FORTRAN_UNSUPPORTED_KEYS entries for writestep/do_history/
histstep said these have no pamica equivalent; false for the legacy
NumPy backend, which implements all three (numpy_impl/core.py's fit
loop and _write_history). Keeps the keys unsupported here (this
module targets the torch wrapper, which has no matching mechanism)
but corrects the reason: NumPy-only, torch/MLX gap tracked as #312.

* Refresh stale feature-parity status notes

feature_parity.md and progress_summary.md still claimed the runtime-
vs-Fortran benchmark was unmeasured and issue #15 (save/load and
plot_components test coverage) was open; both landed since. Also
corrects progress_summary.md's validation-harness claim (same fix as
AGENTS.md: torch-vs-Fortran only, not NG + NumPy). Adds a header note
to feature_parity.md pointing to amica-differences.md's table as the
live, maintained backend-parity source of truth.

* Align NumPy backend's inert pdftype default to 0

self.pdftype is never read after assignment (this backend always
runs the GG update; _compute_log_pdf takes no pdftype param), so the
old default of 1 was a harmless but confusing mismatch against
torch/MLX's constructor default of 0. Aligned for surface consistency
only; no behavior change.

* Add changelog entry for epic polish round

Summarizes the audit-driven fixes ahead of merge to dev: MLX
variance_order, the doc corrections, and the new tracking issues
(#312, #314, #315) plus the #306 extension.

* Scope variance_order precision claim to defaults

Author: neuromechanist

.context/feature_parity.md

@@ -1,5 +1,11 @@
 # Feature Parity Report: Fortran vs PyTorch AMICA
 
+**This file predates the MLX and NumPy backends and covers only the Fortran-vs-`AMICATorchNG`
+comparison from issue #24's original parity push; it is not maintained against either backend added
+since. The live, maintained backend-parity source of truth is
+[`docs/guides/amica-differences.md`](../docs/guides/amica-differences.md)'s "At a glance" table,
+which covers all three array backends. Treat this file as a historical snapshot.**
+
 Compares the Fortran reference (`amica15.f90`, binary `amica15mac`) with the current PyTorch
 backend `AMICATorchNG` (the sole PyTorch backend; the earlier Adam/autograd `AMICATorch` and
 `AMICATorchV2` were removed in #32). The NumPy reference (`AMICA_NumPy`) is retained as an oracle
@@ -8,7 +14,9 @@ and CLI. Living status is in `../AGENTS.md` (Known Issues); ADRs are in `decisio
 **Headline:** single-model parity is done (LL ~ -3.40 vs Fortran -3.4018; Hungarian component
 correlation ~0.997 with Newton positive-definite, 0 fallbacks). Adaptive PDF (#26), multi-model
 (#27, distributional equivalence), best-iterate (#51), and the degenerate-fit contract (#50) are
-done, as is component sharing (#60). The one unverified success criterion is runtime.
+done, as is component sharing (#60). Runtime vs Fortran has since been measured and the ~2-3x
+criterion met/exceeded (CUDA float64 ~4.5x, MLX ~7x on Apple Silicon; see `AGENTS.md`'s
+Performance section and `plan.md`'s checked runtime item) -- the "unmeasured" row below is stale.
 
 ## Core AMICA features
 
@@ -53,7 +61,7 @@ done, as is component sharing (#60). The one unverified success criterion is run
 |---------|---------|--------------|--------|-------|
 | Binary data loading | yes | yes | Complete | `.fdt` files |
 | Parameter files | yes | yes | Complete | JSON |
-| Checkpoint save/load | yes | yes | Complete | NG state_dict persistence (#36); untested (#15) |
+| Checkpoint save/load | yes | yes | Complete | NG state_dict persistence (#36); tested (#15, closed) |
 | Result loading | yes | yes | Complete | via `loadmodout()` |
 
 ## Numerical stability
@@ -71,7 +79,7 @@ done, as is component sharing (#60). The one unverified success criterion is run
 |---------|---------|--------------|-------|
 | OpenMP parallelization | yes | n/a | PyTorch uses tensor ops / device parallelism |
 | GPU support | no | yes | CUDA / MPS / CPU automatic (float64 parity runs on CPU/CUDA) |
-| Runtime vs Fortran | baseline | **unmeasured** | the 2-3x criterion has never been benchmarked |
+| Runtime vs Fortran | baseline | **measured, met/exceeded** | CUDA float64 ~4.5x over 16-thread CPU, MLX ~7x on Apple Silicon (#77/#84); see `AGENTS.md` Performance section |
 
 ## Validation status (issue #24)
 
@@ -88,9 +96,10 @@ indistinguishable from Fortran's run-to-run distribution (#27, `.context/issue-2
 
 ## Remaining roadmap
 
-- [ ] **Performance benchmark** vs the Fortran binary (CPU/CUDA/MPS); verify or revise the 2-3x
-      runtime criterion.
+- [x] **Performance benchmark** vs the Fortran binary (CPU/CUDA/MPS); 2-3x runtime criterion
+      met/exceeded (#77/#84).
 - [x] **Component sharing** (`share_comps`, `share_start`/`share_iter`, `comp_thresh`) ported to
       `AMICATorchNG` (#60), off by default, behavior-validated on real data.
-- [ ] **Test hardening:** single-channel / single-sample edge cases, numerical-stability
-      regression tests, and `save`/`load` + `plot_components` coverage (#15).
+- [x] **Test hardening:** `save`/`load` + `plot_components` coverage landed (#15, closed).
+      Single-channel/single-sample edge cases and numerical-stability regression tests remain
+      open; not tracked under #15.

.context/progress_summary.md

@@ -71,13 +71,17 @@ what remains as of the v0.1.0 preparation.
 - UV is the canonical environment (`pyproject.toml` + `uv.lock`); the legacy conda env is retired.
 - CI is live and green on `main`: ruff lint/format, pytest (excluding slow/Fortran-binary parity),
   and a build + clean-env import matrix on Python 3.12 and 3.13. Typos check green.
-- Validation harness (`validate_implementations.py`) runs both backends and matches components via
-  the Hungarian algorithm, on real sample EEG plus the Fortran binary (`amica15mac`).
+- Validation harness (`validate_implementations.py`) runs the PyTorch (NG) backend against the
+  Fortran binary (`amica15mac`) and matches components via the Hungarian algorithm, on real sample
+  EEG; it does not exercise the NumPy or MLX backends. NumPy-vs-Fortran parity lives in pytest
+  (`test_sample_data_numpy_vs_fortran`), MLX validation in `mlx_tests/` plus the cross-backend
+  suites (extending the harness itself is tracked as issue #315).
 
 ## Remaining before / around v0.1.0
 
-- **Performance benchmark:** the "runtime within 2-3x of Fortran" success criterion has never been
-  measured. Needs a repeatable NG-vs-Fortran benchmark across CPU/CUDA/MPS.
-- **Test hardening:** no single-channel / single-sample edge tests, no numerical-stability
-  regression tests (mincond / minlog / maxdble / mineig bounds); `AMICA.save`/`load` and
-  `plot_components` remain untested (issue #15).
+- **Performance benchmark:** DONE. The "runtime within 2-3x of Fortran" success criterion has been
+  measured and met/exceeded: CUDA float64 ~4.5x over a 16-thread CPU, MLX ~7x on Apple Silicon
+  (#77/#84; see `AGENTS.md`'s Performance section).
+- **Test hardening:** `AMICA.save`/`load` and `plot_components` coverage landed (issue #15,
+  closed). Single-channel / single-sample edge tests and numerical-stability regression tests
+  (mincond / minlog / maxdble / mineig bounds) remain open, not tracked under #15.

AGENTS.md

@@ -104,8 +104,10 @@ gap vs the PyTorch backend is none, other than float32-only precision (Apple GPU
 - PyTorch backend with GPU/MPS/CPU support; the `AMICATorchNG` natural-gradient EM backend now
   matches the Fortran reference (LL ~ -3.40, component correlation ~0.997) with Newton enabled
   and positive-definite (issue #24).
-- Validation harness runs both implementations (NG + NumPy) and matches components via the Hungarian
-  algorithm.
+- `validate_implementations.py` runs the PyTorch (NG) backend against the Fortran binary and matches
+  components via the Hungarian algorithm; it does not exercise the NumPy or MLX backends. NumPy-vs-
+  Fortran parity lives in pytest (`test_sample_data_numpy_vs_fortran`), and MLX validation lives in
+  `mlx_tests/` plus the cross-backend suites (extending the harness itself is tracked as issue #315).
 - Newton and exact-EM updates are implemented in `AMICATorchNG` and the legacy NumPy `numpy_impl/core.py`
   (both Fortran-faithful). Adaptive PDF (#26) is DONE (all five `pdftype` families + ext-Infomax
   switcher); full multi-model matching (#27) is validated by distributional equivalence.

docs/changelog.md

@@ -5,6 +5,32 @@ Release notes are also published on the
 
 ## Unreleased
 
+- **Epic #278 polish round: audit-driven fixes ahead of merge to `dev`.**
+  `AMICAMLXNG` gained `variance_order` (issue #92), the EEGLAB
+  back-projected-variance component order, closing the one accessor gap the
+  epic's feature-parity audit found in an otherwise-complete Phase 3
+  (validated on real data against a float64 `AMICATorchNG` twin holding
+  identical fitted parameters: the component order matches exactly on a
+  config with non-degenerate variance gaps). The audit also found several
+  stale/misattributed doc claims, fixed here: `docs/guides/amica-differences.md`
+  now attributes the degenerate-fit refusal to the `AMICA` wrapper rather than
+  the raw PyTorch backend (the raw-backend gap is issue #306), and gained an
+  "Unmapped Fortran keywords" section pointing to `fortran_params.py`'s
+  `FORTRAN_UNSUPPORTED_KEYS` as the enumeration, naming three keywords dead in
+  the reference itself (`filter_length`/`dft_length`/`decwindow`), and
+  recording the `do_rho`-vs-`pdftype` divergence explicitly; `AGENTS.md` and
+  `.context/progress_summary.md` no longer claim `validate_implementations.py`
+  covers the NumPy/MLX backends (it is torch-vs-Fortran only; extending it is
+  issue #315); `.context/feature_parity.md` and `.context/progress_summary.md`
+  no longer claim the runtime-vs-Fortran benchmark is unmeasured or that issue
+  #15 (save/load and `plot_components` test coverage) is open, both stale
+  since earlier work landed; and `fortran_params.py`'s unsupported-keys table
+  no longer claims `writestep`/`do_history`/`histstep` have no pamica
+  equivalent -- they are implemented on the legacy NumPy backend, just not
+  yet on torch/MLX (issue #312). Also aligned the legacy NumPy backend's
+  inert `pdftype` constructor default to 0, matching torch/MLX (the value is
+  never read, so this is a documentation-equivalent surface fix, not a
+  behavior change).
 - **MLX backend: outlier rejection, LLt stash, EEGLAB export, MIR/PMI**
   (issue #289, epic #278 Phase 3 -- completes the epic). `AMICAMLXNG` gains:
   the LLt stash (issue #157), filled per-block by the E-step (never a second

docs/guides/amica-differences.md

@@ -16,7 +16,7 @@ that is not listed, that is a bug worth
 | 2 | Zero numerical rank | `numeigs = 0`, continues | `ValueError` naming cause and fix | fitting a zero-dimensional model is not a recoverable state | — (no reason to want it) |
 | 3 | Returned iterate | last EM iterate | highest-likelihood iterate (`keep_best`) | the lrate schedule is non-monotone; late Newton overshoots cut LL variance 12.7x → 2.0x | `keep_best=False` |
 | 4 | Newton | on (`do_newton=1`) | off | isolates the algorithm from initialization for parity work | `do_newton=True` |
-| 5 | Degenerate fits | returns NaN sources, and writes them out on its `writestep` cadence | PyTorch refuses `transform`/`get_*`/`save`; NumPy reports `converged=False` with a `stop_reason`, refuses the final write, and skips each periodic checkpoint with a logged reason (leaving the last valid one on disk) | NaN sources silently poison downstream analysis, and `loadmodout` reads a NaN checkpoint back without complaint | — (see issues #50 and #240) |
+| 5 | Degenerate fits | returns NaN sources, and writes them out on its `writestep` cadence | the `AMICA` wrapper refuses `transform`/`get_*`/`save` (the raw `AMICATorchNG` backend has no such guard of its own — tracked as issue #306); NumPy reports `converged=False` with a `stop_reason`, refuses the final write, and skips each periodic checkpoint with a logged reason (leaving the last valid one on disk) | NaN sources silently poison downstream analysis, and `loadmodout` reads a NaN checkpoint back without complaint | — (see issues #50 and #240) |
 | 6 | Precision | float64 | float64 (float32 on Apple GPUs) | Apple GPUs have no float64; float32 agrees to ~7 significant digits, not bit-parity | `dtype=torch.float64` |
 | 7 | Sensor-space maps | `Spinv` applied internally | `get_sensor_mixing_matrix()` | `get_mixing_matrix()` returns sphered-space `A`; switching its meaning by data conditioning would be worse | — |
 | 8 | Columns merged away by `share_comps` | updated to NaN, then hidden by the `comp_used` mask | frozen at their last finite value (never divided) | a fit must not end holding NaN parameters, mask or no mask; the columns are dead either way | — (see issues #60, #240) |
@@ -589,3 +589,57 @@ Practical notes:
   can appear on disk mid-fit. The final write replaces it — what is on disk when
   `fit` returns is the winner's state, which is a tested claim, not just a
   documented intention.
+
+## Unmapped Fortran keywords
+
+This page's own contract ("anything not on this page is intended to match the
+reference") only covers *behavior*. A Fortran keyword that pamica's parameter
+translator does not map at all is a separate, narrower question, and it has
+its own enumeration: `pamica/fortran_params.py`'s `FORTRAN_UNSUPPORTED_KEYS`
+lists every keyword the reference parser accepts that this project does not
+translate into a pamica constructor/`fit()` argument, with a one-line reason
+for each. That dict, not this page, is the exhaustive list.
+
+Most of those keywords are unmapped because the feature genuinely has no
+pamica equivalent (checkpoint warm-start, per-family EM freeze toggles,
+console/file-reporting cadence, ...). Three, though, are dead even in the
+reference binary itself — the same category as the `do_choose_pdfs` and
+`Spinv2` dead code documented above:
+
+- **`filter_length`, `dft_length`** — parsed, printed, and broadcast to every
+  MPI rank (`amica15.f90` `case('filter_length')`/`case('dft_length')`,
+  ~3263-3280), but no filter or DFT subroutine exists anywhere in
+  `amica15.f90`/`funmod2.f90` to consume either value. A pre-filtering
+  pipeline was apparently planned and never built.
+- **`decwindow`** — parsed into the header the same way, but its
+  `MPI_BCAST(decwindow, ...)` call is commented out (`amica15.f90:192`), so a
+  multi-process reference run never even shares the parsed value past rank 0;
+  every worker rank keeps the compiled-in default regardless of what the
+  parameter file said.
+- (Already documented above:) `do_choose_pdfs`'s `pdftype=1` auto-switcher is
+  declared but its moment buffers (`m2sum`/`m4sum`) are never accumulated, and
+  `share_comps`'s `Spinv2` similarity metric is declared but never allocated.
+
+One live (non-dead) divergence is worth recording explicitly rather than
+leaving it implicit in the unsupported-keys table: Fortran's `do_rho` can
+freeze the generalized-Gaussian shape parameter while keeping `pdftype=0` —
+an independent toggle, "use the GG family but do not adapt its shape this
+run." Every pamica backend instead hard-derives the freeze from `pdftype`
+itself: `AMICATorchNG`/`AMICAMLXNG` set `self.dorho = (pdftype == 0)`
+directly (so `pdftype=0` always updates rho, never frozen), and the legacy
+NumPy backend has no `pdftype` family switch at all — it always runs the
+GG update, the same effective always-on freeze-off behavior. So the
+combination Fortran supports (GG family, frozen shape) is unreachable on any
+current pamica backend. Restore-reference: none currently exposed; `do_rho`
+would need to become an independent constructor keyword to port this on
+demand.
+
+Two clusters of keywords are neither dead code nor "no pamica equivalent" —
+they are live Fortran features with a real gap, filed rather than silently
+carried:
+
+- **Lifecycle** (checkpoint warm-start `load_*`, `writestep`/`do_history`/
+  `histstep` periodic checkpointing on torch/MLX, per-family EM freeze
+  toggles, `fix_init`): issue #312.
+- **Diagnostics** (`write_nd`'s per-component gradient trajectory, the
+  per-iteration run log): issue #314.

pamica/fortran_params.py

@@ -61,8 +61,11 @@
 
 ``FORTRAN_UNSUPPORTED_KEYS`` lists the remaining 32 keywords the Fortran
 parser accepts (checkpoint warm-start, per-family EM freeze toggles, FIR/DFT
-pre-filtering, console/file reporting cadence, ...) that have no pamica
-equivalent; these are
+pre-filtering, console/file reporting cadence, ...) that this module does not
+translate -- most with no pamica equivalent anywhere, but a few
+(``writestep``/``do_history``/``histstep``) exist on the legacy NumPy backend
+only (see the table entry below); this module's output targets the torch
+wrapper, which has no matching mechanism (issue #312). These are
 *deliberately* unmapped, not missed, and ``read_fortran_param_file`` warns
 about them by name rather than dropping them in silence. A keyword absent
 from *both* dicts is not a Fortran keyword this module knows about at all
@@ -300,9 +303,16 @@
     "print_debug": "Fortran console verbosity, no pamica equivalent",
     "write_nd": "Fortran output-file toggle (weight/gradient dumps)",
     "write_LLt": "Fortran output-file toggle (per-sample log-likelihood dumps)",
-    "writestep": "Fortran output-file write cadence",
-    "do_history": "Fortran periodic weight-history dump",
-    "histstep": "Fortran periodic weight-history dump cadence",
+    # Periodic on-disk checkpointing DOES have a pamica equivalent, but only
+    # on the legacy NumPy backend (numpy_impl/core.py's fit loop, ~2195-2198,
+    # and _write_history, ~2460-2489), which implements writestep/do_history/
+    # histstep with the same names and cadence semantics as Fortran. These
+    # stay unsupported HERE only because this module's output targets the
+    # torch wrapper (AMICA.fit/AMICATorchNG), which has no matching
+    # mechanism; porting it to torch/MLX is tracked as issue #312.
+    "writestep": "on-disk checkpoint write cadence; NumPy backend only (issue #312)",
+    "do_history": "periodic weight-history dump; NumPy backend only (issue #312)",
+    "histstep": "weight-history dump cadence; NumPy backend only (issue #312)",
     # Misc.
     "decwindow": "decrease-count window size; pamica exposes only max_decs/maxdecs",
     "fix_init": "fixed initialization scheme, not ported",