Rename package pyAMICA to pamica

.context/decisions/0001-torch-backend-natural-gradient-em.md

@@ -11,7 +11,7 @@ The default PyTorch backend (`torch_impl/amica_torch.py`, and the experimental
 reparameterized tensors" (`softmax`/`exp`/`sigmoid` on `alpha`, `beta`, `rho`), driven by
 autograd. AMICA is fundamentally an EM / natural-gradient fixed-point iteration with
 closed-form sufficient-statistic updates; the Fortran reference (`amica17.f90`) and the legacy
-NumPy `pyAMICA.py` implement it that way. The reframing follows a different optimization
+NumPy `pamica.py` implement it that way. The reframing follows a different optimization
 trajectory and converges to a different fixed point, which is the primary cause of the poor
 component correlation with Fortran (~0.46-0.9 vs target >0.95). It also blocks scaling: the
 autograd path materializes all-sample intermediates and retains the graph, so peak memory grows
@@ -23,7 +23,7 @@ binary is the definition of done for this project.
 Rewrite the PyTorch backend as a direct, vectorized port of the NumPy/Fortran natural-gradient
 (and Newton) update rules. Parameterize `W` directly (no `pinv(A.T).T` per forward), broadcast
 the E-step over `(model, mix, source, block)` instead of Python loops, accumulate sufficient
-statistics block-wise, and drop Adam/autograd for the parameter updates. The NumPy `pyAMICA.py`
+statistics block-wise, and drop Adam/autograd for the parameter updates. The NumPy `pamica.py`
 `_get_block_updates` / `_update_parameters` are the reference spec; validation runs in float64.
 
 ## Consequences
@@ -60,7 +60,7 @@ partition matching is tracked in #27, adaptive-PDF in #26.
 
 - Fortran LL normalization: `amica17.f90:1866` (`LL = LLtmp2 / (num_samples*nw)`).
 - Fortran per-source mixture reduction: `amica17.f90:1313-1360`.
-- NumPy reference updates: `pyAMICA.py:505-730` (block updates, natural-gradient + Newton).
+- NumPy reference updates: `pamica.py:505-730` (block updates, natural-gradient + Newton).
 - Bug catalog and perf/memory analysis: `.context/research.md` (2026-07-02 design review).
 
 ## Addendum (2026-07-04, issue #32)

.context/decisions/0002-adaptive-pdf-families.md

@@ -24,7 +24,7 @@ sub-Gaussian cosh+, and `pdftype=1` = the extended-Infomax adaptive switcher (Fo
 sub-Gaussian (code 4) cosh densities by kurtosis sign on the `kurt_start`/`num_kurt`/
 `kurt_int` schedule. `rho` is frozen for every non-GG family (`amica15.f90:3682`), and the
 single-component families 1/4 require `n_mix=1`. The ground-truth `amica15.f90`/
-`amica15_header.f90` are copied into `pyAMICA/`.
+`amica15_header.f90` are copied into `pamica/`.
 
 ## Consequences
 
@@ -51,7 +51,7 @@ single-component families 1/4 require `n_mix=1`. The ground-truth `amica15.f90`/
 
 ## Receipts
 
-- `pyAMICA/amica15.f90` select-cases at :1277 (likelihood) / :1449 (score); `dorho=.false.`
+- `pamica/amica15.f90` select-cases at :1277 (likelihood) / :1449 (score); `dorho=.false.`
   at :3682; `do_choose_pdfs` at :594; the `m2sum`/`m4sum` moment buffers are allocated/zeroed
   (:590-591) but never accumulated, confirming the dynamic switch is dead code in the binary.
 - The extended-Infomax intent comes from the upstream AMICA MATLAB wrapper `runamica15.m`
@@ -63,6 +63,6 @@ single-component families 1/4 require `n_mix=1`. The ground-truth `amica15.f90`/
   ```
   and defaults `pdftype=0; kurt_start=3; num_kurt=5; kurt_int=1;`. The super/sub-Gaussian
   scores `y +/- tanh(y)` (amica15 codes 1/4) are the classic extended-Infomax nonlinearities.
-- `pyAMICA/torch_impl/amica_torch_ng.py`: `_log_pdf_and_deriv`, `_score`, `_choose_pdfs`.
-- `pyAMICA/tests/torch_tests/test_ng_pdf_families.py` (formula parity + real-data + opt-in
+- `pamica/torch_impl/amica_torch_ng.py`: `_log_pdf_and_deriv`, `_score`, `_choose_pdfs`.
+- `pamica/tests/torch_tests/test_ng_pdf_families.py` (formula parity + real-data + opt-in
   binary integration behind `AMICA_RUN_FORTRAN=1`).

.context/decisions/0003-best-iterate-safeguard.md

@@ -70,8 +70,8 @@ changes across iterations and per-iteration LLs are not comparable.
 
 ## Receipts
 
-- `pyAMICA/torch_impl/amica_torch_ng.py` (`keep_best`, `_snapshot_params`/
+- `pamica/torch_impl/amica_torch_ng.py` (`keep_best`, `_snapshot_params`/
   `_restore_params`, `final_ll_`, `_KEEP_BEST_TOL`).
-- `pyAMICA/tests/torch_tests/test_ng_backend.py::test_keep_best_*`.
+- `pamica/tests/torch_tests/test_ng_backend.py::test_keep_best_*`.
 - `.context/issue-51/ensemble_ll.py` (Fortran-vs-NG LL ensemble, real data).
-- Fortran schedule: `pyAMICA/amica15.f90:1038-1058` (anneal-on-decrease).
+- Fortran schedule: `pamica/amica15.f90:1038-1058` (anneal-on-decrease).

.context/ideas.md

@@ -1,4 +1,4 @@
-# pyAMICA Design Ideas
+# pamica Design Ideas
 
 High-level PyTorch design decisions and library options for the AMICA port.
 

.context/issue-136/matlab_viz_verification.md

@@ -37,7 +37,7 @@ MATLAB cannot run in CI, so this is recorded rather than automated.
 `pop_topohistplot.m` and `pop_modPMI.m` carry explicit **GPL-2.0-or-later** headers
 (Copyright Ozgur Baklan, SCCN, INC, UCSD). `modprobplot.m`, `minfojp.m`, `LLt2v.m`,
 `smooth_amica_prob.m` carry no header but sit inside that GPL plugin, so they are
-conservatively GPL too. pyAMICA is BSD-3-Clause, which is why Phase 2's PMI was a
+conservatively GPL too. pamica is BSD-3-Clause, which is why Phase 2's PMI was a
 clean-room reimplementation.
 
 **Posture: run-and-observe only. No `.m` implementation source was read at any point.**
@@ -77,10 +77,10 @@ Notes on the two correlation-rather-than-equality rows:
 
 Side-by-side renders on the same data are committed here:
 
-- `cmp_modprob.png` — MATLAB `modprobplot` vs `pyAMICA.viz.plot_model_probability`
+- `cmp_modprob.png` — MATLAB `modprobplot` vs `pamica.viz.plot_model_probability`
   (1 s smoothing). Same two stacked panels, same switching times (~1.4, 3.4, 6.5, 9.3,
   12.5, 15.7 s), same log-likelihood trace and range (-105 to -125), seconds axis.
-- `cmp_pmi.png` — MATLAB `pop_modPMI` vs `pyAMICA.viz.plot_pmi_heatmap`, rendered on
+- `cmp_pmi.png` — MATLAB `pop_modPMI` vs `pamica.viz.plot_pmi_heatmap`, rendered on
   **identical signals** (MATLAB's own `EEG.icaact`) so the comparison isolates the
   estimator and the ordering. Both show the same dependent-subspace cluster near the
   centre with the same radiating cross pattern, at the same MI scale.
@@ -193,7 +193,7 @@ algorithm (ours greedy nearest-neighbour chain vs MATLAB's iterative cost minimi
    must agree, since exact-equality dispatch sends them down different branches).
 
 4. **postAmicaUtility's own `loadmodout15.m` is broken on R2025b** (`Unmatched ']'`,
-   line 120). pyAMICA's bundled copy works. `addpath` `pyAMICA/sample_data` LAST so ours
+   line 120). pamica's bundled copy works. `addpath` `pamica/sample_data` LAST so ours
    shadows theirs, or the model never loads and every plot fails with a misleading
    "No AMICA solution found".
 5. **`pop_topohistplot` is broken upstream** (`Unrecognized function or variable
@@ -216,7 +216,7 @@ git clone --depth 1 https://github.com/sccn/postAmicaUtility.git     # GPL: run,
 git clone --depth 1 https://github.com/bigdelys/pre_ICA_cleaning.git # Apache-2.0: getMIR.m
 ```
 
-Then: `addpath(genpath(eeglab)); addpath(postAmicaUtility); addpath(pyAMICA/sample_data)`
+Then: `addpath(genpath(eeglab)); addpath(postAmicaUtility); addpath(pamica/sample_data)`
 (last, per trap 4); `eeglab nogui`; `pop_loadset` + `pop_loadmodout(EEG, <amicaout dir>)`;
 `modprobplot(EEG, 1:num_models, smooth_sec, [])` returns `[v2plot, llt2plot]` — the exact
 series it draws — and `pop_modPMI(EEG, 'models2plot', 1, 'order', true)` writes

.context/issue-144-parity-data-adequacy/bundled_sample_newton0.py

@@ -29,8 +29,8 @@
 HERE = Path(__file__).resolve().parent
 REPO = HERE.parents[1]
 sys.path.insert(0, str(REPO))
-from pyAMICA import AMICA  # noqa: E402
-from pyAMICA.torch_impl.utils import load_eeglab_data  # noqa: E402
+from pamica import AMICA  # noqa: E402
+from pamica.torch_impl.utils import load_eeglab_data  # noqa: E402
 
 
 def xcorr(Wa, Wb):
@@ -62,9 +62,9 @@ def amari_distance(Wa, Wb):
 def run_fortran(data_dim, max_iter, seed, work_dir):
     work_dir.mkdir(parents=True, exist_ok=True)
     shutil.copy(
-        REPO / "pyAMICA/sample_data/eeglab_data.fdt", work_dir / "eeglab_data.fdt"
+        REPO / "pamica/sample_data/eeglab_data.fdt", work_dir / "eeglab_data.fdt"
     )
-    template = (REPO / "pyAMICA/sample_data/input.param").read_text().splitlines()
+    template = (REPO / "pamica/sample_data/input.param").read_text().splitlines()
     lines = []
     for line in template:
         if line.startswith("files"):
@@ -81,7 +81,7 @@ def run_fortran(data_dim, max_iter, seed, work_dir):
     (work_dir / "fortran_output").mkdir(exist_ok=True)
 
     result = subprocess.run(
-        [str(REPO / "pyAMICA/sample_data/amica15mac"), "input.param"],
+        [str(REPO / "pamica/sample_data/amica15mac"), "input.param"],
         cwd=work_dir,
         capture_output=True,
         text=True,
@@ -116,13 +116,13 @@ def main():
     )
     seeds = list(range(301, 301 + n_seeds))
 
-    with open(REPO / "pyAMICA/sample_data/sample_params.json") as f:
+    with open(REPO / "pamica/sample_data/sample_params.json") as f:
         params = json.load(f)
     data_dim = params["data_dim"]
     field_dim = params["field_dim"][0]
 
     data = load_eeglab_data(
-        str(REPO / "pyAMICA/sample_data/eeglab_data.fdt"),
+        str(REPO / "pamica/sample_data/eeglab_data.fdt"),
         data_dim=data_dim,
         field_dim=field_dim,
         dtype=np.float32,

.context/issue-144-parity-data-adequacy/run_5seed_newton0.sh

@@ -10,7 +10,7 @@
 # the NEXT seed's Fortran starts immediately -- CPU and GPU work overlap
 # since they don't compete for the same resource.
 set -e
-cd ~/pyAMICA-issue144
+cd ~/pamica-issue144
 NPY=benchmarks/data/ds002718_sub-002_eeg70_full.npy
 SCRIPTS=.context/issue-144-parity-data-adequacy
 

.context/issue-144-parity-data-adequacy/run_fortran_only.py

@@ -15,8 +15,8 @@
 
 HERE = Path(__file__).resolve().parent
 REPO = HERE.parents[1]
-BIN = REPO / "pyAMICA/sample_data/amica15_linux"
-INPUT_PARAM = REPO / "pyAMICA/sample_data/input.param"
+BIN = REPO / "pamica/sample_data/amica15_linux"
+INPUT_PARAM = REPO / "pamica/sample_data/input.param"
 
 
 def write_fdt(data: np.ndarray, path: Path) -> None:

.context/issue-144-parity-data-adequacy/run_ng_only.py

@@ -14,7 +14,7 @@
 HERE = Path(__file__).resolve().parent
 REPO = HERE.parents[1]
 sys.path.insert(0, str(REPO))
-from pyAMICA.torch_impl import AMICATorchNG  # noqa: E402
+from pamica.torch_impl import AMICATorchNG  # noqa: E402
 
 
 def xcorr(Wa, Wb):

.context/issue-144-parity-data-adequacy/test_ds002718_32ch.py

@@ -25,10 +25,10 @@
 HERE = Path(__file__).resolve().parent
 REPO = HERE.parents[1]
 sys.path.insert(0, str(REPO))
-from pyAMICA.torch_impl import AMICATorchNG  # noqa: E402
+from pamica.torch_impl import AMICATorchNG  # noqa: E402
 
-BIN = REPO / "pyAMICA/sample_data/amica15mac"
-INPUT_PARAM = REPO / "pyAMICA/sample_data/input.param"
+BIN = REPO / "pamica/sample_data/amica15mac"
+INPUT_PARAM = REPO / "pamica/sample_data/input.param"
 
 
 def xcorr(Wa, Wb):

.context/issue-144-parity-data-adequacy/test_ds002718_hallu.py

@@ -19,10 +19,10 @@
 HERE = Path(__file__).resolve().parent
 REPO = HERE.parents[1]
 sys.path.insert(0, str(REPO))
-from pyAMICA.torch_impl import AMICATorchNG  # noqa: E402
+from pamica.torch_impl import AMICATorchNG  # noqa: E402
 
-BIN = REPO / "pyAMICA/sample_data/amica15_linux"
-INPUT_PARAM = REPO / "pyAMICA/sample_data/input.param"
+BIN = REPO / "pamica/sample_data/amica15_linux"
+INPUT_PARAM = REPO / "pamica/sample_data/input.param"
 
 
 def xcorr(Wa, Wb):

.context/issue-155/matlab_interop_verification.md

@@ -1,16 +1,16 @@
-# LLt interop verification: pyAMICA <-> EEGLAB `loadmodout15.m` (issue #155, PR #156)
+# LLt interop verification: pamica <-> EEGLAB `loadmodout15.m` (issue #155, PR #156)
 
 ## The contract
 
 The acceptance bar for the `LLt` work is bidirectional interop, not internal
 self-consistency:
 
-1. **pyAMICA's reader must understand Fortran's output.**
-2. **EEGLAB's reader (`loadmodout15.m`) must understand pyAMICA's output.**
+1. **pamica's reader must understand Fortran's output.**
+2. **EEGLAB's reader (`loadmodout15.m`) must understand pamica's output.**
 
 PR #156's automated tests only pin direction 1 (via the real bundled
 `sample_data/amicaout/LLt` fixture). They do **not** pin direction 2: the
-round-trip tests prove pyAMICA's writer agrees with pyAMICA's *own* reader,
+round-trip tests prove pamica's writer agrees with pamica's *own* reader,
 which a self-consistently-wrong writer/reader pair would also satisfy. Only
 the genuine MATLAB reader can close that.
 
@@ -24,16 +24,16 @@ same way #92's was.
 
 ## Method
 
-MATLAB R2025b, real `loadmodout15.m` from `pyAMICA/sample_data/`, run against
+MATLAB R2025b, real `loadmodout15.m` from `pamica/sample_data/`, run against
 three directories:
 
-- `pyamica_m1` -- pyAMICA `AMICATorchNG` single-model fit, real bundled sample
+- `pyamica_m1` -- pamica `AMICATorchNG` single-model fit, real bundled sample
   EEG (`eeglab_data.fdt`, 32ch x 4096 samples), seed 1, 20 iters.
 - `pyamica_m2` -- same data, 2 models, seed 4, 8 iters (non-trivial `mod_prob`,
   so the reader's gm-based model reordering is actually exercised).
 - `amicaout` -- the genuine Fortran-produced fixture bundled in the repo.
 
-Each result was compared against `pyAMICA.numpy_impl.load.loadmodout`'s view of
+Each result was compared against `pamica.numpy_impl.load.loadmodout`'s view of
 the same directory with `np.array_equal` (not `allclose`).
 
 ## Result: bit-exact in both directions
@@ -43,28 +43,28 @@ pyamica_m1  Lht (1, 4096)  equal=True | Lt (4096,)  equal=True | max|dH|=0.0 max
 pyamica_m2  Lht (2, 4096)  equal=True | Lt (4096,)  equal=True | max|dH|=0.0 max|dT|=0.0
 fortran     Lht (1, 30504) equal=True | Lt (30504,) equal=True | max|dH|=0.0 max|dT|=0.0
 
-EEGLAB loadmodout15 == pyAMICA loadmodout, bit-exact, all cases: True
+EEGLAB loadmodout15 == pamica loadmodout, bit-exact, all cases: True
 pyamica_m1  single-model Lht[0]==Lt via MATLAB: True
 fortran     single-model Lht[0]==Lt via MATLAB: True
 ```
 
 Corroborating details:
 
-- 2-model `mod_prob` agrees: MATLAB `[0.554689 0.445311]` vs pyAMICA
+- 2-model `mod_prob` agrees: MATLAB `[0.554689 0.445311]` vs pamica
   `[0.5547 0.4453]`. Both readers apply the same gm-descending model
   reordering to `Lht`, so the model axis stays aligned with `W`/`mod_prob`
   across the two implementations.
 - Genuine Fortran fixture reads to `Lt mean = -108.859935652062` under BOTH
   readers, matching `nw * final_ll = 32 * -3.40187` independently.
-- MATLAB reads `Lt` as `(1, N)` and pyAMICA as `(N,)`; that is MATLAB's
+- MATLAB reads `Lt` as `(1, N)` and pamica as `(N,)`; that is MATLAB's
   everything-is-2D convention, not a layout difference (values compare equal
   after `ravel`).
 
 ## Why it agrees
 
 `loadmodout15.m:119-124` does `fread(...,'double')` then
 `reshape(LLt, num_models+1, N)`. MATLAB's `reshape` is column-major, so this is
-`order="F"`. pyAMICA's writer (`numpy_impl/load.py:write_amicaout`) does
+`order="F"`. pamica's writer (`numpy_impl/load.py:write_amicaout`) does
 `vstack([Lht, Lt]).ravel(order="F")`, and its reader does
 `reshape(num_models+1, -1, order="F")`. All three agree with Fortran's
 `write_output` (`amica15.f90:2308-2333`), which writes per timepoint each

.context/issue-159/gate_check.py

@@ -1,7 +1,7 @@
 """MATLAB gate check for issue #159 (run last).
 
 Compares Python ``loadmodout`` against MATLAB ``loadmodout15.m`` element-wise for
-W/A/sbeta/rho, on the genuine single-model fixture and the pyAMICA 2-model output.
+W/A/sbeta/rho, on the genuine single-model fixture and the pamica 2-model output.
 Both are the same algorithm (Python is a port), so a correct byte order makes them
 agree to floating-point noise; the pre-#159 C-order read made W disagree by the
 internal transpose (and A/svar with it), and sbeta/rho disagree for num_mix > 1.

.context/issue-159/gate_compare.m

@@ -1,13 +1,13 @@
 % MATLAB gate for issue #159 (run after gate_prep.py, before gate_check.py).
-% Loads the genuine single-model Fortran fixture and the pyAMICA-written 2-model
+% Loads the genuine single-model Fortran fixture and the pamica-written 2-model
 % output with EEGLAB's real loadmodout15.m, and saves W/A/sbeta/rho so the Python
 % companion can check they match what Python loadmodout read. This is the only
-% test that pins direction (2) of the interop contract: EEGLAB reads pyAMICA's
-% (and Fortran's) bytes correctly. A pyAMICA write->read round trip cannot.
+% test that pins direction (2) of the interop contract: EEGLAB reads pamica's
+% (and Fortran's) bytes correctly. A pamica write->read round trip cannot.
 
 here = fileparts(mfilename('fullpath'));
 root = fullfile(here, '..', '..');
-sample = fullfile(root, 'pyAMICA', 'sample_data');
+sample = fullfile(root, 'pamica', 'sample_data');
 
 % addpath sample_data LAST so its working loadmodout15.m shadows any broken
 % copy elsewhere on the path (postAmicaUtility's has a syntax error on R2025b).

.context/issue-159/gate_prep.py

@@ -1,6 +1,6 @@
 """MATLAB gate prep for issue #159 (run first).
 
-Writes a real 2-model pyAMICA output, then dumps what Python ``loadmodout``
+Writes a real 2-model pamica output, then dumps what Python ``loadmodout``
 reads for W/A/sbeta/rho on (a) the genuine single-model Fortran fixture and
 (b) that 2-model output. ``gate_compare.m`` then loads the same two directories
 with EEGLAB's ``loadmodout15.m`` and this script's companion assertion (run last)
@@ -12,13 +12,13 @@
 import os
 import numpy as np
 
-from pyAMICA import AMICA
-from pyAMICA.numpy_impl.load import loadmodout
-from pyAMICA.torch_impl.utils import load_eeglab_data
+from pamica import AMICA
+from pamica.numpy_impl.load import loadmodout
+from pamica.torch_impl.utils import load_eeglab_data
 
 HERE = os.path.dirname(os.path.abspath(__file__))
 ROOT = os.path.abspath(os.path.join(HERE, "..", ".."))
-SAMPLE = os.path.join(ROOT, "pyAMICA", "sample_data")
+SAMPLE = os.path.join(ROOT, "pamica", "sample_data")
 FIXTURE = os.path.join(SAMPLE, "amicaout")
 TWO_MODEL = os.path.join(HERE, "gate_2model")
 

.context/issue-159/matlab_interop_verification.md

@@ -1,14 +1,14 @@
 # Issue #159 -- MATLAB interop verification (W / A / sbeta / rho)
 
 Direction (2) of the interop contract: EEGLAB's real `loadmodout15.m` reads
-pyAMICA's (and Fortran's) bytes correctly. A pyAMICA write->read round trip
+pamica's (and Fortran's) bytes correctly. A pamica write->read round trip
 cannot pin this -- it cancels the byte-order error -- so this is a manual MATLAB
 run, recorded here (MATLAB is not on PATH and not in CI).
 
 ## Setup
 
 - MATLAB `R2025b` at `/Volumes/S1/Applications/MATLAB_R2025b.app/bin/matlab`.
