Kuramoto Oscillator Model

A local research pipeline applying a modified Kuramoto model (data-driven natural frequencies, non-uniform coupling, and phase delays) to two domains:

1. U.S. Treasury constant-maturity yields (post-2008 window)
2. Pre-extracted EEG alpha-band phases (four Muse channels, four subjects, three mental states)

Author: Samay Suratwala
License: MIT — Copyright (c) 2026 Samay Suratwala
Repository: SamaySuratwala/Kuramoto-Oscillator-Model

---

Overview

The classical Kuramoto system is extended to

[ \frac{d\theta_i}{dt} = \omega_i - \sum_j K_{ij}\sin(\theta_i - \theta_j + \delta_{ij}) ]

with parameters estimated from data and held constant during numerical integration (scipy.integrate.solve_ivp). Evaluation emphasizes circular statistics: the order parameter (R(t)), pairwise phase-locking value (PLV), and mean absolute circular phase error (CPE) between observed and re-simulated phases.

Primary scientific conclusion: under this constant-parameter protocol, the model does not recover observed phase trajectories. Bulk synchronization can remain high (especially for Treasury phases) while paths diverge; for EEG, simulation also tends to over-synchronize relative to the data.

---

Research questions

1. Can a constant-parameter modified Kuramoto reproduce synchronization statistics ((R), PLV) of Treasury maturity phases and EEG alpha phases?
2. Does the same model reproduce pointwise phase trajectories (circular phase error)?
3. How do those answers differ between a slowly varying financial panel and nonstationary neural segments?

---

Datasets and sources

Domain	File(s)	Source
Treasury yields	rates_data.csv	U.S. Treasury Daily Treasury Rate Archives
EEG alpha phases	subjecta_alpha_phase.csv … subjectd_alpha_phase.csv	Derived from EEG Brainwave Dataset: Mental State (Kaggle)

Treasury columns

date, 3 mo, 6 mo, 1 yr, 2 yr, 3 yr, 5 yr, 7 yr, 10 yr, 20 yr, 30 yr
(There is no 1-month column in the provided file.)

EEG columns

timestamps, state, trial, TP9_phase, AF7_phase, AF8_phase, TP10_phase
States: concentrating, neutral, relaxed. Median sampling rate on the files: 250 Hz.

Data cleaning (in code)

• Rates: drop unnamed index column; parse dates; keep dates after 2008-01-01 → analysis window 2008-01-02 through 2023-12-29 (4000 trading days); use the ten maturity columns above.
• EEG: no bandpass/Hilbert in this repo (phases are pre-extracted); analyze each (subject, state, trial) segment separately (23 available segments; subject d has no concentrating trial 2).

---

Key methods

Step	Treasury	EEG
Phase	90-day centered rolling mean; peak/trough interpolation into ([-\pi/2,\pi/2])	Use provided alpha phases; unwrap for (\omega)
(\omega)	Mean phase increment (rad/day)	Mean unwrapped increment (rad/sample)
(K)	Residual rate-change correlation × 0.01 (parallel shift removed)	PLV × 0.05
(\delta)	Circular mean of phase differences	Same
Integration	solve_ivp Radau	solve_ivp RK45
Metrics	(R(t)), PLV, CPE on historical re-simulation	Same; full subject×state×trial sweep + detailed segment

Constants live at the top of kuramoto_model.py (source of truth).

---

Key results and conclusions

Numbers from the committed output/results_summary.json and output/eeg_segment_metrics.csv produced by kuramoto_model.py.

Treasury (post-2008)

Metric	Value
Window	2008-01-02 → 2023-12-29 ((N=4000))
Aligned phase samples	3911
(R_\mathrm{obs}) mean ± std	0.8348 ± 0.1469
Mean off-diagonal PLV (obs / hist-sim)	0.6889 / 0.8698
Circular phase error	1.0934 rad (62.65°)

EEG (23 segments)

Metric	Value
Mean (R_\mathrm{obs}) / (R_\mathrm{sim})	0.5571 / 0.9012
Mean off-diagonal PLV(_\mathrm{obs})	0.1744
Mean / median CPE	89.39° / 87.89°

