couplnorm 0.1.0__tar.gz

couplnorm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anish Bhat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

couplnorm-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: couplnorm
+Version: 0.1.0
+Summary: Normalized 4th-order coupling metrics and losses for generative model evaluation.
+Author: Anish Bhat
+License: MIT
+Project-URL: Homepage, https://github.com/anishbhat28/couplnorm
+Project-URL: Issues, https://github.com/anishbhat28/couplnorm/issues
+Keywords: generative-models,normalizing-flows,pytorch,coupling,spectral-analysis,model-evaluation,non-gaussianity,fourth-order-statistics,lattice-field-theory,scientific-ml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: matplotlib; extra == "dev"
+Dynamic: license-file
+
+# couplnorm
+
+**Normalized 4th-order coupling metrics and losses for generative model evaluation.**
+
+`couplnorm` implements the normalized off-diagonal coupling diagnostic **C**, a
+4th-order spectral statistic that measures *joint* coupling between Fourier modes
+— structure that second-order metrics (power spectrum, two-point function) miss
+by construction.
+
+> Marginal Gaussianity does not imply joint independence. **C measures the gap.**
+
+![C across distributions with matched marginals](assets/coupling_hook.png)
+
+All three distributions above have (near-)identical per-mode marginals; a power
+spectrum cannot tell them apart. C rises from ~0.04 to ~0.82 as joint 4th-order
+coupling is switched on. (Reproduce with `notebooks/01_basic_usage.ipynb`.)
+
+Given field samples, `couplnorm` computes the covariance of the per-mode spectral
+energies `E_k = |φ̃_k|²` and reduces it to a single scale-free number:
+
+```
+C = ‖Σ − diag(Σ)‖_F / ‖Σ‖_F
+```
+
+`C = 0` means the spectral energies are pairwise uncorrelated (a Gaussian /
+free-field signature); `C → 1` means off-diagonal coupling dominates.
+
+## Install
+
+```bash
+pip install -e .[dev]     # from a checkout
+```
+
+Requires Python ≥ 3.10 and PyTorch ≥ 2.0.
+
+## Quickstart
+
+```python
+import torch
+from couplnorm import coupling_from_samples, CouplingMetric, CouplingLoss
+
+# One-shot number from a batch of (B, N) real fields
+phi = torch.randn(10_000, 32)
+print(coupling_from_samples(phi).item())        # ~0.03  (independent modes)
+
+# As a streaming nn.Module metric
+metric = CouplingMetric(mode="running", momentum=0.02, n_modes=32 // 2 + 1)
+for chunk in loader:                            # doctest: +SKIP
+    metric(chunk)
+print(metric.compute().item())
+
+# As a training loss that matches a reference distribution's coupling
+loss_fn = CouplingLoss.from_data(reference_data, target_type="matrix")  # doctest: +SKIP
+loss = loss_fn(generated_batch)                 # doctest: +SKIP
+```
+
+## Three forms
+
+| Object                  | Use                                                            |
+| ----------------------- | ------------------------------------------------------------- |
+| `coupling_from_samples` | one-line functional helper — just want the number             |
+| `CouplingMetric`        | `nn.Module` metric; batch **or** streaming (running EMA) mode  |
+| `CouplingLoss`          | differentiable loss: match a covariance, match a scalar C, or minimize C (DeCov-style) |
+
+## The FFT convention (important)
+
+For a **real** field of length `N`, the DFT is conjugate-symmetric
+(`φ̃_k = φ̃*_{N−k}`), so `|φ̃_k|² = |φ̃_{N−k}|²` *exactly*. Feeding the full FFT into
+C creates `N − 2` off-diagonal entries that equal diagonal entries before any
+physics enters, inflating C by an analytical floor of
+
+```
+C_floor = sqrt((N − 2) / (2N − 2)) ≈ 0.7
+```
+
+`couplnorm` defaults to `real_fft=True` (uses `torch.fft.rfft`, keeping only the
+`N//2 + 1` unique modes), which reflects only genuine coupling. Set
+`real_fft=False` only for intrinsically complex fields. A regression test pins
+the analytical floor so this convention can't silently break.
+
+## What's in the box
+
+```
+src/couplnorm/
+  coupling.py     # the metric, loss, and helpers (the contribution)
+  samplers.py     # Phi4Sampler: 1D phi^4 Metropolis-Hastings reference sampler
+  models/         # FourierModel, FullGaussian, PCAModel, MAF baselines
+  plotting.py     # matplotlib helpers for the notebooks
+notebooks/
+  01_basic_usage.ipynb      # compare C across distributions
+  02_reproduce_paper.ipynb  # phi^4 free vs interacting theory
+  03_coupling_as_loss.ipynb # train a generator to match coupling
+```
+
+Baselines share one interface: construct, `.fit(data)` where applicable, then
+`.sample(n)` returning `(n, N)` real position-space fields. The `FourierModel`
+assumes marginal mode independence, so it collapses C to ≈ 0 regardless of the
+target — the concrete demonstration of why C is worth measuring.
+
+## Case study
+
+The φ⁴ lattice study that motivates C is:
+
+> A. Bhat, R. Ide, Z. Zhao. *When Independent Gaussian Models Break Down:
+> Characterizing Regime-Dependent Modeling Failures in φ⁴ Theory.*
+> arXiv:[2605.01145](https://arxiv.org/abs/2605.01145).
+
+That paper's reported C values (C(N=32) ≈ 0.06 up to C(N=128) ≈ 0.2, strong
+coupling saturating near 0.17–0.18) are computed on the **unique rfft modes** —
+the `real_fft=True` default here. The full FFT would inflate every value to the
+~0.7 conjugate-symmetry floor (see above), so the published magnitudes are only
+consistent with the unique-mode convention.
+
+## Citation
+
+See [`CITATION.cff`](CITATION.cff).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

