Phase 4: CI wheels, cross-validation tests, Python examples

CI workflow (.github/workflows/python-wheels.yml):
- cibuildwheel for Linux/macOS/Windows, Python 3.9-3.13
- nanobind STABLE_ABI for fewer wheels
- Gurobi/HiGHS disabled for wheel builds
- Auto-publish to PyPI on tagged releases

Cross-validation tests (15 tests):
- C++ dtw_distance matches Problem.dist_by_ind for all variants
- DenseDistanceMatrix matches pairwise direct computation
- DTWClustering sugar produces consistent results with raw fast_pam
- DDTW = derivative_transform + standard DTW
- ADTW(penalty=0) = standard DTW
- Soft-DTW(gamma->0) approaches standard DTW

Python examples:
- 01_quickstart.py: DTW distance + clustering in 10 lines
- 02_dtw_variants.py: compare all 5 DTW variants
- 03_clustering_evaluation.py: clustering with silhouette/DBI scoring

Total: 100 Python tests pass in 0.23s.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ElektrikAkar

.github/workflows/python-wheels.yml

@@ -0,0 +1,87 @@
+name: Python wheels
+
+on:
+  push:
+    branches: [main, Claude]
+    tags: ['v*']
+  pull_request:
+    branches: ['**']
+
+jobs:
+  build_wheels:
+    name: Wheels on ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - uses: pypa/cibuildwheel@v2.21
+        env:
+          # Build for Python 3.9-3.13; nanobind STABLE_ABI means fewer wheels
+          CIBW_BUILD: "cp39-* cp310-* cp311-* cp312-* cp313-*"
+          CIBW_SKIP: "*-musllinux_* *-win32 *-manylinux_i686"
+          CIBW_ARCHS_MACOS: "x86_64 arm64"
+
+          # Disable commercial/heavy solvers for wheel builds
+          CIBW_CONFIG_SETTINGS: >-
+            cmake.args="-DDTWC_BUILD_PYTHON=ON;-DDTWC_ENABLE_GUROBI=OFF;-DDTWC_ENABLE_HIGHS=OFF"
+
+          # macOS needs libomp for OpenMP
+          CIBW_BEFORE_BUILD_MACOS: "brew install libomp || true"
+
+          # Test the built wheel
+          CIBW_TEST_REQUIRES: "pytest numpy"
+          CIBW_TEST_COMMAND: "pytest {project}/tests/python -v --tb=short"
+          CIBW_BUILD_VERBOSITY: 1
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  build_sdist:
+    name: Source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: pip install build && python -m build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  test_python:
+    name: Test Python ${{ matrix.python }} on ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ['3.10', '3.12']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install and test
+        run: |
+          pip install ".[test]" -v
+          pytest tests/python/ -v --tb=short
+
+  publish:
+    name: Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [build_wheels, build_sdist, test_python]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

python/examples/01_quickstart.py

@@ -0,0 +1,41 @@
+"""
+DTWC++ Quick Start — DTW distance and clustering in 10 lines.
+
+Install: pip install dtwcpp
+"""
+
+import numpy as np
+import dtwcpp
+
+# --- 1. Compute DTW distance between two time series ---
+x = [1.0, 2.0, 3.0, 4.0, 5.0]
+y = [2.0, 4.0, 6.0, 3.0, 1.0]
+
+d = dtwcpp.dtw_distance(x, y)
+print(f"DTW distance: {d}")
+
+# Banded DTW (Sakoe-Chiba constraint) — much faster for long series
+d_banded = dtwcpp.dtw_distance(x, y, band=2)
+print(f"DTW distance (band=2): {d_banded}")
+
+# --- 2. Cluster time series with sklearn-like API ---
+rng = np.random.RandomState(42)
+
+# Create 3 groups of 10 series each (length 50)
+group_a = rng.randn(10, 50)              # centered at 0
+group_b = rng.randn(10, 50) + 5          # centered at 5
+group_c = rng.randn(10, 50) + 10         # centered at 10
+X = np.vstack([group_a, group_b, group_c])
+
+clf = dtwcpp.DTWClustering(n_clusters=3, band=10)
+labels = clf.fit_predict(X)
+
+print(f"\nCluster labels: {labels}")
+print(f"Inertia (total cost): {clf.inertia_:.2f}")
+print(f"Medoid indices: {clf.medoid_indices_}")
+print(f"Iterations: {clf.n_iter_}")
+
+# Predict cluster for new data
+new_series = rng.randn(3, 50) + 5  # should be assigned to group_b's cluster
+predicted = clf.predict(new_series)
+print(f"Predicted labels for new data: {predicted}")

python/examples/02_dtw_variants.py

