Phase 1: Native-Fortran adapter + CUDA host setup

[neuromechanist]

Summary

Adds a native-fortran-f64 backend to the Phase B dimension-sweep harness
(benchmarks/benchmark_dimsweep.py) that times an amica15 compiled from source, plus a
cross-platform build (benchmarks/fortran/). First piece of epic #84: an honest
native-Fortran reference-timing row, on both the x86 CUDA host and Apple Silicon.

Closes #85
Part of epic #84

What changed

• _run_fortran adapter: writes a real subset as a float32 column-major .fdt, renders a
  matched input.param (n_mix=3, pdftype=0, do_newton off, block_size 512, full fixed-iter
  budget), runs the binary, and times it from amica's own per-iteration out.txt stamps
  (startup-immune: after MPI init / data load / PCA / sphering). Registered in _BACKENDS;
  available only when a native binary exists (so CI / Apple-only checkouts are unaffected).
• benchmarks/fortran/build_amica.sh + vmath_shim.c: cross-platform native build.
  amica15.f90 targets ifort + MKL, so a plain gfortran build needs three fixes, applied to a
  build copy (never the tracked reference source): -cpp (skip the MKL #include), a
  portable random_seed seed size, and a libm shim for AMD LibM's vrda_exp/vrda_log.
  Built clean on macOS arm64 (gfortran 16) and Ubuntu 24.04 x86_64 (gfortran 13).
• Docs: benchmarks/fortran/README.md (host setup, timing method + 10 ms resolution
  caveat, portability notes), dimsweep README/docstring updated, .context/issue-84/.

Test plan

• pyAMICA/tests/test_fortran_adapter.py (real committed data, NO MOCKS): .fdt round-trip vs
  the canonical load_data_file (locks the column-major convention), channel-subset round-trip,
  out.txt parser (200 iters, LL), param rendering, and an end-to-end smoke that runs a native
  amica (skipped unless a binary is present / AMICA_FORTRAN_BIN is set).
• Validated end-to-end on both platforms: 5/5 pass against a native arm64 (Mac) and native
  x86 (hallu) binary. Real dimsweep on hallu (RTX 4090): native-fortran-f64 12.07 ms/it @32ch,
  44.83 @70ch vs torch-cuda-f64 34.88/38.61 and torch-cpu-f64 217/226; LL agrees ~2 digits.
• ruff check + ruff format clean; shellcheck clean; full suite collects (154 tests).

Notes / caveats

• Per-iteration stamp is ~10 ms resolution; the adapter rejects configs that round to 0.00 s/iter
  and documents the floor (use per-iter >> 10 ms, i.e. the 70-ch size).
• native-Fortran uses libm (not vendor SIMD) math -> portable-baseline timing, not max-tuned.
• Build portability fixes are candidates to upstream to sccn/amica (Implement save/load persistence for AMICATorchNG #44 M1 compile, Add per-model bias c update for multi-model AMICA (#27) #49 Ubuntu).
• Out of scope: --threads CPU-scaling sweep (Phase 2 Phase 2: CPU core-count scaling sweep #86); full grid + CUDA multi-model report
  (Phase 3 Phase 3: Full matrix + CUDA multi-model cross-platform report #87).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.44%. Comparing base (9700752) to head (b2df278).

Additional details and impacted files

@@                            Coverage Diff                            @@
##           feature/issue-84-epic-xplat-benchmark      #88      +/-   ##
=========================================================================
+ Coverage                                  79.03%   79.44%   +0.40%     
=========================================================================
  Files                                         14       14              
  Lines                                       1975     1975              
  Branches                                     337      337              
=========================================================================
+ Hits                                        1561     1569       +8     
+ Misses                                       310      301       -9     
- Partials                                     104      105       +1     

see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[neuromechanist]

Review summary (4 agents, Sonnet)

Ran code, tests, silent-failure, and comment reviews. Code correctness: clean (byte order, shim ABI, regex, param ordering all verified against real data/hardware). Addressed all actionable findings in b2df278:

Silent failures

• Native crash now prints full stderr/stdout before raising (main() truncates the exception to ~70 chars, so the transcript is the only place to see LAPACK/MPI/segfault causes).
• Explicitly-requested-but-unavailable backends now emit a WARNING instead of silently dropping (was: sweep exits 0 having benchmarked fewer backends than asked).
• build_amica.sh verifies the random_seed sed-patch actually applied (grep -q, else fail loud) so source drift can't produce a binary that only crashes at runtime.
• _parse_fortran_out uses errors="replace" (corruption surfaces as U+FFFD, breaks the regex cleanly) instead of errors="ignore".
• Skipped (with rationale): the regex not matching a negative seconds value is theoretical (monotonic timer); leaving it excluded is the safe behavior.

Test coverage (all error-guard paths were previously untested)

• Added: nonzero-exit raise (real system false, unconditional), sub-10ms zero-guard raise (verified repro 8ch x 2000), <2 timed-iters raise, _fortran_available/_available dispatch + share-gate, and multi-model param rendering. pcakeep 16 now asserted. 4 -> 10 tests; binary-gated ones skip on CI/Apple-only.
• Fixed the flaky "16ch/8k rounds to 0.00s" docstring claim (empirically alternates 0.00/0.01; the real reliable sub-floor size is 8ch x 2000).

Comment/doc accuracy

• Fixed two factual bugs: the "not on Apple/CI" docstring (the Apple native build works) and the "amica15 is single-model" comment (it supports num_models>1; the adapter only gates share). Aligned .gitignore + README_dimsweep.md.
• Documented the native-fortran final_ll reproducibility caveat (clock-seeded, unlike the fixed-seed backends) in README_dimsweep.md.
• Softened the uncited "equal or better than vendor" accuracy claim in vmath_shim.c; qualified the sccn/amica Add per-model bias c update for multi-model AMICA (#27) #49 reference (OneAPI, not gfortran).

Full suite: 10 passed (both with and without a native binary); ruff + shellcheck clean.