wdm-transform 0.1.1__tar.gz

wdm_transform-0.1.1/CHANGELOG.md

@@ -0,0 +1,15 @@
+## v0.1.1 (2026-03-30)
+
+### fix
+
+- update api overview
+
+## v0.1.0 (2026-03-30)
+
+### add
+
+- prep for v0.1.0 release
+
+### fix
+
+- workflows were rekt

wdm_transform-0.1.1/MANIFEST.in

@@ -0,0 +1,5 @@
+prune .github
+prune docs
+prune site
+exclude .gitignore
+exclude uv.lock

wdm_transform-0.1.1/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: wdm-transform
+Version: 0.1.1
+Summary: Object-oriented WDM transforms for sampled one-dimensional signals.
+Project-URL: Homepage, https://github.com/pywavelet/wdm_transform
+Project-URL: Repository, https://github.com/pywavelet/wdm_transform
+Project-URL: Issues, https://github.com/pywavelet/wdm_transform/issues
+Keywords: wdm,wavelets,signal-processing,time-series
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.26
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: scipy>=1.13
+Provides-Extra: jax
+Requires-Dist: jax[cpu]>=0.4.30; extra == "jax"
+Provides-Extra: dev
+Requires-Dist: black>=24.8; extra == "dev"
+Requires-Dist: commitizen>=3.29; extra == "dev"
+Requires-Dist: pre-commit>=3.7; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-jupyter>=0.25; extra == "docs"
+Requires-Dist: mkdocs-material>=9.6; extra == "docs"
+Requires-Dist: mkdocstrings>=1.0; extra == "docs"
+Requires-Dist: mkdocstrings-python>=2.0; extra == "docs"
+
+# wdm-transform
+
+`wdm-transform` is a small object-oriented package for Wilson-Daubechies-Meyer transforms on
+sampled one-dimensional signals.
+
+![wdm-transform demo](https://raw.githubusercontent.com/pywavelet/wdm_transform/main/docs/_static/demo.gif)
+
+The public API centers on three objects:
+
+- `TimeSeries`
+- `FrequencySeries`
+- `WDM`
+
+## Installation
+
+```bash
+pip install wdm-transform
+```
+
+Optional JAX support:
+
+```bash
+pip install "wdm-transform[jax]"
+```
+
+Documentation and source live at:
+
+- <https://github.com/pywavelet/wdm_transform>
+- <https://github.com/pywavelet/wdm_transform/tree/main/docs>

wdm_transform-0.1.1/README.md

@@ -0,0 +1,29 @@
+# wdm-transform
+
+`wdm-transform` is a small object-oriented package for Wilson-Daubechies-Meyer transforms on
+sampled one-dimensional signals.
+
+![wdm-transform demo](https://raw.githubusercontent.com/pywavelet/wdm_transform/main/docs/_static/demo.gif)
+
+The public API centers on three objects:
+
+- `TimeSeries`
+- `FrequencySeries`
+- `WDM`
+
+## Installation
+
+```bash
+pip install wdm-transform
+```
+
+Optional JAX support:
+
+```bash
+pip install "wdm-transform[jax]"
+```
+
+Documentation and source live at:
+
+- <https://github.com/pywavelet/wdm_transform>
+- <https://github.com/pywavelet/wdm_transform/tree/main/docs>

wdm_transform-0.1.1/pyproject.toml

@@ -0,0 +1,121 @@
+[build-system]
+requires = ["setuptools>=80", "setuptools-scm>=8", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wdm-transform"
+dynamic = ["version"]
+description = "Object-oriented WDM transforms for sampled one-dimensional signals."
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["wdm", "wavelets", "signal-processing", "time-series"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+    "numpy>=1.26",
+    "matplotlib>=3.8",
+    "scipy>=1.13",
+]
+
+[project.urls]
+Homepage = "https://github.com/pywavelet/wdm_transform"
+Repository = "https://github.com/pywavelet/wdm_transform"
+Issues = "https://github.com/pywavelet/wdm_transform/issues"
+
+[project.optional-dependencies]
+jax = [
+    "jax[cpu]>=0.4.30",
+]
+dev = [
+    "black>=24.8",
+    "commitizen>=3.29",
+    "pre-commit>=3.7",
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-jupyter>=0.25",
+    "mkdocs-material>=9.6",
+    "mkdocstrings>=1.0",
+    "mkdocstrings-python>=2.0",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools_scm]
+local_scheme = "no-local-version"
+tag_regex = "^v(?P<version>.+)$"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = [
+    "--cov=wdm_transform",
+    "--cov-report=term-missing",
+    "--cov-report=xml",
+]
+
+[tool.coverage.run]
+branch = true
+source = ["wdm_transform"]
+relative_files = true
+omit = ["*/benchmarking.py", "*/backends/cupy_backend.py"]
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true
+exclude_lines = [
+    "pragma: no cover",
+]
+
+[tool.black]
+line-length = 88
+target-version = ["py310"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]
+
+[tool.commitizen]
+name = "cz_customize"
+version_provider = "scm"
+tag_format = "v$version"
+version_scheme = "pep440"
+update_changelog_on_bump = true
+
+[tool.commitizen.customize]
+schema = "<type>: <message>"
+schema_pattern = "^(feat|add|fix):\\s.+"
+example = "feat: add inverse transform helper"
+commit_parser = "^(?P<change_type>feat|add|fix):\\s(?P<message>.*)$"
+changelog_pattern = "^(feat|add|fix):"
+bump_pattern = "^(feat|add|fix)"
+change_type_order = ["feat", "add", "fix"]
+info = """
+Use one of:
+- feat: new user-facing feature (minor bump)
+- add: additive improvement (minor bump)
+- fix: bug fix (patch bump)
+"""
+
+[tool.commitizen.customize.bump_map]
+feat = "MINOR"
+add = "MINOR"
+fix = "PATCH"

wdm_transform-0.1.1/setup.cfg

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

wdm_transform-0.1.1/src/wdm_transform/__init__.py

@@ -0,0 +1,13 @@
+"""Public package exports for the WDM transform scaffold."""
+
+from .backends import Backend, get_backend, register_backend
+from .datatypes import FrequencySeries, TimeSeries, WDM
+
+__all__ = [
+    "Backend",
+    "FrequencySeries",
+    "TimeSeries",
+    "WDM",
+    "get_backend",
+    "register_backend",
+]

wdm_transform-0.1.1/src/wdm_transform/backends/__init__.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import os
+from importlib import import_module
+from typing import Any
+
+from .base import Backend
+from .numpy_backend import NUMPY_BACKEND
+
+_BACKENDS: dict[str, Backend] = {
+    NUMPY_BACKEND.name: NUMPY_BACKEND,
+}
+
+_BUILTIN_BACKEND_LOADERS = {
+    "jax": ("wdm_transform.backends.jax_backend", "load_jax_backend"),
+    "cupy": ("wdm_transform.backends.cupy_backend", "load_cupy_backend"),
+}
+
+
+def register_backend(name: str, xp: Any, fft: Any) -> Backend:
+    """Register a backend by name and return the resulting backend object."""
+    backend = Backend(name=name, xp=xp, fft=fft)
+    _BACKENDS[name] = backend
+    return backend
+
+
+def _load_builtin_backend(name: str) -> Backend:
+    try:
+        module_name, loader_name = _BUILTIN_BACKEND_LOADERS[name]
+    except KeyError as exc:
+        raise ValueError(f"Unknown backend {name!r}.") from exc
+
+    module = import_module(module_name)
+    loader = getattr(module, loader_name)
+    backend = loader()
+    _BACKENDS[name] = backend
+    return backend
+
+
+def get_backend(backend: str | Backend | None = None) -> Backend:
+    """Resolve a backend object from a name, instance, or environment default."""
+    if isinstance(backend, Backend):
+        return backend
+    if backend is None:
+        backend = os.environ.get("WDM_BACKEND")
+    if backend is None:
+        return NUMPY_BACKEND
+    try:
+        return _BACKENDS[backend]
+    except KeyError as exc:
+        try:
+            return _load_builtin_backend(backend)
+        except ValueError:
+            available = ", ".join(
+                sorted(set(_BACKENDS) | set(_BUILTIN_BACKEND_LOADERS))
+            )
+            raise ValueError(
+                f"Unknown backend {backend!r}. Available backends: {available}."
+            ) from exc
+
+
+__all__ = ["Backend", "NUMPY_BACKEND", "get_backend", "register_backend"]

wdm_transform-0.1.1/src/wdm_transform/backends/base.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Backend:
+    """Minimal backend wrapper around an array namespace and FFT namespace."""
+
+    name: str
+    xp: Any
+    fft: Any
+
+    def asarray(self, value: Any, dtype: Any | None = None) -> Any:
+        """Convert a value into an array for this backend."""
+        return self.xp.asarray(value, dtype=dtype)

wdm_transform-0.1.1/src/wdm_transform/backends/cupy_backend.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from .base import Backend
+
+
+def load_cupy_backend() -> Backend:
+    try:
+        import cupy as cp
+        import cupy.fft as cpfft
+    except ImportError as exc:
+        raise ImportError(
+            "CuPy backend requested, but cupy is not installed. Install a compatible cupy package first."
+        ) from exc
+
+    return Backend(name="cupy", xp=cp, fft=cpfft)

wdm_transform-0.1.1/src/wdm_transform/backends/jax_backend.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from .base import Backend
+
+
+def load_jax_backend() -> Backend:
+    try:
+        import jax
+        jax.config.update("jax_enable_x64", True)
+        import jax.numpy as jnp
+        import jax.numpy.fft as jfft
+    except ImportError as exc:
+        raise ImportError(
+            "JAX backend requested, but jax is not installed. Install a compatible jax package first."
+        ) from exc
+
+    return Backend(name="jax", xp=jnp, fft=jfft)

wdm_transform-0.1.1/src/wdm_transform/backends/numpy_backend.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import numpy as np
+
+from .base import Backend
+
+
+NUMPY_BACKEND = Backend(name="numpy", xp=np, fft=np.fft)

wdm_transform-0.1.1/src/wdm_transform/benchmarking.py

@@ -0,0 +1,284 @@
+"""Benchmarking CLI for WDM transforms across different backends and input sizes.
+
+This module is excluded from pytest coverage and should not be imported
+when loading the main wdm_transform package.
+
+Run with: python -m wdm_transform.benchmarking [options]
+"""
+
+import time
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from . import backends, transforms
+
+
+def validate_backend_available(backend_name: str) -> bool:  # pragma: no cover
+    """Check if a backend is available."""
+    try:
+        backends.get_backend(backend_name)
+        return True
+    except ValueError:
+        return False
+
+
+def generate_benchmark_data(n: int) -> np.ndarray:  # pragma: no cover
+    """Generate random complex benchmark data."""
+    np.random.seed(42)
+    return np.random.randn(n) + 1j * np.random.randn(n)
+
+
+def find_factorization(n: int) -> tuple[int, int] | None:  # pragma: no cover
+    """Find a factorization n = nt * nf where both nt and nf are even.
+    
+    Prioritizes balanced factorizations (nt close to sqrt(n)).
+    Returns (nt, nf) or None if no valid factorization exists.
+    """
+    if n < 4:
+        return None
+    
+    # Try factorizations starting from sqrt(n) and working outward
+    sqrt_n = int(np.sqrt(n))
+    
+    for nt in range(sqrt_n, 1, -1):
+        if n % nt != 0:
+            continue
+        nf = n // nt
+        # Both must be even
+        if nt % 2 == 0 and nf % 2 == 0:
+            return (nt, nf)
+    
+    return None
+
+
+def benchmark_forward(
+    data: np.ndarray,
+    backend_name: str,
+    nt: int,
+    nf: int,
+    num_runs: int = 3,
+) -> float:  # pragma: no cover
+    """Benchmark the forward WDM transform.
+
+    Returns the mean runtime in seconds.
+    """
+    backend = backends.get_backend(backend_name)
+    fixed_params = {"a": 0.4, "d": 0.8, "dt": 1.0, "backend": backend}
+
+    # Convert data to backend array
+    backend_data = backend.asarray(data)
+
+    # Warmup run
+    transforms.forward_wdm(backend_data, nt=nt, nf=nf, **fixed_params)
+
+    # Timed runs
+    times = []
+    for _ in range(num_runs):
+        start = time.perf_counter()
+        transforms.forward_wdm(backend_data, nt=nt, nf=nf, **fixed_params)
+        elapsed = time.perf_counter() - start
+        times.append(elapsed)
+
+    return np.mean(times)
+
+
+def benchmark_inverse(
+    coeffs: np.ndarray,
+    backend_name: str,
+    num_runs: int = 3,
+) -> float:  # pragma: no cover
+    """Benchmark the inverse WDM transform.
+
+    Returns the mean runtime in seconds.
+    """
+    backend = backends.get_backend(backend_name)
+    fixed_params = {"a": 0.4, "d": 0.8, "dt": 1.0, "backend": backend}
+
+    # Convert coeffs to backend array
+    backend_coeffs = backend.asarray(coeffs)
+
+    # Warmup run
+    transforms.inverse_wdm(backend_coeffs, **fixed_params)
+
+    # Timed runs
+    times = []
+    for _ in range(num_runs):
+        start = time.perf_counter()
+        transforms.inverse_wdm(backend_coeffs, **fixed_params)
+        elapsed = time.perf_counter() - start
+        times.append(elapsed)
+
+    return np.mean(times)
+
+
+def run_benchmarks(  # pragma: no cover
+    backends_to_test: list[str],
+    n_values: list[int],
+    num_runs: int = 3,
+) -> dict[str, Any]:
+    """Run benchmark suite across backends and input sizes.
+
+    Returns results dictionary with structure:
+    {
+        'forward': {backend_name: {n: time_in_seconds}},
+        'inverse': {backend_name: {n: time_in_seconds}},
+    }
+    """
+    results = {"forward": {}, "inverse": {}}
+
+    # Validate backends
+    available_backends = [b for b in backends_to_test if validate_backend_available(b)]
+    if not available_backends:
+        print(f"ERROR: No backends available from: {backends_to_test}")
+        return results
+
+    if len(available_backends) < len(backends_to_test):
+        unavailable = set(backends_to_test) - set(available_backends)
+        print(f"WARNING: Skipping unavailable backends: {unavailable}")
+
+    # Forward transform benchmarks
+    print("\n" + "=" * 70)
+    print("FORWARD WDM TRANSFORM BENCHMARKS")
+    print("=" * 70)
+
+    for backend_name in available_backends:
+        results["forward"][backend_name] = {}
+        print(f"\nBackend: {backend_name}")
+        print("-" * 40)
+
+        for n in n_values:
+            # Find a valid factorization for this N
+            factorization = find_factorization(n)
+            if factorization is None:
+                print(f"  N={n:>8}: SKIPPED (no valid factorization)")
+                continue
+            
+            nt, nf = factorization
+            data = generate_benchmark_data(nt * nf)
+            try:
+                mean_time = benchmark_forward(data, backend_name, nt, nf, num_runs)
+                results["forward"][backend_name][n] = mean_time
+                print(f"  N={n:>8}: {mean_time*1e3:>10.4f} ms (nt={nt}, nf={nf})")
+            except Exception as e:
+                print(f"  N={n:>8}: FAILED ({type(e).__name__}: {e})")
+
+    # Inverse transform benchmarks
+    print("\n" + "=" * 70)
+    print("INVERSE WDM TRANSFORM BENCHMARKS")
+    print("=" * 70)
+
+    for backend_name in available_backends:
+        results["inverse"][backend_name] = {}
+        print(f"\nBackend: {backend_name}")
+        print("-" * 40)
+
+        for n in n_values:
+            # Find a valid factorization for this N
+            factorization = find_factorization(n)
+            if factorization is None:
+                print(f"  N={n:>8}: SKIPPED (no valid factorization)")
+                continue
+            
+            nt, nf = factorization
+            coeffs = generate_benchmark_data(nt * nf).reshape(nt, nf)
+            try:
+                mean_time = benchmark_inverse(coeffs, backend_name, num_runs)
+                results["inverse"][backend_name][n] = mean_time
+                print(f"  N={n:>8}: {mean_time*1e3:>10.4f} ms (nt={nt}, nf={nf})")
+            except Exception as e:
+                print(f"  N={n:>8}: FAILED ({type(e).__name__}: {e})")
+
+    return results
+
+
+def print_summary(results: dict[str, Any]) -> None:  # pragma: no cover
+    """Print a summary table of results."""
+    print("\n" + "=" * 70)
+    print("SUMMARY TABLE")
+    print("=" * 70)
+
+    for transform_type, backends_data in results.items():
+        if not backends_data:
+            continue
+
+        print(f"\n{transform_type.upper()} TRANSFORM:")
+        print("-" * 40)
+
+        # Get all N values
+        all_n = set()
+        for n_dict in backends_data.values():
+            all_n.update(n_dict.keys())
+        all_n = sorted(all_n)
+
+        # Header
+        header = f"{'N':>10} | " + " | ".join(f"{b:>12}" for b in backends_data.keys())
+        print(header)
+        print("-" * len(header))
+
+        # Rows
+        for n in all_n:
+            row = f"{n:>10} | "
+            times = [backends_data.get(b, {}).get(n) for b in backends_data.keys()]
+            time_strs = [
+                f"{t*1e3:>10.4f} ms" if t is not None else f"{'SKIPPED':>12}" for t in times
+            ]
+            row += " | ".join(time_strs)
+            print(row)
+
+
+def main() -> None:  # pragma: no cover
+    """CLI entry point for benchmarking."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Benchmark WDM transforms across backends and input sizes.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python -m wdm_transform.benchmarking
+  python -m wdm_transform.benchmarking --backends numpy jax
+  python -m wdm_transform.benchmarking --n 2048 4096 8192
+  python -m wdm_transform.benchmarking --runs 5
+        """,
+    )
+
+    parser.add_argument(
+        "--backends",
+        nargs="+",
+        default=["numpy"],
+        choices=["numpy", "jax", "cupy"],
+        help="Backends to benchmark (default: numpy)",
+    )
+
+    parser.add_argument(
+        "--n",
+        nargs="+",
+        type=int,
+        default=[2048, 4096, 8192, 16384],
+        help="Input sizes to test (default: 2048 4096 8192 16384)",
+    )
+
+    parser.add_argument(
+        "--runs",
+        type=int,
+        default=3,
+        help="Number of runs per benchmark (default: 3)",
+    )
+
+    args = parser.parse_args()
+
+    results = run_benchmarks(
+        backends_to_test=args.backends,
+        n_values=args.n,
+        num_runs=args.runs,
+    )
+
+    print_summary(results)
+    print("\n")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()
+

wdm_transform-0.1.1/src/wdm_transform/datatypes/__init__.py

@@ -0,0 +1,4 @@
+from .series import FrequencySeries, TimeSeries
+from .wdm import WDM
+
+__all__ = ["FrequencySeries", "TimeSeries", "WDM"]