Add Fortran convergence criteria to AMICATorchNG (#213)

* feat: add NG convergence stops (issue #207)

AMICATorchNG was missing three Fortran convergence criteria
(amica15.f90): use_min_dll/maxincs (consecutive small-gain stop),
use_grad_norm/min_nd (weight-gradient-norm stop), and the
decrease-branch's ".or. ndtmpsum <= min_nd" half -- the last is
why lrate could sit at newtrate and oscillate under do_newton=True
without ever stopping. All three are Fortran-faithful defaults
(True/1e-9/5/True/1e-7, matching amica15_header.f90).

ndtmpsum is now computed every iteration (Fortran-faithful,
including the comp_used mask): the direction/dAk computation in
_update_parameters was decoupled from the share_comps A-freeze
gate, since Fortran computes dAk/ndtmpsum unconditionally in
accum_updates_and_likelihood, strictly before the separately-gated
update_A step. Default (non-sharing) path is unaffected.

New stop_reason values (min_dll, grad_norm, grad_norm_floor) are
converged, not degenerate; plumbed through AMICA (**kwargs) and
state_dict()/from_state_dict(). Corrected a misleading comment
claiming only amica17 normalizes LL before the min_dll comparison
-- amica15 (the actual reference binary's source) normalizes
identically; the real divergence is numpy_impl's un-normalized
raw-sum LL comparison, a separate pre-existing gap this does not
touch.

Tested: full torch suite green (188 passed, 5 pre-existing skips);
validate_implementations.py unchanged at max-iter 100 and 2000
(matches sample_params.json's budget) -- PyTorch LL/iteration count
identical before/after, neither stop fires on the bundled 32-channel
sample within that budget.

* test: add NG convergence-stop suite (issue #207)

Real bundled sample EEG only. Covers: each stop firing with the
right stop_reason (min_dll, grad_norm, grad_norm_floor, and the
pre-existing lrate_floor unshadowed by the new check); the maxincs
consecutive-count rule including reset-on-larger-gain, verified
against an independent reimplementation applied to a stops-disabled
reference trajectory rather than hardcoded iteration numbers; the
have_prev guard (never fires before two LL values exist); the
share_comps freeze window still computing a fresh (non-stale)
ndtmpsum every iteration; a converged stop leaving transform/
state_dict/AMICA.save usable; keep_best and do_reject interactions;
and that both stops disabled reproduces pre-#207 behavior (never
emits the three new stop_reason values).

14/14 pass; ruff and ty clean.

* test: drop slow marker from non-Fortran convergence tests

Three tests in test_ng_convergence.py used only bundled EEG and pure
PyTorch (no Fortran binary) and ran in seconds, but were marked
@pytest.mark.slow. CI runs pytest -m "not slow", documented as
excluding tests that invoke the macOS-only Fortran reference binary,
so these three never ran in CI. One of them,
test_a_frozen_window_still_computes_fresh_grad_norm, is the only test
of the dAk/A-freeze decoupling (issue #207), so that change had zero
CI coverage.

PR #213 review finding 1.

* fix: document and test stop_reason shadowing (issue #207)

None of the three fit()-loop stop blocks (decrease branch; min_dll;
grad_norm) short-circuits on an earlier one having already fired the
same iteration, matching Fortran's independent leave=.true. structure
(not a fidelity bug). But the standalone grad_norm check runs
unconditionally after the decrease branch, so under the shipped
use_grad_norm=True default it always wins: "grad_norm_floor" is
unreachable as a final stop_reason, and the use_grad_norm docstring
wrongly implied it was the fix for the reported CUDA case. Corrected
the docstring/comments in torch_impl/core.py and amica.py, and added a
test proving the shadowing under shipped True/True defaults.

PR #213 review finding 2.

* test: rename mislabeled do_reject test, add missing coverage

test_do_reject_interaction_min_dll_stop_leaves_good_idx_usable set
use_min_dll=False, so it actually exercised grad_norm_floor, not
min_dll; renamed to match. Added the two genuinely missing do_reject
combinations: the standalone min_dll and grad_norm stops.

PR #213 review finding 3.

* test: exercise a genuine keep_best overshoot restore

The old test's trajectory was monotonically increasing, so
final_ll_ == max(ll_history) == ll_history[-1] held whether the
restore logic worked or was a no-op. Reworked it around the known
non-monotone recipe from test_write_amica_output_ll_matches_kept_iterate
(#92), combined with a loosened min_dll so the run stops a few
iterations past its peak via the new min_dll stop_reason, and assert
final_ll_ != ll_history[-1] to prove the restore branch actually ran.

PR #213 review finding 4.

* test: exercise AMICA.save/load in convergence-stop tests

The wrapper usability test's own docstring claimed "transform()/
save() usable" but never called AMICA.save() anywhere in the file.
Added a real save()/load() round trip and confirmed the reloaded
model reports the same stop_reason_ and reproduces transform()
exactly.

PR #213 review finding 5.

* test: cover issue #207 config persistence round-trip

Added tests that the five new config keys (use_min_dll/min_dll/
maxincs/use_grad_norm/min_nd) round-trip through state_dict()/
from_state_dict(), and that a simulated pre-#207 payload (format_
version 3, missing those keys) still loads and falls back to the
Fortran defaults. Also documented, at the format_version check itself,
why it deliberately was not bumped for this change (prior precedent
#52/#53 bumped it; the additive-only new keys don't need to).

PR #213 review finding 6.

* test: add stop reachability at literal shipped default thresholds

Every prior min_dll/grad_norm test loosens the threshold by 5-6 orders
of magnitude to force a fast stop, which would not catch a scale bug
in the comparison itself (issue #212 found exactly that in the
numpy_impl backend). Added a fast (a few seconds), non-slow test at
the literal shipped defaults (min_dll=1e-9, maxincs=5,
use_grad_norm=True, min_nd=1e-7, none overridden) that reaches
min_dll via an early Newton start on a small real-data subset.

PR #213 review finding 7.

* test: cover mir_history_ vs keep_best restore and save/load

Issue #161 flagged two documented-but-untested mir_history_ claims:
that a keep_best restore (#51) does not rewrite it (so its last entry
can be from discarded, pre-restore parameters, distinct from
model.mir(X) on the returned ones), and that it comes back empty after
a save/load round trip (not persisted in state_dict()). Both verified
true on real data; also updated the module docstring to summarize the
full set of PR #213 review additions in this file.

Folds in issue #161.

* docs: add changelog entry for issue #207 convergence stops

* fix: correct timing claim in threshold-reachability docstring

The test is actually the slowest in the file (~8s from the 326-iteration
fit itself), not "well under 3s" as originally written; corrected to
state the real number and why it's still not a slow-marker candidate.

* Give the shipped-default reachability test real headroom

The iteration at which min_dll fires is BLAS-dependent: 326 on
macOS-arm64, 412 on Linux-x86_64 with a CUDA torch build, and past 500
on the GitHub Linux runner, where CI failed with stop_reason=max_iter.
At max_iter=500 the test consumed 82 percent of its budget on the
fastest platform, so any numerical variation tipped it over.

The claim under test is that the default threshold is reachable at all,
not that it is reached by a given iteration, so raise the budget well
above the observed spread and record the spread in the docstring.

Refs #207

* Assert convergence behaviour, not the iteration it happens on

CI failed twice on iteration-count assumptions. First the stop reason,
because max_iter=500 left no headroom; then a leftover
len(ll_history) < 500 bound after the budget was raised. The stop fires
at 326 on macOS-arm64, 412 on Linux-x86_64 with a CUDA torch build, and
1076 on the GitHub runner, so any constant fitted to one machine is a
trap.

Both bounds now track the budget. The unrelated len(ll_history) == 23
golden value in the lrate_floor test is loosened for the same reason,
before it fails the same way.

Refs #207

* Rebuild paper.pdf [skip ci]

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: neuromechanist

docs/changelog.md

@@ -3,6 +3,20 @@
 Release notes are also published on the
 [GitHub releases page](https://github.com/sccn/pAMICA/releases).
 
+## Unreleased
+
+- Added the three missing Fortran convergence stops to `AMICATorchNG`
+  (issue #207): `use_min_dll`/`min_dll`/`maxincs` (small-likelihood-increase
+  stop), `use_grad_norm`/`min_nd` (weight-gradient-norm stop), and the
+  lrate-decrease branch's missing gradient-norm half
+  (`stop_reason="grad_norm_floor"`). Fixes the reported case where, under
+  `do_newton=True`, `lrate` settles at `newtrate` and oscillates instead of
+  annealing, so the pre-existing `lrate_floor` check never fired and
+  `max_iter` was the only working stop. All five new constructor arguments
+  persist through `state_dict()`/`from_state_dict()`; older saved files
+  (missing these keys) still load, falling back to the Fortran-faithful
+  defaults.
+
 ## 0.3.1
 
 Rho-rate schedule fixes across all backends and a reproducible-seed option in the

pamica/amica.py

@@ -60,8 +60,20 @@ class AMICA:
         one (``stop_reason_`` not in ``nan_ll``/``singular_ll``). A degenerate fit
         holds non-finite parameters and would produce NaN sources (issue #50).
     stop_reason_ : str or None
-        Why the last ``fit`` stopped (the backend ``stop_reason``): e.g.
-        ``"max_iter"``, ``"lrate_floor"``, ``"nan_ll"``, ``"singular_ll"``.
+        Why the last ``fit`` stopped (the backend ``stop_reason``):
+        ``"max_iter"``, ``"lrate_floor"``, ``"grad_norm_floor"``, ``"min_dll"``,
+        ``"grad_norm"``, ``"nan_ll"``, or ``"singular_ll"``. The last five are
+        Fortran-faithful convergence stops (issue #207: ``lrate_floor``/
+        ``grad_norm_floor`` fire together as two halves of the same
+        likelihood-decrease branch; ``min_dll``/``grad_norm`` are separate,
+        unconditional per-iteration checks); only ``nan_ll``/``singular_ll``
+        are degenerate (see ``converged_``). None of these checks short-
+        circuits on an earlier one in the same iteration, so under the
+        shipped ``use_grad_norm=True`` default ``"grad_norm"`` always takes
+        precedence over ``"grad_norm_floor"`` when both would apply --
+        ``"grad_norm_floor"`` only surfaces as this value when
+        ``use_grad_norm=False`` (see ``AMICATorchNG``'s ``use_grad_norm``
+        docstring for the full explanation).
     ll_history_ : list
         Log-likelihood history during training (the true per-iteration
         trajectory; may dip below its peak on a late overshoot)
@@ -177,8 +189,11 @@ def fit(
             and the interaction with ``keep_best``.
         **kwargs
             Additional parameters passed to the :class:`AMICATorchNG`
-            constructor (e.g. ``block_size``, ``rho0``, ``seed``, ``dtype``) --
-            the backend's tunables are constructor arguments, not fit() kwargs.
+            constructor (e.g. ``block_size``, ``rho0``, ``seed``, ``dtype``,
+            ``use_min_dll``, ``min_dll``, ``maxincs``, ``use_grad_norm``,
+            ``min_nd`` -- the issue #207 convergence stops, Fortran-faithful
+            defaults ``True``/``1e-9``/``5``/``True``/``1e-7``) -- the
+            backend's tunables are constructor arguments, not fit() kwargs.
 
         Returns
         -------