visqol-python 3.7.0__tar.gz → 3.8.0__tar.gz

{visqol_python-3.7.0 → visqol_python-3.8.0}/CHANGELOG.md

@@ -4,6 +4,45 @@ 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/).
 
+## [Unreleased]
+
+## [3.8.0] - 2026-09-20
+
+### Performance
+- Cache reference-patch statistics, replace DP predecessor scans with prefix
+  maxima, and evaluate independent candidates in parallel. Preserve the original
+  tie rule and reduction order.
+- Fuse four Gammatone IIR stages with RMS accumulation, removing the large
+  intermediate buffer while preserving FP64 arithmetic and filter resets.
+- Keep scoring models, search windows, alignment stages and public API unchanged.
+  Recorded warmed comparisons against accelerated v3.7.0 are 2.57× on Apple M4
+  Pro, 2.80× on AMD EPYC 9K84 and 2.29× on Windows Core Ultra 9 285H; see the
+  [protocol and raw measurements](docs/portable-cpu-windows-validation.md).
+
+### Fixed
+- Support Windows Unicode SVR model paths using the native filename encoding,
+  short filenames and temporary copies. Try the system temp directory if the
+  user's temp path is also unusable. Invalid models fail during initialization.
+- Read lattice model bytes through Python so Unicode installation paths work.
+- Cap automatic Windows process counts at 61 and document the spawn entry-point
+  guard and the cost of starting pools for small batches.
+- Keep benchmark scripts out of pytest collection and reject invalid explicit
+  conformance-data paths. Resolve NumPy/SciPy together and exclude unsupported
+  NumPy 1.x/Python 3.13 combinations.
+
+### Tests and release validation
+- Retain the frozen v3.7.0 kernel oracles, exact output checks, backend numerical
+  comparisons, real process-pool tests and Windows filename/CLI regressions.
+- Tighten C++ MOS tolerances to 0.0002 for audio and 0.003 for speech, separately
+  from the exact old/new checks. Verify the official audio data by Git blob SHA.
+- Validate both FFT backends on Linux, macOS and Windows; expand Windows to
+  Python 3.10–3.13 and exercise older compatible dependency combinations.
+- Add long-audio, speech, batch and fresh-cache comparisons. Include the test
+  helpers, benchmarks and validation documents in sdists; keep wheels package-only.
+- Gate publication on tag/version/changelog checks, full CI of the tagged commit
+  and installation of the built wheel in Unicode environments on three platforms.
+  Publish the tested artifact without rebuilding it. See [releasing](docs/releasing.md).
+
 ## [3.7.0] - 2026-05-30
 
 ### Fixed
@@ -257,6 +296,8 @@ All v3.5.0 conformance baselines preserved within ULP precision:
 - Bundled SVR model (`libsvm_nu_svr_model.txt`)
 - GitHub Actions workflow for auto-publish to PyPI via Trusted Publisher
 
