qdynet

A lightweight, educational Python library for simulating one-dimensional quantum spin chains using the Time-Evolving Block Decimation (TEBD) algorithm with Matrix Product States (MPS).

Features

• Ground-state preparation via imaginary-time evolution
• Real-time quench dynamics for studying information spreading
• Light-cone visualization with Lieb-Robinson bound validation
• Systematic error analysis (Trotter, truncation, convergence)
• Modular design — easily extend to new models
• Minimal dependencies — only NumPy, SciPy, and Matplotlib

Installation

git clone https://github.com/yi-hsiu-yang/qdynet.git
cd qdynet
pip install -e .

Quick Start

Ground-State Preparation

from qdynet.models import TFIM
from qdynet.mps import product_state_mps, imaginary_time_evolution
from qdynet.observables import half_chain_entropy
from qdynet.utils import TEBDConfig

# Configure simulation
config = TEBDConfig(L=40, chi_max=64, dtau=0.02)

# Initialize MPS in |+⟩^⊗L state
mps = product_state_mps(config.L, state="plus")

# Create TFIM at critical point (J=h=1)
model = TFIM(J=1.0, h=1.0, L=config.L)

# Evolve to ground state
mps, history = imaginary_time_evolution(mps, model, config)

# Measure observables
energy = model.energy_density(mps)
entropy = half_chain_entropy(mps)
print(f"E/N = {energy:.6f}, S = {entropy:.4f}")

Quench Dynamics

from qdynet.mps import real_time_evolution, apply_local_operator
from qdynet.observables import measure_profile
import numpy as np

# Prepare ground state (as above)...

