torchwavelets 0.1.0__py3-none-any.whl

torchwavelets/__init__.py

@@ -0,0 +1,62 @@
+"""torchwavelets: differentiable discrete wavelet transforms for PyTorch."""
+
+from . import compat  # noqa: F401  (drop-in pytorch_wavelets API)
+from ._version import __version__
+from .core.modes import SUPPORTED_MODES
+from .dtcwt.transform1d import DTCWT1D, IDTCWT1D, dtcwt1d, idtcwt1d
+from .dtcwt.transform2d import DTCWT2D, IDTCWT2D, dtcwt2d, idtcwt2d
+from .dtcwt.transform3d import DTCWT3D, IDTCWT3D, dtcwt3d, idtcwt3d
+from .dwt.transform1d import DWT1D, IDWT1D, dwt1d, idwt1d
+from .dwt.transform2d import DWT2D, IDWT2D, dwt2d, idwt2d
+from .packets import WaveletPacket, WaveletPacket2D
+from .scatter.lowlevel import ScatLayer, ScatLayerj2
+from .scatter.network import DTCWTScattering, dtcwt_scattering
+from .swt.transform import (
+    ISWT1D,
+    ISWT2D,
+    SWT1D,
+    SWT2D,
+    iswt1d,
+    iswt2d,
+    swt1d,
+    swt2d,
+)
+
+__all__ = [
+    "__version__",
+    "SUPPORTED_MODES",
+    "dwt1d",
+    "idwt1d",
+    "dwt2d",
+    "idwt2d",
+    "dtcwt2d",
+    "idtcwt2d",
+    "DWT1D",
+    "IDWT1D",
+    "DWT2D",
+    "IDWT2D",
+    "DTCWT2D",
+    "IDTCWT2D",
+    "DTCWT1D",
+    "IDTCWT1D",
+    "DTCWT3D",
+    "IDTCWT3D",
+    "dtcwt1d",
+    "idtcwt1d",
+    "dtcwt3d",
+    "idtcwt3d",
+    "ScatLayer",
+    "ScatLayerj2",
+    "DTCWTScattering",
+    "dtcwt_scattering",
+    "WaveletPacket",
+    "WaveletPacket2D",
+    "swt1d",
+    "iswt1d",
+    "swt2d",
+    "iswt2d",
+    "SWT1D",
+    "ISWT1D",
+    "SWT2D",
+    "ISWT2D",
+]

torchwavelets/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

torchwavelets/compat.py