+[Unreleased]: https://github.com/talker93/visqol-python/compare/v3.7.0...HEAD
+[3.8.0]: https://github.com/talker93/visqol-python/compare/v3.7.0...v3.8.0
 [3.7.0]: https://github.com/talker93/visqol-python/compare/v3.6.0...v3.7.0
 [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

{visqol_python-3.7.0 → visqol_python-3.8.0}/CONTRIBUTING.md

@@ -37,6 +37,29 @@ pytest tests/test_quick.py -v
 pytest tests/test_conformance.py -v --testdata /path/to/visqol/testdata
 ```
 
+On Windows PowerShell, an isolated setup with all optional backends is:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
+.\.venv\Scripts\python.exe -m pytest tests -v
+```
+
+The normal test suite includes real `spawn` multiprocessing, Unicode file
+paths, and numerical comparisons of Numba/FFTW against the fallback paths.
+Optional backend tests skip when their dependencies are absent; conformance
+tests need the official testdata. Experimental `bench_*.py` scripts are not
+collected by pytest.
+
+For official testdata setup, repeatable performance measurements and the
+Windows compatibility results, see [Windows validation](docs/windows-validation.md).
+
+For accelerated changes, fetch verified official data with
+`python tests/fetch_conformance_data.py` and run both FFT backends as described
+in [release validation](docs/releasing.md). Preserve the frozen v3.7.0 kernels;
+compare every public result field against them. The reusable CI workflow also
+checks installed wheels and older compatible dependency combinations.
+
 ## Code Style
 
 - **Type hints**: All public functions and methods must include type annotations.

visqol_python-3.8.0/MANIFEST.in

@@ -0,0 +1,18 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+recursive-include visqol/model *.txt
+recursive-include docs *.md *.json
+include tests/_*.py
+include tests/conftest.py
+include tests/test_*.py
+include tests/bench_portable.py
+include tests/bench_platform.py
+include tests/bench_release.py
+include tests/check_validation.py
+include tests/verify_distribution.py
+include tests/verify_release.py
+include tests/requirements-min-*.txt
+include tests/fetch_conformance_data.py
+include tests/conformance_files.json

{visqol_python-3.7.0/visqol_python.egg-info → visqol_python-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: visqol-python
-Version: 3.7.0
+Version: 3.8.0
 Summary: ViSQOL - Virtual Speech Quality Objective Listener (Pure Python)
 Author: Shan Jiang
 License-Expression: Apache-2.0
@@ -70,10 +70,10 @@ ViSQOL compares a reference audio signal with a degraded version and outputs a *
 - **Two speech quality mappers** matching C++ ViSQOL:
   - **Lattice (default)** — deep-lattice TFLite network (`--use_lattice_model=true` in C++); requires the optional `[lattice]` extra
   - **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)
+- **Python scoring implementation**: installable with pip; some native dependencies need a compiler when a wheel is unavailable (see [platform setup](docs/portable-cpu-optimization.md))
 - **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) 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)
