Skip to content

SPDX-License-Identifier: AGPL-3.0-or-later

Commercial license available

© Concepts 1996–2026 Miroslav Šotek. All rights reserved.

© Code 2020–2026 Miroslav Šotek. All rights reserved.

ORCID: 0009-0009-3560-0851

Contact: www.anulum.li | protoscience@anulum.li

scpn-quantum-control — Kuramoto handbook

Kuramoto Handbook

This handbook is the reference page for the in-repository Kuramoto toolkit. It is generated from the live scpn_quantum_control.kuramoto facade and the committed multi-tier benchmark artefact, so the public API inventory, model families, and performance evidence stay aligned with the code.

The current facade exposes 344 public symbols in 9 capability groups. The committed tier benchmark covers 35 registered compute primitives across the Rust and Python tiers on the local workstation, with Julia and CI columns rendered when their artefacts exist.

Mathematical Core

The base phase dynamics are

\[ \dot\theta_i = \omega_i + \sum_j K_{ij}\sin(\theta_j - \theta_i). \]

omega_i is the natural frequency of oscillator i, K_ij is the coupling from oscillator j to i, and the complex order parameter is

\[ Z = R e^{i\psi} = \frac{1}{N}\sum_{j=1}^N e^{i\theta_j}. \]

The toolkit keeps this object explicit across every extension. Mean-field, networked, Sakaguchi, Daido, simplex, hyperedge, heterogeneous, delayed, noisy, inertial, plastic, and controlled variants all reduce to a named force field plus the Jacobian or adjoint needed by the analysis and control layers.

Model Families

Family Equation or contract Main API surface
Mean-field Kuramoto K r sin(psi - theta_i) and its dense Jacobian. mean_field_force, mean_field_jacobian
Networked Kuramoto sum_j K_ij sin(theta_j - theta_i) for dense coupling matrices. networked_kuramoto_force, networked_kuramoto_jacobian
Sakaguchi-Kuramoto Frustrated coupling sin(theta_j - theta_i - alpha). sakaguchi_force, sakaguchi_mean_field_force
Daido harmonics Higher harmonic order parameter r_m exp(i psi_m). daido_order_parameter, daido_mean_field_force
Triadic/simplex/hyperedge Higher-order terms over simplex order or explicit hyperedge lists. simplex_mean_field_force, hyperedge_force, heterogeneous_force
Delayed synchronisation Method-of-steps dynamics with branch-stability equations. integrate_delayed_kuramoto, synchronised_frequency_roots
Noisy mean-field Euler-Maruyama trajectories and Fokker-Planck onset equations. integrate_noisy_kuramoto, noisy_critical_coupling
Inertial oscillators Second-order phase-space dynamics with a mechanical-energy diagnostic. integrate_inertial, inertial_energy
Plastic/adaptive coupling Co-evolving phase and coupling state with Hebbian equilibrium. integrate_adaptive_kuramoto, hebbian_coupling_equilibrium

Integrators and Adjoints

The public facade exposes fixed-step Euler and RK4 trajectories, adaptive Dormand-Prince trajectories, delayed/inertial/noisy/adaptive variants, and reverse-mode adjoints for the differentiable Euler, RK4, and DOPRI paths. The adjoints return gradients with respect to the initial phases, natural frequencies, and coupling parameters where the corresponding mathematical contract is implemented. Unsupported routes fail closed rather than fabricating gradients.

Observables and Diagnostics

  • Global and local order parameters expose values, phases, gradients, and Hessians where defined.
  • Interaction energy exposes value, gradient, and Hessian for optimisation and terminal-control objectives.
  • Frequency-locking diagnostics report effective frequencies, synchronisation index, locked fraction, and gradient of the terminal index.
  • Chimera and metastability diagnostics measure community order, spatial incoherence, and temporal variability.
  • Phase-information diagnostics compute circular entropy, normalised entropy, pairwise mutual information, and the full mutual-information matrix.
  • Coherence and clustering diagnostics expose phase-locking matrices, spectral structure, leading coherence eigenvectors, and partial-synchronisation partitions.

