Skip to content

notebooks.md

Latest commit

 

History

History
606 lines (452 loc) · 25.6 KB

notebooks.md

File metadata and controls

606 lines (452 loc) · 25.6 KB

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 — Interactive Notebooks

Interactive Notebooks

47 Jupyter notebooks covering the full journey from basic Kuramoto dynamics to frontier research. Notebooks 01-13 cover core quantum simulation. Notebooks 14-47 document the FIM (Fisher Information Metric) strange loop investigation campaign (2026-03-29) with 19 findings (6 negative) including hardware-artifact dual protection on ibm_fez.

Notebook Map

The notebooks form a directed learning graph. Earlier notebooks provide the physical intuition and computational primitives that later notebooks build on.

graph TD
    N01["01: Kuramoto XY\nDynamics"] --> N02["02: VQE Ground\nState"]
    N01 --> N04["04: UPDE\n16-Layer"]
    N02 --> N03["03: Error\nMitigation"]
    N02 --> N05["05: Crypto &\nEntanglement"]
    N03 --> N06["06: PEC Error\nCancellation"]
    N04 --> N07["07: Quantum\nAdvantage"]
    N02 --> N08["08: Identity\nContinuity"]
    N01 --> N09["09: ITER\nDisruption"]
    N01 --> N10["10: QSNN\nTraining"]
    N06 --> N11["11: Surface Code\nBudget"]
    N03 --> N12["12: Trapped Ion\nComparison"]
    N08 --> N13["13: Cross-Repo\nBridges"]

    style N01 fill:#6929C4,color:#fff
    style N04 fill:#6929C4,color:#fff
    style N07 fill:#d4a017,color:#000
    style N11 fill:#d4a017,color:#000
Loading
Colour Meaning
Purple Foundational (start here)
Grey Core workflow
Gold Advanced / frontier

At a Glance

# Notebook Physics Level Key Output
01 Kuramoto XY Dynamics Trotter evolution of the XY Hamiltonian Beginner $R(t)$ trajectory, quantum-classical overlay
02 VQE Ground State Variational eigensolver with $K_{nm}$-informed ansatz Beginner Energy convergence, ansatz comparison table
03 Error Mitigation ZNE unitary folding + Richardson extrapolation Intermediate Mitigated vs raw expectation plot
04 UPDE 16-Layer Full 16-qubit SCPN spin chain Intermediate Per-layer $R$ bar chart, time evolution
05 Crypto & Entanglement CHSH Bell test, QKD QBER Intermediate $S$-parameter, correlator matrix heatmap
06 PEC Error Cancellation Quasi-probability decomposition, Monte Carlo Advanced PEC vs ZNE comparison, overhead scaling
07 Quantum Advantage Classical vs quantum timing crossover Advanced Scaling plot, $n_{\text{cross}}$ prediction
08 Identity Continuity VQE attractor, coherence budget, fingerprint Advanced Fidelity curves, phase roundtrip
09 ITER Disruption 11-feature plasma classifier Domain Feature distributions, accuracy report
10 QSNN Training Parameter-shift gradient descent Advanced Loss curve, weight evolution
11 Surface Code Budget QEC resource estimation Advanced Rep vs surface code table, feasibility
12 Trapped Ion Comparison Superconducting vs ion trap noise Advanced Transpilation comparison, noisy $\langle Z \rangle$
13 Cross-Repo Bridges SNN adapter, SSGF, orchestrator Integration Phase roundtrip plot, warning report

Notebook Details

01 — Kuramoto XY Dynamics

File: notebooks/01_kuramoto_xy_dynamics.ipynb

The entry point to the entire package. This notebook constructs the quantum XY Hamiltonian from the SCPN coupling matrix $K_{nm}$, runs Trotterized time evolution on the AerSimulator, and measures the Kuramoto order parameter $R(t)$ at each timestep.

Think of it as watching four quantum pendulums evolve on a shared vibrating beam. The beam stiffness is the coupling matrix. The notebook lets you see how quickly they fall into step — or whether the quantum dynamics depart from the classical prediction.