+- **Optional Numba acceleration**: `pip install visqol-python[accel]` for parallel Gammatone filtering and DP patch matching, preserving strict FP64 arithmetic
+- **Optional pyFFTW backend**: `pip install visqol-python[fftw]` routes alignment and cross-correlation FFTs through FFTW3; see [Performance](#performance) for version comparisons
 - **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
 
@@ -158,31 +158,43 @@ print(f"MOS-LQO: {result.moslqo:.4f}")
 ```python
 from visqol import VisqolApi
 
-api = VisqolApi()
-api.create(mode="audio")
 
-file_pairs = [
-    ("ref1.wav", "deg1.wav"),
-    ("ref2.wav", "deg2.wav"),
-    ("ref3.wav", "deg3.wav"),
-]
-
-# Sequential with progress callback
-results = api.measure_batch(
-    file_pairs,
-    progress_callback=lambda done, total: print(f"{done}/{total}"),
-)
-
-# Multi-process parallel (uses all CPU cores)
-results = api.measure_batch(file_pairs, parallel=True, max_workers=4)
-
-for pair, result in zip(file_pairs, results):
-    if isinstance(result, Exception):
-        print(f"{pair}: FAILED — {result}")
-    else:
-        print(f"{pair}: MOS-LQO = {result.moslqo:.4f}")
+def main():
+    api = VisqolApi()
+    api.create(mode="audio")
+
+    file_pairs = [
+        ("ref1.wav", "deg1.wav"),
+        ("ref2.wav", "deg2.wav"),
+        ("ref3.wav", "deg3.wav"),
+    ]
+
+    # Sequential with progress callback
+    results = api.measure_batch(
+        file_pairs,
+        parallel=False,
+        progress_callback=lambda done, total: print(f"{done}/{total}"),
+    )
+
+    # Multi-process parallel
+    results = api.measure_batch(file_pairs, parallel=True, max_workers=4)
+
+    for pair, result in zip(file_pairs, results):
+        if isinstance(result, Exception):
+            print(f"{pair}: FAILED — {result}")
+        else:
+            print(f"{pair}: MOS-LQO = {result.moslqo:.4f}")
+
+
+if __name__ == "__main__":
+    main()
 ```
 
+Save parallel batch code in a Python script and keep the `__main__` guard:
+Windows starts fresh Python processes that import the script. For notebooks
+or interactive sessions, use `parallel=False`. Process startup can make small
+batches slower than sequential evaluation.
+
 ### Command Line
 
 ```bash
@@ -244,26 +256,34 @@ The `measure()` method returns a `SimilarityResult` object with:
 
 ## Performance
 
-Measured on Apple M-series, Python 3.13, audio mode on the `guitar48_stereo` 12.5 s conformance case (3-run average):
-
-| 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×** |
-
-> 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).
-
-Stage-level breakdown of the v3.6.0 fully-accelerated path:
-
-| 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% |
+The v3.8.0 CPU kernels cache reference statistics, parallelize independent
+patch candidates and fuse Gammatone filtering with energy accumulation.
+They preserve scoring models, search ranges, both alignment stages and FP64
+arithmetic. Install `visqol-python[accel,fftw]` to use the measured path.
+
+Same-machine comparisons against **accelerated v3.7.0**, recorded during
+kernel validation:
+
+| Platform / CPU | v3.7.0 median | Optimized median | Speedup |
+|---|---:|---:|---:|
+| macOS arm64 / Apple M4 Pro | 1.080 s | 0.421 s | 2.57× |
+| Linux x86-64 / AMD EPYC 9K84 | 1.510 s | 0.540 s | 2.80× |
+| Windows x86-64 / Intel Core Ultra 9 285H | 1.074 s | 0.469 s | 2.29× |
+
+Protocol: the same 12.454-second official guitar case, four Numba threads,
+Numba 0.65.1, pyFFTW 0.15.0, five-run medians after warm-up, excluding WAV I/O
+and first-use compilation. All tested old/new output fields were exactly equal
+within each platform/backend. These ratios describe that workload; cold starts,
+longer audio and batch process startup are measured separately by
+`tests/bench_release.py`. Set `NUMBA_NUM_THREADS` before importing the package,
+and budget workers × threads when using process pools.
+
+See the [measurement records](docs/portable-cpu-windows-validation.md),
+[integrated validation and workload results](docs/v3.8.0-validation.md), and
+[release validation procedure](docs/releasing.md). The earlier Windows
+[approximately 10× result](docs/windows-validation.md) compared accelerator
+configurations within v3.7.0. Historical v3.6.0 measurements remain in the
+[CHANGELOG](CHANGELOG.md); they predate the v3.7.0 alignment correction.
 
 ## Project Structure
 

{visqol_python-3.7.0 → visqol_python-3.8.0}/README.md

@@ -19,10 +19,10 @@ ViSQOL compares a reference audio signal with a degraded version and outputs a *
 - **Two speech quality mappers** matching C++ ViSQOL:
   - **Lattice (default)** — deep-lattice TFLite network (`--use_lattice_model=true` in C++); requires the optional `[lattice]` extra
   - **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)
+- **Python scoring implementation**: installable with pip; some native dependencies need a compiler when a wheel is unavailable (see [platform setup](docs/portable-cpu-optimization.md))
 - **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) 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)
+- **Optional Numba acceleration**: `pip install visqol-python[accel]` for parallel Gammatone filtering and DP patch matching, preserving strict FP64 arithmetic
+- **Optional pyFFTW backend**: `pip install visqol-python[fftw]` routes alignment and cross-correlation FFTs through FFTW3; see [Performance](#performance) for version comparisons
 - **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
 
@@ -107,31 +107,43 @@ print(f"MOS-LQO: {result.moslqo:.4f}")
 ```python
 from visqol import VisqolApi
 
-api = VisqolApi()
-api.create(mode="audio")
 
-file_pairs = [
-    ("ref1.wav", "deg1.wav"),
-    ("ref2.wav", "deg2.wav"),
-    ("ref3.wav", "deg3.wav"),
-]
-
-# Sequential with progress callback
-results = api.measure_batch(
-    file_pairs,
-    progress_callback=lambda done, total: print(f"{done}/{total}"),
-)
-
-# Multi-process parallel (uses all CPU cores)
-results = api.measure_batch(file_pairs, parallel=True, max_workers=4)
-
-for pair, result in zip(file_pairs, results):
-    if isinstance(result, Exception):
-        print(f"{pair}: FAILED — {result}")
-    else:
-        print(f"{pair}: MOS-LQO = {result.moslqo:.4f}")
+def main():
+    api = VisqolApi()
+    api.create(mode="audio")
+
+    file_pairs = [
+        ("ref1.wav", "deg1.wav"),
+        ("ref2.wav", "deg2.wav"),
+        ("ref3.wav", "deg3.wav"),
+    ]
+
+    # Sequential with progress callback
+    results = api.measure_batch(
+        file_pairs,
+        parallel=False,
+        progress_callback=lambda done, total: print(f"{done}/{total}"),
+    )
+
+    # Multi-process parallel
+    results = api.measure_batch(file_pairs, parallel=True, max_workers=4)
+
+    for pair, result in zip(file_pairs, results):
+        if isinstance(result, Exception):
+            print(f"{pair}: FAILED — {result}")
+        else:
+            print(f"{pair}: MOS-LQO = {result.moslqo:.4f}")
+
+
+if __name__ == "__main__":
+    main()
 ```
 
+Save parallel batch code in a Python script and keep the `__main__` guard:
+Windows starts fresh Python processes that import the script. For notebooks
+or interactive sessions, use `parallel=False`. Process startup can make small
+batches slower than sequential evaluation.
+
 ### Command Line
 
 ```bash
@@ -193,26 +205,34 @@ The `measure()` method returns a `SimilarityResult` object with:
 
 ## Performance
 
-Measured on Apple M-series, Python 3.13, audio mode on the `guitar48_stereo` 12.5 s conformance case (3-run average):
-
-| 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×** |
-
-> 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).
-
-Stage-level breakdown of the v3.6.0 fully-accelerated path:
-
-| 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% |
+The v3.8.0 CPU kernels cache reference statistics, parallelize independent
+patch candidates and fuse Gammatone filtering with energy accumulation.
+They preserve scoring models, search ranges, both alignment stages and FP64
+arithmetic. Install `visqol-python[accel,fftw]` to use the measured path.
+
+Same-machine comparisons against **accelerated v3.7.0**, recorded during
+kernel validation:
+
+| Platform / CPU | v3.7.0 median | Optimized median | Speedup |
+|---|---:|---:|---:|
+| macOS arm64 / Apple M4 Pro | 1.080 s | 0.421 s | 2.57× |
+| Linux x86-64 / AMD EPYC 9K84 | 1.510 s | 0.540 s | 2.80× |
+| Windows x86-64 / Intel Core Ultra 9 285H | 1.074 s | 0.469 s | 2.29× |
+
+Protocol: the same 12.454-second official guitar case, four Numba threads,
+Numba 0.65.1, pyFFTW 0.15.0, five-run medians after warm-up, excluding WAV I/O
+and first-use compilation. All tested old/new output fields were exactly equal
+within each platform/backend. These ratios describe that workload; cold starts,
+longer audio and batch process startup are measured separately by
+`tests/bench_release.py`. Set `NUMBA_NUM_THREADS` before importing the package,
+and budget workers × threads when using process pools.
+
+See the [measurement records](docs/portable-cpu-windows-validation.md),
+[integrated validation and workload results](docs/v3.8.0-validation.md), and
+[release validation procedure](docs/releasing.md). The earlier Windows
+[approximately 10× result](docs/windows-validation.md) compared accelerator
+configurations within v3.7.0. Historical v3.6.0 measurements remain in the
+[CHANGELOG](CHANGELOG.md); they predate the v3.7.0 alignment correction.
 
 ## Project Structure
 

