Trotter Quantum Simulator (trotter_qsim)

A sparse, persistent quantum state simulator for the two-excitation XXZ spin chain, featuring:

• Second-order Trotter decomposition for O(dt³) global accuracy
• Sparse in-memory state representation for efficient scaling
• Binary persistence for resumable simulations
• CLI parameter control for flexible experimentation
• Optional GPU kernel stubs (future integration-ready)

🧠 Overview

trotter_qsim simulates the time evolution of a 1D spin chain under the XXZ Hamiltonian:

[ H = \sum_i J (X_i X_{i+1} + Y_i Y_{i+1}) + \Delta Z_i Z_{i+1} ]

The simulator uses second-order symmetric Trotter decomposition to approximate the unitary evolution operator:

[ U(\Delta t) \approx e^{-i H_{\text{even}} \Delta t / 2} e^{-i H_{\text{odd}} \Delta t} e^{-i H_{\text{even}} \Delta t / 2} ]

This achieves cubic order accuracy in the timestep ((O(\Delta t^3))) while maintaining numerical stability and normalization through periodic renormalization.

⚙️ Features

• Sparse Amplitude Storage: Only non-negligible amplitudes (|ψ| > threshold) are kept in memory.
• Disk Persistence: Saves simulation state to quantum_state.bin, allowing resumption from checkpoints.
• Customizable Dynamics: Adjustable XXZ parameters (J, Δ, dt, steps) via command-line.
• Research Logging: Records key observables (occupation and correlations) into observables.csv.
• Extensible Design: Includes OpenCL kernel placeholders for future GPU acceleration.

🚀 Quick Start

1. Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. Clone and Build

git clone https://github.com/<yourname>/trotter_qsim.git
cd trotter_qsim
cargo build --release

3. Run the Simulation

cargo run --release --     --num-qubits 60     --delta -1.5     --dt 0.05     --steps 600     --j 1.0     --threshold 1e-8

The program will output progress logs and write observables to observables.csv.

📊 Output Files

Example output snippet from observables.csv:

Time,P_Q29,P_Q30,C_Q30_Q29,Total_Prob
0.000,0.000000,1.000000,0.000000,1.000000
0.500,0.012532,0.987468,0.002300,0.999998

🔧 Command-Line Options

🧩 Project Structure

trotter_qsim/
├── Cargo.toml
├── README.md
├── src/
│   └── main.rs          # Core simulation logic and CLI entry point
├── target/release/
│   └── trotter_qsim.exe # Compiled binary
└── observables.csv      # Output log (generated after run)

🧮 Mathematical Model

The system evolves according to: [ |\psi(t + \Delta t)\rangle = U(\Delta t)|\psi(t)\rangle ] with each Trotter layer applying alternating even/odd two-site unitaries: [ U_{i,i+1} = e^{-i J \Delta t (X_i X_{i+1} + Y_i Y_{i+1})} e^{-i \Delta \Delta t Z_i Z_{i+1}} ]

For large systems, only amplitudes above a configurable threshold are tracked, enabling simulations beyond 30–40 qubits on standard hardware.

💾 Save/Resume

To resume a simulation:

cargo run --release

If quantum_state.bin exists, it will be automatically loaded; otherwise, a fresh initial state will be created.

🧠 Future Enhancements

• GPU acceleration via OpenCL or CUDA backend
• Arbitrary excitation sectors (not just 2-particle)
• Alternative Hamiltonians (Heisenberg, XY, random field XXZ)
• Parallelized logging and diagnostics

📜 License

MIT License © 2025 Angry Beaver