Skip to content

Quick start

Welcome to XDiag! This quick start walks you through your very first exact diagonalization: computing the ground-state energy of the spin \(S=1/2\) Heisenberg chain, $$ H = J\sum_{\langle i,j \rangle} \mathbf{S}_i \cdot \mathbf{S}_j, $$ on a periodic one-dimensional lattice. Here \(\mathbf{S}_i = (S_i^x, S_i^y, S_i^z)\) are the spin \(S=1/2\) operators and \(\langle i,j \rangle\) denotes summation over nearest-neighbor sites \(i\) and \(j\).

XDiag comes in two flavors that share the same API — a Julia package for interactive use and a C++ library for maximum performance. Pick whichever you prefer below. For a thorough, step-by-step introduction, see the User Guide.

Installation

Enter the package mode in the Julia REPL by typing ] and run 

add XDiag
That's it — no compilation step is required.

First compile and install the XDiag library, following the library compilation instructions. The application code below is then compiled against it.

Your first calculation

The complete program to set up the Heisenberg chain and compute its ground-state energy reads:

using XDiag

let
    say_hello()
    N = 16
    nup = N ÷ 2
    block = Spinhalf(N, nup)

    # Define the nearest-neighbor Heisenberg model
    ops = OpSum()
    for i in 1:N
        ops += "J" * Op("SdotS", [i, mod1(i+1, N)])
    end
    ops["J"] = 1.0

    set_verbosity(2)            # set verbosity for monitoring progress
    e0 = eigval0(ops, block)    # compute ground state energy

    println("Ground state energy: $e0")
end

#include <xdiag/all.hpp>

using namespace xdiag;

int main() try {
  say_hello();
  int N = 16;
  int nup = N / 2;
  Spinhalf block(N, nup);

  // Define the nearest-neighbor Heisenberg model
  OpSum ops;
  for (int i = 0; i < N; ++i) {
    ops += "J" * Op("SdotS", {i, (i + 1) % N});
  }
  ops["J"] = 1.0;

  set_verbosity(2);                  // set verbosity for monitoring progress
  double e0 = eigval0(ops, block); // compute ground state energy

  Log("Ground state energy: {:.12f}", e0);
} catch (Error e) {
  error_trace(e);
}

In just a few lines we define the Hilbert space (a Spinhalf block), build the Hamiltonian as an OpSum, and obtain the ground-state energy with eigval0.

C++ error traces

The try / catch clause implements an error-trace mechanism, activated by error_trace. While optional, we recommend it for every XDiag application, as it produces a readable traceback when a runtime error occurs.

C++ compilation

Once written, the application is compiled with CMake — see the application compilation instructions. The C++ version also lets you optimize the compiled code for your target architecture, which can give a substantial speed-up (see optimization).

Next steps