Notebook 03 — Mackey-Glass chaotic attractor prediction

[rosspeili]

Context

Notebook 02 delivers the first validated QRC result on NARMA-10. Notebook 03 extends the same pipeline to Mackey-Glass — a standard chaotic time-series benchmark for reservoir computing (REFERENCES.md M4).

mackey_glass() already exists in tasks.py:

series = mackey_glass(length=2000, tau=17, dt=1.0, x0=1.2)

Unlike NARMA-10, Mackey-Glass returns a single autonomous series (no separate input channel). The usual RC formulation is one-step-ahead prediction:

u(t) = x(t)           (current value as reservoir input)
y(t) = x(t + 1)       (next value as target)

Normalize u into [0, 1] before encoding (tasks.py and encoder.py expect bounded inputs). Document the normalization formula in the notebook.

Issue #4 established the notebook pattern: generate data -> QRCConfig -> run_qrc -> figure + optional CSV. Reuse that structure.

Goal

Create and execute notebooks/03_qrc_mackey_glass.ipynb that:

1. Generates Mackey-Glass train/test splits
2. Runs the QRC pipeline from Issue Implement end-to-end QRC pipeline (ApproxTimeEvolution + feature matrix builder) #1
3. Reports train/test RMSE and NMSE
4. Saves figures/qrc_mackey_glass.png
5. Optionally saves data/mackey_glass_results.csv (recommended for reproducibility)

Notebook structure

Cell 1 — Title and context (markdown)

• QONDRA / spintronic-qrc header
• Explain Mackey-Glass as chaotic short-term prediction benchmark
• Define u(t) = x(t), y(t) = x(t+1) and normalization to [0, 1]
• Cite: Mackey & Glass (1977), Jaeger (2001), Cucchi et al. (2022) tutorial
• Note: compare against ESN in a follow-up cell or separate run if Issue Classical Echo State Network baseline module + unit tests #5 is merged

Cell 2 — Setup

from __future__ import annotations

import os
import warnings
warnings.filterwarnings("ignore")

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt

from spintronic_qrc.tasks import mackey_glass
from spintronic_qrc.pipeline import QRCConfig, run_qrc, collect_features
from spintronic_qrc.trainer import predict
from spintronic_qrc import utils

os.makedirs("../figures", exist_ok=True)
os.makedirs("../data", exist_ok=True)

Cell 3 — Generate Mackey-Glass series

Suggested defaults:

Parameter	Value	Notes
tau	17	Classic chaotic regime
dt	1.0	From tasks.py default
x0	1.2	From tasks.py default
total_length	3000	Enough for train + test after alignment
washout	100	Match NB02 convention

Helper to build supervised pairs:

def mackey_glass_supervised(series: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
    u = series[:-1]
    y = series[1:]
    u_min, u_max = u.min(), u.max()
    u_norm = (u - u_min) / (u_max - u_min + 1e-12)
    return u_norm, y

Chronological split: first 80% train, last 20% test (no shuffle).

Plot attractor preview (x(t) vs x(t-17) or time series subset).

Cell 4 — QRC configuration

Start from hyperparameters that worked in Notebook 02; document any changes:

config = QRCConfig(
    n_sites=6,
    evolution_time=0.8,
    n_trotter_steps=8,
    disorder=0.5,
    seed=42,
    encoding="local",
    encoding_site=0,
    washout=100,
)

Mackey-Glass may need different tau or N — tune if test error is flat; document attempts.

Cell 5 — Train and evaluate

• Train on u_train, y_train via run_qrc()
• Evaluate on test: collect_features(u_test, config) then predict with fitted model
• Report train_rmse, test_rmse, test_nmse

Optional (if Issue #5 merged): one ESN row via run_esn() for side-by-side comparison in CSV.

Cell 6 — Visualization

Two-panel figure:

1. Time series overlay: y_test vs predictions (test window, subset if long)
2. Attractor view: delayed embedding of true vs predicted (e.g. x(t) vs x(t-17))

Use utils palette. Save ../figures/qrc_mackey_glass.png at 150 DPI.

Cell 7 — Export CSV (recommended)

data/mackey_glass_results.csv columns (mirror narma10_results.csv):

method, n_sites, evolution_time, n_trotter_steps, disorder, encoding, washout, ridge_alpha, train_length, test_length, train_rmse, test_rmse, test_nmse, mg_tau, seed

Cell 8 — Sanity checks

• test_rmse finite
• Figure exists
• Normalized inputs in [0, 1]
• Prediction length matches test targets after washout alignment

Acceptance criteria

• notebooks/03_qrc_mackey_glass.ipynb runs top-to-bottom without manual edits
• figures/qrc_mackey_glass.png committed
• data/mackey_glass_results.csv committed (recommended)
• Uses spintronic_qrc.tasks.mackey_glass and pipeline (no duplicated MG integrator)
• OVERVIEW.md deliverables: check off notebook 03
• Runtime under ~15 min CPU at N=6 (N=4 acceptable if documented)

Files likely touched

• notebooks/03_qrc_mackey_glass.ipynb (new)
• figures/qrc_mackey_glass.png (new)
• data/mackey_glass_results.csv (new, recommended)
• OVERVIEW.md (optional)

Depends on

• Issue Implement end-to-end QRC pipeline (ApproxTimeEvolution + feature matrix builder) #1 (pipeline) — required
• Issue Notebook 02 — NARMA-10 end-to-end QRC + committed results #4 (Notebook 02 pattern) — recommended
• Issue Classical Echo State Network baseline module + unit tests #5 (ESN) — optional for comparison column

Blocks

• Notebook 04 (memory capacity uses same reservoir config conventions)
• benchmarks/ multi-task scripts