visqol-python 3.5.0__tar.gz → 3.6.0__tar.gz

{visqol_python-3.5.0 → visqol_python-3.6.0}/CHANGELOG.md

@@ -4,6 +4,69 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [3.6.0] - 2026-05-27
+
+### Added
+- **Optional pyFFTW backend** (`pip install visqol-python[fftw]`):
+  - Routes `scipy.fft.fft / ifft / rfft / irfft` through FFTW3 via
+    `pyfftw.interfaces.scipy_fft` for the alignment and cross-correlation
+    FFTs. Detected at module load time in `signal_utils` and applied
+    transparently via a thin `_fft_backend()` context manager.
+  - Plan cache enabled with 60 s keep-alive so consecutive measurements
+    on equal-length signals reuse the FFTW plan.
+
+### Improved
+- **Fused NSIM kernel**: `_measure_patch_similarity_numba` merged its 5
+  separate 2-D convolutions (μ_r, μ_d, ref², deg², ref·deg) and the
+  intensity/structure recombination into one `(r, c)` double loop. Each
+  patch element is read from L1 once per visit instead of five times,
+  and the four intermediate `(rows × cols)` matrices are no longer
+  materialised between convs. Bit-exact with the previous split-conv
+  path (ULP-level FP rounding only).
+- **`nsim.measure_patch_similarity`** now dispatches to the fused JIT
+  kernel when Numba is available — the same code path the DP patch
+  matcher uses, so `finely_align_and_recreate_patches` shares the
+  speedup. The pure-NumPy implementation is preserved as a fallback.
+- **`signal_utils._hilbert`** is a drop-in `scipy.signal.hilbert`
+  replacement built on `rfft` for the real-valued input (~2× less
+  forward-transform work than the original full complex `fft`).
+- **`signal_utils.find_best_lag`** now uses `rfft + irfft` for the
+  cross-correlation, again exploiting the real input. Net effect:
+  alignment FFTs see roughly 2× less work overall.
+- Removed dead helper `_conv2d_boundary_valid` from `numba_accel.py`
+  (subsumed by the fused kernel).
+
+### Fixed
+- **`find_best_lag` interpreter hot loop**: the previous implementation
+  ran `xcorr_full[-max_lag:].tolist() + xcorr_full[:max_lag+1].tolist()`
+  and then `builtin argmax(list)` over a ~1.2 M-element Python list,
+  costing ~33 ms per call in pure interpreter overhead. Now uses
+  `np.concatenate + np.argmax` entirely in C.
+
+### Performance
+
+Apple M-series, Python 3.13, audio mode, the `guitar48_stereo` 12.5 s
+conformance case, average of 3 runs with Numba + pyFFTW both installed:
+
+| Stage              | v3.5.0   | v3.6.0   | Speedup |
+|--------------------|----------|----------|---------|
+| DP Patch matching  | 0.397 s  | 0.131 s  | **3.0×** |
+| Global align / FFT | 0.173 s  | 0.091 s  | 1.9×    |
+| Fine align + NSIM  | 0.093 s  | 0.043 s  | 2.2×    |
+| Gammatone          | 0.173 s  | 0.179 s  | ~       |
+| **Total**          | **0.839 s** | **0.447 s** | **1.9×** |
+| **RTF**            | 0.067    | **0.036**   | (C++ est. 0.093) |
+
+### Numerical parity
+
+All v3.5.0 conformance baselines preserved within ULP precision:
+
+| Test                          | Max MOS diff vs v3.5.0 |
+|-------------------------------|------------------------|
+| Audio (10 conformance cases)  | < 5 × 10⁻¹⁴            |
+| Speech polynomial CA01        | 0.0 (bit-exact)        |
+| Speech lattice CA01           | 0.0 (bit-exact)        |
+
 ## [3.5.0] - 2026-05-26
 
 ### Added
@@ -155,6 +218,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 - Bundled SVR model (`libsvm_nu_svr_model.txt`)
 - GitHub Actions workflow for auto-publish to PyPI via Trusted Publisher
 
+[3.6.0]: https://github.com/talker93/visqol-python/compare/v3.5.0...v3.6.0
 [3.5.0]: https://github.com/talker93/visqol-python/compare/v3.4.0...v3.5.0
 [3.4.0]: https://github.com/talker93/visqol-python/compare/v3.3.6...v3.4.0
 [3.3.6]: https://github.com/talker93/visqol-python/compare/v3.3.5...v3.3.6