Detailed EEG (subject a, concentrating, trial 1; first 3000 samples)

Metric	Value
(R_\mathrm{obs}) / (R_\mathrm{sim})	0.5891 / 0.9876
PLV off-diag (obs / sim)	0.2404 / 0.9867
CPE	1.6230 rad (92.99°)

Conclusion: A constant-parameter modified Kuramoto is not a faithful trajectory model for either domain under this protocol. For EEG it also inflates synchrony. Trajectory mismatch is a primary result, not a side note.

Full write-up with embedded figures: paper/Kuramoto_Oscillator_Model.md.

---

Repository layout

Kuramoto-Oscillator-Model/
├── kuramoto_model.py          # Analysis pipeline (run this)
├── rates_data.csv             # Treasury yields
├── subjecta_alpha_phase.csv   # EEG phases (subjects a–d)
├── subjectb_alpha_phase.csv
├── subjectc_alpha_phase.csv
├── subjectd_alpha_phase.csv
├── requirements.txt
├── LICENSE
├── README.md
├── output/                    # Figures + numeric results from the pipeline
│   ├── results_summary.json
│   ├── eeg_segment_metrics.csv
│   └── fig_*.png
└── paper/
    ├── Kuramoto_Oscillator_Model.md   # Research paper (GitHub-readable)
    └── Kuramoto_Oscillator_Model.Rmd  # Same content; optional R Markdown knit

How files connect

rates_data.csv ──┐
                 ├──► kuramoto_model.py ──► output/* ──► paper (figures + tables)
subject*_alpha_phase.csv ─┘

• Code defines constants and methods.
• Outputs store numbers and plots.
• Paper / README cite those outputs only.

---

Reproduction

Requirements

• Python 3.10+ recommended
• Packages in requirements.txt: numpy, pandas, scipy, matplotlib

Steps (Windows PowerShell)

cd C:\Users\samay\Kuramoto
python -m pip install -r requirements.txt
python kuramoto_model.py

The script writes (or overwrites) everything under output/ and prints a console summary. Paths are relative to the script directory; no Colab, Drive, or widgets.

Optional paper knit (R)

Rscript -e "rmarkdown::render('paper/Kuramoto_Oscillator_Model.Rmd')"

Not required to read the paper: use paper/Kuramoto_Oscillator_Model.md.

---

Limitations

• Yield “phase” is a peak–trough construction, not a unique physical phase.
• EEG phases are pre-extracted; raw filtering details are outside this repo.
• Constant (K), (\delta), (\omega) cannot capture regime shifts or task nonstationarity.
• Coupling scales (COUPLING_SCALE=0.01, EEG_PLV_SCALE=0.05) are fixed design choices, not cross-validated.
• No out-of-sample forecasting evaluation.
• Small neural montage (4 channels, 4 subjects).
• Forward yield plots are illustrative reconstructions, not forecasts.
• Floating-point results may differ slightly across SciPy/NumPy versions.

---

Future work

• Time-varying coupling (K(t))
• Formal scale calibration (e.g. match mean observed (R))
• Hierarchical or Bayesian (\omega)
• Multi-band EEG and larger electrode sets
• Score-based comparison to term-structure and neural-mass baselines
• Proper train/test splits for predictive claims

---

File-by-file descriptions

Path	Description
kuramoto_model.py	End-to-end pipeline: load data, estimate parameters, integrate ODE, metrics, save figures/JSON/CSV
rates_data.csv	Daily Treasury yields used for the financial application
subject*_alpha_phase.csv	Pre-extracted EEG alpha phases per subject
output/results_summary.json	Machine-readable aggregate results
output/eeg_segment_metrics.csv	Per segment (subject × state × trial) metrics
output/fig_*.png	Figures embedded in the paper
paper/Kuramoto_Oscillator_Model.md	Full research paper
paper/Kuramoto_Oscillator_Model.Rmd	Optional R Markdown version of the paper
requirements.txt	Python dependencies
LICENSE	MIT License
README.md	This file

---

License

This project is released under the MIT License. Copyright (c) 2026 Samay Suratwala. See LICENSE.

Third-party data remain subject to their original terms (U.S. Treasury data; Kaggle EEG dataset license).