Analysis and Control

  • Stability analysis computes the locked-state Jacobian spectrum, removes the Goldstone mode, and classifies synchronisation stability.
  • Critical-coupling routines implement Lorentzian and Gaussian closed forms and self-consistent order-parameter branches.
  • Ott-Antonsen reduction integrates the two-dimensional reduced order parameter and terminal sensitivities.
  • Lyapunov, continuation, hysteresis, and basin-estimation routines expose transition and multistability structure.
  • Control routines optimise terminal coherence, phase-target objectives, interaction-energy objectives, pinning gains, synchronising couplings, and trajectory-matching system-identification losses.

Public Capability Index

Group Count Public symbols
forces 40 mean_field_force, mean_field_jacobian, mean_field_phase_rule, mean_field_phase_rule_jacobian, networked_kuramoto_force, networked_kuramoto_jacobian, networked_phase_rule, networked_phase_rule_jacobian, sakaguchi_force, sakaguchi_jacobian, sakaguchi_mean_field_force, sakaguchi_mean_field_jacobian, triadic_mean_field_force, triadic_mean_field_jacobian, daido_mean_field_force, daido_mean_field_jacobian, simplex_mean_field_force, simplex_mean_field_jacobian, hyperedge_force, hyperedge_jacobian, heterogeneous_force, heterogeneous_force_components, heterogeneous_jacobian, CouplingTerm, pairwise_term, hyperedge_term, simplex_mean_field_term, delayed_mean_field_force, delayed_networked_force, qif_mean_field_rates, qif_mean_field_jacobian, stuart_landau_field, stuart_landau_jacobian, swarmalator_field, winfree_field, winfree_jacobian, multiplex_field, multiplex_jacobian, oscillator_ising_field, topological_kuramoto_field
integrators 56 KuramotoSystem, KuramotoParameters, KuramotoIvpSolution, kuramoto_ode_rhs, kuramoto_ode_jacobian, solve_kuramoto_ivp, kuramoto_euler_trajectory, kuramoto_euler_vjp, kuramoto_rk4_trajectory, kuramoto_rk4_vjp, kuramoto_dopri_trajectory, kuramoto_dopri_vjp, DopriTrajectory, integrate_delayed_kuramoto, delayed_phase_sensitivity, DelayedTrajectory, integrate_inertial, InertialTrajectory, inertial_vector_field, inertial_jacobian, inertial_energy, inertial_state_sensitivity, integrate_symplectic_inertial, integrate_noisy_kuramoto, noisy_kuramoto_step, noisy_phase_sensitivity, NoisyKuramotoRun, integrate_adaptive_kuramoto, AdaptiveTrajectory, adaptive_vector_field, hebbian_adaptive_jacobian, hebbian_coupling_equilibrium, hebbian_plasticity_rate, adaptive_state_sensitivity, ott_antonsen_trajectory, integrate_qif_mean_field, QifMeanFieldTrajectory, integrate_watanabe_strogatz, WatanabeStrogatzTrajectory, integrate_higher_order_watanabe_strogatz, HigherOrderWatanabeStrogatzTrajectory, integrate_stuart_landau, StuartLandauTrajectory, integrate_swarmalators, SwarmalatorTrajectory, integrate_winfree, WinfreeTrajectory, integrate_multiplex, MultiplexTrajectory, integrate_oscillator_ising_machine, OscillatorIsingTrajectory, integrate_quantum_vanderpol, QuantumVanDerPolTrajectory, vacuum_state, integrate_topological_kuramoto, TopologicalKuramotoTrajectory
observables 33 order_parameter, order_parameter_gradient, order_parameter_hessian, mean_phase, mean_phase_gradient, mean_phase_hessian, local_order_parameter, local_order_parameter_jacobian, local_mean_phase, local_mean_phase_jacobian, daido_order_parameter, daido_order_parameter_gradient, daido_order_parameter_hessian, daido_mode_phase, daido_mode_phase_gradient, daido_mode_phase_hessian, kuramoto_interaction_energy, kuramoto_interaction_energy_gradient, kuramoto_interaction_energy_hessian, stuart_landau_order_parameter, swarmalator_order_parameters, SwarmalatorOrderParameters, layer_order_parameters, interlayer_synchronisation, oscillator_ising_energy, ising_spins, ising_hamiltonian, cut_value, coherent_amplitude, mean_photon_number, phase_distribution, phase_synchronisation, topological_order_parameter
diagnostics 30 FrequencyOrder, effective_frequencies, frequency_synchronisation_index, frequency_synchronisation_index_gradient, frequency_locked_fraction, frequency_order_diagnostics, ChimeraDiagnostics, chimera_index, chimera_index_gradient, chimera_diagnostics, metastability_index, metastability_index_gradient, community_metastability, community_order_parameters, phase_entropy, normalised_phase_entropy, phase_entropy_series, pairwise_mutual_information, mutual_information_matrix, coherence_matrix, mean_coherence_matrix, phase_locking_matrix, coherence_spectrum, leading_coherence_eigenvector, ClusterPartition, phase_clusters, cluster_count, cluster_partition, amplitudes, is_oscillation_death
analysis 71 StabilitySpectrum, stability_spectrum, MultiplexSynchronisationStability, master_stability_function, multiplex_synchronisation_stability, HodgeStructure, HodgeComponents, simplicial_hodge_structure, hodge_decomposition, SynchronisationCertificate, phase_cohesiveness, contraction_rate, synchronisation_potential, potential_decrease_rate, certify_synchronisation, is_synchronisation_stable, synchronisation_rate, critical_coupling, gaussian_critical_coupling, lorentzian_critical_coupling, gaussian_density, lorentzian_density, lorentzian_order_parameter, synchronised_order_parameter, ott_antonsen_field, ott_antonsen_order_parameter, ott_antonsen_steady_state, ott_antonsen_terminal_order_parameter_value_and_grad, lyapunov_spectrum, maximal_lyapunov_exponent, ContinuationBranch, HysteresisLoop, continuation_sweep, KuramotoParameterGrid, Observable, ParameterSweepResult, sweep_parameter_grid, mean_order_parameter, terminal_order_parameter, metastability, frequency_spread, PseudoArclengthBranch, pseudo_arclength_continuation, hysteresis_loop, triadic_hysteresis_loop, BasinEstimate, estimate_ring_basins, BasinStabilityEstimate, synchronisation_basin_stability, ring_coupling_matrix, twisted_state, twisted_state_eigenvalues, is_twisted_state_stable, winding_number, synchronised_frequency_roots, synchronised_frequency_residual, synchronised_branch_stability, is_synchronised_branch_stable, stable_synchronised_frequencies, noisy_critical_coupling, lorentzian_noisy_critical_coupling, noisy_stationary_order_parameter, qif_mean_field_fixed_point, kuramoto_order_parameter_from_macro, macro_from_kuramoto_order_parameter, qif_potential_from_theta, theta_from_qif_potential, watanabe_strogatz_constants, watanabe_strogatz_phases, watanabe_strogatz_order_parameter, watanabe_strogatz_invariant
control_and_design 65 ForcedCollectiveTrajectory, CollectiveControlGradients, integrate_forced_collective, collective_control_value_and_grad, optimise_collective_forcing, ControlledNetworkTrajectory, NetworkControlGradients, integrate_controlled_network, network_control_value_and_grad, optimise_network_control, kuramoto_sdre_gain, sdre_control_input, integrate_sdre_controlled_kuramoto, DesynchronisingPolicy, PolicyRolloutGradients, policy_rollout_value_and_grad, learn_desynchronising_policy, CouplingFunctionEstimate, CouplingFunctionGradients, coupling_function_value, infer_coupling_function, coupling_function_trajectory_value_and_grad, refine_coupling_function, DynamicalBayesianPosterior, TimeVaryingCouplingHistory, infer_network_bayesian, track_time_varying_coupling, SparseDynamicsModel, discover_phase_dynamics, SparseDynamicsEstimator, CouplingFunctionEstimator, terminal_objective_value, terminal_objective_value_and_grad, coherence_objective, phase_target_objective, interaction_energy_objective, synchronisation_value_and_grad, CouplingDesignResult, optimise_coupling, design_synchronising_coupling, symmetric_nonnegative_projection, PinningDesignResult, design_pinning, pinning_coherence_value, pinning_coherence_value_and_grad, SystemIdentificationResult, learn_coupling, trajectory_match_value, trajectory_match_value_and_grad, InertialGradients, inertial_terminal_value_and_grad, AdaptiveGradients, adaptive_terminal_value_and_grad, NoisyGradients, noisy_terminal_value_and_grad, DelayedGradients, delayed_terminal_value_and_grad, qif_mean_field_terminal_value_and_grad, QifMeanFieldGradients, coordinated_reset_sites, coordinated_reset_phases, integrate_coordinated_reset, CoordinatedResetTrajectory, coordinated_reset_terminal_value_and_grad, CoordinatedResetGradients
types 11 PhaseForce, PhaseJacobian, MeanFieldForce, DelayedForce, AdaptivePhaseForce, PlasticityRule, StochasticForce, CouplingProjection, FrequencyDensity, PhasePotential, TerminalObjective
dispatch 3 MultiLangDispatcher, available_tiers, dispatch
tier_introspection 35 last_daido_gradient_tier_used, last_daido_hessian_tier_used, last_daido_mean_field_force_tier_used, last_daido_mean_field_jacobian_tier_used, last_daido_mode_phase_gradient_tier_used, last_daido_mode_phase_hessian_tier_used, last_daido_mode_phase_tier_used, last_daido_tier_used, last_gradient_tier_used, last_hessian_tier_used, last_kuramoto_euler_trajectory_tier_used, last_kuramoto_euler_vjp_tier_used, last_kuramoto_interaction_energy_gradient_tier_used, last_kuramoto_interaction_energy_hessian_tier_used, last_kuramoto_interaction_energy_tier_used, last_kuramoto_rk4_trajectory_tier_used, last_kuramoto_rk4_vjp_tier_used, last_local_mean_phase_jacobian_tier_used, last_local_mean_phase_tier_used, last_local_order_parameter_jacobian_tier_used, last_local_order_parameter_tier_used, last_mean_field_force_tier_used, last_mean_field_jacobian_tier_used, last_mean_phase_gradient_tier_used, last_mean_phase_hessian_tier_used, last_mean_phase_tier_used, last_networked_kuramoto_force_tier_used, last_networked_kuramoto_jacobian_tier_used, last_sakaguchi_force_tier_used, last_sakaguchi_jacobian_tier_used, last_sakaguchi_mean_field_force_tier_used, last_sakaguchi_mean_field_jacobian_tier_used, last_tier_used, last_triadic_mean_field_force_tier_used, last_triadic_mean_field_jacobian_tier_used