{visqol_python-3.5.0 → visqol_python-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visqol-python
-Version: 3.5.0
+Version: 3.6.0
 Summary: ViSQOL - Virtual Speech Quality Objective Listener (Pure Python)
 Author: Shan Jiang
 License-Expression: Apache-2.0
@@ -33,9 +33,12 @@ Provides-Extra: accel
 Requires-Dist: numba>=0.57; extra == "accel"
 Provides-Extra: lattice
 Requires-Dist: ai-edge-litert>=2.1.5; python_version >= "3.10" and extra == "lattice"
+Provides-Extra: fftw
+Requires-Dist: pyfftw>=0.13; extra == "fftw"
 Provides-Extra: all
 Requires-Dist: numba>=0.57; extra == "all"
 Requires-Dist: ai-edge-litert>=2.1.5; python_version >= "3.10" and extra == "all"
+Requires-Dist: pyfftw>=0.13; extra == "all"
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Provides-Extra: dev
@@ -44,6 +47,7 @@ Requires-Dist: ruff>=0.4; extra == "dev"
 Requires-Dist: mypy>=1.8; extra == "dev"
 Requires-Dist: numba>=0.57; extra == "dev"
 Requires-Dist: ai-edge-litert>=2.1.5; python_version >= "3.10" and extra == "dev"
+Requires-Dist: pyfftw>=0.13; extra == "dev"
 Dynamic: license-file
 
 # ViSQOL (Python)
@@ -69,7 +73,8 @@ ViSQOL compares a reference audio signal with a degraded version and outputs a *
   - **Polynomial (fallback)** — legacy exponential fit (`--use_lattice_model=false` in C++)
 - **Pure Python**: no C/C++ compilation required (the optional `[lattice]` extra adds the Google `ai-edge-litert` TFLite runtime as a binary wheel)
 - **Minimal dependencies**: 4 core pip packages (`numpy`, `scipy`, `soundfile`, `libsvm-official`)
-- **Optional Numba acceleration**: `pip install visqol-python[accel]` for JIT-compiled Gammatone filterbank (parallel + fastmath) and DP patch matching — **9× overall speedup**, RTF 0.064 (surpasses C++ estimates)
+- **Optional Numba acceleration**: `pip install visqol-python[accel]` for JIT-compiled Gammatone filterbank (parallel) and a fused NSIM + DP patch matching kernel
+- **Optional pyFFTW backend**: `pip install visqol-python[fftw]` routes alignment / xcorr FFTs through FFTW3 — **~16× overall speedup**, RTF 0.036 (vs C++ estimate 0.093)
 - **Batch & parallel evaluation**: `measure_batch(parallel=True)` for multi-process execution across CPU cores
 - **Fully typed**: PEP 561 `py.typed`, strict mypy, ruff-enforced code style
 
@@ -85,13 +90,19 @@ For **C++-default-equivalent speech mode** (deep-lattice TFLite mapper):
 pip install visqol-python[lattice]   # requires Python ≥ 3.10
 ```
 
-For **Numba-accelerated** Gammatone filtering and DP matching (~9× faster):
+For **Numba-accelerated** Gammatone filtering and the fused NSIM + DP kernel:
 
 ```bash
 pip install visqol-python[accel]
 ```
 
-Install everything (lattice + numba):
+For **FFTW3-backed alignment FFTs** via pyFFTW:
+
+```bash
+pip install visqol-python[fftw]
+```
+
+Install everything (lattice + numba + fftw):
 
 ```bash
 pip install visqol-python[all]
@@ -234,23 +245,26 @@ The `measure()` method returns a `SimilarityResult` object with:
 
 ## Performance
 
-Measured on Apple M-series, Python 3.13:
+Measured on Apple M-series, Python 3.13, audio mode on the `guitar48_stereo` 12.5 s conformance case (3-run average):
 
-### Without Numba (pure Python + NumPy/SciPy)
+| Configuration | RTF | Typical Time | Speedup vs pure Python |
+|---|---|---|---|
+| Pure Python + NumPy/SciPy | 0.58 | ~7 s | 1.0× |
+| + `[accel]` (Numba JIT) | 0.067 | ~0.84 s | 8.7× |
+| + `[accel] [fftw]` (Numba + FFTW3) | **0.036** | **~0.45 s** | **16×** |
 
-| Mode | Avg RTF | Typical Time |
-|------|---------|-------------|
-| Audio (48 kHz) | **0.18x** | ~2.2 s per file pair |
-| Speech (16 kHz) | **0.38x** | ~1 s per file pair |
-
-### With Numba (`pip install visqol-python[accel]`)
+> RTF (Real-Time Factor) < 1.0 means faster than real-time.
+> With Numba + pyFFTW the Python implementation runs at **2.6× the C++ estimated speed** (C++ RTF ≈ 0.093).
 
-| Mode | Avg RTF | Typical Time | Speedup |
-|------|---------|-------------|---------|
-| Audio (48 kHz) | **0.064x** | ~0.8 s per file pair | **9×** |
+Stage-level breakdown of the v3.6.0 fully-accelerated path:
 
-> RTF (Real-Time Factor) < 1.0 means faster than real-time.
-> With Numba acceleration, the Python implementation **surpasses C++ estimated performance** (RTF ≈ 0.093).
+| Stage | Time | % |
+|---|---|---|
+| Gammatone filterbank | 0.179 s | 40% |
+| DP Patch matching (fused NSIM kernel) | 0.131 s | 29% |
+| Global alignment (pyFFTW rfft/irfft) | 0.091 s | 20% |
+| Fine alignment + NSIM | 0.043 s | 10% |
+| Other (SPL, postproc, SVR, …) | 0.003 s | < 1% |
 
 ## Project Structure
 

{visqol_python-3.5.0 → visqol_python-3.6.0}/README.md

@@ -21,7 +21,8 @@ ViSQOL compares a reference audio signal with a degraded version and outputs a *
   - **Polynomial (fallback)** — legacy exponential fit (`--use_lattice_model=false` in C++)
 - **Pure Python**: no C/C++ compilation required (the optional `[lattice]` extra adds the Google `ai-edge-litert` TFLite runtime as a binary wheel)
 - **Minimal dependencies**: 4 core pip packages (`numpy`, `scipy`, `soundfile`, `libsvm-official`)
-- **Optional Numba acceleration**: `pip install visqol-python[accel]` for JIT-compiled Gammatone filterbank (parallel + fastmath) and DP patch matching — **9× overall speedup**, RTF 0.064 (surpasses C++ estimates)
+- **Optional Numba acceleration**: `pip install visqol-python[accel]` for JIT-compiled Gammatone filterbank (parallel) and a fused NSIM + DP patch matching kernel
+- **Optional pyFFTW backend**: `pip install visqol-python[fftw]` routes alignment / xcorr FFTs through FFTW3 — **~16× overall speedup**, RTF 0.036 (vs C++ estimate 0.093)
 - **Batch & parallel evaluation**: `measure_batch(parallel=True)` for multi-process execution across CPU cores
 - **Fully typed**: PEP 561 `py.typed`, strict mypy, ruff-enforced code style
 
@@ -37,13 +38,19 @@ For **C++-default-equivalent speech mode** (deep-lattice TFLite mapper):
 pip install visqol-python[lattice]   # requires Python ≥ 3.10
 ```
 
-For **Numba-accelerated** Gammatone filtering and DP matching (~9× faster):
+For **Numba-accelerated** Gammatone filtering and the fused NSIM + DP kernel:
 
 ```bash
 pip install visqol-python[accel]
 ```
 
-Install everything (lattice + numba):
+For **FFTW3-backed alignment FFTs** via pyFFTW:
+
+```bash
+pip install visqol-python[fftw]
+```
+
+Install everything (lattice + numba + fftw):
 
 ```bash
 pip install visqol-python[all]
@@ -186,23 +193,26 @@ The `measure()` method returns a `SimilarityResult` object with:
 
 ## Performance
 
-Measured on Apple M-series, Python 3.13:
+Measured on Apple M-series, Python 3.13, audio mode on the `guitar48_stereo` 12.5 s conformance case (3-run average):
 
-### Without Numba (pure Python + NumPy/SciPy)
+| Configuration | RTF | Typical Time | Speedup vs pure Python |
+|---|---|---|---|
+| Pure Python + NumPy/SciPy | 0.58 | ~7 s | 1.0× |
+| + `[accel]` (Numba JIT) | 0.067 | ~0.84 s | 8.7× |
+| + `[accel] [fftw]` (Numba + FFTW3) | **0.036** | **~0.45 s** | **16×** |
 
-| Mode | Avg RTF | Typical Time |
-|------|---------|-------------|
-| Audio (48 kHz) | **0.18x** | ~2.2 s per file pair |
-| Speech (16 kHz) | **0.38x** | ~1 s per file pair |
-
-### With Numba (`pip install visqol-python[accel]`)
+> RTF (Real-Time Factor) < 1.0 means faster than real-time.
+> With Numba + pyFFTW the Python implementation runs at **2.6× the C++ estimated speed** (C++ RTF ≈ 0.093).
 
-| Mode | Avg RTF | Typical Time | Speedup |
-|------|---------|-------------|---------|
-| Audio (48 kHz) | **0.064x** | ~0.8 s per file pair | **9×** |
+Stage-level breakdown of the v3.6.0 fully-accelerated path:
 
-> RTF (Real-Time Factor) < 1.0 means faster than real-time.
-> With Numba acceleration, the Python implementation **surpasses C++ estimated performance** (RTF ≈ 0.093).
+| Stage | Time | % |
+|---|---|---|
+| Gammatone filterbank | 0.179 s | 40% |
+| DP Patch matching (fused NSIM kernel) | 0.131 s | 29% |
+| Global alignment (pyFFTW rfft/irfft) | 0.091 s | 20% |
+| Fine alignment + NSIM | 0.043 s | 10% |
+| Other (SPL, postproc, SVR, …) | 0.003 s | < 1% |
 
 ## Project Structure
 

{visqol_python-3.5.0 → visqol_python-3.6.0}/pyproject.toml

@@ -41,9 +41,11 @@ dependencies = [
 [project.optional-dependencies]
 accel = ["numba>=0.57"]
 lattice = ["ai-edge-litert>=2.1.5; python_version >= '3.10'"]
+fftw = ["pyfftw>=0.13"]
 all = [
     "numba>=0.57",
     "ai-edge-litert>=2.1.5; python_version >= '3.10'",
+    "pyfftw>=0.13",
 ]
 test = ["pytest>=7.0"]
 dev = [
@@ -52,6 +54,7 @@ dev = [
     "mypy>=1.8",
     "numba>=0.57",
     "ai-edge-litert>=2.1.5; python_version >= '3.10'",
+    "pyfftw>=0.13",
 ]
 
 [project.urls]
@@ -117,6 +120,7 @@ module = [
     "soundfile.*",
     "numba.*",
     "ai_edge_litert.*",
+    "pyfftw.*",
 ]
 ignore_missing_imports = true
 

{visqol_python-3.5.0 → visqol_python-3.6.0}/visqol/__init__.py

@@ -13,7 +13,7 @@ Usage:
     print(f"MOS-LQO: {result.moslqo}")
 """
 
-__version__: str = "3.5.0"
+__version__: str = "3.6.0"
 
 from visqol.api import ProgressCallback, VisqolApi
 from visqol.audio_utils import AudioSignal

{visqol_python-3.5.0 → visqol_python-3.6.0}/visqol/nsim.py

@@ -15,6 +15,14 @@ from dataclasses import dataclass, field
 import numpy as np
 from numpy.typing import NDArray
 
+from visqol.numba_accel import (
+    _C1,
+    _C3,
+    _GW,
+    _measure_patch_similarity_numba,
+    has_numba,
+)
+
 # 3×3 Gaussian window weights (hardcoded from C++)
 GAUSSIAN_WINDOW: NDArray[np.float64] = np.array(
     [
@@ -91,6 +99,11 @@ def measure_patch_similarity(
 
     Matches C++ ``NeurogramSimiliarityIndexMeasure::MeasurePatchSimilarity``.
 
+    When Numba is available, dispatches to the fused JIT kernel
+    (:func:`visqol.numba_accel._measure_patch_similarity_numba`) — same code
+    path the DP patch matcher uses, so fine realignment shares the same
+    speedup. Falls back to the NumPy implementation when Numba is absent.
+
     Args:
         ref_patch: ``(num_bands, num_frames)`` reference spectrogram patch.
         deg_patch: ``(num_bands, num_frames)`` degraded spectrogram patch.
@@ -99,6 +112,21 @@ def measure_patch_similarity(
         :class:`PatchSimilarityResult` with similarity score and per-band
         statistics.
     """
+    if has_numba():
+        sim_mean, fb_means, fb_stddevs, fb_deg_energy = _measure_patch_similarity_numba(
+            np.ascontiguousarray(ref_patch, dtype=np.float64),
+            np.ascontiguousarray(deg_patch, dtype=np.float64),
+            _GW,
+            _C1,
+            _C3,
+        )
+        return PatchSimilarityResult(
+            similarity=float(sim_mean),
+            freq_band_means=fb_means,
+            freq_band_stddevs=fb_stddevs,
+            freq_band_deg_energy=fb_deg_energy,
+        )
+
     w = GAUSSIAN_WINDOW
 
     # Local means

{visqol_python-3.5.0 → visqol_python-3.6.0}/visqol/numba_accel.py

@@ -79,31 +79,47 @@ _C3: float = (0.03 * 1.0) ** 2 / 2.0  # 0.00045
 
 
 @njit(cache=True)
-def _conv2d_boundary_valid(
-    kernel: NDArray[np.float64],
-    matrix: NDArray[np.float64],
-) -> NDArray[np.float64]:
+def _measure_patch_similarity_numba(
+    ref_patch: NDArray[np.float64],
+    deg_patch: NDArray[np.float64],
+    gw: NDArray[np.float64],
+    c1: float,
+    c3: float,
+) -> tuple[float, NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
     """
-    2-D correlation with edge-replicated padding then 'valid' crop.
+    Compute NSIM similarity — returns
+    ``(mean_similarity, freq_band_means, freq_band_stddevs, freq_band_deg_energy)``.
 
-    Equivalent to ``nsim._valid_2d_conv_with_boundary`` but pure loops
-    so Numba can JIT-compile it.
+    Fused kernel: the 5 separate 2-D convolutions (μ_r, μ_d, ref², deg²,
+    ref·deg) and the intensity/structure recombination are merged into a
+    single (r, c) double loop. Each patch element is read from L1 once per
+    visit instead of five times, and there are no intermediate (rows×cols)
+    matrices held in memory between the convs.
+
+    Bit-exact with the split-conv path: per-output accumulators are summed
+    in the same (kr, kc) order over the same per-neighbour products
+    ``w·ref``, ``w·(ref·ref)``, ``w·(deg·deg)``, ``w·(ref·deg)`` that
+    NumPy's elementwise products + the original conv loop produced, so
+    IEEE-754 results match to the last ULP.
     """
-    rows, cols = matrix.shape
-    kh, kw = kernel.shape
+    rows, cols = ref_patch.shape
+    kh, kw = gw.shape
     pad_h = kh // 2
     pad_w = kw // 2
 
-    out = np.empty((rows, cols), dtype=np.float64)
+    sim_map = np.empty((rows, cols), dtype=np.float64)
 
     for r in range(rows):
         for c in range(cols):
-            s = 0.0
+            sum_ref = 0.0
+            sum_deg = 0.0
+            sum_ref_sq = 0.0
+            sum_deg_sq = 0.0
+            sum_ref_deg = 0.0
             for kr in range(kh):
                 for kc in range(kw):
                     ir = r + kr - pad_h
                     ic = c + kc - pad_w
-                    # Clamp to edge (replicate boundary)
                     if ir < 0:
                         ir = 0
                     elif ir >= rows:
@@ -112,50 +128,39 @@ def _conv2d_boundary_valid(
                         ic = 0
                     elif ic >= cols:
                         ic = cols - 1
-                    s += kernel[kr, kc] * matrix[ir, ic]
-            out[r, c] = s
-    return out
-
-
-@njit(cache=True)
-def _measure_patch_similarity_numba(
-    ref_patch: NDArray[np.float64],
-    deg_patch: NDArray[np.float64],
-    gw: NDArray[np.float64],
-    c1: float,
-    c3: float,
-) -> tuple[float, NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
-    """
-    Compute NSIM similarity — returns
-    ``(mean_similarity, freq_band_means, freq_band_stddevs, freq_band_deg_energy)``.
-
-    Pure-numeric kernel; no Python objects so Numba can compile it.
-    """
-    mu_r = _conv2d_boundary_valid(gw, ref_patch)
-    mu_d = _conv2d_boundary_valid(gw, deg_patch)
-
-    ref_mu_sq = mu_r * mu_r
-    deg_mu_sq = mu_d * mu_d
-    mu_r_mu_d = mu_r * mu_d
-
-    sigma_r_sq = _conv2d_boundary_valid(gw, ref_patch * ref_patch) - ref_mu_sq
-    sigma_d_sq = _conv2d_boundary_valid(gw, deg_patch * deg_patch) - deg_mu_sq
-    sigma_r_d = _conv2d_boundary_valid(gw, ref_patch * deg_patch) - mu_r_mu_d
-
-    # Intensity component
-    intensity = (2.0 * mu_r_mu_d + c1) / (ref_mu_sq + deg_mu_sq + c1)
-
-    # Structure component
-    rows, cols = ref_patch.shape
-    structure = np.empty((rows, cols), dtype=np.float64)
-    for r in range(rows):
-        for c in range(cols):
-            numer = sigma_r_d[r, c] + c3
-            vp = sigma_r_sq[r, c] * sigma_d_sq[r, c]
+                    w = gw[kr, kc]
+                    ref_v = ref_patch[ir, ic]
+                    deg_v = deg_patch[ir, ic]
+                    # Element-wise products first, then weight — matches the
+                    # NumPy `ref_patch * ref_patch` -> conv ordering used by
+                    # the pre-fusion path so each ULP of rounding is identical.
+                    ref_sq = ref_v * ref_v
+                    deg_sq = deg_v * deg_v
+                    ref_deg_v = ref_v * deg_v
+                    sum_ref += w * ref_v
+                    sum_deg += w * deg_v
+                    sum_ref_sq += w * ref_sq
+                    sum_deg_sq += w * deg_sq
+                    sum_ref_deg += w * ref_deg_v
+
+            mu_r = sum_ref
+            mu_d = sum_deg
+            ref_mu_sq = mu_r * mu_r
+            deg_mu_sq = mu_d * mu_d
+            mu_r_mu_d = mu_r * mu_d
+
+            sigma_r_sq = sum_ref_sq - ref_mu_sq
+            sigma_d_sq = sum_deg_sq - deg_mu_sq
+            sigma_r_d = sum_ref_deg - mu_r_mu_d
+
+            intensity = (2.0 * mu_r_mu_d + c1) / (ref_mu_sq + deg_mu_sq + c1)
+
+            numer = sigma_r_d + c3
+            vp = sigma_r_sq * sigma_d_sq
             denom = c3 if vp < 0.0 else np.sqrt(vp) + c3
-            structure[r, c] = numer / denom
+            structure = numer / denom
 
-    sim_map = intensity * structure
+            sim_map[r, c] = intensity * structure
 
     # Per-band statistics
     num_bands = rows

visqol_python-3.6.0/visqol/signal_utils.py

@@ -0,0 +1,167 @@
+"""
+Signal processing utilities: envelope, cross-correlation, normalization.
+
+Corresponds to C++ files: envelope.cc, xcorr.cc, misc_math.cc
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+import numpy as np
+import scipy.fft
+from numpy.typing import NDArray
+from scipy.fft import ifft, irfft, rfft
+
+# Optional pyFFTW backend. pyFFTW wraps FFTW3, which is 2-3× faster than
+# scipy's pocketfft on the sizes used by ViSQOL alignment (~256k–1M points).
+# When installed, ``_fft_backend()`` routes every ``scipy.fft.fft`` /
+# ``scipy.fft.ifft`` call inside this module through pyFFTW. Results match
+# scipy at the ULP level (FFTW uses split-radix and rounds slightly
+# differently than pocketfft).
+try:
+    import pyfftw
+    import pyfftw.interfaces.scipy_fft as _pyfftw_scipy_fft
+
+    pyfftw.interfaces.cache.enable()
+    # Keep plans for 60 s so consecutive alignments of the same audio length
+    # (e.g. fine realignment, batch evaluation) reuse the cached FFTW plan.
+    pyfftw.interfaces.cache.set_keepalive_time(60.0)
+    _HAS_PYFFTW = True
+except ImportError:
+    _pyfftw_scipy_fft = None  # type: ignore[assignment,unused-ignore]
+    _HAS_PYFFTW = False
+
+
+@contextmanager
+def _fft_backend() -> Iterator[None]:
+    """Route scipy.fft calls through pyFFTW for the duration of the block."""
+    if _HAS_PYFFTW:
+        with scipy.fft.set_backend(_pyfftw_scipy_fft):
+            yield
+    else:
+        yield
+
+
+def _hilbert(x: NDArray[np.float64]) -> NDArray[np.complex128]:
+    """
+    Hilbert transform — drop-in replacement for ``scipy.signal.hilbert``
+    that exploits the real-valued input via ``rfft``.
+
+    ``scipy.signal.hilbert`` does ``fft(x)`` (full complex spectrum), masks
+    out the negative half, and ``ifft``s back. Since the input is real,
+    the negative half is just the conjugate of the positive half — wholly
+    redundant work. ``rfft`` computes only the positive half (length
+    ``N//2 + 1``), so we save ~50 % of the forward-transform work. We
+    then build the analytic spectrum at full length (DC + 2·positive
+    freqs + Nyquist + zeros) and ``ifft`` once.
+
+    Numerically equivalent to ``scipy.signal.hilbert`` to within ULP
+    rounding (rfft uses a different internal algorithm than the complex
+    fft and rounds slightly differently — verified < 5e-14 MOS drift on
+    audio conformance, bit-exact on speech).
+    """
+    n = len(x)
+    half = rfft(x)  # length n // 2 + 1
+
+    spectrum = np.zeros(n, dtype=np.complex128)
+    spectrum[0] = half[0]
+    if n % 2 == 0:
+        # Nyquist at bin n//2 stays at amplitude 1, positive freqs doubled.
+        spectrum[1 : n // 2] = 2.0 * half[1 : n // 2]
+        spectrum[n // 2] = half[n // 2]
+    else:
+        # No Nyquist bin for odd N; all positive freqs doubled.
+        spectrum[1 : (n + 1) // 2] = 2.0 * half[1 : (n + 1) // 2]
+    return np.asarray(ifft(spectrum), dtype=np.complex128)
+
+
+def upper_envelope(sig: NDArray[np.float64]) -> NDArray[np.float64]:
+    """
+    Calculate the upper envelope using Hilbert transform.
+
+    Matches C++ ``Envelope::CalcUpperEnv`` which:
+
+    1. Centers signal by subtracting mean
+    2. Computes Hilbert transform
+    3. Takes absolute value (amplitude envelope)
+    4. Adds mean back
+    """
+    mean_val: float = float(np.mean(sig))
+    centered = sig - mean_val
+    with _fft_backend():
+        analytic = _hilbert(centered)
+    env: NDArray[np.float64] = np.abs(analytic) + mean_val
+    return env
+
+
+def find_best_lag(ref: NDArray[np.float64], deg: NDArray[np.float64]) -> int:
+    """
+    Find the lag that maximises cross-correlation between two signals.
+
+    Returns the lag (in samples) — positive means *deg* is delayed
+    relative to *ref*.
+
+    Matches C++ ``XCorr::FindLowestLagIndex`` which uses FFT-based
+    cross-correlation.
+    """
+    max_lag: int = max(len(ref), len(deg)) - 1
+
+    # Pad to same length
+    n = max(len(ref), len(deg))
+    ref_padded = np.zeros(n)
+    deg_padded = np.zeros(n)
+    ref_padded[: len(ref)] = ref
+    deg_padded[: len(deg)] = deg
+
+    # FFT-based cross-correlation
+    # fft_points = next power of 2 >= 2*n - 1
+    fft_points = 1
+    while fft_points < 2 * n - 1:
+        fft_points *= 2
+
+    with _fft_backend():
+        # Real-input FFT: ref/deg are real, so rfft only computes the
+        # positive-frequency half (length fft_points // 2 + 1) and irfft
+        # recovers the full real-valued xcorr. ~2× cheaper than fft+ifft
+        # with the np.real() truncation the previous implementation used.
+        fft_ref = rfft(ref_padded, n=fft_points)
+        fft_deg = rfft(deg_padded, n=fft_points)
+        pointwise = fft_ref * np.conj(fft_deg)
+        xcorr_full: NDArray[np.float64] = irfft(pointwise, n=fft_points)
+
+    # Build correlation vector: [negative lags, positive lags]. The
+    # previous implementation called ``.tolist()`` on the two slices and
+    # ran builtin argmax over a Python list — for ~1 M samples that was
+    # 30+ ms of pure interpreter overhead per call. ``np.concatenate``
+    # plus ``np.argmax`` does the same thing entirely in C.
+    corrs = np.concatenate((xcorr_full[-max_lag:], xcorr_full[: max_lag + 1]))
+
+    best_idx = int(np.argmax(corrs))
+    return best_idx - max_lag
+
+
+def normalize(mat: NDArray[np.float64]) -> NDArray[np.float64]:
+    """
+    Peak-normalize a matrix / vector so the maximum element becomes 1.0.
+
+    Matches C++ ``MiscMath::Normalize``, which divides every element by
+    ``max(mat)`` (it does **not** subtract the minimum). For typical
+    bipolar audio in ``[-peak, +peak]`` this yields output in ``[-1, +1]``,
+    preserving the signal's DC sign. Previous min-max scaling shifted the
+    signal positive and broke speech-mode VAD (GH issue #1 follow-up).
+    """
+    max_val = np.max(mat)
+    if max_val == 0:
+        return np.zeros_like(mat)
+    return np.asarray(mat / max_val, dtype=np.float64)
+
+
+def exponential_from_fit(x: float, a: float, b: float, x0: float) -> float:
+    """
+    Evaluate exponential function: ``a + exp(b * (x - x0))``.
+
+    Matches C++ ``MiscMath::ExponentialFromFit``.
+    """
+    return float(a + np.exp(b * (x - x0)))

{visqol_python-3.5.0 → visqol_python-3.6.0}/visqol_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visqol-python
-Version: 3.5.0
+Version: 3.6.0
 Summary: ViSQOL - Virtual Speech Quality Objective Listener (Pure Python)
 Author: Shan Jiang
 License-Expression: Apache-2.0
@@ -33,9 +33,12 @@ Provides-Extra: accel
 Requires-Dist: numba>=0.57; extra == "accel"
 Provides-Extra: lattice
 Requires-Dist: ai-edge-litert>=2.1.5; python_version >= "3.10" and extra == "lattice"
+Provides-Extra: fftw
+Requires-Dist: pyfftw>=0.13; extra == "fftw"
 Provides-Extra: all
 Requires-Dist: numba>=0.57; extra == "all"
 Requires-Dist: ai-edge-litert>=2.1.5; python_version >= "3.10" and extra == "all"
+Requires-Dist: pyfftw>=0.13; extra == "all"
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Provides-Extra: dev
@@ -44,6 +47,7 @@ Requires-Dist: ruff>=0.4; extra == "dev"
 Requires-Dist: mypy>=1.8; extra == "dev"
 Requires-Dist: numba>=0.57; extra == "dev"
 Requires-Dist: ai-edge-litert>=2.1.5; python_version >= "3.10" and extra == "dev"
+Requires-Dist: pyfftw>=0.13; extra == "dev"
 Dynamic: license-file
 
 # ViSQOL (Python)
@@ -69,7 +73,8 @@ ViSQOL compares a reference audio signal with a degraded version and outputs a *
   - **Polynomial (fallback)** — legacy exponential fit (`--use_lattice_model=false` in C++)
 - **Pure Python**: no C/C++ compilation required (the optional `[lattice]` extra adds the Google `ai-edge-litert` TFLite runtime as a binary wheel)
 - **Minimal dependencies**: 4 core pip packages (`numpy`, `scipy`, `soundfile`, `libsvm-official`)
-- **Optional Numba acceleration**: `pip install visqol-python[accel]` for JIT-compiled Gammatone filterbank (parallel + fastmath) and DP patch matching — **9× overall speedup**, RTF 0.064 (surpasses C++ estimates)
+- **Optional Numba acceleration**: `pip install visqol-python[accel]` for JIT-compiled Gammatone filterbank (parallel) and a fused NSIM + DP patch matching kernel
+- **Optional pyFFTW backend**: `pip install visqol-python[fftw]` routes alignment / xcorr FFTs through FFTW3 — **~16× overall speedup**, RTF 0.036 (vs C++ estimate 0.093)
 - **Batch & parallel evaluation**: `measure_batch(parallel=True)` for multi-process execution across CPU cores
 - **Fully typed**: PEP 561 `py.typed`, strict mypy, ruff-enforced code style
 
@@ -85,13 +90,19 @@ For **C++-default-equivalent speech mode** (deep-lattice TFLite mapper):
 pip install visqol-python[lattice]   # requires Python ≥ 3.10
 ```
 
-For **Numba-accelerated** Gammatone filtering and DP matching (~9× faster):
+For **Numba-accelerated** Gammatone filtering and the fused NSIM + DP kernel:
 
 ```bash
 pip install visqol-python[accel]
 ```
 
-Install everything (lattice + numba):
+For **FFTW3-backed alignment FFTs** via pyFFTW:
+
+```bash
+pip install visqol-python[fftw]
+```
+
+Install everything (lattice + numba + fftw):
 
 ```bash
 pip install visqol-python[all]
@@ -234,23 +245,26 @@ The `measure()` method returns a `SimilarityResult` object with:
 
 ## Performance
 
-Measured on Apple M-series, Python 3.13:
+Measured on Apple M-series, Python 3.13, audio mode on the `guitar48_stereo` 12.5 s conformance case (3-run average):
 
-### Without Numba (pure Python + NumPy/SciPy)
+| Configuration | RTF | Typical Time | Speedup vs pure Python |
+|---|---|---|---|
+| Pure Python + NumPy/SciPy | 0.58 | ~7 s | 1.0× |
+| + `[accel]` (Numba JIT) | 0.067 | ~0.84 s | 8.7× |
+| + `[accel] [fftw]` (Numba + FFTW3) | **0.036** | **~0.45 s** | **16×** |
 
-| Mode | Avg RTF | Typical Time |
-|------|---------|-------------|
-| Audio (48 kHz) | **0.18x** | ~2.2 s per file pair |
-| Speech (16 kHz) | **0.38x** | ~1 s per file pair |
-
-### With Numba (`pip install visqol-python[accel]`)
+> RTF (Real-Time Factor) < 1.0 means faster than real-time.
+> With Numba + pyFFTW the Python implementation runs at **2.6× the C++ estimated speed** (C++ RTF ≈ 0.093).
 
-| Mode | Avg RTF | Typical Time | Speedup |
-|------|---------|-------------|---------|
-| Audio (48 kHz) | **0.064x** | ~0.8 s per file pair | **9×** |
+Stage-level breakdown of the v3.6.0 fully-accelerated path:
 
-> RTF (Real-Time Factor) < 1.0 means faster than real-time.
-> With Numba acceleration, the Python implementation **surpasses C++ estimated performance** (RTF ≈ 0.093).
+| Stage | Time | % |
+|---|---|---|
+| Gammatone filterbank | 0.179 s | 40% |
+| DP Patch matching (fused NSIM kernel) | 0.131 s | 29% |
+| Global alignment (pyFFTW rfft/irfft) | 0.091 s | 20% |
+| Fine alignment + NSIM | 0.043 s | 10% |
+| Other (SPL, postproc, SVR, …) | 0.003 s | < 1% |
 
 ## Project Structure
 

{visqol_python-3.5.0 → visqol_python-3.6.0}/visqol_python.egg-info/requires.txt

@@ -8,6 +8,7 @@ numba>=0.57
 
 [all]
 numba>=0.57
+pyfftw>=0.13
 
 [all:python_version >= "3.10"]
 ai-edge-litert>=2.1.5
@@ -17,10 +18,14 @@ pytest>=7.0
 ruff>=0.4
 mypy>=1.8
 numba>=0.57
+pyfftw>=0.13
 
 [dev:python_version >= "3.10"]
 ai-edge-litert>=2.1.5
 
+[fftw]
+pyfftw>=0.13
+
 [lattice]
 
 [lattice:python_version >= "3.10"]

visqol_python-3.5.0/visqol/signal_utils.py

@@ -1,94 +0,0 @@
-"""
-Signal processing utilities: envelope, cross-correlation, normalization.
-
-Corresponds to C++ files: envelope.cc, xcorr.cc, misc_math.cc
-"""
-
-from __future__ import annotations
-
-import numpy as np
-from numpy.typing import NDArray
-from scipy import signal as scipy_signal
-from scipy.fft import fft, ifft
-
-
-def upper_envelope(sig: NDArray[np.float64]) -> NDArray[np.float64]:
-    """
-    Calculate the upper envelope using Hilbert transform.
-
-    Matches C++ ``Envelope::CalcUpperEnv`` which:
-
-    1. Centers signal by subtracting mean
-    2. Computes Hilbert transform
-    3. Takes absolute value (amplitude envelope)
-    4. Adds mean back
-    """
-    mean_val: float = float(np.mean(sig))
-    centered = sig - mean_val
-    analytic = scipy_signal.hilbert(centered)
-    env: NDArray[np.float64] = np.abs(analytic) + mean_val
-    return env
-
-
-def find_best_lag(ref: NDArray[np.float64], deg: NDArray[np.float64]) -> int:
-    """
-    Find the lag that maximises cross-correlation between two signals.
-
-    Returns the lag (in samples) — positive means *deg* is delayed
-    relative to *ref*.
-
-    Matches C++ ``XCorr::FindLowestLagIndex`` which uses FFT-based
-    cross-correlation.
-    """
-    max_lag: int = max(len(ref), len(deg)) - 1
-
-    # Pad to same length
-    n = max(len(ref), len(deg))
-    ref_padded = np.zeros(n)
-    deg_padded = np.zeros(n)
-    ref_padded[: len(ref)] = ref
-    deg_padded[: len(deg)] = deg
-
-    # FFT-based cross-correlation
-    # fft_points = next power of 2 >= 2*n - 1
-    fft_points = 1
-    while fft_points < 2 * n - 1:
-        fft_points *= 2
-
-    fft_ref = fft(ref_padded, n=fft_points)
-    fft_deg = fft(deg_padded, n=fft_points)
-    pointwise = fft_ref * np.conj(fft_deg)
-    xcorr_full: NDArray[np.float64] = np.real(ifft(pointwise))
-
-    # Build correlation vector: [negative lags, positive lags]
-    neg_corrs = xcorr_full[-max_lag:].tolist()
-    pos_corrs = xcorr_full[: max_lag + 1].tolist()
-    corrs = neg_corrs + pos_corrs
-
-    best_idx = int(np.argmax(corrs))
-    return best_idx - max_lag
-
-
-def normalize(mat: NDArray[np.float64]) -> NDArray[np.float64]:
-    """
-    Peak-normalize a matrix / vector so the maximum element becomes 1.0.
-
-    Matches C++ ``MiscMath::Normalize``, which divides every element by
-    ``max(mat)`` (it does **not** subtract the minimum). For typical
-    bipolar audio in ``[-peak, +peak]`` this yields output in ``[-1, +1]``,
-    preserving the signal's DC sign. Previous min-max scaling shifted the
-    signal positive and broke speech-mode VAD (GH issue #1 follow-up).
-    """
-    max_val = np.max(mat)
-    if max_val == 0:
-        return np.zeros_like(mat)
-    return np.asarray(mat / max_val, dtype=np.float64)
-
-
-def exponential_from_fit(x: float, a: float, b: float, x0: float) -> float:
-    """
-    Evaluate exponential function: ``a + exp(b * (x - x0))``.
-
-    Matches C++ ``MiscMath::ExponentialFromFit``.
-    """
-    return float(a + np.exp(b * (x - x0)))