dsp-props 0.1.0__py3-none-any.whl

dsp_props/__init__.py

@@ -0,0 +1,39 @@
+"""dsp-props: property-based testing for digital signal processing code."""
+
+from . import core, generators, relations
+from .core import calibrate
+from .api import (
+    PropertyViolation,
+    Report,
+    LTISpec,
+    MultirateSpec,
+    resampler,
+    StreamingSpec,
+    lti_filter,
+    TransformSpec,
+    stateful,
+    streaming,
+    transform,
+    verify,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "core",
+    "generators",
+    "relations",
+    "transform",
+    "calibrate",
+    "streaming",
+    "lti_filter",
+    "LTISpec",
+    "resampler",
+    "MultirateSpec",
+    "stateful",
+    "StreamingSpec",
+    "verify",
+    "Report",
+    "TransformSpec",
+    "PropertyViolation",
+]

dsp_props/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

dsp_props/adapters.py

@@ -0,0 +1,93 @@
+"""Adapters for DSP code written in C (shared libraries loaded with ctypes).
+
+Two calling conventions are supported, both on contiguous ``double`` arrays:
+
+* stateless: ``void f(const double *x, size_t n, double *y)``, where ``y`` holds
+  ``out_length(n)`` samples (``n`` by default);
+* block with state: ``void f(const double *x, size_t n, double *y, double *state)``,
+  where ``state`` holds ``state_size`` doubles carried from one block to the next.
+
+The returned Python callables can then be declared like any other operator::
+
+    lib = build_shared("biquad.c")
+    lowpass = dp.lti_filter(transfer=(b, a))(c_function(lib, "biquad", state_size=2))
+    Block = dp.streaming()(c_block_processor(lib, "biquad", state_size=2))
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import pathlib
+import shutil
+import subprocess
+import tempfile
+
+import numpy as np
+
+_DOUBLE_P = ctypes.POINTER(ctypes.c_double)
+
+
+def build_shared(*sources, out=None, cc=None, flags=("-O2",)):
+    """Compile C sources into a shared library and load it (needs a C compiler)."""
+    cc = cc or os.environ.get("CC") or shutil.which("cc") or shutil.which("gcc") or shutil.which("clang")
+    if cc is None:
+        raise RuntimeError("no C compiler found (set CC)")
+    if out is None:
+        out = pathlib.Path(tempfile.mkdtemp(prefix="dsp_props_")) / "libdsp.so"
+    cmd = [cc, *flags, "-shared", "-fPIC", "-o", str(out), *map(str, sources), "-lm"]
+    subprocess.run(cmd, check=True, capture_output=True, text=True)
+    return ctypes.CDLL(str(out))
+
+
+def _load(lib):
+    return lib if isinstance(lib, ctypes.CDLL) else ctypes.CDLL(str(lib))
+
+
+def _symbol(lib, name, with_state):
+    f = getattr(_load(lib), name)
+    f.restype = None
+    f.argtypes = [_DOUBLE_P, ctypes.c_size_t, _DOUBLE_P] + ([_DOUBLE_P] if with_state else [])
+    return f
+
+
+def _ptr(a):
+    return a.ctypes.data_as(_DOUBLE_P)
+
+
+def c_function(lib, name, *, out_length=None, state_size=None):
+    """A Python callable ``y = f(x)`` around a C function (state, if any, starts at zero)."""
+    f = _symbol(lib, name, state_size is not None)
+    out_length = out_length or (lambda n: n)
+
+    def call(x):
+        x = np.ascontiguousarray(x, dtype=np.float64)
+        y = np.zeros(out_length(len(x)))
+        if state_size is None:
+            f(_ptr(x), len(x), _ptr(y))
+        else:
+            state = np.zeros(state_size)
+            f(_ptr(x), len(x), _ptr(y), _ptr(state))
+        return y
+
+    call.__name__ = name
+    call.__qualname__ = name
+    return call
+
+
+def c_block_processor(lib, name, *, state_size, init_state=None):
+    """A factory of block processors (``process(block)``) for ``dp.streaming``."""
+    f = _symbol(lib, name, True)
+
+    class Processor:
+        def __init__(self):
+            self.state = np.zeros(state_size) if init_state is None else np.array(init_state, dtype=float)
+
+        def process(self, block):
+            x = np.ascontiguousarray(block, dtype=np.float64)
+            y = np.zeros(len(x))
+            f(_ptr(x), len(x), _ptr(y), _ptr(self.state))
+            return y
+
+    Processor.__name__ = Processor.__qualname__ = name
+    return Processor

dsp_props/api.py

@@ -0,0 +1,285 @@
+"""Declarative API: describe an operator once, check every applicable relation."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+import numpy as np
+
+from hypothesis import HealthCheck, given, settings
+from hypothesis.errors import FlakyFailure, HypothesisException
+
+from .core.tolerance import FFTTolerance, ToleranceModel
+from .report import Failure, PropertyViolation, Report
+from .relations import LTI_RELATIONS, MULTIRATE_RELATIONS, STREAMING_RELATIONS, TRANSFORM_RELATIONS
+
+
+KINDS = ("dft", "rdft", "generic")
+
+
+def hermitian_extend(half, n):
+    """Full length-``n`` DFT from the ``n // 2 + 1`` bins of a real-input DFT."""
+    half = np.asarray(half)
+    full = np.empty(n, dtype=np.result_type(half.dtype, np.complex64))
+    m = n // 2 + 1
+    full[:m] = half[:m]
+    if n > m:
+        full[m:] = np.conj(half[1 : n - m + 1][::-1])
+    return full
+
+
+@dataclass
+class TransformSpec:
+    func: Callable
+    inverse: Optional[Callable] = None
+    kind: str = "dft"
+    linear: bool = True
+    parseval: bool = False
+    parseval_scale: Callable[[int], float] = lambda n: n
+    real_input_hermitian: bool = False
+    real_input_only: bool = False
+    inverse_takes_length: bool = False
+    tolerance: ToleranceModel = field(default_factory=FFTTolerance)
+    max_n: int = 512
+
+    @property
+    def relations(self):
+        return [r for r in TRANSFORM_RELATIONS if r.applies(self)]
+
+    @property
+    def is_fourier(self):
+        return self.kind in ("dft", "rdft")
+
+    def full(self, x):
+        """The transform of ``x`` as a full spectrum (rdft outputs are Hermitian-extended)."""
+        y = np.asarray(self.func(x))
+        if self.kind == "rdft":
+            n = len(x)
+            if y.shape != (n // 2 + 1,):
+                raise AssertionError(f"rdft output has shape {y.shape}, expected ({n // 2 + 1},) for N={n}")
+            return hermitian_extend(y, n)
+        return y
+
+    def invert(self, X, n):
+        return np.asarray(self.inverse(X, n) if self.inverse_takes_length else self.inverse(X))
+
+
+@dataclass
+class StreamingSpec:
+    make: Callable
+    tolerance: ToleranceModel = field(default_factory=lambda: FFTTolerance(c=1000.0))
+    max_n: int = 512
+
+    @property
+    def relations(self):
+        return [r for r in STREAMING_RELATIONS if r.applies(self)]
+
+
+@dataclass
+class LTISpec:
+    func: Callable
+    causal: bool = True
+    transfer: Optional[tuple] = None
+    max_gain: Optional[float] = None
+    tolerance: ToleranceModel = field(default_factory=lambda: FFTTolerance(c=1000.0))
+    max_n: int = 512
+
+    @property
+    def relations(self):
+        return [r for r in LTI_RELATIONS if r.applies(self)]
+
+
+def lti_filter(*, causal=True, transfer=None, max_gain=None, tolerance=None, max_n=512):
+    """Declare a linear time-invariant filter applied with zero initial state.
+
+    Checks linearity, time invariance and (if ``causal``) causality. With
+    ``transfer=(b, a)`` it also checks the measured frequency response against
+    B(z)/A(z), and the tolerance defaults to ``IIRTolerance(b, a)``, which
+    follows the conditioning of the recursion. With ``max_gain`` it checks
+    that no input bounded by 1 gives an output above ``max_gain`` (BIBO
+    stability with a declared bound, e.g. the l1 norm of the impulse response).
+    """
+    if tolerance is None:
+        if transfer is not None:
+            from .core.iir import IIRTolerance
+
+            tolerance = IIRTolerance(*transfer)
+        else:
+            tolerance = FFTTolerance(c=1000.0)
+
+    def decorate(func):
+        func.__dsp_props__ = LTISpec(func=func, causal=causal, transfer=transfer, max_gain=max_gain,
+                                     tolerance=tolerance, max_n=max_n)
+        return func
+
+    return decorate
+
+
+@dataclass
+class MultirateSpec:
+    func: Callable
+    up: int = 1
+    down: int = 1
+    causal: bool = False
+    length: Optional[Callable[[int], int]] = None
+    dc_gain: Optional[float] = 1.0
+    ripple: float = 1e-2
+    stopband: Optional[float] = 0.1
+    tolerance: ToleranceModel = field(default_factory=lambda: FFTTolerance(c=1000.0))
+    max_n: int = 512
+
+    @property
+    def relations(self):
+        return [r for r in MULTIRATE_RELATIONS if r.applies(self)]
+
+    def expected_length(self, n):
+        return self.length(n)
+
+
+def resampler(up=1, down=1, *, causal=False, length="ceil", dc_gain=1.0, ripple=1e-2,
+              stopband=0.1, tolerance=None, max_n=512):
+    """Declare a rational resampler (up by ``up``, down by ``down``), like ``resample_poly``.
+
+    Checks linearity and periodic time invariance (an input delay of
+    ``down`` samples gives an output delay of ``up`` samples). Also, unless
+    disabled with ``None``: the output length (``"ceil"``: ceil(N up / down),
+    ``"floor"``, or a callable), the DC gain within ``ripple`` away from the
+    edges, and, when decimating, that a tone above the output Nyquist
+    frequency comes out below ``stopband`` (relative amplitude).
+    """
+    if up < 1 or down < 1:
+        raise ValueError("up and down must be positive integers")
+    rules = {
+        "ceil": lambda n: -(-n * up // down),
+        "floor": lambda n: n * up // down,
+        None: None,
+    }
+    rule = rules[length] if (length is None or isinstance(length, str)) else length
+
+    def decorate(func):
+        func.__dsp_props__ = MultirateSpec(func=func, up=up, down=down, causal=causal, length=rule,
+                                           dc_gain=dc_gain, ripple=ripple, stopband=stopband,
+                                           tolerance=tolerance or FFTTolerance(c=1000.0), max_n=max_n)
+        return func
+
+    return decorate
+
+
+def streaming(*, tolerance=None, max_n=512):
+    """Declare a block processor: a class (or factory) whose instances have ``process(block)``.
+
+    ``dp.verify`` then checks that any split into blocks, including empty
+    blocks and single samples, gives the same output as one call.
+    """
+
+    def decorate(make):
+        make.__dsp_props__ = StreamingSpec(make=make, tolerance=tolerance or FFTTolerance(c=1000.0),
+                                           max_n=max_n)
+        return make
+
+    return decorate
+
+
+class _StatefulProcessor:
+    def __init__(self, func, init_state):
+        self.func = func
+        self.state = init_state() if callable(init_state) else np.array(init_state, copy=True)
+
+    def process(self, block):
+        y, self.state = self.func(block, self.state)
+        return y
+
+
+def stateful(func, init_state, **kwargs):
+    """Wrap ``func(block, state) -> (out, state)`` (e.g. lfilter with zi) as a streaming operator."""
+    return streaming(**kwargs)(lambda: _StatefulProcessor(func, init_state))
+
+
+def transform(inverse=None, *, kind="dft", linear=True, parseval=False, parseval_scale=None,
+              real_input_hermitian=False, real_input_only=None, inverse_takes_length=None,
+              tolerance=None, max_n=512):
+    """Declare a function as a transform; ``dp.verify`` then checks it.
+
+    ``kind="dft"``: complex DFT (shift and convolution theorems apply).
+    ``kind="rdft"``: real-input DFT returning ``N // 2 + 1`` bins, like
+    ``numpy.fft.rfft``; its inverse is called as ``inverse(X, N)``.
+    ``kind="generic"``: any linear transform (DCT, wavelets, STFT...): only
+    linearity, Parseval and inversibility are checked.
+    """
+    if kind not in KINDS:
+        raise ValueError(f"kind must be one of {KINDS}, got {kind!r}")
+    if real_input_only is None:
+        real_input_only = kind == "rdft"
+    if inverse_takes_length is None:
+        inverse_takes_length = kind == "rdft"
+
+    def decorate(func):
+        func.__dsp_props__ = TransformSpec(
+            func=func,
+            inverse=inverse,
+            kind=kind,
+            linear=linear,
+            parseval=parseval,
+            parseval_scale=parseval_scale or (lambda n: n),
+            real_input_hermitian=real_input_hermitian,
+            real_input_only=real_input_only,
+            inverse_takes_length=inverse_takes_length,
+            tolerance=tolerance or FFTTolerance(),
+            max_n=max_n,
+        )
+        return func
+
+    return decorate
+
+
+def _hypothesis_test(rel, spec, max_examples, derandomize):
+    @settings(max_examples=max_examples, deadline=None, database=None,
+              derandomize=derandomize, suppress_health_check=list(HealthCheck),
+              print_blob=False)
+    @given(rel.inputs(spec))
+    def run(inputs):
+        trace["calls"] += 1
+        try:
+            rel.check(spec, inputs)
+        except Exception:
+            # Hypothesis replays the shrunk example last, so this ends as the minimal input.
+            trace["example"] = inputs
+            if trace["first_failure"] is None:
+                trace["first_failure"] = trace["calls"]
+            raise
+
+    trace = {"calls": 0, "example": None, "first_failure": None}
+    return run, trace
+
+
+def verify(func, *, max_examples=200, raise_on_failure=True, derandomize=False) -> Report:
+    """Run every relation declared for ``func`` and return a report."""
+    spec = getattr(func, "__dsp_props__", None)
+    if spec is None:
+        raise TypeError(f"{func!r} has no dsp-props declaration (use @dp.transform, @dp.lti_filter, @dp.resampler or @dp.streaming)")
+    failures, checked, seconds = [], [], {}
+    for rel in spec.relations:
+        checked.append(rel.name)
+        run, trace = _hypothesis_test(rel, spec, max_examples, derandomize)
+        t0 = time.perf_counter()
+        error = None
+        try:
+            run()
+        except FlakyFailure as exc:
+            # the operator gave different results for the same input: hidden state
+            error = AssertionError(f"{rel.name}: non-deterministic operator (same input, different result): {exc}")
+        except HypothesisException:
+            raise  # misuse of the framework, not a property violation
+        except Exception as exc:  # noqa: BLE001 - every failure is reported
+            error = exc
+        seconds[rel.name] = time.perf_counter() - t0
+        if error is not None:
+            failures.append(Failure(rel.name, error, trace["example"], trace["first_failure"]))
+    report = Report(getattr(func, "__name__", repr(func)), checked, failures,
+                    kind=type(spec).__name__.replace("Spec", "").lower(),
+                    examples_per_relation=max_examples, seconds=seconds)
+    if failures and raise_on_failure:
+        raise PropertyViolation(report)
+    return report

dsp_props/cli.py

@@ -0,0 +1,123 @@
+"""Command line: find every declared operator in modules or files and verify it.
+
+    dsp-props check mypkg.filters             # a module
+    dsp-props check src/filters.py            # a file
+    dsp-props check mypkg.filters:my_fft      # one operator
+    dsp-props check mypkg --json report.json --examples 500
+
+Exit status: 0 if every operator passes, 1 if any relation fails, 2 on usage errors.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import importlib.util
+import json
+import pathlib
+import sys
+import time
+
+from . import __version__
+from .api import verify
+
+
+def _load_module(target):
+    path = pathlib.Path(target)
+    if path.suffix == ".py" and path.exists():
+        name = "_dsp_props_target_" + path.stem
+        spec = importlib.util.spec_from_file_location(name, path)
+        module = importlib.util.module_from_spec(spec)
+        sys.path.insert(0, str(path.resolve().parent))
+        sys.modules[name] = module
+        spec.loader.exec_module(module)
+        return module
+    return importlib.import_module(target)
+
+
+def discover(target):
+    """``[(qualified name, operator)]`` for a ``module``, ``file.py`` or ``module:attribute`` target."""
+    module_part, _, attr = target.partition(":")
+    module = _load_module(module_part)
+    label = module_part if module_part.endswith(".py") else module.__name__
+    if attr:
+        obj = module
+        for part in attr.split("."):
+            obj = getattr(obj, part)
+        if not hasattr(obj, "__dsp_props__"):
+            raise SystemExit(f"dsp-props: {target} has no dsp-props declaration")
+        return [(f"{label}:{attr}", obj)]
+    found, seen = [], set()
+    for name in sorted(vars(module)):
+        obj = vars(module)[name]
+        if name.startswith("_") or id(obj) in seen:
+            continue
+        if getattr(obj, "__dsp_props__", None) is not None:
+            seen.add(id(obj))
+            found.append((f"{label}:{name}", obj))
+        elif isinstance(obj, dict):  # registries such as {"name": operator}
+            for key, value in obj.items():
+                if getattr(value, "__dsp_props__", None) is not None and id(value) not in seen:
+                    seen.add(id(value))
+                    found.append((f"{label}:{name}[{key!r}]", value))
+    return found
+
+
+def _check(args):
+    sys.path.insert(0, ".")
+    targets = []
+    for t in args.targets:
+        try:
+            targets += discover(t)
+        except (ImportError, AttributeError, FileNotFoundError) as exc:
+            print(f"dsp-props: cannot load {t}: {exc}", file=sys.stderr)
+            return 2
+    if not targets:
+        print("dsp-props: no declared operator found (use @dp.transform, @dp.lti_filter, ...)", file=sys.stderr)
+        return 2
+
+    reports, failed = [], 0
+    for name, op in targets:
+        t0 = time.perf_counter()
+        report = verify(op, max_examples=args.examples, raise_on_failure=False, derandomize=args.derandomize)
+        dt = time.perf_counter() - t0
+        failed += not report.ok
+        reports.append((name, report))
+        print(f"{'ok  ' if report.ok else 'FAIL'} {name}  ({len(report.checked)} relations, {dt:.1f}s)")
+        if not report.ok or args.verbose:
+            print("\n".join("    " + line for line in str(report).splitlines()[1:]))
+
+    print(f"\n{len(targets) - failed}/{len(targets)} operators pass")
+    if args.json:
+        data = {"dsp_props": __version__, "examples": args.examples,
+                "operators": [{**r.to_dict(), "target": n} for n, r in reports]}
+        pathlib.Path(args.json).write_text(json.dumps(data, indent=2))
+    if args.markdown:
+        pathlib.Path(args.markdown).write_text("\n\n".join(r.to_markdown() for _, r in reports) + "\n")
+    if args.html:
+        from .report import render_html
+
+        for n, r in reports:
+            r.func_name = n
+        pathlib.Path(args.html).write_text(render_html([r for _, r in reports]))
+    return 1 if failed else 0
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="dsp-props", description="Property-based checks for DSP code.")
+    parser.add_argument("--version", action="version", version=f"dsp-props {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+    check = sub.add_parser("check", help="verify every declared operator in modules or files")
+    check.add_argument("targets", nargs="+", help="module, file.py, or module:attribute")
+    check.add_argument("--examples", type=int, default=200, help="inputs per relation (default 200)")
+    check.add_argument("--derandomize", action="store_true", help="reproducible inputs (for CI)")
+    check.add_argument("--json", help="write the full report as JSON")
+    check.add_argument("--markdown", help="write the report as Markdown")
+    check.add_argument("--html", help="write the report as a standalone HTML page")
+    check.add_argument("-v", "--verbose", action="store_true", help="list relations of passing operators too")
+    args = parser.parse_args(argv)
+    return _check(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dsp_props/core/__init__.py

@@ -0,0 +1,19 @@
+from .calibration import (
+    CalibratedTolerance,
+    CalibrationError,
+    calibrate,
+    longdouble_dft,
+    relative_error,
+)
+from .iir import IIRTolerance, longdouble_lfilter, recursion_gain
+from .tolerance import ToleranceModel, FFTTolerance, ToleranceError, assert_close, norm
+
+__all__ = [
+    "IIRTolerance",
+    "longdouble_lfilter",
+    "recursion_gain",
+    "CalibratedTolerance",
+    "CalibrationError",
+    "calibrate",
+    "longdouble_dft",
+    "relative_error","ToleranceModel", "FFTTolerance", "ToleranceError", "assert_close", "norm"]

dsp_props/core/calibration.py

@@ -0,0 +1,116 @@
+"""Empirical error models: calibrate a tolerance against extended precision.
+
+A fixed formula such as c * eps * log2(N) cannot describe every
+implementation: an FFT library may switch algorithm with the factorisation
+of N (mixed radix, naive small DFTs, Bluestein), and its error then varies by
+two orders of magnitude between neighbouring lengths. ``calibrate`` measures
+the actual relative error of an operator against an extended-precision
+reference for each length and turns it into a tolerance model.
+
+Calibration doubles as a sanity check: an error far above what rounding can
+explain (``max_plausible``) means the operator is wrong, not imprecise, and
+calibration refuses to absorb it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from .tolerance import FFTTolerance, ToleranceError, ToleranceModel, norm
+
+
+def longdouble_dft(x):
+    """Extended-precision DFT reference (NumPy computes FFTs in long double)."""
+    return np.fft.fft(np.asarray(x).astype(np.clongdouble))
+
+
+def _eps(dtype):
+    return float(np.finfo(np.result_type(dtype, np.float32)).eps)
+
+
+def relative_error(op, reference, x):
+    """||op(x) - reference(x)|| / (eps * ||reference(x)||), eps of op's output dtype."""
+    y = np.asarray(op(x))
+    ref = np.asarray(reference(x))
+    if y.shape != ref.shape:
+        raise ToleranceError(f"shape {y.shape} != reference shape {ref.shape}")
+    ref_norm = float(norm(ref.astype(np.complex128)))
+    if ref_norm == 0.0:
+        return 0.0 if norm(y) == 0 else np.inf
+    diff = (y.astype(np.clongdouble) - ref).astype(np.complex128)
+    return float(norm(diff)) / (_eps(y.dtype) * ref_norm)
+
+
+@dataclass
+class CalibratedTolerance(ToleranceModel):
+    """Analytic bound, raised where measurements show the implementation is worse.
+
+    bound(N) = max(base.bound(N), margin * chained * eps * ratio(N) * ||y||)
+
+    ``ratios[N]`` is the worst measured error for length N, in units of eps.
+    Unmeasured lengths fall back to the worst ratio over all measured lengths,
+    which keeps the model conservative. The analytic ``base`` model covers
+    the inputs calibration did not try.
+    """
+
+    ratios: dict = field(default_factory=dict)
+    margin: float = 8.0
+    chained: int = 2  # relations chain a few operations (e.g. inverse(f(x)))
+    base: ToleranceModel = field(default_factory=FFTTolerance)
+
+    @property
+    def worst(self):
+        return max(self.ratios.values(), default=1.0)
+
+    def ratio(self, n):
+        return max(self.ratios.get(n, self.worst), 1.0)
+
+    def bound(self, n, dtype, ref_norm):
+        measured = self.margin * self.chained * _eps(dtype) * self.ratio(n) * ref_norm
+        return max(self.base.bound(n, dtype, ref_norm), measured)
+
+    def summary(self, top=5):
+        worst = sorted(self.ratios.items(), key=lambda kv: -kv[1])[:top]
+        lines = [f"calibrated on {len(self.ratios)} lengths, worst ratio {self.worst:.1f} eps"]
+        lines += [f"  N={n:<6} {r:8.1f} eps" for n, r in worst]
+        return "\n".join(lines)
+
+
+class CalibrationError(AssertionError):
+    pass
+
+
+def calibrate(op, reference=longdouble_dft, lengths=range(1, 257), trials=6, *,
+              margin=8.0, max_plausible=1e6, seed=0) -> CalibratedTolerance:
+    """Measure ``op`` against ``reference`` on random signals of each length.
+
+    Raises ``CalibrationError`` when the error is too large to be rounding
+    (``max_plausible`` eps): calibrating a wrong operator would hide its bug.
+    """
+    rng = np.random.default_rng(seed)
+    ratios = {}
+    for n in lengths:
+        worst = 0.0
+        for x in _probe_signals(n, trials, rng):
+            worst = max(worst, relative_error(op, reference, x))
+        if not worst <= max_plausible:
+            raise CalibrationError(
+                f"error of {worst:.3g} eps at N={n}: the operator disagrees with the reference "
+                "beyond any plausible rounding error"
+            )
+        ratios[n] = worst
+    return CalibratedTolerance(ratios=ratios, margin=margin)
+
+
+def _probe_signals(n, trials, rng):
+    """Gaussian noise plus the structured signals that stress FFT rounding."""
+    t = np.arange(n)
+    for _ in range(trials):
+        yield rng.standard_normal(n)
+    x = np.zeros(n)
+    x[rng.integers(n)] = 1.0
+    yield x
+    yield np.cos(2 * np.pi * rng.uniform(0, 0.5) * t + rng.uniform(-np.pi, np.pi))
+    yield np.cos(np.pi * t) + 1e-6 * rng.standard_normal(n)  # near Nyquist, small detail