visqol_python-3.8.0/docs/benchmarks/2026-09-16-linux-x86_64.json

@@ -0,0 +1,45 @@
+{
+  "baseline_commit": "1c3953ec4b6ed2e7fa2a2ce56eab3bad648d98d4",
+  "kernel_sha256": "dc39818c9518f8686b0cfd5711739ad28d14ac6de3921675767b91e3f5433071",
+  "platform": "Linux-5.4.241-1-tlinux4-0017.14-x86_64-with-glibc2.35",
+  "architecture": "x86_64",
+  "python": "3.10.20",
+  "versions": {
+    "numpy": "2.2.6",
+    "scipy": "1.15.3",
+    "numba": "0.65.1",
+    "llvmlite": "0.47.0",
+    "pyfftw": "0.15.0",
+    "ai-edge-litert": "2.2.0"
+  },
+  "threads": 4,
+  "threading_layer": "workqueue",
+  "fft_backend": "fftw",
+  "repeats": 5,
+  "case": "official guitar48_stereo_64kbps_aac",
+  "duration_sec": 12.453833333333334,
+  "protocol": "audio, FP64, search_window=60, both alignments enabled; warmed; excludes audio I/O",
+  "seconds": {
+    "optimized": [
+      0.5394072169438004,
+      0.5373025466687977,
+      0.5457052960991859,
+      0.5398548180237412,
+      0.5398879866115749
+    ],
+    "legacy_3_7_0": [
+      1.4971719882450998,
+      1.5210356987081468,
+      1.5065979771316051,
+      1.5096658081747591,
+      1.5108016063459218
+    ]
+  },
+  "median_sec": {
+    "optimized": 0.5398548180237412,
+    "legacy_3_7_0": 1.5096658081747591
+  },
+  "speedup": 2.7964292579646264,
+  "moslqo": 4.349722308064309,
+  "all_outputs_exact": true
+}

