Source-linked AI summary
QuSpin: a Python Package for Dynamics and Exact Diagonalisation of Quantum Many Body Systems part I: spin chains
Phillip Weinberg, Marin Bukov
TL;DR
QuSpin addresses the continued use of exact diagonalisation for out-of-equilibrium quantum many-body problems by providing an open-source Python package for spin(-photon) chains. It supports symmetry reduction, time evolution, and customisable studies across several dynamical settings, demonstrated through four examples.
Problem
Exact diagonalisation remains widely used for out-of-equilibrium quantum many-body problems, motivating accessible numerical tools for studying diverse dynamics.
Method
QuSpin constructs spin Hamiltonians with arbitrary many-body operators, exploits one-dimensional symmetries to reduce Hilbert spaces, and provides time-evolution and measurement tools for spin(-photon) chains.
Results
Four examples demonstrate QuSpin for XXZ exact diagonalisation, adiabatic control in many-body-localised phases, periodically driven spin-chain heating, and quantised light-atom interactions.
Takeaways & Limitations
QuSpin provides a user-friendly, customisable framework for studying quantum quenches, localisation, Floquet dynamics, adiabatic ramps, and spin-photon interactions.
Takeaways & Limitations
Planned extensions include one-dimensional fermion symmetries, higher spins, bosons, and potentially two-dimensional lattices, so these capabilities are not yet included.
Abstract
from arXiv · showhide
We present a new open-source Python package for exact diagonalization and quantum dynamics of spin(-photon) chains, called QuSpin, supporting the use of various symmetries in 1-dimension and (imaginary) time evolution for chains up to 32 sites in length. The package is well-suited to study, among others, quantum quenches at finite and infinite times, the Eigenstate Thermalisation hypothesis, many-body localisation and other dynamical phase transitions, periodically-driven (Floquet) systems, adiabatic and counter-diabatic ramps, and spin-photon interactions. Moreover, QuSpin's user-friendly interface can easily be used in combination with other Python packages which makes it amenable to a high-level customisation. We explain how to use QuSpin using four detailed examples: (i) Standard exact diagonalisation of XXZ chain (ii) adiabatic ramping of parameters in the many-body localised XXZ model, (iii) heating in the periodically-driven transverse-field Ising model in a parallel field, and (iv) quantised light-atom interactions: recovering the periodically-driven atom in the semi-classical limit of a static Hamiltonian.
1 What Problems can I Solve with QuSpin?
QuSpin is an open-source Python package for exact diagonalisation and dynamics of quantum many-body spin systems. It combines broad Hamiltonian and symmetry support with time evolution, spin-photon coupling, and concise code for studying diverse nonequilibrium problems.
- Package scope: QuSpin provides an optimised open-source Python package for dynamics and exact diagonalisation of quantum many-body spin systems.It is positioned alongside other freely accessible numerical packages while retaining an open-source distribution model.
- Hamiltonian construction: Users can construct arbitrary, including spatially non-local, many-body spin operators.The package supports multi-spin operators that can arise in perturbative expansions or reverse-engineered models.
- Symmetries: Built-in symmetries produce conservation laws and selection rules that reduce the relevant Hilbert-space dimension, enabling studies of larger systems.Supported examples include total magnetisation, parity, spin inversion, and combined parity and spin inversion.
- Dynamics: The package supports arbitrary time-dependent Hamiltonians and real or imaginary time evolution of user-defined quantum states.Time evolution uses SciPy’s ordinary-differential-equation integration tools.
- Applications: QuSpin extends beyond spin chains to interacting spin chains coupled to a single photon mode, using combined photon-and-spin-number conservation.The package is intended for problems including quenches, adiabatic ramps, Floquet systems, localisation, thermalisation, and spin-photon interactions.
- Usability: Typical QuSpin exact-diagonalisation codes contain fewer than 200 lines, reducing setup time and supporting users with little programming experience.The user-friendly interface is demonstrated through short Python examples and can be customised with other packages.
2 How do I use QuSpin?
QuSpin provides a user-friendly workflow for constructing and studying static, time-dependent, disordered, periodically driven, and spin-photon Hamiltonians. The examples emphasize symmetry-reduced exact diagonalization, parameter ramps, heating dynamics, and semiclassical comparisons.
- Workflow: QuSpin guides users from defining physical quantities and plotting their behavior to assembling the Python code that generates those results.The complete code for the examples and figures is provided in the appendices or example-code sections.
- Hamiltonians: Users can construct spin Hamiltonians from local, non-local, and multi-spin operators using operator strings and site-coupling lists.The XXZ example defines interactions and fields on an open chain before specifying static or dynamic operator lists.
- Basis construction: Symmetry sectors such as fixed magnetisation and parity reduce the relevant Hilbert-space dimension, enabling studies of larger systems.For the disordered XXZ example, parity is broken by the disorder field, so the calculation uses the zero-magnetisation sector.
- Driven and spin-photon dynamics: The periodically driven TFIM example studies heating through stroboscopic energy and entanglement-entropy dynamics, while the spin-photon example compares quantum and semiclassical evolution.The spin-photon comparison shows reasonable agreement, with deviations increasing at longer times depending on photon number and drive frequency.
3 Future Perspectives for QuSpin
QuSpin supports diverse exact-diagonalisation calculations and extends its functionality through tensor-product bases, matrix-free operations, parallel symmetry-sector evolution, and arbitrary matrix inputs. The project is designed for broader system support, with additional fermionic, higher-spin, bosonic, and possibly two-dimensional capabilities planned.
- QuSpin supports higher-dimensional Hamiltonians without symmetries and limited higher-dimensional cases that map uniquely to one-dimensional systems.
- The tensor_basis class combines two basis objects through a tensor product, enabling studies such as interacting hard-core-boson ladders.
- HamiltonianOperator performs matrix-vector products without storing matrix elements, reducing memory needs for diagonalising very large spin chains.
- The block_tools module projects states into user-provided symmetry sectors and evolves each block in parallel, including when the initial state lacks the Hamiltonian’s symmetries.
- QuSpin accepts arbitrary matrices as static or dynamic operators, while future work targets fermionic symmetries, higher spins, bosons, and possibly two-dimensional lattices.
A Installation Guide in a Few Steps
The guide notes that QuSpin requires Python 2.7 or Python 3.5 and recommends Anaconda for installing and managing Python packages.
- QuSpin is supported only for Python 2.7 and Python 3.5.
- Anaconda is recommended because it provides Python and manages installed packages.
A.1 Mac OS X/Linux
On Mac OS X and Linux, the guide recommends installing Anaconda or miniconda, then installing QuSpin through conda; manual installation is an alternative requiring prerequisites.
- Anaconda or miniconda is installed by running its installation script with administrative privileges.
- The installer should prepend its installation directory to PATH so the intended Python executable is used from the terminal.
- QuSpin can be installed through conda with `conda install -c weinbe58 quspin`.
- Manual installation requires NumPy, SciPy, and Joblib before running `python setup.py install --record install_file.txt`.
- The recorded install file can be used to remove the package, and updates require removing the current installation before reinstalling.
A.2 Windows
On Windows, the guide instructs users to install Anaconda or miniconda, use the conda terminal for the recommended installation, or manually install QuSpin after installing prerequisites.
- Windows users install Anaconda or miniconda by downloading and executing the installer.
- The recommended Windows installation uses `conda install -c weinbe58 quspin` in the conda terminal.
- The conda installation can be updated by running the installation command regularly.
- Manual installation requires NumPy, SciPy, and Joblib before downloading and extracting QuSpin’s source code.
- The manual procedure runs `python setup.py install --record install_file.txt`, and updates require completely removing the existing version first.
B Basic Use of Command Line to Run Python
This appendix reviews command-line use on Windows and OS X/Linux for navigating folders and running Python scripts.
- The appendix explains command-line use for Windows and OS X/Linux.
- It covers navigating computer folders and directories.
- It also covers running Python scripts from the command line.
B.1 Mac OS X/Linux
On OS X/Linux, users navigate directories and manage files with Unix commands before executing Python scripts from the terminal.
- Unix users can list files, change directories, create directories, copy files, move or rename files, and remove files.The commands shown include ls, cd, mkdir, cp, mv, and rm.
- Unix autocomplete uses the TAB key and stops when a match is ambiguous.The current directory is denoted by "." and the directory above by "..".
- To execute a Python script, users open a terminal and navigate to the directory containing the script.
B.2 Windows
On Windows, users navigate directories and manage files with Windows command-line commands before executing scripts from the terminal.
- Windows users can change directories, list files, create directories, copy files, move or rename files, and erase files.The commands shown include cd, dir, mkdir, copy, move, and erase.
- Windows command-line navigation is used to reach the directory containing the Python script.
- Windows autocomplete uses the TAB key and selects the first alphabetically matching file or folder.The current directory is denoted by "." and the directory above by "..".
B.3 Execute Python Script (any operating system)
Python scripts can be executed on any operating system by opening a terminal, navigating to the script’s directory, and using the execution command.
- A Python script is identified by the .py extension.
- Users must open a terminal and navigate to the directory containing the Python script.
- The section then provides the command used to execute the script.
C Complete Example Codes
The appendix provides complete QuSpin scripts for four examples covering exact diagonalisation, MBL ramps, Floquet heating, and spin-chain dynamics workflows.
- The examples include exact diagonalisation of the XXZ model and adiabatic parameter control in MBL phases.
- Adiabatic Control of Parameters in MBL Phases: The MBL example computes diagonal and entanglement entropies while ramping driven zz-interactions across disorder realisations.It evaluates both MBL and ETH Hamiltonians for the same disorder realisation and evolves states for multiple ramp speeds.
- Adiabatic Control of Parameters in MBL Phases: The MBL and ETH workflows identify states near infinite-temperature energy, evolve them through ramps, and calculate final-state entropies.
- Heating in Periodically Driven Spin Chains: The periodically driven example constructs alternating Hamiltonians, a second-order van Vleck Floquet Hamiltonian, and its kick operator.
- Heating in Periodically Driven Spin Chains: It then rotates the effective Hamiltonian to the stroboscopic basis, computes exact Floquet eigenstates, and evaluates time-dependent and diagonal-ensemble measurements.
D Package Documentation
QuSpin represents quantum many-body operators as sparse matrices, using Cython-compiled code and NumPy/SciPy interfaces to support efficient scientific computation and customisation.
- QuSpin represents quantum many-body operators as matrices whose computation uses custom Cython code compiled into efficient C/C++ shared libraries.The compiled libraries can run orders of magnitude faster than pure Python code.
- The matrices use SciPy sparse formats, allowing QuSpin to interface with NumPy, SciPy, and other mature scientific-computing packages.
- QuSpin includes functionality for common exact-diagonalisation calculations while requiring users to call only a few NumPy or SciPy functions directly.
- The package provides complete, up-to-date documentation online.