@@ -0,0 +1,136 @@
+"""Drop-in compatibility with the ``pytorch_wavelets`` API.
+
+The upstream class names are plain aliases: the constructor signatures and
+call semantics are identical, only the semantics are fixed (precision follows
+the input dtype, autocast works, and boundary handling matches PyWavelets
+exactly). For the DTCWT, the bandpass coefficients are converted from the
+native complex format to the upstream ``(..., 2)`` real/imag layout.
+"""
+
+from __future__ import annotations
+
+import torch
+
+from .dtcwt.transform2d import DTCWT2D, IDTCWT2D
+from .dwt.transform1d import DWT1D, IDWT1D
+from .dwt.transform2d import DWT2D, IDWT2D
+
+__all__ = [
+    "DWTForward",
+    "DWTInverse",
+    "DWT1DForward",
+    "DWT1DInverse",
+    "DTCWTForward",
+    "DTCWTInverse",
+    "DWT",
+    "IDWT",
+    "DWT1D",
+    "IDWT1D",
+    "DTCWT",
+    "IDTCWT",
+]
+
+
+class DWTForward(DWT2D):
+    """``pytorch_wavelets``-compatible 2-D DWT forward (upstream defaults)."""
+
+    def __init__(self, J=1, wave="db1", mode="zero"):
+        super().__init__(J=J, wave=wave, mode=mode)
+
+
+class DWTInverse(IDWT2D):
+    """``pytorch_wavelets``-compatible 2-D DWT inverse (upstream defaults)."""
+
+    def __init__(self, wave="db1", mode="zero"):
+        super().__init__(wave=wave, mode=mode)
+
+
+class DWT1DForward(DWT1D):
+    """``pytorch_wavelets``-compatible 1-D DWT forward (upstream defaults)."""
+
+    def __init__(self, J=1, wave="db1", mode="zero"):
+        super().__init__(J=J, wave=wave, mode=mode)
+
+
+class DWT1DInverse(IDWT1D):
+    """``pytorch_wavelets``-compatible 1-D DWT inverse (upstream defaults)."""
+
+    def __init__(self, wave="db1", mode="zero"):
+        super().__init__(wave=wave, mode=mode)
+
+
+class DTCWTForward(DTCWT2D):
+    """``pytorch_wavelets``-compatible DTCWT forward.
+
+    Returns bandpasses in the upstream layout ``(N, C, 6, H, W, 2)``
+    (real and imaginary parts along the last dimension). ``ri_dim`` must be
+    the default ``-1`` (the native complex layout is fixed).
+    """
+
+    def __init__(
+        self,
+        biort="near_sym_a",
+        qshift="qshift_a",
+        J=3,
+        skip_hps=False,
+        include_scale=False,
+        o_dim=2,
+        ri_dim=-1,
+        mode="symmetric",
+    ):
+        if ri_dim != -1:
+            raise ValueError("torchwavelets DTCWT only supports ri_dim=-1")
+        if mode != "symmetric":
+            raise ValueError(
+                "torchwavelets DTCWT only supports mode='symmetric' (Kingsbury boundary handling)"
+            )
+        super().__init__(
+            biort=biort,
+            qshift=qshift,
+            J=J,
+            skip_hps=skip_hps,
+            include_scale=include_scale,
+            o_dim=o_dim,
+        )
+
+    def forward(self, x: torch.Tensor):
+        yl, yh = super().forward(x)
+        if yh is None:
+            return yl, yh
+        return yl, [None if h is None else torch.stack((h.real, h.imag), dim=-1) for h in yh]
+
+
+class DTCWTInverse(IDTCWT2D):
+    """``pytorch_wavelets``-compatible DTCWT inverse (accepts the upstream
+    ``(..., 2)`` real/imag layout or the native complex format)."""
+
+    def __init__(self, biort="near_sym_a", qshift="qshift_a", o_dim=2, ri_dim=-1, mode="symmetric"):
+        if ri_dim != -1:
+            raise ValueError("torchwavelets DTCWT only supports ri_dim=-1")
+        if mode != "symmetric":
+            raise ValueError(
+                "torchwavelets DTCWT only supports mode='symmetric' (Kingsbury boundary handling)"
+            )
+        super().__init__(biort=biort, qshift=qshift, o_dim=o_dim)
+
+    def forward(self, coeffs):
+        yl, yh = coeffs
+        yh = [None if h is None else _to_complex(h) for h in yh]
+        return super().forward((yl, yh))
+
+
+def _to_complex(h: torch.Tensor) -> torch.Tensor:
+    if h.dtype.is_complex:
+        return h
+    if h.shape[-1] == 2:
+        return torch.complex(h[..., 0], h[..., 1])
+    raise ValueError(
+        f"Expected a complex tensor or a (..., 2) real/imag tensor; got shape {tuple(h.shape)}"
+    )
+
+
+# pytorch_wavelets' historical aliases
+DWT = DWTForward
+IDWT = DWTInverse
+DTCWT = DTCWTForward
+IDTCWT = DTCWTInverse

torchwavelets/core/__init__.py

@@ -0,0 +1,13 @@
+"""Core utilities: filter banks and boundary modes."""
+
+from .filters import FilterBank, filter_bank, resolve_1d, resolve_2d
+from .modes import SUPPORTED_MODES, validate_mode
+
+__all__ = [
+    "FilterBank",
+    "filter_bank",
+    "resolve_1d",
+    "resolve_2d",
+    "SUPPORTED_MODES",
+    "validate_mode",
+]

