Rename package pyAMICA to pamica (#176)

* Rename package pyAMICA to pamica

* Rebuild paper.pdf [skip ci]

* Fix cloned-repo dir refs (cd pyAMICA, not pamica)

---------

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

Author: neuromechanist

.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):