What it covers:

  • Building $K_{nm}$ from Paper 27 parameters ($K_{\text{base}} = 0.45$, $\alpha = 0.3$, calibration anchors)
  • Compiling $K_{nm} \to H_{XY}$ via knm_to_hamiltonian()
  • First-order Lie-Trotter decomposition: $U(\Delta t) = e^{-iH_{XY}\Delta t},e^{-iH_Z\Delta t}$
  • Extracting $R$ from single-qubit $\langle X \rangle$, $\langle Y \rangle$ expectations
  • Side-by-side comparison with the classical Kuramoto ODE solver

Key outputs:

Output What it shows
$R(t)$ trajectory plot Quantum and classical order parameter over 10 timesteps
Per-qubit Bloch coordinates $\langle X_i \rangle$, $\langle Y_i \rangle$, $\langle Z_i \rangle$ at each step
Circuit depth table Gate count and depth after transpilation

Modules used: bridge.knm_hamiltonian, phase.xy_kuramoto, hardware.classical

02 — VQE Ground State

File: notebooks/02_vqe_ground_state.ipynb

Finds the ground state of the Kuramoto-XY Hamiltonian using three different variational ansatze, then compares their convergence, parameter count, and final energy against exact diagonalisation.

The ground state is the equilibrium that the coupled oscillators settle into at zero temperature. Its structure encodes the natural synchronization pattern of the network — which oscillators are correlated, which are anti-correlated, and how much entanglement the coupling topology generates. Every analysis module in the package starts from this state.

Ansatz comparison:

Ansatz Parameters Entanglement topology Relative error
$K_{nm}$-informed (Gem 4) $3N \times \text{reps}$ Matches non-zero $K_{ij}$ 0.05% (4q)
Hardware-efficient $3N \times \text{reps}$ Linear nearest-neighbour ~0.3% (4q)
EfficientSU2 $4N \times \text{reps}$ Full connectivity ~0.1% (4q)

The $K_{nm}$-informed ansatz wins because it encodes the physics: entangling gates connect only qubit pairs with non-zero coupling, so the circuit explores the physically relevant subspace of the Hilbert space rather than wasting parameters on unphysical directions.

Key outputs:

  • Energy convergence curves (COBYLA iterations vs $\langle H \rangle$)
  • Ansatz comparison table (4-qubit and 8-qubit)
  • Ground state density matrix visualisation

Modules used: phase.phase_vqe, phase.ansatz_bench, phase.coupling_topology_ansatz

03 — Error Mitigation

File: notebooks/03_error_mitigation.ipynb

Demonstrates zero-noise extrapolation (ZNE) on a simulated Heron r2 noise model. The circuit is run at three noise levels (1x, 3x, 5x amplification via global unitary folding), then Richardson extrapolation recovers the zero-noise limit.

Real quantum hardware introduces errors proportional to circuit depth. ZNE turns this into a feature: by deliberately increasing the noise (folding the circuit back on itself), you get multiple data points on the noise-vs-expectation curve. Extrapolating to zero noise recovers a better estimate than any single noisy measurement.

Pipeline:

graph LR
    A["Build circuit"] --> B["Fold: 1x, 3x, 5x"]
    B --> C["Run on noisy sim"]
    C --> D["Richardson\nextrapolation"]
    D --> E["Zero-noise\nestimate"]

    style D fill:#6929C4,color:#fff
Loading

Key outputs:

Metric Raw (1x noise) ZNE extrapolated Exact
$\langle Z_0 \rangle$ ~0.72 ~0.79 0.81

Modules used: mitigation.zne, mitigation.dd

04 — UPDE 16-Layer

File: notebooks/04_upde_16_layer.ipynb

The full 16-oscillator SCPN network simulated as a 16-qubit spin chain. This is the quantum version of the Unified Phase Dynamics Equation — the master equation governing all 16 layers of the SCPN consciousness model.

Each qubit represents one ontological layer. The coupling between qubits follows the exponential decay $K_{nm} = 0.45 \cdot e^{-0.3|n-m|}$ with cross-hierarchy boosts (L1-L16 = 0.05, L5-L7 = 0.15). The notebook evolves this system under Trotter decomposition and measures per-layer coherence $\langle X_n \rangle$, $\langle Y_n \rangle$ at each timestep.