# Apply X operator at center site
X = np.array([[0, 1], [1, 0]])
mps_perturbed = apply_local_operator(mps, X, site=config.L // 2)

# Evolve in real time
config_real = TEBDConfig(L=40, chi_max=64, dt=0.01, t_max=3.0)
mps_t, profiles = real_time_evolution(mps_perturbed, model, config_real)

Project Structure

qdynet/
├── src/qdynet/              # Core library
│   ├── models/              # Physical models (TFIM, XXZ)
│   │   ├── base.py          # Abstract base class
│   │   ├── tfim.py          # Transverse-field Ising model
│   │   └── xxz.py           # XXZ Heisenberg model
│   ├── mps/                 # MPS representation and TEBD
│   │   ├── mps_init.py      # State initialization
│   │   ├── tebd.py          # TEBD algorithm
│   │   ├── evolution.py     # High-level evolution routines
│   │   └── gates.py         # Gate utilities
│   ├── observables/         # Measurement functions
│   │   ├── energy.py        # Energy computation
│   │   ├── entropy.py       # Entanglement entropy
│   │   ├── mps_utils.py     # MPS manipulation utilities
│   │   └── correlators.py   # Two-point functions
│   ├── analysis/            # Post-processing tools
│   │   └── front.py         # Light-cone front tracking
│   └── utils/               # Configuration and utilities
│       ├── config.py        # Centralized parameters
│       ├── svd.py           # SVD with truncation
│       └── timing.py        # Performance measurement
└── experiments/             # Runnable experiment scripts
    ├── ground_state.py      # Ground-state preparation
    ├── quench_dynamics.py   # Light-cone dynamics
    ├── convergence.py       # Parameter sweeps
    └── error_analysis.py    # Systematic error budget

Experiment Scripts

Run pre-built experiments from the experiments/ directory:

# Ground-state preparation
python experiments/ground_state.py
# Outputs: ground_state.csv, fig_gs_energy.png, fig_gs_entropy.png

# Quench dynamics and light-cone visualization
python experiments/quench_dynamics.py
# Outputs: quench_profiles.csv, quench_diagnostics.csv, fig_quench_log.png, fig_quench_front.png

# Parameter convergence analysis
python experiments/convergence.py
# Outputs: convergence.csv, fig_conv_E_vs_chi.png, fig_conv_S_vs_chi.png, fig_conv_time.png

# Full error budget (~8 hours)
python experiments/error_analysis.py --full

# Quick validation (~15 minutes)
python experiments/error_analysis.py --fast
# Outputs: error_*.csv, error_analysis.txt, fig_error_analysis.png

Physical Models

Transverse-Field Ising Model (TFIM)

$$H = -J \sum_{i=1}^{L-1} Z_i Z_{i+1} - h \sum_{i=1}^{L} X_i$$

The model exhibits a quantum phase transition at $g \equiv h/J = 1$:

• $g < 1$: Ordered (ferromagnetic) phase
• $g > 1$: Disordered (paramagnetic) phase
• $g = 1$: Critical point with logarithmic entanglement scaling

Exact ground-state energy density (thermodynamic limit): $E_0/L = -4J/\pi \approx -1.2732$

XXZ Model

$$H = J \sum_{i} \left( X_i X_{i+1} + Y_i Y_{i+1} + \Delta Z_i Z_{i+1} \right)$$

Key Results

Validated on TFIM at criticality (J = h = 1, L = 40):

Metric	Value	Note
Ground-state energy	$E/N \approx -1.2598$	~1% deviation from exact (finite-size)
Numerical error	$\delta E \approx 6 \times 10^{-4}$	Trotter + truncation + convergence
Light-cone velocity	$v \approx 1.4$–1.8	Below Lieb-Robinson bound $v_{LR} = 2J$

Default Parameters

Parameter	Ground State	Quench Dynamics
System size $L$	40	40
Bond dimension $\chi$	64	64
Time step $\delta$	$d\tau = 0.02$	$dt = 0.01$
Total time	$\tau_{max} = 8$	$t_{max} = 3$
Trotter order	1st	2nd
SVD threshold $\epsilon$	$10^{-10}$	$10^{-12}$

Adding New Models

Extend the SpinChainModel base class:

from qdynet.models.base import SpinChainModel
from scipy.linalg import expm
import numpy as np

class MyModel(SpinChainModel):
    def __init__(self, L, **params):
        super().__init__(L)
        self.params = params
    
    def two_site_gate(self, dt, kind="real"):
        """Return exp(-dt * h_{i,i+1}) for TEBD."""
        # Build local Hamiltonian h_{i,i+1}
        h_local = ...  # Your implementation
        
        if kind == "real":
            return expm(-1j * dt * h_local).reshape(2, 2, 2, 2)
        else:  # imaginary
            return expm(-dt * h_local).reshape(2, 2, 2, 2)
    
    def energy(self, mps):
        """Compute total energy ⟨H⟩."""
        # Your implementation
        pass

Dependencies

Required:

• Python ≥ 3.9
• NumPy ≥ 1.20
• SciPy ≥ 1.7
• Matplotlib ≥ 3.5

Optional:

• pytest (testing)
• tqdm (progress bars)

Tested Environment

Python 3.12.0
NumPy 1.26.4
SciPy 1.12.0
Matplotlib 3.8.3
OS: Ubuntu 22.04 (WSL2 on Windows 11)
Hardware: AMD Ryzen 7 5800U, 16 GB RAM

Performance

Typical execution times on consumer hardware (AMD Ryzen 7, 16 GB RAM):

Task	Time	Memory
Ground state ($\chi=64$)	~3 hours	< 1 GB
Quench dynamics ($t_{max}=3$)	~45 min	< 1 GB
Convergence sweep	~3 hours	< 2 GB
Full error analysis	~8 hours	< 2 GB

References

1. P. Pfeuty, The one-dimensional Ising model with a transverse field, Ann. Phys. 57, 79 (1970)
2. P. Calabrese & J. Cardy, Entanglement entropy and quantum field theory, J. Stat. Mech. (2004)
3. P. Calabrese & J. Cardy, Evolution of entanglement entropy in one-dimensional systems, J. Stat. Mech. (2005)
4. E. H. Lieb & D. W. Robinson, The finite group velocity of quantum spin systems, Commun. Math. Phys. 28, 251 (1972)
5. G. Vidal, Efficient classical simulation of slightly entangled quantum computations, Phys. Rev. Lett. 91, 147902 (2003)
6. G. Vidal, Efficient simulation of one-dimensional quantum many-body systems, Phys. Rev. Lett. 93, 040502 (2004)
7. G. Vidal, Classical simulation of infinite-size quantum lattice systems in one spatial dimension, Phys. Rev. Lett. 98, 070201 (2007)

License

MIT License — see LICENSE for details.

Acknowledgments

This project was developed as part of the module "Modern Computational Techniques for Theoretical Physicists" at King's College London, based on a research idea proposed by Professor Nikolay Gromov.