@@ -0,0 +1,62 @@
+"""
+DTWC++ DTW Variants — Compare all 5 DTW distance measures.
+
+Demonstrates: Standard DTW, DDTW, WDTW, ADTW, Soft-DTW.
+"""
+
+import numpy as np
+import dtwcpp
+
+# Create two time series
+np.random.seed(42)
+t = np.linspace(0, 4 * np.pi, 200)
+x = np.sin(t).tolist()
+y = np.sin(t + 0.5).tolist()  # phase-shifted version
+
+print("=== DTW Variant Comparison ===")
+print(f"Series length: {len(x)}")
+print()
+
+# Standard DTW
+d_std = dtwcpp.dtw_distance(x, y, band=-1)
+print(f"Standard DTW:     {d_std:.4f}")
+
+# Banded DTW (Sakoe-Chiba)
+d_banded = dtwcpp.dtw_distance(x, y, band=20)
+print(f"Banded DTW (b=20): {d_banded:.4f}")
+
+# DDTW — Derivative DTW (shape-based, ignores amplitude)
+d_ddtw = dtwcpp.ddtw_distance(x, y, band=-1)
+print(f"DDTW (derivative): {d_ddtw:.4f}")
+
+# WDTW — Weighted DTW (penalizes off-diagonal alignment)
+d_wdtw_lo = dtwcpp.wdtw_distance(x, y, band=-1, g=0.01)
+d_wdtw_hi = dtwcpp.wdtw_distance(x, y, band=-1, g=0.5)
+print(f"WDTW (g=0.01):    {d_wdtw_lo:.4f}  (lenient)")
+print(f"WDTW (g=0.50):    {d_wdtw_hi:.4f}  (strict)")
+
+# ADTW — Amerced DTW (penalizes non-diagonal steps)
+d_adtw_lo = dtwcpp.adtw_distance(x, y, band=-1, penalty=0.1)
+d_adtw_hi = dtwcpp.adtw_distance(x, y, band=-1, penalty=5.0)
+print(f"ADTW (p=0.1):     {d_adtw_lo:.4f}  (lenient)")
+print(f"ADTW (p=5.0):     {d_adtw_hi:.4f}  (strict)")
+
+# Soft-DTW — Differentiable (for gradient-based optimization)
+d_soft_lo = dtwcpp.soft_dtw_distance(x, y, gamma=0.01)
+d_soft_hi = dtwcpp.soft_dtw_distance(x, y, gamma=10.0)
+print(f"Soft-DTW (g=0.01): {d_soft_lo:.4f}  (~ hard DTW)")
+print(f"Soft-DTW (g=10):  {d_soft_hi:.4f}  (smooth)")
+
+# Soft-DTW gradient — unique to Soft-DTW, enables optimization
+grad = dtwcpp.soft_dtw_gradient(x, y, gamma=1.0)
+print(f"\nSoft-DTW gradient norm: {np.linalg.norm(grad):.4f}")
+print(f"Gradient shape: {len(grad)} (same as input series)")
+
+# --- Preprocessing: derivative transform ---
+dx = dtwcpp.derivative_transform(x)
+print(f"\nDerivative transform: first 5 values = {[f'{v:.3f}' for v in dx[:5]]}")
+
+# --- Z-normalization ---
+z = dtwcpp.z_normalize([10, 20, 30, 40, 50])
+print(f"Z-normalize([10..50]) = [{', '.join(f'{v:.3f}' for v in z)}]")
+print(f"  Mean = {np.mean(z):.6f}, Std = {np.std(z):.6f}")

python/examples/03_clustering_evaluation.py

@@ -0,0 +1,84 @@
+"""
+DTWC++ Clustering Evaluation — Compare clustering quality across DTW variants.
+
+Demonstrates: DTWClustering with different variants, silhouette scores, DBI.
+"""
+
+import numpy as np
+import dtwcpp
+
+# Generate synthetic data: 3 well-separated clusters
+rng = np.random.RandomState(42)
+n_per_cluster = 10
+length = 30
+
+clusters = []
+for center in [0, 50, 100]:
+    for _ in range(n_per_cluster):
+        series = center + rng.randn(length) * 2
+        clusters.append(series)
+
+X = np.array(clusters)
+true_labels = np.array([0] * n_per_cluster + [1] * n_per_cluster + [2] * n_per_cluster)
+
+print("=== Clustering Evaluation ===")
+print(f"Data: {X.shape[0]} series of length {X.shape[1]}")
+print(f"True clusters: {np.bincount(true_labels)}")
+print()
+
+# Compare DTW variants for clustering
+variants = ["standard", "ddtw", "wdtw", "adtw"]
+
+for variant in variants:
+    kwargs = {}
+    if variant == "wdtw":
+        kwargs["wdtw_g"] = 0.1
+    elif variant == "adtw":
+        kwargs["adtw_penalty"] = 1.0
+
+    clf = dtwcpp.DTWClustering(
+        n_clusters=3, variant=variant, band=-1, max_iter=100, **kwargs
+    )
+    labels = clf.fit_predict(X)
+
+    # Check cluster recovery accuracy
+    # (labels may be permuted — check if partition matches)
+    from itertools import permutations
+    best_acc = 0
+    for perm in permutations(range(3)):
+        remapped = np.array([perm[l] for l in labels])
+        acc = np.mean(remapped == true_labels)
+        best_acc = max(best_acc, acc)
+
+    print(f"{variant:10s} — cost: {clf.inertia_:8.2f}, "
+          f"iters: {clf.n_iter_:2d}, "
+          f"accuracy: {best_acc:.0%}")
+
+# --- Detailed evaluation with Problem class ---
+print("\n=== Detailed Scoring (Standard DTW) ===")
+
+prob = dtwcpp.Problem("eval")
+prob.set_data(X.tolist(), [f"s{i}" for i in range(len(X))])
+prob.band = -1
+prob.fill_distance_matrix()
+
+result = dtwcpp.fast_pam(prob, n_clusters=3)
+print(f"FastPAM result: {result}")
+
+# Apply labels to Problem for scoring
+prob.set_number_of_clusters(3)
+prob.clusters_ind = result.labels
+prob.centroids_ind = result.medoid_indices
+
+sil = dtwcpp.silhouette(prob)
+sil_mean = np.mean(sil)
+print(f"Mean silhouette: {sil_mean:.3f}")
+
+dbi = dtwcpp.davies_bouldin_index(prob)
+print(f"Davies-Bouldin Index: {dbi:.3f}")
+
+# --- Distance matrix visualization ---
+print(f"\nDistance matrix size: {prob.size} × {prob.size}")
+print(f"Max distance: {prob.max_distance():.2f}")
+print(f"Medoid indices: {result.medoid_indices}")
+print(f"Medoid names: {[prob.get_name(i) for i in result.medoid_indices] if hasattr(prob, 'get_name') else 'N/A'}")