What the per-layer bar chart reveals:

  • Strongly-coupled layers (L3, L4, L10) maintain coherence longest
  • Weakly-coupled L12 shows near-complete decoherence even in noiseless simulation (the coupling is too weak to sustain synchronization against frequency heterogeneity)
  • The hierarchy structure in $K_{nm}$ directly imprints on the quantum dynamics

Key outputs:

Output Description
Per-layer $R$ bar chart 16 bars showing $R_n$ after Trotter evolution
Time evolution heatmap $R_n(t)$ across all 16 layers and 10 timesteps
Circuit statistics 16-qubit circuit: gate count, depth, CZ count

Modules used: phase.trotter_upde, bridge.knm_hamiltonian

05 — Crypto and Entanglement

File: notebooks/05_crypto_and_entanglement.ipynb

Implements the CHSH Bell test on the VQE ground state of the Kuramoto-XY Hamiltonian, then builds a topology-authenticated QKD protocol where the coupling matrix $K_{nm}$ serves as shared secret.

The CHSH inequality $|S| \leq 2$ holds for all local hidden-variable models. Violation ($S > 2$) certifies genuine quantum entanglement. This notebook measures $S$ for all $\binom{N}{2}$ qubit pairs, producing a correlator matrix that maps which pairs in the SCPN hierarchy are entangled.

Key outputs:

Output Description
$S$-parameter matrix CHSH values for all qubit pairs (heatmap)
QKD key rate Sifted bits per circuit shot
QBER estimate Quantum bit error rate from basis mismatch
Correlator heatmap $\langle X_iX_j \rangle + \langle Y_iY_j \rangle$ for all pairs

Modules used: crypto.bell_test, crypto.topology_auth, crypto.qkd_bb84

06 — PEC Error Cancellation

File: notebooks/06_pec_error_cancellation.ipynb

Probabilistic error cancellation (PEC) decomposes the inverse noise channel into a quasi-probability distribution over Pauli operations. Each circuit execution samples from this distribution, and the sign-weighted average converges to the noiseless expectation value.

PEC is mathematically exact (unlike ZNE which relies on extrapolation assumptions) but pays a sampling overhead $\gamma^{n_{\text{gates}}}$ that grows exponentially with circuit size. This notebook quantifies that overhead for 4-qubit and 8-qubit Kuramoto circuits and compares PEC accuracy against ZNE.

Overhead scaling:

Circuit Gates $\gamma$ per gate Total overhead Shots needed
4-qubit, 1 Trotter 12 CZ 1.015 ~1.20 ~14,400
4-qubit, 3 Trotter 36 CZ 1.015 ~1.72 ~29,600
8-qubit, 1 Trotter 28 CZ 1.015 ~1.53 ~23,400

Key outputs:

  • PEC vs ZNE accuracy comparison (bar chart)
  • Overhead scaling curve ($\gamma$ vs circuit depth)
  • Monte Carlo convergence: mitigated estimate vs number of samples

Modules used: mitigation.pec, mitigation.zne

07 — Quantum Advantage Scaling

File: notebooks/07_quantum_advantage_scaling.ipynb

Benchmarks classical exact diagonalisation against quantum Trotter simulation for increasing qubit counts ($N = 2, 3, \ldots, 8$) and extrapolates the crossover point where quantum becomes faster.

Classical cost scales as $O(2^{2N})$ (full matrix exponential). Quantum Trotter cost scales as $O(N^2 r)$ per step. At small $N$, classical wins — the quantum overhead of circuit compilation, transpilation, and shot noise dominates. The exponential fit predicts $n_{\text{cross}}$ where the curves intersect.

Scaling regimes:

graph LR
    A["N = 2-8\nClassical wins"] --> B["N = 12-16\nNoise-limited\nregion"]
    B --> C["N >> 20\nQuantum advantage\n(error-corrected)"]

    style A fill:#2ecc71,color:#000
    style B fill:#e67e22,color:#000
    style C fill:#6929C4,color:#fff
Loading

Key outputs:

Output Description
Timing plot Classical (red) vs quantum (blue) wall-clock time vs $N$
Exponential fit $t_c(N) = a_c e^{b_c N}$, $t_q(N) = a_q e^{b_q N}$
Crossover estimate $n_{\text{cross}}$ with uncertainty bounds
MPS baseline Bond dimension required for classical tensor-network simulation

Modules used: benchmarks.quantum_advantage, benchmarks.mps_baseline

08 — Identity Continuity

File: notebooks/08_identity_continuity.ipynb

Explores the SCPN identity hypothesis: that a synchronised ground state constitutes a stable attractor representing a persistent "identity" in the Kuramoto-XY framework. This notebook runs five analyses:

  1. VQE attractor basin — perturb the ground state parameters and measure how reliably VQE reconverges. The basin width quantifies robustness.
  2. Coherence budget — decompose the Heron r2 error into gate, readout, and decoherence contributions using the measured hardware parameters.
  3. Entanglement witness — CHSH $S$-parameter for identity-critical qubit pairs.
  4. Spectral fingerprint — Laplacian eigenvalues of $K_{nm}$ as a topology-dependent identity key, verified via HMAC.
  5. Phase roundtrip — encode phases $\to$ quantum state $\to$ recover phases. Measures roundtrip fidelity.

Key outputs:

Analysis Output
Attractor basin Reconvergence rate vs perturbation magnitude
Coherence budget Pie chart of error contributions
CHSH witnesses $S$-parameters for identity-critical pairs
Fingerprint 16-element spectral vector + HMAC verification
Phase roundtrip Input vs recovered phases (scatter plot, RMSE)

Modules used: identity.ground_state, identity.coherence_budget, identity.entanglement_witness, identity.identity_key, identity.binding_spec

09 — ITER Disruption Classifier

File: notebooks/09_iter_disruption.ipynb

A quantum machine learning application: classify tokamak plasma disruptions using 11 physics-based features from the ITER Physics Basis (Nuclear Fusion 39, 1999). The 11-dimensional feature vector is amplitude-encoded into 4 qubits (zero-padded to 16), and a parametric circuit acts as the classifier.

This is the bridge between SCPN quantum control and nuclear fusion engineering. Real tokamak disruptions cause sudden loss of plasma confinement, potentially damaging the vessel wall. Early detection (the "disruption predictor") is one of the highest-priority engineering challenges for ITER.

Feature space (11 dimensions):

Feature Symbol Physical meaning
Plasma current $I_p$ Total toroidal current
Safety factor $q_{95}$ MHD stability margin
Internal inductance $l_i$ Current profile peakedness
Greenwald fraction $n_{\text{GW}}$ Density limit proximity
Normalized beta $\beta_N$ Pressure stability limit
Radiated power $P_{\text{rad}}$ Power loss channel
Locked mode LM Rotating → locked tearing mode
Loop voltage $V_{\text{loop}}$ Resistive dissipation
Stored energy $W$ Thermal energy content
Elongation $\kappa$ Plasma shape factor
Current ramp $dI_p/dt$ Temporal gradient

Key outputs:

  • Feature distribution plots (disruption vs stable)
  • Classifier accuracy on synthetic test set
  • Confusion matrix

Modules used: control.q_disruption_iter, applications.disruption_classifier

10 — QSNN Training

File: notebooks/10_qsnn_training.ipynb

Trains a quantum spiking neural network using the parameter-shift gradient rule. Each neuron is a qubit with $R_y(\theta)$ rotation encoding the membrane potential. Synapses are controlled rotations $CR_y(\theta_w)$. The network learns via a quantum analog of STDP (spike-timing-dependent plasticity).

Classical spiking neural networks in sc-neurocore use stochastic bitstream computation. The quantum version maps the stochastic firing probability $P(\text{spike})$ to $\sin^2(\theta/2)$ — the Born probability of measuring $|1\rangle$ after a $R_y(\theta)$ rotation. Training uses the exact parameter-shift rule rather than finite-difference approximations.

Training pipeline:

graph TD
    A["Encode input\nRy(theta)"] --> B["Entangle\nCRy(theta_w)"]
    B --> C["Measure Z-basis"]
    C --> D["Compute loss"]
    D --> E["Parameter-shift\ngradient"]
    E --> F["Update weights"]
    F --> B

    style E fill:#6929C4,color:#fff
Loading

Key outputs:

Output Description
Loss curve MSE vs training epoch
Weight evolution $\theta_w$ trajectories for each synapse
Spike rate comparison Quantum vs classical firing rates

Modules used: qsnn.qlif, qsnn.qsynapse, qsnn.qstdp, qsnn.training

11 — Surface Code Budget

File: notebooks/11_surface_code_budget.ipynb

Estimates the physical qubit overhead for fault-tolerant quantum simulation of the 16-layer SCPN UPDE. Compares three error correction strategies:

Strategy Code distance Physical qubits (16 logical) Overhead
No QEC — 16 1x
Repetition code $d=3$ 80 5x
Surface code $d=5$ 800 50x

The repetition code protects only against bit-flip errors — sufficient for shallow circuits where dephasing dominates. The surface code handles arbitrary errors but requires $O(d^2)$ physical qubits per logical qubit. The notebook calculates which strategy is feasible on near-term (2026-2028) and mid-term (2028-2032) hardware roadmaps.

Key outputs:

  • Qubit budget table (repetition vs surface vs no QEC)
  • Hardware feasibility timeline
  • Logical error rate vs code distance plot

Modules used: qec.fault_tolerant, qec.surface_code_upde, qec.error_budget

12 — Trapped Ion Comparison

File: notebooks/12_trapped_ion_comparison.ipynb

Runs the same Kuramoto-XY circuit on two noise models — IBM Heron r2 (superconducting, nearest-neighbour connectivity) and a QCCD trapped-ion model (all-to-all connectivity, slower gates, longer coherence times) — and compares the results.

Superconducting qubits are fast but noisy and topologically constrained (SWAP overhead for non-adjacent interactions). Trapped ions are slower but have all-to-all connectivity (no SWAPs needed) and longer coherence times. For the Kuramoto Hamiltonian — which has long-range coupling from the exponential decay in $K_{nm}$ — the connectivity advantage of trapped ions can offset their slower gate speed.

Comparison:

Metric Superconducting (Heron r2) Trapped ion (QCCD)
2-qubit gate error 0.5% (CZ) 0.5% (MS)
Gate time 60 ns (CZ) 200 $\mu$s (MS)
$T_1$ 300 $\mu$s 100 ms
Connectivity Heavy-hex (sparse) All-to-all
SWAP overhead (4q) 0 0
SWAP overhead (16q) ~12 SWAPs 0

Key outputs:

  • Transpiled circuit comparison (gate counts, depth)
  • Noisy $\langle Z \rangle$ expectations (both backends)
  • Fidelity vs circuit depth for both architectures

Modules used: hardware.trapped_ion, hardware.runner

13 — Cross-Repo Bridges

File: notebooks/13_cross_repo_bridges.ipynb

Demonstrates all cross-repository integration bridges:

graph LR
    SC["sc-neurocore\n(SNN)"] --> |"snn_adapter"| QC["scpn-quantum-\ncontrol"]
    SSGF["SSGF geometry\nengine"] --> |"ssgf_adapter"| QC
    PO["scpn-phase-\norchestrator"] --> |"orchestrator_adapter"| QC
    FC["scpn-fusion-\ncore"] --> |"control_plasma_knm"| QC
    QC --> |"phase_artifact"| PO

    style QC fill:#6929C4,color:#fff
Loading
  1. SNN adapter — converts ArcaneNeuron membrane potentials from sc-neurocore into $R_y(\theta)$ rotation angles for the quantum layer, and back.
  2. SSGF adapter — maps the SSGF geometry matrix $W$ to a quantum Hamiltonian via the same $K_{nm} \to H$ compiler, enabling quantum-in-the-loop geometry optimization.
  3. Orchestrator adapter — translates scpn-phase-orchestrator state payloads (regime label, phase vector, confidence score) into UPDEPhaseArtifact for quantum simulation, and feeds quantum results back as advance/hold/rollback signals.
  4. Fusion-core adapter — imports plasma-native $K_{nm}$ from scpn-control and scpn-fusion-core coupling calibration.