-- Reader: pyAMICA's own working `pyAMICA/sample_data/loadmodout15.m`, added to the
+- Reader: pamica's own working `pamica/sample_data/loadmodout15.m`, added to the
   path LAST so it shadows any broken copy (postAmicaUtility's has a syntax error
   on R2025b). `loadmodout15` concatenates paths directly, so the outdir argument
   is passed with a trailing `filesep`.
@@ -17,7 +17,7 @@ run, recorded here (MATLAB is not on PATH and not in CI).
   `gate_compare.m` (MATLAB `loadmodout15` on the same dirs), `gate_check.py`
   (element-wise compare).
 - Inputs: (a) the genuine single-model Fortran fixture `sample_data/amicaout`;
-  (b) the freshly written pyAMICA 2-model output `.context/issue-159/gate_2model`.
+  (b) the freshly written pamica 2-model output `.context/issue-159/gate_2model`.
 
 ## Result -- GATE PASS
 

.context/issue-21/corrected_mstep_prototype.py

@@ -1,5 +1,5 @@
 """VALIDATED reference prototype for the issue #21 fix (do not ship as-is; port
-these methods into amica_torch_ng.py and pyAMICA.py -- see handoff.md).
+these methods into amica_torch_ng.py and pamica.py -- see handoff.md).
 
 `CorrectedNG` subclasses the shipped `AMICATorchNG` and overrides the M-step with the
 Fortran-faithful version that this session validated:
@@ -22,12 +22,12 @@
 import numpy as np
 import torch
 
-from pyAMICA.torch_impl import AMICATorchNG
-from pyAMICA.torch_impl.amica_torch_ng import _score
-from pyAMICA.torch_impl.utils import load_eeglab_data
+from pamica.torch_impl import AMICATorchNG
+from pamica.torch_impl.amica_torch_ng import _score
+from pamica.torch_impl.utils import load_eeglab_data
 
 NW, FIELD, SEED = 32, 30504, 42
-SAMPLE = Path(__file__).resolve().parents[2] / "pyAMICA" / "sample_data"
+SAMPLE = Path(__file__).resolve().parents[2] / "pamica" / "sample_data"
 AO = SAMPLE / "amicaout"