torchwavelets/core/filters.py

@@ -0,0 +1,211 @@
+"""Filter-bank handling: PyWavelets-compatible wavelets and custom banks.
+
+Custom banks are validated for perfect reconstruction at creation time, so a
+biorthogonal bank passed as a 2-tuple (which assumes orthogonality) raises
+immediately instead of silently producing a wrong inverse.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+
+import numpy as np
+import pywt
+import torch
+import torch.nn.functional as F
+
+__all__ = [
+    "FilterBank",
+    "filter_bank",
+    "wave_name",
+    "resolve_1d",
+    "resolve_2d",
+]
+
+
+@dataclass(frozen=True)
+class FilterBank:
+    """A 1-D two-channel filter bank in PyWavelets' natural (non-reversed) order.
+
+    Attributes:
+        h0: analysis lowpass (``pywt.Wavelet.dec_lo``).
+        h1: analysis highpass (``pywt.Wavelet.dec_hi``).
+        g0: synthesis lowpass (``pywt.Wavelet.rec_lo``).
+        g1: synthesis highpass (``pywt.Wavelet.rec_hi``).
+    """
+
+    h0: np.ndarray
+    h1: np.ndarray
+    g0: np.ndarray
+    g1: np.ndarray
+
+    @property
+    def length(self) -> int:
+        """Filter length (number of taps)."""
+        return int(self.h0.size)
+
+
+def _normalize(wave: object):
+    """Return a hashable cache key for ``wave``."""
+    if isinstance(wave, pywt.Wavelet):
+        # Key on the actual filter bank, not just the name: pywt allows
+        # ``pywt.Wavelet("db2", filter_bank=<custom bank>)``.
+        return (
+            "pywt",
+            wave.name,
+            tuple(np.asarray(wave.dec_lo, dtype=np.float64).ravel().tolist()),
+            tuple(np.asarray(wave.dec_hi, dtype=np.float64).ravel().tolist()),
+            tuple(np.asarray(wave.rec_lo, dtype=np.float64).ravel().tolist()),
+            tuple(np.asarray(wave.rec_hi, dtype=np.float64).ravel().tolist()),
+        )
+    if isinstance(wave, str):
+        return wave
+    if not isinstance(wave, (tuple, list, np.ndarray)):
+        raise ValueError(f"Unsupported wavelet specification: {wave!r}")
+    arrs = tuple(tuple(np.asarray(w, dtype=np.float64).ravel()) for w in wave)
+    if len(arrs) not in (2, 4):
+        raise ValueError(
+            "A custom filter bank must be a 2-tuple (h0, h1) or "
+            f"4-tuple (h0, h1, g0, g1); got {len(arrs)} arrays."
+        )
+    return ("custom", arrs)
+
+
+def wave_name(wave: object) -> str:
+    """A short human-readable name for a wavelet specification."""
+    if isinstance(wave, pywt.Wavelet):
+        return wave.name
+    if isinstance(wave, str):
+        return wave
+    return "custom"
+
+
+def _check_pr(bank: FilterBank, tol: float = 1e-5) -> None:
+    """Verify perfect reconstruction of a custom bank on a random fp64 signal.
+
+    Raises ``ValueError`` if the bank is not perfectly reconstructing (for
+    example, a biorthogonal pair given as a 2-tuple, where the synthesis
+    filters would wrongly equal the analysis filters).
+    """
+    if len(bank.h0) != len(bank.h1) or len(bank.g0) != len(bank.g1):
+        raise ValueError(
+            "Custom filter banks must have equal-length analysis filters "
+            f"(got {len(bank.h0)} vs {len(bank.h1)}) and equal-length "
+            f"synthesis filters (got {len(bank.g0)} vs {len(bank.g1)})."
+        )
+    if len(bank.h0) != len(bank.g0):
+        raise NotImplementedError(
+            "Custom banks with different analysis/synthesis filter lengths "
+            "(e.g. LeGall 5/3) are not supported yet; got analysis length "
+            f"{len(bank.h0)} and synthesis length {len(bank.g0)}."
+        )
+
+    n = 64
+    L = len(bank.h0)
+    x = torch.randn(n, dtype=torch.float64)
+    h0 = torch.tensor(bank.h0[::-1].copy(), dtype=torch.float64)[None, None, :]
+    h1 = torch.tensor(bank.h1[::-1].copy(), dtype=torch.float64)[None, None, :]
+    g0 = torch.tensor(bank.g0.copy(), dtype=torch.float64)[None, None, :]
+    g1 = torch.tensor(bank.g1.copy(), dtype=torch.float64)[None, None, :]
+    xp = F.pad(x[None, None, :], (L - 2, L - 2))
+    lo = F.conv1d(xp, h0, stride=2)
+    hi = F.conv1d(xp, h1, stride=2)
+    xr = F.conv_transpose1d(lo, g0, stride=2, padding=(L - 2,))
+    xr = xr + F.conv_transpose1d(hi, g1, stride=2, padding=(L - 2,))
+    xr = xr[0, 0, :n]
+    rel_err = (x - xr).norm().item() / x.norm().item()
+    if rel_err > tol:
+        raise ValueError(
+            "The custom filter bank is not perfectly reconstructing "
+            f"(relative error {rel_err:.2e}). For a biorthogonal bank pass the "
+            "4-tuple (h0, h1, g0, g1) with explicit synthesis filters; a "
+            "2-tuple assumes an orthogonal bank with g = h."
+        )
+
+
+@lru_cache(maxsize=256)
+def _bank_from_key(key) -> FilterBank:
+    if isinstance(key, str):
+        w = pywt.Wavelet(key)
+        return FilterBank(
+            np.array(w.dec_lo),
+            np.array(w.dec_hi),
+            np.array(w.rec_lo),
+            np.array(w.rec_hi),
+        )
+    if key[0] == "pywt":
+        _, name, dec_lo, dec_hi, rec_lo, rec_hi = key
+        w = pywt.Wavelet(name, filter_bank=(dec_lo, dec_hi, rec_lo, rec_hi))
+        return FilterBank(
+            np.array(w.dec_lo),
+            np.array(w.dec_hi),
+            np.array(w.rec_lo),
+            np.array(w.rec_hi),
+        )
+    _, arrs = key
+    if len(arrs) == 2:
+        # Custom orthogonal bank: synthesis filters are the time-reversed
+        # analysis filters (this is exactly pywt's rec_lo convention for
+        # orthogonal wavelets, e.g. db2.rec_lo == db2.dec_lo[::-1]).
+        h0, h1 = arrs
+        bank = FilterBank(np.array(h0), np.array(h1), np.array(h0[::-1]), np.array(h1[::-1]))
+    else:
+        bank = FilterBank(
+            np.array(arrs[0]), np.array(arrs[1]), np.array(arrs[2]), np.array(arrs[3])
+        )
+    _check_pr(bank)
+    return bank
+
+
+def filter_bank(wave) -> FilterBank:
+    """Resolve ``wave`` to a :class:`FilterBank`.
+
+    ``wave`` may be a PyWavelets wavelet name (``"db4"``), a
+    :class:`pywt.Wavelet`, a 2-tuple ``(h0, h1)`` (orthogonal custom bank), or
+    a 4-tuple ``(h0, h1, g0, g1)`` (general bank). Custom banks are validated
+    for perfect reconstruction and raise ``ValueError`` otherwise.
+    """
+    return _bank_from_key(_normalize(wave))
+
+
+@lru_cache(maxsize=1024)
+def _resolve_1d_cached(key, dtype, device):
+    bank = _bank_from_key(key)
+    h0 = torch.tensor(bank.h0[::-1].copy(), dtype=dtype, device=device).reshape(1, 1, 1, -1)
+    h1 = torch.tensor(bank.h1[::-1].copy(), dtype=dtype, device=device).reshape(1, 1, 1, -1)
+    g0 = torch.tensor(bank.g0.copy(), dtype=dtype, device=device).reshape(1, 1, 1, -1)
+    g1 = torch.tensor(bank.g1.copy(), dtype=dtype, device=device).reshape(1, 1, 1, -1)
+    return (h0, h1, g0, g1)
+
+
+def resolve_1d(
+    wave, dtype: torch.dtype, device: torch.device
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
+    """Analysis (reversed, for correlation) and synthesis (natural) 1-D filters.
+
+    Returns tensors of shape ``(1, 1, 1, L)``, ready to filter a signal along
+    the width dimension (``dim=3``) of a 4-D tensor. The analysis filters are
+    reversed so ``conv2d`` implements correlation like PyWavelets' ``dwt``.
+    Cached per ``(wave, dtype, device)``.
+    """
+    return _resolve_1d_cached(_normalize(wave), dtype, device)
+
+
+def resolve_2d(wave, dtype: torch.dtype, device: torch.device) -> tuple[torch.Tensor, ...]:
+    """Like :func:`resolve_1d` but returns column and row orientations.
+
+    Returns ``(h0_col, h1_col, h0_row, h1_row, g0_col, g1_col, g0_row, g1_row)``
+    with column filters shaped ``(1, 1, L, 1)`` and row filters ``(1, 1, 1, L)``.
+    """
+    h0, h1, g0, g1 = resolve_1d(wave, dtype, device)
+    return (
+        h0.reshape(1, 1, -1, 1),
+        h1.reshape(1, 1, -1, 1),
+        h0,
+        h1,
+        g0.reshape(1, 1, -1, 1),
+        g1.reshape(1, 1, -1, 1),
+        g0,
+        g1,
+    )

torchwavelets/core/modes.py

@@ -0,0 +1,109 @@
+"""Boundary modes: PyWavelets-exact padding for all supported modes."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+import torch
+
+__all__ = [
+    "SUPPORTED_MODES",
+    "validate_mode",
+    "output_length",
+    "padding_sizes",
+    "pad_indices",
+]
+
+#: Modes supported by torchwavelets.  ``zero``, ``symmetric``, ``reflect``,
+#: ``periodization``, ``periodic``, ``constant`` and ``smooth`` match
+#: PyWavelets exactly (``smooth`` is a linear extrapolation from the edges).
+#: ``replicate`` (edge extension) is an alias for ``constant``.
+SUPPORTED_MODES = (
+    "zero",
+    "symmetric",
+    "reflect",
+    "periodization",
+    "periodic",
+    "constant",
+    "replicate",
+    "smooth",
+)
+
+_ALIASES = {
+    "per": "periodization",
+    "wrap": "periodic",
+    "edge": "constant",
+    "replicate": "constant",
+}
+
+
+def validate_mode(mode: str) -> str:
+    """Normalize ``mode`` (accepts pywt aliases like ``per``/``wrap``/``edge``)."""
+    if mode in _ALIASES:
+        return _ALIASES[mode]
+    if mode not in SUPPORTED_MODES:
+        raise ValueError(f"Unknown mode {mode!r}. Supported modes: {SUPPORTED_MODES}")
+    return mode
+
+
+def output_length(n: int, length: int, mode: str) -> int:
+    """Length of a single-level decimated transform, as PyWavelets computes it.
+
+    Equivalent to ``pywt.dwt_coeff_len`` for the modes PyWavelets supports.
+    """
+    if mode == "periodization":
+        return (n + 1) // 2
+    return (n + length - 1) // 2
+
+
+def padding_sizes(n: int, length: int, mode: str) -> tuple[int, int]:
+    """Total padding ``(before, after)`` needed so the strided convolution
+    reproduces PyWavelets' output length exactly.
+
+    The padding is ``(L - 2)`` before the signal and the remainder after —
+    this is the distribution PyWavelets uses for every extension mode, and it
+    holds for arbitrary ``n`` (no limit relative to the filter length).
+    """
+    out = output_length(n, length, mode)
+    p = 2 * (out - 1) - n + length
+    before = length - 2
+    return before, p - before
+
+
+@lru_cache(maxsize=512)
+def _pad_indices_cached(n, before, after, mode, device):
+    """Long index tensor of length ``n + before + after`` extending a signal of
+    length ``n`` with the given boundary mode (for ``mode != 'zero'``).
+    Cached per ``(n, before, after, mode, device)``; do not mutate the result.
+    """
+    idx = torch.arange(-before, n + after, device=device)
+    if mode == "symmetric":
+        # Half-sample symmetric extension (period 2n, mirrors at -0.5 and n-0.5).
+        rel = idx + 0.5
+        rng = 2 * n
+        normed = torch.remainder(rel, rng)
+        ref = torch.where(normed >= n, rng - normed, normed)
+        idx = (ref - 0.5).long()
+    elif mode == "reflect":
+        # Whole-sample symmetric extension (period 2n-2, mirrors at 0 and n-1).
+        if n <= 1:
+            idx = torch.zeros_like(idx)
+        else:
+            rng = 2 * n - 2
+            normed = torch.remainder(idx, rng)
+            idx = torch.where(normed >= n, rng - normed, normed).long()
+    elif mode == "periodic":
+        idx = torch.remainder(idx, n)
+    elif mode == "constant":
+        # Edge extension (PyWavelets' 'constant' mode pads with the boundary
+        # value; this is the same as torch's 'replicate' padding).
+        idx = torch.clamp(idx, 0, n - 1)
+    else:  # pragma: no cover - validated upstream
+        raise ValueError(f"pad_indices does not support mode {mode!r}")
+    return idx
+
+
+def pad_indices(n: int, before: int, after: int, mode: str, device: torch.device) -> torch.Tensor:
+    """Long index tensor extending a signal of length ``n`` with the given
+    boundary mode (for ``mode != 'zero'``)."""
+    return _pad_indices_cached(n, before, after, mode, device)