couplnorm-0.1.0/README.md

@@ -0,0 +1,120 @@
+# couplnorm
+
+**Normalized 4th-order coupling metrics and losses for generative model evaluation.**
+
+`couplnorm` implements the normalized off-diagonal coupling diagnostic **C**, a
+4th-order spectral statistic that measures *joint* coupling between Fourier modes
+— structure that second-order metrics (power spectrum, two-point function) miss
+by construction.
+
+> Marginal Gaussianity does not imply joint independence. **C measures the gap.**
+
+![C across distributions with matched marginals](assets/coupling_hook.png)
+
+All three distributions above have (near-)identical per-mode marginals; a power
+spectrum cannot tell them apart. C rises from ~0.04 to ~0.82 as joint 4th-order
+coupling is switched on. (Reproduce with `notebooks/01_basic_usage.ipynb`.)
+
+Given field samples, `couplnorm` computes the covariance of the per-mode spectral
+energies `E_k = |φ̃_k|²` and reduces it to a single scale-free number:
+
+```
+C = ‖Σ − diag(Σ)‖_F / ‖Σ‖_F
+```
+
+`C = 0` means the spectral energies are pairwise uncorrelated (a Gaussian /
+free-field signature); `C → 1` means off-diagonal coupling dominates.
+
+## Install
+
+```bash
+pip install -e .[dev]     # from a checkout
+```
+
+Requires Python ≥ 3.10 and PyTorch ≥ 2.0.
+
+## Quickstart
+
+```python
+import torch
+from couplnorm import coupling_from_samples, CouplingMetric, CouplingLoss
+
+# One-shot number from a batch of (B, N) real fields
+phi = torch.randn(10_000, 32)
+print(coupling_from_samples(phi).item())        # ~0.03  (independent modes)
+
+# As a streaming nn.Module metric
+metric = CouplingMetric(mode="running", momentum=0.02, n_modes=32 // 2 + 1)
+for chunk in loader:                            # doctest: +SKIP
+    metric(chunk)
+print(metric.compute().item())
+
+# As a training loss that matches a reference distribution's coupling
+loss_fn = CouplingLoss.from_data(reference_data, target_type="matrix")  # doctest: +SKIP
+loss = loss_fn(generated_batch)                 # doctest: +SKIP
+```
+
+## Three forms
+
+| Object                  | Use                                                            |
+| ----------------------- | ------------------------------------------------------------- |
+| `coupling_from_samples` | one-line functional helper — just want the number             |
+| `CouplingMetric`        | `nn.Module` metric; batch **or** streaming (running EMA) mode  |
+| `CouplingLoss`          | differentiable loss: match a covariance, match a scalar C, or minimize C (DeCov-style) |
+
+## The FFT convention (important)
+
+For a **real** field of length `N`, the DFT is conjugate-symmetric
+(`φ̃_k = φ̃*_{N−k}`), so `|φ̃_k|² = |φ̃_{N−k}|²` *exactly*. Feeding the full FFT into
+C creates `N − 2` off-diagonal entries that equal diagonal entries before any
+physics enters, inflating C by an analytical floor of
+
+```
+C_floor = sqrt((N − 2) / (2N − 2)) ≈ 0.7
+```
+
+`couplnorm` defaults to `real_fft=True` (uses `torch.fft.rfft`, keeping only the
+`N//2 + 1` unique modes), which reflects only genuine coupling. Set
+`real_fft=False` only for intrinsically complex fields. A regression test pins
+the analytical floor so this convention can't silently break.
+
+## What's in the box
+
+```
+src/couplnorm/
+  coupling.py     # the metric, loss, and helpers (the contribution)
+  samplers.py     # Phi4Sampler: 1D phi^4 Metropolis-Hastings reference sampler
+  models/         # FourierModel, FullGaussian, PCAModel, MAF baselines
+  plotting.py     # matplotlib helpers for the notebooks
+notebooks/
+  01_basic_usage.ipynb      # compare C across distributions
+  02_reproduce_paper.ipynb  # phi^4 free vs interacting theory
+  03_coupling_as_loss.ipynb # train a generator to match coupling
+```
+
+Baselines share one interface: construct, `.fit(data)` where applicable, then
+`.sample(n)` returning `(n, N)` real position-space fields. The `FourierModel`
+assumes marginal mode independence, so it collapses C to ≈ 0 regardless of the
+target — the concrete demonstration of why C is worth measuring.
+
+## Case study
+
+The φ⁴ lattice study that motivates C is:
+
+> A. Bhat, R. Ide, Z. Zhao. *When Independent Gaussian Models Break Down:
+> Characterizing Regime-Dependent Modeling Failures in φ⁴ Theory.*
+> arXiv:[2605.01145](https://arxiv.org/abs/2605.01145).
+
+That paper's reported C values (C(N=32) ≈ 0.06 up to C(N=128) ≈ 0.2, strong
+coupling saturating near 0.17–0.18) are computed on the **unique rfft modes** —
+the `real_fft=True` default here. The full FFT would inflate every value to the
+~0.7 conjugate-symmetry floor (see above), so the published magnitudes are only
+consistent with the unique-mode convention.
+
+## Citation
+
+See [`CITATION.cff`](CITATION.cff).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

