pimf 0.1.0__tar.gz

pimf-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+      - run: uv run --frozen python -m pytest -q
+      - run: uv build
+      - uses: actions/upload-artifact@v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # Must match the environment name configured on the PyPI trusted publisher.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8.0.1
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

pimf-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.DS_Store

pimf-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Kuziuk
+
+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.

pimf-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: pimf
+Version: 0.1.0
+Summary: Intrinsic multiscale filtering (IMF) for 1-D signals: linear and robust decompositions.
+Project-URL: Homepage, https://github.com/mkuziuk/pimf
+Project-URL: Source, https://github.com/mkuziuk/pimf
+Project-URL: Issues, https://github.com/mkuziuk/pimf/issues
+Author: Mikhail Kuziuk
+License-Expression: MIT
+License-File: LICENSE
+Keywords: decomposition,m-estimator,robust-statistics,signal-processing,smoothing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.22
+Description-Content-Type: text/markdown
+
+# pimf
+
+Intrinsic multiscale filtering (IMF) for one-dimensional signals: a **linear**
+decomposition (local weighted mean) and a **robust** variant that replaces the
+mean with a smooth robust location fit solved by gradient descent.
+
+Both are the same algorithm. Starting from `r_1 = y`, each stage smooths the
+current residual with a local M-estimator and passes on what is left:
+
+```
+S_k = argmin_x  sum_u  w_{t,u} * rho(r_k(u) - x)        (per position t)
+r_{k+1} = r_k - S_k
+```
+
+The signal decomposes exactly: `y = S_1 + ... + S_K + r_{K+1}`. The only
+difference between the variants is the contrast `rho`:
+
+- **Quadratic** `rho(r) = r^2/2` — closed form, the kernel-weighted local mean
+  (the linear IMF).
+- **SmoothAbs** `rho_h(r) = r*erf(r/(sqrt(2)h)) + sqrt(2/pi)*h*exp(-r^2/(2h^2))`
+  — a smoothed absolute value with bounded score `psi_h(r) = erf(r/(sqrt(2)h))`,
+  solved by clipped gradient descent (the robust IMF). Large contaminated
+  observations have bounded influence.
+
+The library packages the algorithms validated in the IMF research project
+(`Projects/imf`) and reproduces its numerics — the robust decomposition is
+bit-identical to the reference notebook on the research example.
+
+## Install
+
+```bash
+pip install pimf
+```
+
+Requires Python >= 3.10. NumPy is the only dependency.
+
+For development, clone the repo and install in editable mode:
+
+```bash
+pip install -e .
+```
+
+## Quickstart
+
+```python
+import numpy as np
+import pimf
+
+t = np.linspace(0.0, 1.0, 1000)
+y = (
+    np.sin(2 * np.pi * t)
+    + 0.25 * np.sin(12 * np.pi * t)
+    + np.random.default_rng(0).normal(0, 0.1, 1000)
+)
+
+linear = pimf.linear_imf(y)  # quadratic contrast, closed form
+robust = pimf.robust_imf(y, h=0.2)  # smooth-abs contrast, h ~ 2 * noise sigma
+
+robust.imfs  # (K, n) array of components, coarsest first
+robust.residual  # (n,) final residual
+robust.stages  # per-stage diagnostics (window size, GD iterations, ...)
+robust.reconstruction  # imfs.sum(axis=0) + residual == y to ~1e-15
+```
+
+The general entry point is `pimf.imf(y, window_sizes=..., contrast=..., kernel=...,
+boundary=...)`; `linear_imf` and `robust_imf` are one-line wrappers around it.
+
+## Concepts
+
+**Window schedule.** `make_window_schedule(n)` generates the per-stage window
+sizes: odd, strictly decreasing, starting at about `n/2` and shrinking
+geometrically by `sqrt(2)` down to a floor of 31. Pass `window_sizes=` to
+override. Windows must be odd.
+
+**Kernel.** The window weights come from a kernel profile `k(u)` on `[-1, 1]`.
+The default `SquaredTriangle` uses `k(u) = 0.75 * (1 - |u|)^2` — the square of
+the triangular kernel. (The research project and IMF.pdf call this kernel
+"Epanechnikov"; that is a misnomer — the classical Epanechnikov kernel is
+`(3/4)(1 - u^2)` — so this library names it for what it is.) Endpoint weights
+are exactly zero, and weights are normalized to sum to one.
+
+**Contrast.** A contrast supplies the loss `rho` (via `__call__`), its
+derivative `psi` (the score), and `curvature()` — an upper bound on `rho''`
+that sets the stable gradient step `0.95 / curvature()`. A contrast with a
+closed-form minimizer can provide `solve(windows, weights)`, which the driver
+uses instead of gradient descent (that is what makes `Quadratic` the fast
+linear path). For `SmoothAbs(h)`, `h ~ 2 * sigma` of the Gaussian noise is the
+research-validated choice: smaller `h` behaves like a running median, larger
+`h` like the local mean.
+
+**Boundary.** `boundary="wrap"` (circular) is the default and the setting the
+linear-operator theory of the research project assumes; it is passed straight
+to `np.pad`, so `"reflect"` and `"edge"` also work.
+
+## Extending
+
+Custom contrast — one small class:
+
+```python
+import numpy as np
+import pimf
+
+
+class Huber(pimf.Contrast):
+    def __init__(self, delta):
+        self.delta = delta
+
+    def __call__(self, r):
+        a = np.abs(r)
+        return np.where(a <= self.delta, 0.5 * r**2, self.delta * (a - 0.5 * self.delta))
+
+    def psi(self, r):
+        return np.clip(r, -self.delta, self.delta)
+
+    def curvature(self):
+        return 1.0
+
+
+result = pimf.imf(y, contrast=Huber(0.3))
+```
+
+Custom kernel — one line:
+
+```python
+class Triangle(pimf.Kernel):
+    def profile(self, u):
+        return 1.0 - np.abs(u)
+
+
+result = pimf.imf(y, kernel=Triangle())
+```
+
+## Numerical guarantees
+
+- Exact reconstruction: `imfs.sum(axis=0) + residual` matches the input to
+  ~1e-15 (float rounding only).
+- Deterministic: no threading, no hidden state; the same input always gives
+  the same output.
+- Research parity (verified by cross-check against the reference notebook on
+  the seed-777 example): kernel weights, the erf approximation
+  (Abramowitz–Stegun 7.1.26 — deliberately kept instead of SciPy), signal
+  generation, and the full robust decomposition are bit-identical; the linear
+  path matches the loop-based notebook to ~2e-15 (float summation order — it
+  is bit-identical to the vectorized `windows @ weights` notebooks).
+
+## Development
+
+```bash
+uv sync                  # or: pip install -e . && pip install pytest ruff
+python -m pytest
+ruff check . && ruff format --check .
+```
+
+See [AGENTS.md](AGENTS.md) for the project's code style and hard rules.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pimf-0.1.0/README.md