visqol_python-3.8.0/docs/benchmarks/2026-09-16-macos-arm64.json

@@ -0,0 +1,45 @@
+{
+  "baseline_commit": "1c3953ec4b6ed2e7fa2a2ce56eab3bad648d98d4",
+  "kernel_sha256": "dc39818c9518f8686b0cfd5711739ad28d14ac6de3921675767b91e3f5433071",
+  "platform": "macOS-15.7.3-arm64-arm-64bit-Mach-O",
+  "architecture": "arm64",
+  "python": "3.13.2",
+  "versions": {
+    "numpy": "2.4.3",
+    "scipy": "1.17.1",
+    "numba": "0.65.1",
+    "llvmlite": "0.47.0",
+    "pyfftw": "0.15.0",
+    "ai-edge-litert": "2.2.0"
+  },
+  "threads": 4,
+  "threading_layer": "workqueue",
+  "fft_backend": "fftw",
+  "repeats": 5,
+  "case": "official guitar48_stereo_64kbps_aac",
+  "duration_sec": 12.453833333333334,
+  "protocol": "audio, FP64, search_window=60, both alignments enabled; warmed; excludes audio I/O",
+  "seconds": {
+    "optimized": [
+      0.40294154200091725,
+      0.4215942089977034,
+      0.40989537499990547,
+      0.4250234579994867,
+      0.42086304199983715
+    ],
+    "legacy_3_7_0": [
+      1.0646232920007606,
+      1.0958797089988366,
+      1.092644124997605,
+      1.0716607499998645,
+      1.0800574999993842
+    ]
+  },
+  "median_sec": {
+    "optimized": 0.42086304199983715,
+    "legacy_3_7_0": 1.0800574999993842
+  },
+  "speedup": 2.566292100316573,
+  "moslqo": 4.349722308064313,
+  "all_outputs_exact": true
+}