torchwavelets/dtcwt/__init__.py

@@ -0,0 +1,24 @@
+"""Dual-tree complex wavelet transforms."""
+
+from .coeffs import biort, level1, qshift
+from .transform1d import DTCWT1D, IDTCWT1D, dtcwt1d, idtcwt1d
+from .transform2d import DTCWT2D, IDTCWT2D, dtcwt2d, idtcwt2d
+from .transform3d import DTCWT3D, IDTCWT3D, dtcwt3d, idtcwt3d
+
+__all__ = [
+    "DTCWT1D",
+    "IDTCWT1D",
+    "DTCWT2D",
+    "IDTCWT2D",
+    "DTCWT3D",
+    "IDTCWT3D",
+    "dtcwt1d",
+    "idtcwt1d",
+    "dtcwt2d",
+    "idtcwt2d",
+    "dtcwt3d",
+    "idtcwt3d",
+    "biort",
+    "level1",
+    "qshift",
+]

torchwavelets/dtcwt/_autocast.py

@@ -0,0 +1,24 @@
+"""Autocast handling for the DTCWT family.
+
+The DTCWT assembles complex bandpasses with ``torch.complex``, which rejects
+half and bfloat16. Under ``torch.autocast`` the convolution outputs are cast
+to the autocast dtype, so the whole computation runs in an autocast-disabled
+scope: inputs are promoted to float32 internally (the documented half/bf16
+behavior) and the result keeps that precision.
+"""
+
+from __future__ import annotations
+
+import torch
+
+
+def autocast_off(device: torch.device) -> torch.autocast:
+    """Return an autocast-disabled context for ``device``'s type.
+
+    A plain factory rather than a ``contextlib.contextmanager``: Dynamo
+    inlines regular function calls and natively supports ``torch.autocast``,
+    but generator-based context managers cannot be traced, so they break
+    ``torch.compile(fullgraph=True)``.
+    """
+    device_type = "cuda" if device.type == "cuda" else "cpu"
+    return torch.autocast(device_type=device_type, enabled=False)