couplnorm-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "couplnorm"
+version = "0.1.0"
+description = "Normalized 4th-order coupling metrics and losses for generative model evaluation."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Anish Bhat"}]
+dependencies = ["torch>=2.0"]
+keywords = [
+    "generative-models", "normalizing-flows", "pytorch",
+    "coupling", "spectral-analysis", "model-evaluation",
+    "non-gaussianity", "fourth-order-statistics",
+    "lattice-field-theory", "scientific-ml",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-cov", "matplotlib"]
+
+[project.urls]
+Homepage = "https://github.com/anishbhat28/couplnorm"
+Issues = "https://github.com/anishbhat28/couplnorm/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

couplnorm-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

couplnorm-0.1.0/src/couplnorm/__init__.py

@@ -0,0 +1,11 @@
+"""couplnorm: normalized 4th-order coupling metrics and losses for
+generative model evaluation on Fourier-decomposable data.
+"""
+from couplnorm.coupling import (
+    CouplingLoss,
+    CouplingMetric,
+    coupling_from_samples,
+)
+
+__all__ = ["CouplingMetric", "CouplingLoss", "coupling_from_samples"]
+__version__ = "0.1.0"

couplnorm-0.1.0/src/couplnorm/coupling.py

@@ -0,0 +1,285 @@
+"""Normalized off-diagonal coupling diagnostic and loss for evaluating
+generative models on Fourier-decomposable data.
+"""
+from __future__ import annotations
+
+from typing import Optional, Union
+
+import torch
+import torch.nn as nn
+from torch import Tensor
+
+__all__ = ["CouplingMetric", "CouplingLoss", "coupling_from_samples"]
+
+
+def _spectral_energies(
+    x: Tensor,
+    input_space: str = "position",
+    fft_norm: str = "ortho",
+    real_fft: bool = True,
+) -> Tensor:
+    if input_space == "position":
+        if real_fft:
+            x_hat = torch.fft.rfft(x, dim=-1, norm=fft_norm)
+        else:
+            x_hat = torch.fft.fft(x, dim=-1, norm=fft_norm)
+        return x_hat.real.pow(2) + x_hat.imag.pow(2)
+    elif input_space == "spectral":
+        return x
+    else:
+        raise ValueError(
+            f"input_space must be 'position' or 'spectral', got {input_space!r}"
+        )
+
+
+def _batch_covariance(E: Tensor, unbiased: bool = True) -> Tensor:
+    if E.dim() != 2:
+        raise ValueError(f"Expected 2D tensor (B, M), got shape {tuple(E.shape)}")
+    B = E.shape[0]
+    if B < 2 and unbiased:
+        raise ValueError(
+            f"Need B >= 2 for unbiased covariance; got B={B}. "
+            "Set unbiased=False or use mode='running' for streaming."
+        )
+    mean = E.mean(dim=0, keepdim=True)
+    centered = E - mean
+    denom = (B - 1) if unbiased else B
+    return centered.T @ centered / denom
+
+
+def _coupling_from_cov(cov: Tensor, eps: float = 1e-12) -> Tensor:
+    diag_vec = torch.diagonal(cov)
+    off_diag = cov - torch.diag_embed(diag_vec)
+    num = torch.linalg.matrix_norm(off_diag, ord="fro")
+    den = torch.linalg.matrix_norm(cov, ord="fro")
+    return num / (den + eps)
+
+
+def coupling_from_samples(
+    x: Tensor,
+    input_space: str = "position",
+    fft_norm: str = "ortho",
+    real_fft: bool = True,
+    eps: float = 1e-12,
+    unbiased: bool = True,
+) -> Tensor:
+    if x.dim() == 1:
+        raise ValueError(
+            "coupling_from_samples requires batched input (B, N). "
+            "For streaming, use CouplingMetric(mode='running')."
+        )
+    E = _spectral_energies(x, input_space=input_space, fft_norm=fft_norm, real_fft=real_fft)
+    cov = _batch_covariance(E, unbiased=unbiased)
+    return _coupling_from_cov(cov, eps)
+
+
+class CouplingMetric(nn.Module):
+    def __init__(
+        self,
+        input_space: str = "position",
+        mode: str = "batch",
+        momentum: float = 0.1,
+        eps: float = 1e-12,
+        fft_norm: str = "ortho",
+        real_fft: bool = True,
+        unbiased: bool = True,
+        n_modes: Optional[int] = None,
+    ):
+        super().__init__()
+        if input_space not in ("position", "spectral"):
+            raise ValueError(
+                f"input_space must be 'position' or 'spectral'; got {input_space!r}"
+            )
+        if mode not in ("batch", "running"):
+            raise ValueError(f"mode must be 'batch' or 'running'; got {mode!r}")
+        if not (0.0 < momentum <= 1.0):
+            raise ValueError(f"momentum must be in (0, 1]; got {momentum}")
+
+        self.input_space = input_space
+        self.mode = mode
+        self.momentum = float(momentum)
+        self.eps = float(eps)
+        self.fft_norm = fft_norm
+        self.real_fft = bool(real_fft)
+        self.unbiased = bool(unbiased)
+
+        if mode == "running":
+            if n_modes is not None:
+                self.register_buffer("running_mean", torch.zeros(n_modes))
+                self.register_buffer("running_second", torch.zeros(n_modes, n_modes))
+            else:
+                self.register_buffer("running_mean", torch.empty(0))
+                self.register_buffer("running_second", torch.empty(0))
+            self.register_buffer("num_batches_tracked", torch.tensor(0, dtype=torch.long))
+
+    def _maybe_init_buffers(self, M: int, device, dtype) -> None:
+        if self.running_mean.numel() == 0:
+            self.running_mean = torch.zeros(M, device=device, dtype=dtype)
+            self.running_second = torch.zeros(M, M, device=device, dtype=dtype)
+
+    def forward(self, x: Tensor) -> Tensor:
+        if x.dim() == 1:
+            x = x.unsqueeze(0)
+        if x.dim() != 2:
+            raise ValueError(f"Expected 1D or 2D input, got shape {tuple(x.shape)}")
+        E = _spectral_energies(x, self.input_space, self.fft_norm, self.real_fft)
+        B, M = E.shape
+
+        if self.mode == "batch":
+            cov = _batch_covariance(E, unbiased=self.unbiased)
+            return _coupling_from_cov(cov, self.eps)
+
+        self._maybe_init_buffers(M, E.device, E.dtype)
+        if self.running_mean.shape[0] != M:
+            raise ValueError(
+                "Number of modes changed: running buffers have "
+                f"N={self.running_mean.shape[0]} but got N={M}."
+            )
+
+        with torch.no_grad():
+            batch_mean = E.mean(dim=0)
+            batch_second = (E.T @ E) / B
+            m = self.momentum
+            self.running_mean.mul_(1.0 - m).add_(batch_mean, alpha=m)
+            self.running_second.mul_(1.0 - m).add_(batch_second, alpha=m)
+            self.num_batches_tracked.add_(1)
+        return self.compute()
+
+    def compute(self) -> Tensor:
+        if self.mode != "running":
+            raise RuntimeError("compute() is only valid in running mode.")
+        if self.running_mean.numel() == 0 or self.num_batches_tracked.item() == 0:
+            raise RuntimeError("No batches tracked yet; call forward() at least once.")
+        mu = self.running_mean
+        M = self.running_second
+        cov = M - torch.outer(mu, mu)
+        return _coupling_from_cov(cov, self.eps)
+
+    def covariance(self) -> Tensor:
+        if self.mode != "running":
+            raise RuntimeError(
+                "covariance() requires mode='running'. For one-off batches, "
+                "use coupling_from_samples or recompute manually."
+            )
+        mu = self.running_mean
+        M = self.running_second
+        return M - torch.outer(mu, mu)
+
+    def reset(self) -> None:
+        if self.mode != "running":
+            return
+        if self.running_mean.numel() > 0:
+            self.running_mean.zero_()
+            self.running_second.zero_()
+        self.num_batches_tracked.zero_()
+
+    def extra_repr(self) -> str:
+        return (
+            f"input_space={self.input_space!r}, mode={self.mode!r}, "
+            f"momentum={self.momentum}, eps={self.eps}, "
+            f"fft_norm={self.fft_norm!r}, real_fft={self.real_fft}"
+        )
+
+
+class CouplingLoss(nn.Module):
+    def __init__(
+        self,
+        target_type: str = "matrix",
+        target: Optional[Union[Tensor, float]] = None,
+        input_space: str = "position",
+        eps: float = 1e-12,
+        fft_norm: str = "ortho",
+        real_fft: bool = True,
+        unbiased: bool = True,
+    ):
+        super().__init__()
+        if target_type not in ("matrix", "scalar", "regularize"):
+            raise ValueError(
+                "target_type must be 'matrix', 'scalar', or 'regularize'; "
+                f"got {target_type!r}"
+            )
+        if input_space not in ("position", "spectral"):
+            raise ValueError(
+                f"input_space must be 'position' or 'spectral'; got {input_space!r}"
+            )
+
+        if target_type == "matrix":
+            if target is None:
+                raise ValueError(
+                    "target_type='matrix' requires a (M, M) target covariance."
+                )
+            tgt = torch.as_tensor(target, dtype=torch.float32)
+            if tgt.dim() != 2 or tgt.shape[0] != tgt.shape[1]:
+                raise ValueError(
+                    f"matrix target must be (M, M); got shape {tuple(tgt.shape)}"
+                )
+            self.register_buffer("target_cov", tgt.detach().clone())
+            self.register_buffer(
+                "target_cov_frob",
+                torch.linalg.matrix_norm(tgt, ord="fro").detach().clone(),
+            )
+        elif target_type == "scalar":
+            if target is None:
+                raise ValueError("target_type='scalar' requires a target C value.")
+            self.register_buffer(
+                "target_C", torch.as_tensor(float(target), dtype=torch.float32)
+            )
+
+        self.target_type = target_type
+        self.input_space = input_space
+        self.eps = float(eps)
+        self.fft_norm = fft_norm
+        self.real_fft = bool(real_fft)
+        self.unbiased = bool(unbiased)
+
+    @classmethod
+    def from_data(
+        cls,
+        data: Tensor,
+        target_type: str = "matrix",
+        input_space: str = "position",
+        fft_norm: str = "ortho",
+        real_fft: bool = True,
+        unbiased: bool = True,
+        eps: float = 1e-12,
+    ) -> "CouplingLoss":
+        if target_type not in ("matrix", "scalar"):
+            raise ValueError(f"from_data does not support target_type={target_type!r}")
+        with torch.no_grad():
+            E = _spectral_energies(
+                data, input_space=input_space, fft_norm=fft_norm, real_fft=real_fft
+            )
+            cov = _batch_covariance(E, unbiased=unbiased)
+            if target_type == "matrix":
+                return cls(
+                    target_type="matrix", target=cov, input_space=input_space, eps=eps,
+                    fft_norm=fft_norm, real_fft=real_fft, unbiased=unbiased,
+                )
+            else:
+                C = _coupling_from_cov(cov, eps).item()
+                return cls(
+                    target_type="scalar", target=C, input_space=input_space, eps=eps,
+                    fft_norm=fft_norm, real_fft=real_fft, unbiased=unbiased,
+                )
+
+    def forward(self, x: Tensor) -> Tensor:
+        if x.dim() == 1:
+            x = x.unsqueeze(0)
+        E = _spectral_energies(x, self.input_space, self.fft_norm, self.real_fft)
+        cov = _batch_covariance(E, unbiased=self.unbiased)
+        if self.target_type == "matrix":
+            diff = cov - self.target_cov
+            num = torch.linalg.matrix_norm(diff, ord="fro").pow(2)
+            den = self.target_cov_frob.pow(2) + self.eps
+            return num / den
+        elif self.target_type == "scalar":
+            C = _coupling_from_cov(cov, self.eps)
+            return (C - self.target_C).pow(2)
+        else:
+            return _coupling_from_cov(cov, self.eps)
+
+    def extra_repr(self) -> str:
+        return (
+            f"target_type={self.target_type!r}, "
+            f"input_space={self.input_space!r}, fft_norm={self.fft_norm!r}"
+        )

couplnorm-0.1.0/src/couplnorm/models/__init__.py

@@ -0,0 +1,25 @@
+"""Baseline generative models for couplnorm demos and benchmarks.
+
+Every model is an ``nn.Module`` with a common interface:
+
+- ``fit(data)`` estimates parameters from a ``(B, N)`` batch of position-space
+  field configurations (a no-op / trainer depending on the model).
+- ``sample(n)`` returns ``(n, N)`` real position-space configurations.
+
+The models span the spectrum of joint-coupling fidelity:
+
+- :class:`FourierModel` assumes marginal independence of Fourier modes, so its
+  samples have C near zero regardless of the target. It is the "wrong by
+  construction" baseline that motivates the C diagnostic.
+- :class:`FullGaussian` matches the full second-order (covariance) structure of
+  the data but, being Gaussian, cannot reproduce genuine 4th-order coupling.
+- :class:`PCAModel` is a low-rank Gaussian; even weaker than FullGaussian.
+- :class:`MAF` is a masked autoregressive flow that can, in principle, capture
+  higher-order structure and drive C toward the target.
+"""
+from couplnorm.models.fourier import FourierModel
+from couplnorm.models.gaussian import FullGaussian
+from couplnorm.models.maf import MAF
+from couplnorm.models.pca import PCAModel
+
+__all__ = ["FourierModel", "FullGaussian", "PCAModel", "MAF"]