Performance Evidence

  • Schema: scpn-quantum-control.tier-benchmark.v1.
  • Environment: local.
  • Generated UTC: 2026-06-24T23:56:12Z.
  • Commit: 352547b92161c3c28d4d6116b5ed3ecaea786a9d.
  • CPU model: 11th Gen Intel(R) Core(TM) i5-11600K @ 3.90GHz.
  • Python / NumPy: 3.12.3 / 2.2.6.
  • Rust engine: installed.
  • Tiers and sizes: python, rust over N = 8, 32, 128, 512.
  • Production performance claim allowed: no.
  • The side-by-side CI/local table is generated in Multi-language Kuramoto tier benchmark.

The table below uses one representative row per benchmarked operation. It does not replace the full raw artefact, which keeps every size, percentile, tier availability row, and parity record.

Operation Representative N Rust p50 (µs) Python p50 (µs) Fastest backend Parity max abs diff
daido_mean_field_force 128 3.342 16.331 rust 4.16e-17
daido_mean_field_jacobian 128 178.621 224.765 rust 8.33e-17
daido_mode_phase 128 1.812 9.364 rust 1.11e-15
daido_mode_phase_gradient 128 3.260 15.715 rust 9.99e-16
daido_mode_phase_hessian 128 10.571 76.121 rust 4.00e-15
daido_order_parameter 128 1.792 7.394 rust 0.00e+00
daido_order_parameter_gradient 128 3.218 14.689 rust 1.50e-17
daido_order_parameter_hessian 128 7.364 53.201 rust 4.86e-17
kuramoto_euler_trajectory 128 9203.602 10976.205 rust 1.33e-15
kuramoto_euler_vjp 128 23078.208 28149.560 rust 1.17e-12
kuramoto_interaction_energy 128 158.591 164.070 rust 3.55e-15
kuramoto_interaction_energy_gradient 128 115.183 171.820 rust 7.11e-15
kuramoto_interaction_energy_hessian 128 172.773 221.272 rust 5.33e-15
kuramoto_rk4_trajectory 128 35132.240 45412.649 rust 1.55e-15
kuramoto_rk4_vjp 128 116512.887 143605.952 rust 4.71e-14
local_mean_phase 128 18.652 13.889 python 5.33e-15
local_mean_phase_jacobian 128 32.179 67.555 rust 1.19e-14
local_order_parameter 128 15.932 17.008 rust 8.33e-17
local_order_parameter_jacobian 128 24.665 75.314 rust 9.23e-17
mean_field_force 128 2.699 15.281 rust 2.78e-17
mean_field_jacobian 128 130.693 168.044 rust 2.78e-17
mean_phase 128 1.623 10.131 rust 8.33e-17
mean_phase_gradient 128 3.199 13.603 rust 9.71e-17
mean_phase_hessian 128 9.897 77.038 rust 1.25e-16
networked_kuramoto_force 128 111.525 138.955 rust 5.33e-15
networked_kuramoto_jacobian 128 166.728 165.645 python 5.33e-15
order_parameter 128 1.516 7.403 rust 2.08e-17
order_parameter_gradient 128 3.089 15.022 rust 2.60e-18
order_parameter_hessian 128 6.733 50.051 rust 3.47e-18
sakaguchi_force 128 129.766 139.121 rust 5.77e-15
sakaguchi_jacobian 128 176.519 170.657 python 4.00e-15
sakaguchi_mean_field_force 128 2.999 16.534 rust 2.78e-17
sakaguchi_mean_field_jacobian 128 135.615 174.131 rust 2.78e-17
triadic_mean_field_force 128 3.114 14.228 rust 2.17e-18
triadic_mean_field_jacobian 128 258.240 442.142 rust 4.34e-18