Key outputs:

Bridge Test Output
SNN adapter Membrane $\to$ angle $\to$ membrane roundtrip RMSE < 0.01
SSGF adapter $W \to H \to$ Trotter $\to$ phases $\to W'$ Phase fidelity plot
Orchestrator State payload $\to$ artifact $\to$ quantum $\to$ feedback Advance/hold decision
Fusion-core Plasma $K_{nm} \to$ Hamiltonian $\to R$ Coupling comparison

Modules used: bridge.snn_adapter, bridge.ssgf_adapter, bridge.orchestrator_adapter, bridge.control_plasma_knm, bridge.phase_artifact

FIM Investigation Campaign (NB14–47)

Notebooks 14-47 form a systematic investigation of the FIM (Fisher Information Metric) strange loop mechanism. See RESULTS_SUMMARY.md for the full findings. All results are saved as JSON in results/.

# Notebook Finding
14 DLA parity IBM hardware Simulator: odd more robust. Hardware: circuit depth artefact
15 Inverse layer optimisation K_nm validated r=0.951 with data-driven mapping
16 Alpha calibration literature Direction correct, magnitude off 30-95x
17 Hierarchical N=16 sync Hierarchy does NOT help (negative)
18 Clinical TDA connectivity No topological advantage over coherence (negative)
19 Directed coupling TE Cross-scale coupling IS directed (asymmetry 0.36)
20 FIM phase transition order FIM creates hysteresis (width 0.61)
21 Scale frustration pathology Direction correct, not significant (negative)
22 Cross-frequency observables PAC, wavelet coherence, Granger confirm SCPN
23 Geometric curvature K_nm Curvature NOT at K_c (negative)
24 Directed K_nm + FIM N=16 FIM solves N=16, directed hurts
25 FIM scaling law λ_c(N) = 0.149·N^1.02
26 Phase diagram (K,λ) FIM alone synchronises at λ≥8
27 Stability analysis 100% basin, hysteresis 0.65, 1.4s recovery
28 Information-theoretic Φ +73%, Fisher info +5 orders
29 Multi-scale sync dynamics Direct global sync, not hierarchical
30 Empirical FIM estimation Method fails (needs Bayesian rework)
31 FIM × MBL interaction FIM enhances MBL (dual protection)
32 Chimera states No chimeras under FIM (clean transition)
33 Entropy production P = 0.085λ (linear thermodynamic cost)
34 Critical slowing down τ = 330 at BKT transition
35 Anaesthesia prediction 6 testable clinical predictions
36 Topology universality Universal on all 6 networks, small-world optimal
37 Mean-field self-consistent R* = √(1−2Δ/(K·R+λ·R/(1−R²+ε)))
38 FIM-MBL mechanism M²/n sector splitting, 2.3x spectrum stretch
39 IBM hardware v2 Equal-depth aggregate artifacts, unpromoted pending raw-count review
40 SPO cross-validation U(1) confirmed, Lyapunov correspondence 5/6
41 Stochastic resonance FIM-mediated SR at weak coupling
42 Delayed FIM Delay-robust with coupling, fragile without
43 Critical exponents BKT universality (β→0, not mean-field)
44 FIM-modulated learning No benefit (FIM ≠ learning signal, negative)
45 Noise as purification Not confirmed on symmetric noise (negative)
46 Metabolic scaling P∝N matches biology (r=0.983, 6 species)
47 Topological defects FIM suppresses vortices 8→0

Running Locally

pip install -e ".[dev]"
jupyter notebook notebooks/

All notebooks run on qiskit-aer (AerSimulator). Typical execution time: 30 seconds to 3 minutes per notebook on a modern laptop. No GPU required.

Running on Colab

Click the "Open in Colab" badge on the README, or upload any notebook to colab.research.google.com. The first cell installs dependencies:

!pip install scpn-quantum-control[dev]

Colab's free T4 GPU is not needed for these notebooks (all computation is statevector simulation), but it can speed up the 16-qubit UPDE notebook by ~2x via CuPy offload if gpu_accel is available.