Skip to content

Sparse Kuramoto CPU Path

oscillatools exposes an explicit sparse CPU route for large classical Kuramoto networks:

  • SparseKuramotoCoupling
  • sparse_coupling_from_scipy
  • ring_sparse_coupling
  • sparse_networked_kuramoto_force
  • sparse_kuramoto_euler_trajectory
  • sparse_kuramoto_rk4_trajectory

The dense networked_kuramoto_force and dense Euler/RK4 routes remain unchanged. They are still the small dense-matrix correctness and multi-language dispatch surfaces. The sparse route accepts SciPy sparse coupling matrices or canonical COO edge records and evaluates F_i = sum_j K_ij sin(theta_j - theta_i) over stored edges only.

Example

import numpy as np
from scipy import sparse

from oscillatools import (
    sparse_coupling_from_scipy,
    sparse_kuramoto_rk4_trajectory,
    sparse_networked_kuramoto_force,
)

theta0 = np.linspace(0.0, 2.0 * np.pi, 100_000, endpoint=False)
omega = np.zeros(theta0.shape[0])
coupling = sparse.diags(
    diagonals=[0.05, 0.05],
    offsets=[-1, 1],
    shape=(theta0.shape[0], theta0.shape[0]),
    format="csr",
)
sparse_coupling = sparse_coupling_from_scipy(coupling)

force = sparse_networked_kuramoto_force(theta0, sparse_coupling)
trajectory = sparse_kuramoto_rk4_trajectory(theta0, omega, sparse_coupling, dt=0.01, n_steps=4)

Evidence

The committed scaling artifact is docs/benchmarks/sparse_kuramoto_cpu.json, generated with:

python scripts/bench_sparse_kuramoto_cpu.py --samples 3 --n-steps 1 --sizes 1000 10000 100000 1000000

Measured on 2026-07-09 with Python 3.12.13, NumPy 2.2.6, and SciPy 1.15.3:

N Stored edges Force median Euler median RK4 median
1,000 2,000 0.040 ms 0.063 ms 0.214 ms
10,000 20,000 0.262 ms 1.023 ms 2.140 ms
100,000 200,000 14.236 ms 15.552 ms 49.873 ms
1,000,000 2,000,000 81.760 ms 141.238 ms 566.206 ms

This is sparse classical CPU scaling evidence for ring-network Kuramoto force and fixed-step integrators. It is not quantum hardware evidence and not a broad performance claim.