First-Path Usage

import numpy as np

from scpn_quantum_control import kuramoto

theta0 = np.array([0.0, 0.7, 1.6, 2.9], dtype=np.float64)
omega = np.array([0.1, -0.2, 0.15, 0.05], dtype=np.float64)
coupling = np.array(
    [
        [0.0, 0.6, 0.0, 0.2],
        [0.6, 0.0, 0.5, 0.0],
        [0.0, 0.5, 0.0, 0.4],
        [0.2, 0.0, 0.4, 0.0],
    ],
    dtype=np.float64,
)

trajectory = kuramoto.kuramoto_rk4_trajectory(theta0, omega, coupling, 0.01, 64)
diagnostics = kuramoto.frequency_order_diagnostics(trajectory, dt=0.01)
value, gradient = kuramoto.synchronisation_value_and_grad(theta0, omega, coupling)

Use kuramoto.capabilities() to inspect the grouped API and kuramoto.describe("analysis") to list one group programmatically.

Worked Workflow

Run the deterministic six-oscillator companion workflow when you need one executable Phase 5 path covering RK4 integration, frequency-locking diagnostics, stability spectrum, coherence clustering, Gaussian critical coupling, and projected synchronising-coupling design:

python examples/29_kuramoto_handbook_workflow.py

The matching notebook is notebooks/48_kuramoto_handbook_workflow.ipynb. Both surfaces use the public scpn_quantum_control.kuramoto facade and emit or preserve diagnostics that can be compared with this handbook's capability and benchmark tables.

Claim Boundaries

  • The local benchmark artefact is functional and reproducibility evidence, not a production latency claim.
  • CI numbers are hosted-runner evidence. They are useful for drift detection and side-by-side comparison, not a universal hardware claim.
  • Quantum hardware execution, broad quantum-advantage claims, and measured physical K_nm magnitudes remain governed by the evidence ledgers and preregistered campaign gates.
  • The standalone package split remains a CEO/IP decision. This handbook documents the current in-repository facade and does not create a new distribution boundary. See Kuramoto Standalone Package Decision.