torchwavelets/dtcwt/coeffs.py

@@ -0,0 +1,76 @@
+"""Dual-tree complex wavelet filter banks (Kingsbury's design).
+
+The filter coefficients are the standard DTCWT banks:
+
+- Level 1 (biorthogonal): ``antonini``, ``farras``, ``legall``, ``near_sym_a``,
+  ``near_sym_b``, ``near_sym_a2``, ``near_sym_b_bp``
+- Levels 2+ (quarter-sample shift): ``qshift_06``, ``qshift_32``, ``qshift_a``,
+  ``qshift_b``, ``qshift_c``, ``qshift_d``, ``qshift_b_bp``
+
+The coefficients originate from Nick Kingsbury's dual-tree complex wavelet
+transform toolbox (Cambridge University), which is free for research use only.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from importlib.resources import files
+
+import numpy as np
+
+__all__ = ["level1", "qshift", "biort", "pywt_coeffs"]
+
+
+@lru_cache(maxsize=32)
+def _load_from_file(basename: str, varnames: tuple) -> tuple[np.ndarray, ...]:
+    """Load filter vectors from the bundled ``.npz`` data files."""
+    data = files("torchwavelets.dtcwt.data").joinpath(basename + ".npz")
+    with data.open("rb") as f:
+        mat = dict(np.load(f))
+    try:
+        return tuple(mat[k] for k in varnames)
+    except KeyError as e:  # pragma: no cover - data files are fixed
+        raise ValueError(
+            f"Wavelet {basename!r} does not define ({', '.join(varnames)}) "
+            f"coefficients; available keys: {sorted(mat)}"
+        ) from e
+
+
+def level1(name: str, compact: bool = False) -> tuple[np.ndarray, ...]:
+    """Load level-1 (biorthogonal) DTCWT filters by name.
+
+    Returns ``(h0o, g0o, h1o, g1o)`` (compact) or the 8-tuple
+    ``(h0a, h0b, g0a, g0b, h1a, h1b, g1a, g1b)``. ``near_sym_b_bp`` also
+    returns the bandpass ``h2o``/``g2o`` (compact) or ``h2a, h2b, g2a, g2b``.
+    """
+    if compact:
+        if name == "near_sym_b_bp":
+            return _load_from_file(name, ("h0o", "g0o", "h1o", "g1o", "h2o", "g2o"))
+        return _load_from_file(name, ("h0o", "g0o", "h1o", "g1o"))
+    return _load_from_file(name, ("h0a", "h0b", "g0a", "g0b", "h1a", "h1b", "g1a", "g1b"))
+
+
+def qshift(name: str) -> tuple[np.ndarray, ...]:
+    """Load level >= 2 (quarter-sample shift) DTCWT filters by name.
+
+    Returns ``(h0a, h0b, g0a, g0b, h1a, h1b, g1a, g1b)`` (``qshift_b_bp``
+    also returns the bandpass ``h2a, h2b, g2a, g2b``).
+    """
+    if name == "qshift_b_bp":
+        return _load_from_file(
+            name,
+            ("h0a", "h0b", "g0a", "g0b", "h1a", "h1b", "g1a", "g1b", "h2a", "h2b", "g2a", "g2b"),
+        )
+    return _load_from_file(name, ("h0a", "h0b", "g0a", "g0b", "h1a", "h1b", "g1a", "g1b"))
+
+
+def biort(name: str) -> tuple[np.ndarray, ...]:
+    """Deprecated alias of :func:`level1` (``compact=True``)."""
+    return level1(name, compact=True)
+
+
+def pywt_coeffs(name: str):
+    """Wrap a PyWavelets wavelet (for custom level-1 banks)."""
+    import pywt
+
+    return pywt.Wavelet(name)

torchwavelets/dtcwt/data/__init__.py

@@ -0,0 +1,5 @@
+"""Bundled DTCWT filter-bank data files (``.npz``).
+
+This package contains no code; it exists so setuptools includes the ``.npz``
+filter files in wheels and sdists (see ``[tool.setuptools.package-data]``).
+"""