@@ -0,0 +1,158 @@
+# pimf
+
+Intrinsic multiscale filtering (IMF) for one-dimensional signals: a **linear**
+decomposition (local weighted mean) and a **robust** variant that replaces the
+mean with a smooth robust location fit solved by gradient descent.
+
+Both are the same algorithm. Starting from `r_1 = y`, each stage smooths the
+current residual with a local M-estimator and passes on what is left:
+
+```
+S_k = argmin_x  sum_u  w_{t,u} * rho(r_k(u) - x)        (per position t)
+r_{k+1} = r_k - S_k
+```
+
+The signal decomposes exactly: `y = S_1 + ... + S_K + r_{K+1}`. The only
+difference between the variants is the contrast `rho`:
+
+- **Quadratic** `rho(r) = r^2/2` — closed form, the kernel-weighted local mean
+  (the linear IMF).
+- **SmoothAbs** `rho_h(r) = r*erf(r/(sqrt(2)h)) + sqrt(2/pi)*h*exp(-r^2/(2h^2))`
+  — a smoothed absolute value with bounded score `psi_h(r) = erf(r/(sqrt(2)h))`,
+  solved by clipped gradient descent (the robust IMF). Large contaminated
+  observations have bounded influence.
+
+The library packages the algorithms validated in the IMF research project
+(`Projects/imf`) and reproduces its numerics — the robust decomposition is
+bit-identical to the reference notebook on the research example.
+
+## Install
+
+```bash
+pip install pimf
+```
+
+Requires Python >= 3.10. NumPy is the only dependency.
+
+For development, clone the repo and install in editable mode:
+
+```bash
+pip install -e .
+```
+
+## Quickstart
+
+```python
+import numpy as np
+import pimf
+
+t = np.linspace(0.0, 1.0, 1000)
+y = (
+    np.sin(2 * np.pi * t)
+    + 0.25 * np.sin(12 * np.pi * t)
+    + np.random.default_rng(0).normal(0, 0.1, 1000)
+)
+
+linear = pimf.linear_imf(y)  # quadratic contrast, closed form
+robust = pimf.robust_imf(y, h=0.2)  # smooth-abs contrast, h ~ 2 * noise sigma
+
+robust.imfs  # (K, n) array of components, coarsest first
+robust.residual  # (n,) final residual
+robust.stages  # per-stage diagnostics (window size, GD iterations, ...)
+robust.reconstruction  # imfs.sum(axis=0) + residual == y to ~1e-15
+```
+
+The general entry point is `pimf.imf(y, window_sizes=..., contrast=..., kernel=...,
+boundary=...)`; `linear_imf` and `robust_imf` are one-line wrappers around it.
+
+## Concepts
+
+**Window schedule.** `make_window_schedule(n)` generates the per-stage window
+sizes: odd, strictly decreasing, starting at about `n/2` and shrinking
+geometrically by `sqrt(2)` down to a floor of 31. Pass `window_sizes=` to
+override. Windows must be odd.
+
+**Kernel.** The window weights come from a kernel profile `k(u)` on `[-1, 1]`.
+The default `SquaredTriangle` uses `k(u) = 0.75 * (1 - |u|)^2` — the square of
+the triangular kernel. (The research project and IMF.pdf call this kernel
+"Epanechnikov"; that is a misnomer — the classical Epanechnikov kernel is
+`(3/4)(1 - u^2)` — so this library names it for what it is.) Endpoint weights
+are exactly zero, and weights are normalized to sum to one.
+
+**Contrast.** A contrast supplies the loss `rho` (via `__call__`), its
+derivative `psi` (the score), and `curvature()` — an upper bound on `rho''`
+that sets the stable gradient step `0.95 / curvature()`. A contrast with a
+closed-form minimizer can provide `solve(windows, weights)`, which the driver
+uses instead of gradient descent (that is what makes `Quadratic` the fast
+linear path). For `SmoothAbs(h)`, `h ~ 2 * sigma` of the Gaussian noise is the
+research-validated choice: smaller `h` behaves like a running median, larger
+`h` like the local mean.
+
+**Boundary.** `boundary="wrap"` (circular) is the default and the setting the
+linear-operator theory of the research project assumes; it is passed straight
+to `np.pad`, so `"reflect"` and `"edge"` also work.
+
+## Extending
+
+Custom contrast — one small class:
+
+```python
+import numpy as np
+import pimf
+
+
+class Huber(pimf.Contrast):
+    def __init__(self, delta):
+        self.delta = delta
+
+    def __call__(self, r):
+        a = np.abs(r)
+        return np.where(a <= self.delta, 0.5 * r**2, self.delta * (a - 0.5 * self.delta))
+
+    def psi(self, r):
+        return np.clip(r, -self.delta, self.delta)
+
+    def curvature(self):
+        return 1.0
+
+
+result = pimf.imf(y, contrast=Huber(0.3))
+```
+
+Custom kernel — one line:
+
+```python
+class Triangle(pimf.Kernel):
+    def profile(self, u):
+        return 1.0 - np.abs(u)
+
+
+result = pimf.imf(y, kernel=Triangle())
+```
+
+## Numerical guarantees
+
+- Exact reconstruction: `imfs.sum(axis=0) + residual` matches the input to
+  ~1e-15 (float rounding only).
+- Deterministic: no threading, no hidden state; the same input always gives
+  the same output.
+- Research parity (verified by cross-check against the reference notebook on
+  the seed-777 example): kernel weights, the erf approximation
+  (Abramowitz–Stegun 7.1.26 — deliberately kept instead of SciPy), signal
+  generation, and the full robust decomposition are bit-identical; the linear
+  path matches the loop-based notebook to ~2e-15 (float summation order — it
+  is bit-identical to the vectorized `windows @ weights` notebooks).
+
+## Development
+
+```bash
+uv sync                  # or: pip install -e . && pip install pytest ruff
+python -m pytest
+ruff check . && ruff format --check .
+```
+
+See [AGENTS.md](AGENTS.md) for the project's code style and hard rules.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pimf-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pimf"
+version = "0.1.0"
+description = "Intrinsic multiscale filtering (IMF) for 1-D signals: linear and robust decompositions."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Mikhail Kuziuk" }]
+keywords = ["signal-processing", "smoothing", "robust-statistics", "m-estimator", "decomposition"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = ["numpy>=1.22"]
+
+[project.urls]
+Homepage = "https://github.com/mkuziuk/pimf"
+Source = "https://github.com/mkuziuk/pimf"
+Issues = "https://github.com/mkuziuk/pimf/issues"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["AGENTS.md", "CLAUDE.md", "uv.lock", ".gitignore"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "NPY"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pimf-0.1.0/src/pimf/__init__.py

@@ -0,0 +1,23 @@
+"""Intrinsic multiscale filtering (IMF) for 1-D signals."""
+
+from .contrasts import Contrast, Quadratic, SmoothAbs
+from .decompose import IMFResult, StageInfo, imf, linear_imf, robust_imf
+from .kernels import Kernel, SquaredTriangle
+from .schedule import make_window_schedule
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Contrast",
+    "IMFResult",
+    "Kernel",
+    "Quadratic",
+    "SmoothAbs",
+    "SquaredTriangle",
+    "StageInfo",
+    "__version__",
+    "imf",
+    "linear_imf",
+    "make_window_schedule",
+    "robust_imf",
+]

pimf-0.1.0/src/pimf/_erf.py

@@ -0,0 +1,28 @@
+"""Error function approximation shared by the contrast functions.
+
+Abramowitz & Stegun formula 7.1.26 (max abs error ~1.5e-7), kept instead of
+scipy.special.erf so results match the IMF research notebooks bit-for-bit.
+"""
+
+import numpy as np
+
+SQRT_2 = np.sqrt(2.0)
+SQRT_2_OVER_PI = np.sqrt(2.0 / np.pi)
+
+
+def erf_approx(x):
+    """Vectorized Abramowitz-Stegun approximation to erf(x)."""
+    x = np.asarray(x, dtype=float)
+    sign = np.sign(x)
+    ax = np.abs(x)
+
+    p = 0.3275911
+    a1 = 0.254829592
+    a2 = -0.284496736
+    a3 = 1.421413741
+    a4 = -1.453152027
+    a5 = 1.061405429
+
+    z = 1.0 / (1.0 + p * ax)
+    poly = ((((a5 * z + a4) * z + a3) * z + a2) * z + a1) * z
+    return sign * (1.0 - poly * np.exp(-(ax**2)))

pimf-0.1.0/src/pimf/contrasts.py

@@ -0,0 +1,71 @@
+"""Contrast functions for the local location fits.
+
+A contrast supplies the loss rho (via __call__), its derivative psi (the
+score), and an upper bound on rho'' (curvature) that sets a stable gradient
+step. A contrast with a closed-form minimizer may also provide
+solve(windows, weights); the decomposition then skips gradient descent.
+"""
+
+import numpy as np
+
+from ._erf import SQRT_2, SQRT_2_OVER_PI, erf_approx
+
+
+class Contrast:
+    """Base contrast. Subclass and implement __call__, psi, and curvature."""
+
+    def __call__(self, r):
+        """Loss rho(r), vectorized."""
+        raise NotImplementedError
+
+    def psi(self, r):
+        """Score rho'(r), vectorized; drives the gradient-descent update."""
+        raise NotImplementedError
+
+    def curvature(self):
+        """Upper bound on rho''; the gradient step size is 0.95 / curvature()."""
+        raise NotImplementedError
+
+
+class Quadratic(Contrast):
+    """rho(r) = r^2 / 2: the local weighted mean, i.e. the linear IMF."""
+
+    def __call__(self, r):
+        return 0.5 * np.asarray(r, dtype=float) ** 2
+
+    def psi(self, r):
+        return np.asarray(r, dtype=float)
+
+    def curvature(self):
+        return 1.0
+
+    def solve(self, windows, weights):
+        """Closed-form minimizer: the weighted mean of each window row."""
+        return windows @ weights
+
+
+class SmoothAbs(Contrast):
+    """Smoothed absolute value: |r| convolved with a N(0, h^2) density.
+
+    rho_h(r) = r * erf(r / (sqrt(2) h)) + sqrt(2 / pi) * h * exp(-r^2 / (2 h^2))
+    psi_h(r) = erf(r / (sqrt(2) h)), bounded in [-1, 1].
+
+    h > 0 controls the transition from quadratic near zero to |r| in the
+    tails: smaller h is more median-like, larger h closer to the local mean.
+    h ~ 2 * noise sigma is the research-validated default choice.
+    """
+
+    def __init__(self, h):
+        if h <= 0:
+            raise ValueError("h must be positive")
+        self.h = float(h)
+
+    def __call__(self, r):
+        r = np.asarray(r, dtype=float)
+        return r * self.psi(r) + SQRT_2_OVER_PI * self.h * np.exp(-0.5 * (r / self.h) ** 2)
+
+    def psi(self, r):
+        return erf_approx(np.asarray(r, dtype=float) / (SQRT_2 * self.h))
+
+    def curvature(self):
+        return SQRT_2_OVER_PI / self.h

pimf-0.1.0/src/pimf/decompose.py

@@ -0,0 +1,138 @@
+"""Intrinsic multiscale filtering: the decomposition driver."""
+
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.lib.stride_tricks import sliding_window_view
+
+from .contrasts import Quadratic, SmoothAbs
+from .kernels import SquaredTriangle
+from .schedule import make_window_schedule
+
+
+@dataclass(frozen=True)
+class StageInfo:
+    """Per-stage diagnostics; the closed-form path reports iterations=1 and
+    final_max_delta=nan."""
+
+    stage: int
+    window_size: int
+    iterations: int
+    final_max_delta: float
+
+
+@dataclass
+class IMFResult:
+    """Decomposition output; y == imfs.sum(axis=0) + residual up to float rounding."""
+
+    imfs: np.ndarray
+    residual: np.ndarray
+    stages: list[StageInfo]
+    window_sizes: list[int]
+
+    @property
+    def reconstruction(self):
+        return self.imfs.sum(axis=0) + self.residual
+
+
+def _gd_fit_windows(windows, weights, contrast, max_iter, tol):
+    """Minimize sum_u w_u * rho(window_u - x) per row by clipped gradient descent.
+
+    Port of robust_gd_fit_windows from the research notebooks, generalized to
+    any contrast via psi and curvature. Returns (x, iterations, max_delta).
+    """
+    weights = weights / weights.sum()
+    row_weights = weights.reshape(1, -1)
+
+    x = np.median(windows, axis=1)
+    lower = windows.min(axis=1)
+    upper = windows.max(axis=1)
+
+    # The weighted score is Lipschitz with constant curvature() because the
+    # weights are normalized, so this step size keeps the iteration stable.
+    step = 0.95 / contrast.curvature()
+
+    iterations = 0
+    max_delta = float("nan")
+    for _ in range(max_iter):
+        local_score = np.sum(row_weights * contrast.psi(windows - x[:, None]), axis=1)
+        x_next = np.clip(x + step * local_score, lower, upper)
+        max_delta = float(np.max(np.abs(x_next - x)))
+        x = x_next
+        iterations += 1
+        if max_delta <= tol * (1.0 + float(np.max(np.abs(x)))):
+            break
+
+    return x, iterations, max_delta
+
+
+def _smooth_stage(residual, window_size, kernel, contrast, boundary, max_iter, tol):
+    """One smoothing pass: fit the local location at every position."""
+    weights = kernel.weights(window_size)
+    radius = window_size // 2
+    padded = np.pad(residual, pad_width=radius, mode=boundary)
+    windows = sliding_window_view(padded, window_size)
+
+    solve = getattr(contrast, "solve", None)
+    if callable(solve):
+        return solve(windows, weights), 1, float("nan")
+    return _gd_fit_windows(windows, weights, contrast, max_iter, tol)
+
+
+def imf(y, window_sizes=None, contrast=None, kernel=None, boundary="wrap", max_iter=60, tol=1e-6):
+    """Decompose a 1-D signal into multiscale components plus a residual.
+
+    At each stage the current residual is smoothed by a local M-estimator
+    defined by kernel and contrast; the smooth becomes that stage's component
+    and the recursion continues on what is left:
+    r_1 = y, S_k = smooth(r_k), r_{k+1} = r_k - S_k.
+
+    Defaults: window_sizes = make_window_schedule(len(y)), contrast =
+    Quadratic() (the linear IMF), kernel = SquaredTriangle(). boundary is
+    passed to np.pad ("wrap", "reflect", "edge", ...). max_iter and tol apply
+    only when the contrast has no closed-form solve.
+    """
+    y = np.asarray(y, dtype=float)
+    if y.ndim != 1:
+        raise ValueError("y must be one-dimensional")
+    if len(y) == 0:
+        raise ValueError("y must not be empty")
+
+    if window_sizes is None:
+        window_sizes = make_window_schedule(len(y))
+    window_sizes = [int(size) for size in window_sizes]
+    if contrast is None:
+        contrast = Quadratic()
+    if kernel is None:
+        kernel = SquaredTriangle()
+
+    residual = y.copy()
+    imfs = []
+    stages = []
+    for stage, window_size in enumerate(window_sizes, start=1):
+        component, iterations, final_max_delta = _smooth_stage(
+            residual, window_size, kernel, contrast, boundary, max_iter, tol
+        )
+        imfs.append(component)
+        residual = residual - component
+        stages.append(StageInfo(stage, window_size, iterations, final_max_delta))
+
+    return IMFResult(np.array(imfs), residual, stages, window_sizes)
+
+
+def linear_imf(y, window_sizes=None, kernel=None, boundary="wrap"):
+    """imf() with the Quadratic contrast: the linear (weighted local mean) IMF."""
+    return imf(y, window_sizes=window_sizes, contrast=Quadratic(), kernel=kernel, boundary=boundary)
+
+
+def robust_imf(y, h, window_sizes=None, kernel=None, boundary="wrap", max_iter=60, tol=1e-6):
+    """imf() with the SmoothAbs(h) contrast; h ~ 2 * noise sigma works well."""
+    return imf(
+        y,
+        window_sizes=window_sizes,
+        contrast=SmoothAbs(h),
+        kernel=kernel,
+        boundary=boundary,
+        max_iter=max_iter,
+        tol=tol,
+    )

pimf-0.1.0/src/pimf/kernels.py

@@ -0,0 +1,54 @@
+"""Kernel window weights for the local fits.
+
+A kernel is defined by its profile k(u) on [-1, 1]; the base class turns the
+profile into a normalized, symmetric weight vector for an odd window size.
+"""
+
+import numpy as np
+
+
+class Kernel:
+    """Base kernel. Subclass and implement profile(u).
+
+    profile(u) must be vectorized and nonnegative on [-1, 1]; any constant
+    factor cancels under normalization.
+    """
+
+    def profile(self, u):
+        """Unnormalized kernel profile k(u) on [-1, 1]."""
+        raise NotImplementedError
+
+    def weights(self, window_size):
+        """Normalized weight vector for an odd window size."""
+        if window_size % 2 == 0:
+            raise ValueError("window_size must be odd")
+
+        radius = window_size // 2
+        if radius == 0:
+            return np.array([1.0])
+
+        offsets = np.arange(-radius, radius + 1)
+        u = offsets / radius
+        weights = np.asarray(self.profile(u), dtype=float)
+        if np.any(weights < 0):
+            raise ValueError("kernel profile must be nonnegative")
+        total = weights.sum()
+        if total <= 0:
+            raise ValueError("kernel weights must have positive sum")
+        return weights / total
+
+    __call__ = weights
+
+
+class SquaredTriangle(Kernel):
+    """Squared triangular profile k(u) = 0.75 * (1 - |u|)^2.
+
+    The default kernel of the IMF research project, where it is called
+    "Epanechnikov" — a misnomer: the classical Epanechnikov kernel is
+    (3/4)(1 - u^2). The 0.75 factor cancels under normalization and is kept
+    for parity with the research code. The endpoint weights (|u| = 1) are
+    exactly zero.
+    """
+
+    def profile(self, u):
+        return 0.75 * np.maximum(0.0, 1.0 - np.abs(u)) ** 2

pimf-0.1.0/src/pimf/schedule.py

@@ -0,0 +1,65 @@
+"""Geometric window-size schedule for the IMF decomposition.
+
+Faithful port of make_window_schedule from the IMF research notebooks:
+odd, strictly decreasing sizes from about n/2 down to min_window_size,
+shrinking by factor each stage.
+"""
+
+import numpy as np
+
+from ._erf import SQRT_2
+
+
+def odd_ceiling(value):
+    """Smallest odd integer >= ceil(value), at least 1."""
+    size = int(np.ceil(value))
+    if size % 2 == 0:
+        size += 1
+    return max(1, size)
+
+
+def nearest_odd(value):
+    """Odd integer nearest to value (ties round down), at least 1."""
+    rounded = int(np.round(value))
+    if rounded % 2 == 1:
+        return max(1, rounded)
+
+    lower = max(1, rounded - 1)
+    upper = rounded + 1
+    if abs(value - lower) <= abs(upper - value):
+        return lower
+    return upper
+
+
+def make_window_schedule(n, factor=SQRT_2, min_window_size=31):
+    """Window sizes for a length-n signal: first = odd_ceiling(n / 2), then
+    geometric shrink by factor, all odd, strictly decreasing, floored at
+    min_window_size."""
+    if n <= 0:
+        raise ValueError("n must be positive")
+    if factor <= 1:
+        raise ValueError("factor must be larger than 1")
+
+    first = odd_ceiling(n / 2)
+    if first > n:
+        first = n if n % 2 == 1 else n - 1
+
+    min_size = nearest_odd(min_window_size)
+    if min_size > first:
+        return [first]
+
+    sizes = [first]
+    current = first
+
+    while current > min_size:
+        candidate = nearest_odd(current / factor)
+        candidate = min(candidate, current - 2)
+        if candidate % 2 == 0:
+            candidate -= 1
+        if candidate < min_size:
+            candidate = min_size
+
+        sizes.append(candidate)
+        current = candidate
+
+    return sizes

pimf-0.1.0/tests/conftest.py

@@ -0,0 +1,25 @@
+"""Test fixtures ported from the IMF research notebooks.
+
+The rng draw order in generate_observation (normal, random, exponential)
+matches the notebooks so seeded observations reproduce bit-for-bit.
+"""
+
+import numpy as np
+
+
+def gen_signal(t):
+    """Deterministic 4-component test signal from the research notebooks."""
+    slow = 0.6 * np.sin(2 * np.pi * t)
+    medium = 0.25 * np.sin(12 * np.pi * t)
+    bump = 0.8 * np.exp(-((t - 0.55) ** 2) / (2 * 0.015**2))
+    trend = 0.5 * (t - 0.5)
+    return slow + medium + bump + trend
+
+
+def generate_observation(x, sigma, contamination_prob, contamination_scale, rng):
+    """Gaussian noise plus one-sided exponential contamination."""
+    gaussian_noise = rng.normal(loc=0.0, scale=sigma, size=len(x))
+    contamination_mask = rng.random(len(x)) < contamination_prob
+    exponential_noise = rng.exponential(scale=contamination_scale, size=len(x))
+    contamination = contamination_mask * exponential_noise
+    return x + gaussian_noise + contamination

pimf-0.1.0/tests/test_contrasts.py

@@ -0,0 +1,65 @@
+import numpy as np
+import pytest
+
+from pimf import Quadratic, SmoothAbs
+from pimf._erf import SQRT_2_OVER_PI
+
+
+def test_smooth_abs_requires_positive_h():
+    with pytest.raises(ValueError):
+        SmoothAbs(0.0)
+    with pytest.raises(ValueError):
+        SmoothAbs(-1.0)
+
+
+def test_smooth_abs_score_is_bounded():
+    contrast = SmoothAbs(0.4)
+    r = np.linspace(-1e6, 1e6, 10001)
+    assert np.all(np.abs(contrast.psi(r)) <= 1.0)
+
+
+def test_smooth_abs_symmetry():
+    contrast = SmoothAbs(0.4)
+    r = np.linspace(0.0, 10.0, 1001)
+    assert np.array_equal(contrast.psi(-r), -contrast.psi(r))
+    assert np.allclose(contrast(-r), contrast(r), atol=1e-15)
+
+
+def test_smooth_abs_at_zero():
+    h = 0.7
+    assert SmoothAbs(h)(0.0) == SQRT_2_OVER_PI * h
+
+
+def test_smooth_abs_approaches_abs_in_tails():
+    h = 0.4
+    r = 50.0 * h
+    assert abs(SmoothAbs(h)(r) - r) / r < 1e-6
+
+
+def test_smooth_abs_curvature():
+    h = 0.4
+    assert SmoothAbs(h).curvature() == SQRT_2_OVER_PI / h
+
+
+def test_quadratic():
+    contrast = Quadratic()
+    r = np.linspace(-3.0, 3.0, 101)
+    assert np.array_equal(contrast.psi(r), r)
+    assert contrast.curvature() == 1.0
+    assert np.array_equal(contrast(r), 0.5 * r**2)
+
+
+def test_quadratic_solve_is_weighted_mean():
+    rng = np.random.default_rng(0)
+    windows = rng.normal(size=(7, 5))
+    weights = np.array([0.0, 0.25, 0.5, 0.25, 0.0])
+    assert np.array_equal(Quadratic().solve(windows, weights), windows @ weights)
+
+
+@pytest.mark.parametrize("contrast", [Quadratic(), SmoothAbs(0.5)])
+def test_psi_is_derivative_of_rho(contrast):
+    # Template consistency check for any contrast implementation.
+    r = np.linspace(-3.0, 3.0, 61)
+    eps = 1e-6
+    finite_difference = (contrast(r + eps) - contrast(r - eps)) / (2 * eps)
+    assert np.max(np.abs(finite_difference - contrast.psi(r))) < 1e-4

pimf-0.1.0/tests/test_decompose.py

@@ -0,0 +1,150 @@
+import numpy as np
+import pytest
+
+from pimf import Quadratic, imf, linear_imf, robust_imf
+from pimf.decompose import _gd_fit_windows
+from pimf.kernels import SquaredTriangle
+
+
+class QuadraticViaGD(Quadratic):
+    """Quadratic contrast with the closed form disabled, to exercise the GD path."""
+
+    solve = None
+
+
+@pytest.fixture
+def noisy_signal():
+    rng = np.random.default_rng(42)
+    t = np.linspace(0.0, 1.0, 512)
+    return np.sin(2 * np.pi * t) + 0.3 * np.sin(14 * np.pi * t) + rng.normal(0.0, 0.2, 512)
+
+
+def test_reconstruction_linear(noisy_signal):
+    result = linear_imf(noisy_signal)
+    assert np.max(np.abs(result.reconstruction - noisy_signal)) < 1e-10
+
+
+def test_reconstruction_robust(noisy_signal):
+    result = robust_imf(noisy_signal, h=0.4)
+    assert np.max(np.abs(result.reconstruction - noisy_signal)) < 1e-10
+
+
+def test_shapes_and_stage_info(noisy_signal):
+    result = robust_imf(noisy_signal, h=0.4, window_sizes=[151, 75, 31])
+    assert result.imfs.shape == (3, len(noisy_signal))
+    assert result.residual.shape == (len(noisy_signal),)
+    assert result.window_sizes == [151, 75, 31]
+    assert np.all(np.isfinite(result.imfs))
+    assert np.all(np.isfinite(result.residual))
+    for k, info in enumerate(result.stages, start=1):
+        assert info.stage == k
+        assert 1 <= info.iterations <= 60
+        assert np.isfinite(info.final_max_delta)
+
+
+def test_linear_stage_info(noisy_signal):
+    result = linear_imf(noisy_signal, window_sizes=[63, 31])
+    for info in result.stages:
+        assert info.iterations == 1
+        assert np.isnan(info.final_max_delta)
+
+
+def test_linearity_of_linear_imf():
+    rng = np.random.default_rng(7)
+    x = rng.normal(size=256)
+    y = rng.normal(size=256)
+    left = linear_imf(y).imfs - linear_imf(x).imfs
+    right = linear_imf(y - x).imfs
+    assert np.max(np.abs(left - right)) < 1e-12
+
+
+def test_gd_quadratic_matches_closed_form(noisy_signal):
+    # tol=1e-12: the GD stopping rule leaves ~tol-scale error, so the default
+    # 1e-6 would only match the closed form to ~1e-7.
+    closed = linear_imf(noisy_signal, window_sizes=[63, 31])
+    via_gd = imf(noisy_signal, window_sizes=[63, 31], contrast=QuadraticViaGD(), tol=1e-12)
+    assert np.max(np.abs(closed.imfs - via_gd.imfs)) < 1e-9
+    assert np.max(np.abs(closed.residual - via_gd.residual)) < 1e-9
+
+
+def test_robust_fit_symmetric_window_returns_center():
+    from pimf import SmoothAbs
+
+    windows = np.array([[0.0, 1.0, 2.0, 3.0, 4.0]])
+    weights = SquaredTriangle().weights(5)
+    x, _, _ = _gd_fit_windows(windows, weights, SmoothAbs(0.5), max_iter=60, tol=1e-6)
+    assert x[0] == 2.0
+
+
+def test_stage_one_noise_sd():
+    # Exact per-point SD under wrap is sigma * sqrt(sum w^2); audit fixture 0.0240001.
+    sigma = 0.4
+    weights = SquaredTriangle().weights(501)
+    exact_sd = sigma * np.sqrt(np.sum(weights**2))
+    assert abs(exact_sd - 0.0240001) < 1e-7
+
+    rng = np.random.default_rng(123)
+    smoothed = []
+    for _ in range(50):
+        noise = rng.normal(0.0, sigma, 1000)
+        smoothed.append(linear_imf(noise, window_sizes=[501]).imfs[0])
+    empirical_sd = np.std(np.concatenate(smoothed))
+    assert abs(empirical_sd - exact_sd) / exact_sd < 0.1
+
+
+def test_invalid_inputs_raise():
+    y = np.zeros(64)
+    with pytest.raises(ValueError):
+        imf(y, window_sizes=[10])
+    with pytest.raises(ValueError):
+        imf(np.zeros((4, 4)))
+    with pytest.raises(ValueError):
+        imf(np.array([]))
+
+
+@pytest.mark.parametrize("boundary", ["wrap", "reflect", "edge"])
+def test_boundary_reaches_the_padding(boundary):
+    # Reconstruction telescopes for any smoother output, so it cannot detect
+    # boundary plumbing bugs. Instead pin the stage-1 edge value against the
+    # weighted window computed from independently padded data.
+    y = np.linspace(0.0, 1.0, 64)  # a ramp: maximally asymmetric at the edges
+    component = linear_imf(y, window_sizes=[31], boundary=boundary).imfs[0]
+    weights = SquaredTriangle().weights(31)
+    padded = np.pad(y, 15, mode=boundary)
+    assert component[0] == pytest.approx(weights @ padded[:31], abs=1e-15)
+    assert component[-1] == pytest.approx(weights @ padded[-31:], abs=1e-15)
+
+
+def test_boundaries_differ_at_the_edges():
+    y = np.linspace(0.0, 1.0, 64)
+    edge_values = {
+        boundary: linear_imf(y, window_sizes=[31], boundary=boundary).imfs[0][:5]
+        for boundary in ("wrap", "reflect", "edge")
+    }
+    assert not np.allclose(edge_values["wrap"], edge_values["reflect"], atol=1e-6)
+    assert not np.allclose(edge_values["wrap"], edge_values["edge"], atol=1e-6)
+    assert not np.allclose(edge_values["reflect"], edge_values["edge"], atol=1e-6)
+
+
+def test_max_iter_is_respected(noisy_signal):
+    result = robust_imf(noisy_signal, h=0.4, window_sizes=[63, 31], max_iter=1)
+    for info in result.stages:
+        assert info.iterations == 1
+
+
+def test_custom_kernel_flows_through_imf(noisy_signal):
+    from numpy.lib.stride_tricks import sliding_window_view
+
+    from pimf import Kernel
+
+    class Uniform(Kernel):
+        def profile(self, u):
+            return np.ones_like(u)
+
+    result = linear_imf(noisy_signal, window_sizes=[7], kernel=Uniform())
+    weights = Uniform().weights(7)
+    expected = sliding_window_view(np.pad(noisy_signal, 3, mode="wrap"), 7) @ weights
+    assert np.array_equal(result.imfs[0], expected)
+
+    default = linear_imf(noisy_signal, window_sizes=[7]).imfs[0]
+    assert not np.allclose(result.imfs[0], default, atol=1e-6)

pimf-0.1.0/tests/test_erf.py

@@ -0,0 +1,25 @@
+import math
+
+import numpy as np
+
+from pimf._erf import erf_approx
+
+
+def test_matches_math_erf():
+    x = np.linspace(-6.0, 6.0, 4001)
+    reference = np.array([math.erf(v) for v in x])
+    assert np.max(np.abs(erf_approx(x) - reference)) < 1.5e-7
+
+
+def test_zero_is_exact():
+    assert erf_approx(0.0) == 0.0
+
+
+def test_odd_symmetry_is_exact():
+    x = np.linspace(0.0, 8.0, 1001)
+    assert np.array_equal(erf_approx(-x), -erf_approx(x))
+
+
+def test_saturates_in_tails():
+    assert erf_approx(1e6) == 1.0
+    assert erf_approx(-1e6) == -1.0

pimf-0.1.0/tests/test_kernels.py

@@ -0,0 +1,69 @@
+import numpy as np
+import pytest
+
+from pimf import Kernel, SquaredTriangle
+
+
+def research_epanechnikov_weights(window_size):
+    """Inlined weight computation from the research notebooks (bit-parity target)."""
+    radius = window_size // 2
+    offsets = np.arange(-radius, radius + 1)
+    u = offsets / radius
+    weights = 0.75 * np.maximum(0, 1 - np.abs(u)) ** 2
+    return weights / weights.sum()
+
+
+@pytest.mark.parametrize("window_size", [3, 31, 501])
+def test_weight_invariants(window_size):
+    weights = SquaredTriangle().weights(window_size)
+    assert len(weights) == window_size
+    assert np.all(weights >= 0)
+    assert np.isclose(weights.sum(), 1.0, atol=1e-15)
+    assert weights[0] == 0.0
+    assert weights[-1] == 0.0
+    assert np.array_equal(weights, weights[::-1])
+
+
+@pytest.mark.parametrize("window_size", [3, 13, 31, 151, 501])
+def test_bit_parity_with_research_code(window_size):
+    assert np.array_equal(
+        SquaredTriangle().weights(window_size), research_epanechnikov_weights(window_size)
+    )
+
+
+def test_sum_of_squares_fixture():
+    # Validated in the research audit: drives the exact stage-1 noise SD.
+    assert abs(np.sum(SquaredTriangle().weights(501) ** 2) - 0.0036000384) < 1e-10
+
+
+def test_even_window_raises():
+    with pytest.raises(ValueError):
+        SquaredTriangle().weights(10)
+
+
+def test_window_of_one():
+    assert np.array_equal(SquaredTriangle().weights(1), np.array([1.0]))
+
+
+def test_kernel_is_callable():
+    kernel = SquaredTriangle()
+    assert np.array_equal(kernel(31), kernel.weights(31))
+
+
+def test_custom_kernel_one_liner():
+    class Triangle(Kernel):
+        def profile(self, u):
+            return 1.0 - np.abs(u)
+
+    weights = Triangle().weights(5)
+    assert np.all(weights >= 0)
+    assert np.isclose(weights.sum(), 1.0)
+
+
+def test_negative_profile_raises():
+    class Bad(Kernel):
+        def profile(self, u):
+            return u  # negative on [-1, 0)
+
+    with pytest.raises(ValueError):
+        Bad().weights(5)

pimf-0.1.0/tests/test_regression.py

@@ -0,0 +1,99 @@
+"""End-to-end regression against the research example.
+
+Setup mirrors experiments/robust-gradient-descent/robust_gradient_descent_imf.ipynb:
+n=1000, sigma=0.1, contamination p=0.2 scale=2.0 (one-sided), seed 777,
+windows [151, 107, 75, 53, 37, 27, 19, 13], robust h = 2 * sigma = 0.2
+(the winner of the notebook's H grid).
+
+The metric expectations follow the notebook's recorded results: the robust
+decomposition wins on component-wise error (the contamination it rejects ends
+up in its residual, so a total-MSE-with-residual comparison favors linear —
+by design, not by defect).
+"""
+
+import numpy as np
+import pytest
+from conftest import gen_signal, generate_observation
+
+from pimf import linear_imf, robust_imf
+
+WINDOW_SIZES = [151, 107, 75, 53, 37, 27, 19, 13]
+SIGMA = 0.1
+H = 0.2
+
+
+@pytest.fixture(scope="module")
+def signals():
+    t = np.linspace(0.0, 1.0, 1000)
+    x_clean = gen_signal(t)
+    rng = np.random.default_rng(777)
+    y_noisy = generate_observation(
+        x_clean, sigma=SIGMA, contamination_prob=0.2, contamination_scale=2.0, rng=rng
+    )
+    return x_clean, y_noisy
+
+
+@pytest.fixture(scope="module")
+def decompositions(signals):
+    x_clean, y_noisy = signals
+    return {
+        "linear_noisy": linear_imf(y_noisy, window_sizes=WINDOW_SIZES),
+        "linear_clean": linear_imf(x_clean, window_sizes=WINDOW_SIZES),
+        "robust_noisy": robust_imf(y_noisy, H, window_sizes=WINDOW_SIZES),
+        "robust_clean": robust_imf(x_clean, H, window_sizes=WINDOW_SIZES),
+    }
+
+
+def test_reconstructions(signals, decompositions):
+    x_clean, y_noisy = signals
+    assert np.max(np.abs(decompositions["linear_noisy"].reconstruction - y_noisy)) < 1e-10
+    assert np.max(np.abs(decompositions["robust_noisy"].reconstruction - y_noisy)) < 1e-10
+    assert np.max(np.abs(decompositions["robust_clean"].reconstruction - x_clean)) < 1e-10
+
+
+def test_robust_beats_linear_on_components(decompositions):
+    # Noisy-vs-clean error per component, excluding the residual: the robust
+    # fit rejects contamination into its residual, the linear fit spreads it
+    # over the components. Cross-checked: robust ~0.0014 vs linear ~0.023.
+    def component_mse(noisy, clean):
+        return float(np.mean((noisy.imfs - clean.imfs) ** 2))
+
+    robust = component_mse(decompositions["robust_noisy"], decompositions["robust_clean"])
+    linear = component_mse(decompositions["linear_noisy"], decompositions["linear_clean"])
+    assert robust < linear
+
+
+def test_robust_beats_linear_on_mean_mae(decompositions):
+    # Mean MAE over components plus residual — the aggregate where the
+    # notebook's benchmark records the robust win (0.058 vs 0.128 here).
+    def mean_mae(noisy, clean):
+        rows = [np.mean(np.abs(a - b)) for a, b in zip(noisy.imfs, clean.imfs, strict=True)]
+        rows.append(np.mean(np.abs(noisy.residual - clean.residual)))
+        return float(np.mean(rows))
+
+    robust = mean_mae(decompositions["robust_noisy"], decompositions["robust_clean"])
+    linear = mean_mae(decompositions["linear_noisy"], decompositions["linear_clean"])
+    assert robust < linear
+
+
+def test_golden_spot_values(decompositions):
+    # Frozen from the implementation after it was verified bit-identical to
+    # the reference notebook on this exact case (cross-check script).
+    result = decompositions["robust_noisy"]
+    golden_imfs = {
+        (0, 0): 0.07303580151881464,
+        (0, 500): 0.11423344217234899,
+        (3, 250): -0.011978870909632695,
+        (5, 777): 0.034920007932709995,
+        (7, 999): 0.08526826398194841,
+    }
+    for (stage, index), value in golden_imfs.items():
+        assert abs(result.imfs[stage, index] - value) < 1e-12
+    assert abs(result.residual[123] - (-0.031524706119654425)) < 1e-12
+
+
+def test_stage_iterations_match_reference(decompositions):
+    # Cross-checked against the reference implementation (bit-identical run):
+    # late stages legitimately hit the max_iter cap on this contaminated case.
+    iterations = [info.iterations for info in decompositions["robust_noisy"].stages]
+    assert iterations == [39, 18, 18, 19, 24, 30, 60, 60]

pimf-0.1.0/tests/test_schedule.py

@@ -0,0 +1,35 @@
+import pytest
+
+from pimf import make_window_schedule
+
+
+@pytest.mark.parametrize(
+    ("n", "expected"),
+    [
+        (200, [101, 71, 51, 37, 31]),
+        (500, [251, 177, 125, 89, 63, 45, 31]),
+        (1000, [501, 355, 251, 177, 125, 89, 63, 45, 31]),
+        (2000, [1001, 707, 499, 353, 249, 177, 125, 89, 63, 45, 31]),
+    ],
+)
+def test_research_fixtures(n, expected):
+    assert make_window_schedule(n) == expected
+
+
+@pytest.mark.parametrize("n", [50, 200, 777, 1000, 4096])
+def test_invariants(n):
+    sizes = make_window_schedule(n)
+    assert all(size % 2 == 1 for size in sizes)
+    assert all(a > b for a, b in zip(sizes, sizes[1:], strict=False))
+    assert sizes[0] <= n
+
+
+def test_tiny_signal_returns_single_window():
+    assert make_window_schedule(10) == [5]
+
+
+def test_invalid_arguments_raise():
+    with pytest.raises(ValueError):
+        make_window_schedule(0)
+    with pytest.raises(ValueError):
+        make_window_schedule(1000, factor=1.0)