Adaptive PDF selection for AMICATorchNG (#26)

[neuromechanist]

Summary

Implements adaptive-PDF selection for AMICATorchNG (issue #26): all five amica15.f90
source-density families plus the extended-Infomax kurtosis auto-switcher. pdftype=0
(generalized Gaussian) stays the default and is byte-for-byte unchanged.

Key correction: the oracle exists

The prior investigation concluded #26 had "no runnable oracle." That read the wrong Fortran
file. The repo shipped amica17.f90 (GG-only) as its reference source, but the validation
binary is amica15mac, whose source is amica15.f90, which does implement the density
families. amica17.f90 is a later GG-only trim; the binary was never amica17. This PR copies
the ground-truth amica15.f90 / amica15_header.f90 into pyAMICA/, so the families are a
bit-comparable parity target rather than a beyond-parity feature.

Families (Fortran pdftype interface)

pdftype	family	structure	score fp
0	generalized Gaussian (default)	mixture, rho adapts	ρ·sign(y)·|y|^(ρ−1)
2	Gaussian	mixture	y
3	logistic (sech²)	mixture	tanh(y/2)
4	sub-Gaussian cosh+	single component	y − tanh(y)
1	extended-Infomax adaptive	single component	per-source y ± tanh(y)

pdftype=1 is Fortran's do_choose_pdfs trigger: each source is flipped between the
super-Gaussian (code 1) and sub-Gaussian (code 4) cosh densities by kurtosis sign on the
kurt_start/num_kurt/kurt_int schedule (documented in runamica15.m as "for ext.
infomax"). For non-GG families rho is frozen (amica15.f90:3682) and the single-component
families 1/4 require n_mix=1.

Validation

• Density math bit-exact: z0 and fp reproduce the literal amica15.f90 expressions
  to ~1e-15 for every family (deterministic unit tests, no binary needed).
• Converged LL parity vs amica15mac (real sample EEG, Newton matched): GG 0.0047,
  Gaussian 0.0030, logistic 0.0025, sub-G 0.0050, super-G 0.00006 — all within the GG-parity
  bar. The cosh families' Newton curvature isn't always positive-definite, so NG falls back to
  natural gradient exactly as Fortran does; LL still reaches parity.
• Default unchanged: pdftype=0 takes a fast path (_pdtype_h returns None) that is
  byte-for-byte the pre-Adaptive-PDF selection for AMICATorchNG #26 code; the existing 39 NG tests pass.
• The dynamic switch is dead code even in amica15.f90 (m2sum/m4sum are never
  accumulated), so the auto-switcher has no bit-exact oracle and is validated by real-data
  log-likelihood (finite, non-decreasing). This is documented, not hidden.

Tested

• pyAMICA/tests/torch_tests/test_ng_pdf_families.py: formula parity, GG bit-identity,
  construction validation, per-family real-data fits, auto-switcher schedule/stability, and an
  opt-in binary integration test behind AMICA_RUN_FORTRAN=1.
• Full tests/torch_tests/ suite green.

Notes for review

• EEG independent components are characteristically super-Gaussian, so on the sample data the
  switcher keeps all sources at code 1; the sub-Gaussian density is separately covered by the
  fixed pdftype=4 tests (no synthetic data was fabricated to force a sub-Gaussian source).
• ADR: .context/decisions/0002-adaptive-pdf-families.md.

[neuromechanist]

PR review (4 agents, model=Sonnet) — findings addressed

Ran code, silent-failure, test-coverage, and comment reviewers. All non-false-positive findings are fixed in follow-up commits.

Critical

• Save/load silently dropped the density family (code + test reviewers). state_dict()/from_state_dict() omitted pdftype/kurt_*/pdtype/n_kurt_done, so a reloaded non-GG (or adaptive) model reverted to generalized Gaussian. Fixed: added them to config/_PARAM_TENSORS/extra, restored on load, bumped format_version 1→2, and added test_state_dict_roundtrips_pdftype_state.

Important

• Kurtosis switch could silently pick a family from a dead model or NaN (silent-failure). Split the decision into a pure _pdtype_from_kurtosis(kurt, nsub) that keeps the prior pdtype and logs when kurtosis is non-finite or the model has zero mass, mirroring the _update_parameters guards. Unit-tested with a constructed mixed-sign/NaN/dead tensor (test_pdtype_from_kurtosis_decision) — this also covers the sub-Gaussian (code 4) branch that real EEG rarely triggers.
• No validation of kurt_int/kurt_start/num_kurt (silent-failure + test): kurt_int=0 would ZeroDivisionError deep in fit(). Added constructor validation (mirrors the rejint checks) + test_kurt_schedule_validation.
• Newton + non-GG never tested in default CI (test): added test_family_fit_with_newton. (Newton with non-GG families is what Fortran itself does — its posdef fallback fires on the cosh families too — and the opt-in binary parity test confirms convergence, so this is validated behavior, not new territory.)
• Added test_multimodel_fixed_family and test_adaptive_switch_with_rejection to cover the per-model and post-rejection paths.

Comments/docs

• Fixed a citation that pointed at amica15.f90 line numbers from inside an amica17.f90-scoped docstring (the two sources are not interchangeable); added the amica15.f90 line to _LOG4; corrected a 1327→1328 citation; documented the four new constructor params in the class docstring; added a module-docstring pointer explaining the amica15-vs-amica17 split; and pasted the runamica15.m "ext. infomax" excerpt into ADR 0002 so the switcher's provenance is verifiable in-repo.
• Reworded two test docstrings that claimed "monotone" — the assertion checks net non-decrease (last ≥ first), which is what natural-gradient AMICA actually guarantees.

Intentionally not changed

• ufp / y unguarded at y == 0 (silent-failure, MEDIUM): this is pre-existing on the GG path, out of scope for Adaptive-PDF selection for AMICATorchNG #26, and adding a guard would perturb the default pdftype=0 trajectory that must stay bit-identical. y = beta*(b - mu) is never exactly 0 on real (continuous) data, and all parity tests pass. Left as-is; a separate hardening issue is the right home if we want it.