tensErr 0.4.0__tar.gz

tenserr-0.4.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Alexander Michel
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

tenserr-0.4.0/MANIFEST.in

@@ -0,0 +1,5 @@
+# Include tests with their shared fixtures and mathematical conventions in sdists.
+recursive-include tests *.py *.md
+
+# Exclude Jupyter-generated checkpoint copies from source distributions.
+global-exclude .ipynb_checkpoints/*

tenserr-0.4.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: tensErr
+Version: 0.4.0
+Summary: Torch implementation of dense UWerr gamma-method mean estimates.
+License-Expression: BSD-3-Clause
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch
+Dynamic: license-file
+
+[//]:<This document targets Github's markdown renderer; do not remove this comment.>
+# tensErr
+
+tensErr computes uncertainties for tensor-valued Markov chain Monte Carlo
+ensembles using the gamma method
+([Wolff, 2004](https://arxiv.org/abs/hep-lat/0306017),
+[Wolff, 2009](https://arxiv.org/pdf/0812.0677#page=19)).
+It works directly with PyTorch tensors, using the same interface on CPUs
+and accelerators.
+
+## Gamma method
+
+```python
+def gamma_method(
+    samples: torch.Tensor,
+    *,
+    gamma_method_s: float = 2.0,
+    accumulation_dtype: torch.dtype = torch.float64,
+    return_autocorrelation: bool = False,
+) -> GammaMethodEstimate: ...
+```
+
+`samples` may have shape $`(N,)`$ for one chain, $`(R,N)`$ for $`R`$ chains,
+or $`(\ast B,R,N)`$ for batched observables. Every chain must have the same
+retained length $`N\geq2`$.
+
+The default `gamma_method_s=2.0` selects the autocorrelation window
+automatically. Setting `gamma_method_s=0.0` disables autocorrelation analysis
+and reports the IID variance of the supplied entries.
+
+`gamma_method` returns a `GammaMethodEstimate` with the following fields:
+
+| Field | Meaning |
+| --- | --- |
+| `value` | Mean of the supplied samples |
+| `stderr` | Standard error of `value` |
+| `snr` | $`\lvert\mathrm{value}\rvert/\mathrm{stderr}`$ if $`\mathrm{stderr}\gt0`$; $`+\infty`$ if $`\mathrm{stderr}=0`$ |
+| `tau_int` | Integrated autocorrelation time $`\tau_{\mathrm{int}}`$ |
+| `C_f` | Summed autocovariance $`C_f=2\tau_{\mathrm{int}}v_f`$, where $`v_f=\Gamma_f(0)`$ |
+| `stderr_of_stderr` | Estimated uncertainty of `stderr` |
+| `window` | Selected maximum lag |
+| `sample_shapes` | Retained length of every replica |
+| `autocovariance` | $`\Gamma_f(t)`$ with shape $`(\ast B,\lfloor N/2\rfloor)`$ when requested; otherwise `None` |
+| `autocorrelation` | $`\rho_f(t)`$ with shape $`(\ast B,\lfloor N/2\rfloor)`$ when requested; otherwise `None` |
+
+`GammaMethodEstimate` objects representing the same observable but arising from independent samples can be averaged to produce one `GammaMethodEstimate` using the overloaded `+` and `sum` operators. Error analysis can thus be performed using chunking, without loading all the samples simultaneously into memory. Combining estimates concatenates `sample_shapes`; `stderr_of_stderr`, `window`,
+`autocovariance`, and `autocorrelation` are `None` on the result.
+
+## Efficient norm and error for autocorrelated vectors
+
+Documentation under construction.

tenserr-0.4.0/README.md

@@ -0,0 +1,51 @@
+[//]:<This document targets Github's markdown renderer; do not remove this comment.>
+# tensErr
+
+tensErr computes uncertainties for tensor-valued Markov chain Monte Carlo
+ensembles using the gamma method
+([Wolff, 2004](https://arxiv.org/abs/hep-lat/0306017),
+[Wolff, 2009](https://arxiv.org/pdf/0812.0677#page=19)).
+It works directly with PyTorch tensors, using the same interface on CPUs
+and accelerators.
+
+## Gamma method
+
+```python
+def gamma_method(
+    samples: torch.Tensor,
+    *,
+    gamma_method_s: float = 2.0,
+    accumulation_dtype: torch.dtype = torch.float64,
+    return_autocorrelation: bool = False,
+) -> GammaMethodEstimate: ...
+```
+
+`samples` may have shape $`(N,)`$ for one chain, $`(R,N)`$ for $`R`$ chains,
+or $`(\ast B,R,N)`$ for batched observables. Every chain must have the same
+retained length $`N\geq2`$.
+
+The default `gamma_method_s=2.0` selects the autocorrelation window
+automatically. Setting `gamma_method_s=0.0` disables autocorrelation analysis
+and reports the IID variance of the supplied entries.
+
+`gamma_method` returns a `GammaMethodEstimate` with the following fields:
+
+| Field | Meaning |
+| --- | --- |
+| `value` | Mean of the supplied samples |
+| `stderr` | Standard error of `value` |
+| `snr` | $`\lvert\mathrm{value}\rvert/\mathrm{stderr}`$ if $`\mathrm{stderr}\gt0`$; $`+\infty`$ if $`\mathrm{stderr}=0`$ |
+| `tau_int` | Integrated autocorrelation time $`\tau_{\mathrm{int}}`$ |
+| `C_f` | Summed autocovariance $`C_f=2\tau_{\mathrm{int}}v_f`$, where $`v_f=\Gamma_f(0)`$ |
+| `stderr_of_stderr` | Estimated uncertainty of `stderr` |
+| `window` | Selected maximum lag |
+| `sample_shapes` | Retained length of every replica |
+| `autocovariance` | $`\Gamma_f(t)`$ with shape $`(\ast B,\lfloor N/2\rfloor)`$ when requested; otherwise `None` |
+| `autocorrelation` | $`\rho_f(t)`$ with shape $`(\ast B,\lfloor N/2\rfloor)`$ when requested; otherwise `None` |
+
+`GammaMethodEstimate` objects representing the same observable but arising from independent samples can be averaged to produce one `GammaMethodEstimate` using the overloaded `+` and `sum` operators. Error analysis can thus be performed using chunking, without loading all the samples simultaneously into memory. Combining estimates concatenates `sample_shapes`; `stderr_of_stderr`, `window`,
+`autocovariance`, and `autocorrelation` are `None` on the result.
+
+## Efficient norm and error for autocorrelated vectors
+
+Documentation under construction.

tenserr-0.4.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tensErr"
+version = "0.4.0"
+description = "Torch implementation of dense UWerr gamma-method mean estimates."
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = ["torch"]
+
+[dependency-groups]
+dev = [
+  "pyerrors>=2.17",
+  "pytest>=8.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["tensErr*"]
+
+[tool.setuptools.package-data]
+tensErr = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tenserr-0.4.0/setup.cfg

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

tenserr-0.4.0/src/tensErr/__init__.py

@@ -0,0 +1,22 @@
+"""Public API for tensErr gamma-method and vector-norm estimates."""
+
+from tensErr.estimate import Estimate
+from tensErr.gamma_method import (
+    GammaMethodEstimate,
+    gamma_method,
+)
+from tensErr.vector_norm_gamma_method import (
+    VectorNormGammaMethodEstimate,
+    VectorNormGammaMethodHelper,
+    vector_norm_gamma_method,
+)
+
+# __all__ lists the stable public names exported by tensErr.
+__all__ = [
+    "Estimate",
+    "GammaMethodEstimate",
+    "VectorNormGammaMethodHelper",
+    "VectorNormGammaMethodEstimate",
+    "gamma_method",
+    "vector_norm_gamma_method",
+]

tenserr-0.4.0/src/tensErr/estimate.py

@@ -0,0 +1,33 @@
+"""Shared tensor estimate interface."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import torch
+
+
+@dataclass(frozen=True, slots=True)
+class Estimate:
+    """Estimate stores a tensor value and its nonnegative standard error.
+
+    ``stderr`` satisfies the invariant ``stderr >= 0``. The derived ``snr`` field
+    represents zero reported noise as positive infinity, independently of
+    ``value``.
+    """
+
+    value: torch.Tensor
+    stderr: torch.Tensor
+    snr: torch.Tensor = field(init=False)
+
+    def __post_init__(self) -> None:
+        """Derive ``snr`` once from ``value`` and ``stderr`` after initialization."""
+        object.__setattr__(
+            self,
+            "snr",
+            torch.where(
+                self.stderr > 0,
+                torch.abs(self.value) / self.stderr,
+                torch.inf,
+            ),
+        )

tenserr-0.4.0/src/tensErr/gamma_method.py

@@ -0,0 +1,237 @@
+"""Dense torch implementation of pyerrors-style gamma-method means."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+
+import torch
+
+from tensErr.estimate import Estimate
+
+
+@dataclass(frozen=True, slots=True)
+class GammaMethodEstimate(Estimate):
+    """Batch-shaped gamma-method estimates with per-replica sample lengths.
+
+    ``C_f`` is the windowed summed autocovariance ``2 * tau_int * v_f``,
+    where ``v_f`` is the lag-zero autocovariance.
+    """
+
+    tau_int: torch.Tensor
+    C_f: torch.Tensor
+    sample_shapes: torch.Tensor
+    stderr_of_stderr: torch.Tensor | None
+    window: torch.Tensor | None
+    autocovariance: torch.Tensor | None = None # Γ(t)
+    autocorrelation: torch.Tensor | None = None # ⍴(t)
+
+    def __add__(self, other: object) -> GammaMethodEstimate:
+        """Return the sample-count-weighted combination of ``self`` and ``other``."""
+        if not isinstance(other, GammaMethodEstimate) or type(self) is not type(other):
+            return NotImplemented
+
+        self_batch_shapes = (self.value.shape, self.stderr.shape, self.tau_int.shape)
+        other_batch_shapes = (other.value.shape, other.stderr.shape, other.tau_int.shape)
+        if len(set(self_batch_shapes + other_batch_shapes)) != 1:
+            raise ValueError(
+                "GammaMethodEstimate batch shapes must match for addition; "
+                f"got self={self_batch_shapes} and other={other_batch_shapes}"
+            )
+
+        self_sample_count = self.sample_shapes.sum().to(dtype=self.value.dtype)
+        other_sample_count = other.sample_shapes.sum().to(dtype=other.value.dtype)
+        total_sample_count = self_sample_count + other_sample_count
+        value = (
+            self_sample_count * self.value
+            + other_sample_count * other.value
+        ) / total_sample_count
+        stderr = torch.sqrt(
+            (self_sample_count * self.stderr).square()
+            + (other_sample_count * other.stderr).square()
+        ) / total_sample_count
+        tau_int = (
+            self_sample_count * self.tau_int
+            + other_sample_count * other.tau_int
+        ) / total_sample_count
+        C_f = (
+            self_sample_count * self.C_f
+            + other_sample_count * other.C_f
+        ) / total_sample_count
+        return replace(
+            self,
+            value=value,
+            stderr=stderr,
+            tau_int=tau_int,
+            C_f=C_f,
+            sample_shapes=torch.cat((self.sample_shapes, other.sample_shapes)),
+            stderr_of_stderr=None,
+            window=None,
+            autocovariance=None,
+            autocorrelation=None,
+            **self._addition_field_updates(other),
+        )
+
+    def _addition_field_updates(
+        self,
+        other: GammaMethodEstimate,
+    ) -> dict[str, object]:
+        """Return subclass field updates required when combining with ``other``."""
+        return {}
+
+    def __radd__(self, other: object) -> GammaMethodEstimate:
+        """Return ``self`` for Python ``sum``'s zero start or defer addition."""
+        if isinstance(other, int) and other == 0:
+            return self
+        if isinstance(other, GammaMethodEstimate):
+            return other.__add__(self)
+        return NotImplemented
+
+
+def _pooled_autocovariance(centered: torch.Tensor, w_max: int) -> torch.Tensor:
+    """Return pooled dense-chain autocovariance for lags [0, w_max).
+
+    Replica power spectra are summed before the inverse transform because its
+    linearity avoids materializing an inverse-FFT output for every replica.
+    """
+    sample_count = centered.shape[-1]
+    chain_count = centered.shape[-2]
+    padding = sample_count + w_max + (sample_count + w_max) % 2
+    spectrum = torch.fft.rfft(centered, n=padding, dim=-1)
+    pooled_power = spectrum.abs().square().sum(dim=-2)
+    lag_sums = torch.fft.irfft(pooled_power, n=padding, dim=-1)[..., :w_max]
+    pair_counts = torch.arange(
+        sample_count,
+        sample_count - w_max,
+        -1,
+        dtype=centered.dtype,
+        device=centered.device,
+    )
+    return lag_sums / (chain_count * pair_counts)
+
+
+def _safe_autocorrelation(autocovariance: torch.Tensor) -> torch.Tensor:
+    """Return autocorrelation while keeping zero-variance histories finite."""
+    variance = autocovariance[..., :1]
+    return torch.where(
+        variance != 0,
+        autocovariance / variance,
+        torch.zeros_like(autocovariance),
+    )
+
+
+def _tau_summation_history(autocorrelation: torch.Tensor) -> torch.Tensor:
+    """Return pyerrors cumulative tau_int history for autocorrelation lags."""
+    leading_half = torch.full_like(autocorrelation[..., :1], 0.5)
+    τ = torch.cumsum(
+        torch.cat((leading_half, autocorrelation[..., 1:]), dim=-1),
+        dim=-1,
+    )
+    return torch.maximum(τ, torch.full_like(τ, 0.5 + torch.finfo(τ.dtype).eps))
+
+
+def _automatic_window(
+    τ_history: torch.Tensor,
+    total_count: int,
+    gamma_method_s: float,
+) -> torch.Tensor:
+    """Return pyerrors automatic-window indices for τ_history and S."""
+    w_max = τ_history.shape[-1]
+    if w_max <= 1:
+        return torch.zeros(τ_history.shape[:-1], dtype=torch.long, device=τ_history.device)
+
+    candidates = torch.arange(1, w_max, dtype=τ_history.dtype, device=τ_history.device)
+    τ_tail = gamma_method_s / torch.log(
+        (2 * τ_history[..., 1:] + 1) / (2 * τ_history[..., 1:] - 1)
+    )
+    g_w = torch.exp(-candidates / τ_tail) - τ_tail / torch.sqrt(candidates * total_count)
+    below_zero = g_w < 0
+    below_zero[..., -1] = True
+    return below_zero.to(torch.long).argmax(dim=-1) + 1
+
+
+def _gather_lag(history: torch.Tensor, window: torch.Tensor) -> torch.Tensor:
+    """Return history entries selected by the per-batch window tensor."""
+    return torch.gather(history, dim=-1, index=window.unsqueeze(-1)).squeeze(-1)
+
+
+def gamma_method(
+    samples: torch.Tensor,
+    *,
+    gamma_method_s: float = 2.0,
+    accumulation_dtype: torch.dtype = torch.float64,
+    return_autocorrelation: bool = False,
+) -> GammaMethodEstimate:
+    """Estimate a dense-history mean and pyerrors-style gamma-method error.
+
+    samples is interpreted as (..., chains, samples), except a one-dimensional
+    input is treated as one unbatched chain. The returned value, stderr, tau_int,
+    C_f, stderr_of_stderr, and window tensors have the leading batch shape,
+    while the optional autocovariance and autocorrelation tensors have shape
+    (*batch_shape, N // 2).
+    """
+    x = samples.to(dtype=accumulation_dtype)
+    if x.ndim == 1:
+        x = x.unsqueeze(0)
+    sample_count = x.shape[-1]
+    chain_count = x.shape[-2]
+    total_count = chain_count * sample_count
+    w_max = sample_count // 2
+
+    value = x.mean(dim=(-2, -1))
+    centered = x - x.mean(dim=-1, keepdim=True)
+    autocovariance = _pooled_autocovariance(centered, w_max)
+    autocorrelation = _safe_autocorrelation(autocovariance)
+    v_f = autocovariance[..., 0]
+    zero_variance = v_f == 0
+
+    if gamma_method_s == 0.0:
+        window = torch.zeros_like(v_f, dtype=torch.long)
+        tau_int = torch.full_like(v_f, 0.5)
+        C_f = 2 * tau_int * v_f
+        stderr = torch.sqrt(C_f / (total_count - 1))
+        stderr_of_stderr = stderr * torch.sqrt(
+            torch.as_tensor(0.5 / total_count, dtype=x.dtype, device=x.device)
+        )
+    else:
+        τ_history = _tau_summation_history(autocorrelation)
+        window = _automatic_window(τ_history, total_count, gamma_method_s)
+        window_float = window.to(dtype=x.dtype)
+        τ_window = _gather_lag(τ_history, window)
+        bias = (1 + (2 * window_float + 1) / total_count) / (1 + 1 / total_count)
+        tau_int = τ_window * bias
+        C_f = 2 * tau_int * v_f
+        stderr = torch.sqrt(C_f * (1 + 1 / total_count) / total_count)
+        stderr_of_stderr = stderr * torch.sqrt((window_float + 0.5) / total_count)
+
+    tau_int = torch.where(zero_variance, torch.full_like(tau_int, 0.5), tau_int)
+    stderr = torch.where(zero_variance, torch.zeros_like(stderr), stderr)
+    stderr_of_stderr = torch.where(
+        zero_variance,
+        torch.zeros_like(stderr_of_stderr),
+        stderr_of_stderr,
+    )
+    window = torch.where(zero_variance, torch.zeros_like(window), window)
+
+    if return_autocorrelation:
+        returned_autocovariance = autocovariance
+        returned_autocorrelation = autocorrelation
+    else:
+        returned_autocovariance = None
+        returned_autocorrelation = None
+
+    return GammaMethodEstimate(
+        value=value,
+        stderr=stderr,
+        tau_int=tau_int,
+        C_f=C_f,
+        sample_shapes=torch.full(
+            (chain_count,),
+            sample_count,
+            dtype=torch.long,
+            device=x.device,
+        ),
+        stderr_of_stderr=stderr_of_stderr,
+        window=window,
+        autocovariance=returned_autocovariance,
+        autocorrelation=returned_autocorrelation,
+    )

tenserr-0.4.0/src/tensErr/py.typed

@@ -0,0 +1 @@
+