Skip to content

DMRGPY

DMRGPY is a Python library for quasi-one-dimensional quantum many-body systems: spin chains, spinless and spinful fermions, bosons and parafermions. Ground states, excitations, dynamical correlators, real-time evolution and finite temperature are computed with matrix product states. Small systems can also be solved with exact diagonalization (ED), so every DMRG result can be checked on a short chain.

This guide explains how to compute physical quantities. For each capability it gives the quantity, its formula, the code and the keywords that matter. The code itself is on GitHub, and the whole guide is also available as one PDF.

Installation

pip install dmrgpy

This installs ED and a DMRG code written in pure Python. It needs no compiler and works on Linux, Mac and Windows. The faster C++ backend (ITensor) is compiled from a clone of the repository with python install.py; the README explains how.

A first calculation

The ground-state energy of a spin-1/2 Heisenberg chain of 12 sites, with DMRG and with ED:

from dmrgpy import spinchain
n = 12
sc = spinchain.Spin_Chain(["S=1/2" for i in range(n)])
h = sum(sc.Sx[i]*sc.Sx[i+1] + sc.Sy[i]*sc.Sy[i+1] + sc.Sz[i]*sc.Sz[i+1]
        for i in range(n-1))
sc.set_hamiltonian(h)
print(sc.gs_energy())            # DMRG
print(sc.gs_energy(mode="ED"))   # exact diagonalization

Both print \(E_0\approx-5.1420906\). Every chain class has the same methods, and most of them accept mode="ED" in the same way.

Dynamical spin structure factor of the Heisenberg chain Dynamical spin structure factor of the Heisenberg chain

A Heisenberg chain with \(n=32\) gives the dynamical spin structure factor \(S(q,\omega)\), the quantity measured by inelastic neutron scattering. The weight fills the two-spinon continuum between its exact edges (dashed). See Dynamical correlators.

Code of this figure (docs/figures/dynamical-correlators_sqw/)
compute.py
# Dynamical spin structure factor S^zz(q,w) of the open spin-1/2 Heisenberg
# chain, one KPM run per momentum. On an open chain the momentum states are
# standing waves, S^z_q = sqrt(2/(n+1)) sum_i sin(q(i+1)) S^z_i, q = pi k/(n+1).
import numpy as np
from dmrgpy import spinchain, kpmdmrg

n = 32
delta = 0.15
es = np.linspace(0.0, 4.0, 400)
qs = np.pi*np.arange(1, n+1)/(n+1)

sc = spinchain.Spin_Chain(["S=1/2"]*n)
h = sum(sc.Sx[i]*sc.Sx[i+1] + sc.Sy[i]*sc.Sy[i+1] + sc.Sz[i]*sc.Sz[i+1]
        for i in range(n-1))
sc.set_hamiltonian(h)
sc.maxm, sc.nsweeps, sc.cutoff = 80, 14, 1e-12
sc.kpmmaxm = 40  # kpmmaxm=80 changes S(q,w) at q close to pi by less than 1%
sc.gs_energy()


def spectrum(x, mus, emin, emax, scale, npol, d):
    _, y = kpmdmrg.dynamical_correlator_from_moments(
        mus, emin, emax, scale, npol, x, kernel="jackson", delta=d,
        origin=sc.e0)
    return y.real


sqw, sumrule, sq = [], [], []
for q in qs:
    Sq = sum(np.sqrt(2/(n+1))*np.sin(q*(i+1))*sc.Sz[i] for i in range(n))
    m = sc.get_dynamical_correlator_moments(name=(Sq, Sq), delta=delta)
    sqw.append(spectrum(es, *m))
    # sum rule: the integral over the whole spectrum is <S^z_q S^z_q>
    ew = np.linspace(-1.0, m[2] - sc.e0 + 1.0, 20000)
    sumrule.append(np.trapezoid(spectrum(ew, *m), ew))
    sq.append(sc.vev(Sq*Sq).real)

np.savez("data.npz", qs=qs, es=es, sqw=sqw, sumrule=sumrule, sq=sq)
plot.py
import numpy as np
from matplotlib.colors import PowerNorm
import style

d = np.load("data.npz")
qs, es = d["qs"], d["es"]
sqw = np.clip(d["sqw"], 0.0, None)  # tiny Jackson ringing below zero
# two-spinon continuum edges
qq = np.linspace(0, np.pi, 300)
lower, upper = np.pi/2*np.abs(np.sin(qq)), np.pi*np.abs(np.sin(qq/2))
cuts = [int(np.argmin(np.abs(qs - np.pi/2))), len(qs) - 1]


def draw(theme):
    c = style.colors(theme)
    fig, (a1, a2) = style.figure(2, gridspec_kw={"width_ratios": [1.15, 1]})
    im = a1.pcolormesh(qs/np.pi, es, sqw.T, cmap=style.CMAP, shading="nearest",
                       norm=PowerNorm(0.5, vmin=0, vmax=np.percentile(sqw, 99.5)),
                       rasterized=True)
    a1.plot(qq/np.pi, lower, **style.heatmap_line())
    a1.plot(qq/np.pi, upper, **style.heatmap_line())
    a1.set_xlim(0, 1)
    a1.set_ylim(es[0], es[-1])
    a1.set_xlabel(r"$q$ [$\pi$]")
    a1.set_ylabel(r"$\omega$ [$J$]")
    style.colorbar(fig, im, a1, r"$S^{zz}(q,\omega)$ [$1/J$]", theme)
    big = np.max(sqw[cuts[-1]])
    for k, idx in enumerate(cuts):
        q, col = qs[idx], c["series"][k]
        f = max(1, int(round(0.5*big/np.max(sqw[idx])))) if k == 0 else 1
        a2.plot(es, f*sqw[idx], color=col, lw=style.LW,
                label=r"$q=%.2f\pi$%s, $\int S\,d\omega$=%.4f (exact %.4f)"
                % (q/np.pi, r" ($\times%d$)" % f if f > 1 else "",
                   d["sumrule"][idx], d["sq"][idx]))
        a2.axvline(np.pi/2*np.sin(q), color=col, ls=":", lw=style.LW_REF)
    a2.set_xlim(es[0], es[-1])
    a2.set_ylim(0, None)
    a2.set_xlabel(r"$\omega$ [$J$]")
    a2.set_ylabel(r"$S^{zz}(q,\omega)$ [$1/J$]")
    a2.legend(loc="upper right")
    fig.tight_layout()
    return fig


style.main(draw, "dynamical-correlators_sqw")

Backends

The keyword itensor_version= of a chain chooses the DMRG code. The results are the same; only the speed and a few features differ.

  • 3: ITensor v3 in C++, the default when it is compiled. The fastest.
  • "python": the pure-Python DMRG, the default after pip install. It can also run on a GPU (Performance).
  • 2: ITensor v2 in C++. Some features are missing.
  • "julia_live": ITensors.jl in Julia, after pip install "dmrgpy[julia]".

mode="ED" uses exact diagonalization instead of DMRG, for small chains.

Contents of the guide

  • Getting started: the chain classes, their local operators, and how to write a Hamiltonian.
  • Ground state: energies, expectation values, correlators and conserved sectors; the solver settings and warm starts; excited states and degeneracies; entanglement; four-point correlators and distributions; mean-field decoupling.
  • Phases: Berry phases, fermion parity and the fidelity susceptibility.
  • Dynamics: dynamical correlators, spectral functions and the local density of states, real-time evolution and STM spectra.
  • Finite temperature: purification, METTS and ED.
  • Infinite chains: iDMRG and VUMPS directly in the thermodynamic limit.
  • More: the common models written out, post-processing tools and performance.