SpinParser

SpinParser ("Spin Pseudofermion Algorithms for Research on Spin Ensembles via Renormalization") is a software platform to perform pseudofermion functional renormalization group (pf-FRG) calculations to solve lattice spin models of quantum magnetism.

The pf-FRG algorithm has first been proposed in [Reuther and Wölfle (2010)] for Heisenberg models on two-dimensional lattices geometries.

The current implementation of the SpinParser is based on a generalized approach [Buessen et al. (2019)] which allows to solve general quantum spin Hamiltonians of the form

<p align="center"><img src="doc/assets/equation_1.png"></p>

where the sum over lattice sites i and j is defined on arbitrary two- or three-dimensional lattices and the spin operator <img src="doc/assets/equation_2.png" style="vertical-align:-4pt"> resembles the <img src="doc/assets/equation_3.png" style="vertical-align:-3pt"> component of a spin-1/2 moment at lattice site i.

In the following, this document provides installation instructions and a quick start guide. A more thorough documentation can be found in the accompanying publication, Ref. [Buessen (2021)].

Citation

If the SpinParser project benefits your research, please acknowledge it by citing the following references:

• Finn Lasse Buessen, The SpinParser software for pseudofermion functional renormalization group calculations on quantum magnets, SciPost Phys. Codebases 5 (2022)
• Finn Lasse Buessen, Codebase release 1.0 for SpinParser, SciPost Phys. Codebases 5-r1.0 (2022)

@Article{10.21468/SciPostPhysCodeb.5,
	title={{The SpinParser software for pseudofermion functional renormalization group calculations on quantum magnets}},
	author={Finn Lasse Buessen},
	journal={SciPost Phys. Codebases},
	pages={5},
	year={2022},
	publisher={SciPost},
	doi={10.21468/SciPostPhysCodeb.5},
	url={https://scipost.org/10.21468/SciPostPhysCodeb.5},
}

@Article{10.21468/SciPostPhysCodeb.5-r1.0,
	title={{Codebase release 1.0 for SpinParser}},
	author={Finn Lasse Buessen},
	journal={SciPost Phys. Codebases},
	pages={5-r1.0},
	year={2022},
	publisher={SciPost},
	doi={10.21468/SciPostPhysCodeb.5-r1.0},
	url={https://scipost.org/10.21468/SciPostPhysCodeb.5-r1.0},
}

Table of contents

• Overview
• Installation
  • Prerequisites
  • Download sources
  • Build from source
  • Install optional tools
• Quick start
  • Prepare a task file
  • Verify the model implementation
  • Run the calculation
  • Evaluate SpinParser output and measurements
• Developer documentation

Overview

Owing to the large class of spin models that can be studied within the pf-FRG approach, the aim of this software implementation is to provide fast, yet flexible numerics for the efficient solution of pf-FRG flow equations.

To allow for easy and universal use, the spin model and the underlying lattice geometry can be defined as plain-text .xml files. The SpinParser provides a built-in abstraction layer to identify symmetries in the spin lattice model and exploit them in the subsequent solution of the flow equations.

The numerical core for the solution of the flow equations themselves is designed to run on massively parallel high-performance computing platforms. It utilizes a hybrid OpenMP/MPI parallelization scheme to make efficient use of individual shared-memory computing nodes, while still allowing to scale across multiple computing nodes.

Due to the algebraic nature of the flow equations (being a large set of coupled integro-differential equations) the computation time for individual contributions to the flow equations can vary. To mitigate the impact, SpinParser performs dynamic load balancing across the different computing nodes. It is thus in principle also possible to efficiently run the code on heterogeneous computing platforms.

This software contains three different numerical cores, which are optimized for different classes of spin models:

• A numerical core for spin-1/2 SU(2)-symmetric spin models with an extension for spin-S SU(2) models as put forward in [Baez and Reuther (2017)]
• A numerical core for Kitaev-like spin-1/2 models with diagonal interactions as put forward in [Reuther et al. (2011)]
• A numerical core for general spin-1/2 models which may include off-diagonal two-spin interactions as put forward in [Buessen et al. (2019)]

Installation

SpinParser needs to be built from source. The build process makes use of the cmake build system. SpinParser is relatively easy to compile and only depends on a few libraries. The build process is described in a step-by-step guide below, exemplified for Ubuntu 20.04 LTS.

Prerequisites

You need to ensure that the following software and libraries are installed on the system:

• Cmake (version 3.16 or newer)
• Boost (version 1.71.0 or newer)
• HDF5 (version 1.10.4 or newer)
• MPI (optional, recommended)
• Doxygen (optional, required for generating documentation files)

Furthermore, in order for the optional python tools to work and tests to be evaluated correctly, a Python installation is required with the following libraries available:

• numpy
• h5py
• matplotlib
• pdoc3

To ensure that all these libraries are installed, invoke the following OS specific commands in your terminal. (You might want to drop the python part if you already have a Python installation.)

Linux:

sudo apt install git cmake libboost-all-dev libhdf5-dev libopenmpi-dev doxygen graphviz python-is-python3 python3-pip

python3 -m pip install numpy h5py matplotlib pdoc3

MacOS (via Homebrew):

brew install git cmake hdf5 boost doxygen graphviz libomp python

python -m pip install numpy h5py matplotlib pdoc3

The SpinParser might also successfully build with older library versions. Especially when tests are disabled (see below), older versions of boost are also compatible; if the generation of documentation files is disabled (see below), older versions of cmake might work.

Download sources

Create and enter a working directory, say

mkdir SpinParser && cd SpinParser

Next, clone a copy of the source files

git clone https://github.com/fbuessen/SpinParser.git SpinParserSource

which should leave you with a directory SpinParserSource, which, among other files and subdirectories, contains a file CMakeLists.txt.

Build from source

Now it is time to compile the sources. It is recommended to build the software in a separate directory, which we shall name build. Furthermore, we want to create a directory install, into which the final compiled software will be moved. Therefore, we create two directories and enter the separate build directory by executing (from within the original working directory SpinParser)

mkdir build && mkdir install && cd build

We instruct cmake to generate the makefiles for our project by invoking

cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../install ../SpinParserSource

The above command includes two command line arguments which tell cmake how to build and install the code. The argument -DCMAKE_BUILD_TYPE=Release specifies that the generated code is intended to be used for production, i.e., the compiler is instructed to perform code optimization. Alternatively, we could set the value to Debug which would instruct the compiler to include debug symbols. The second argument, -DCMAKE_INSTALL_PREFIX=../install defines where the generated code will ultimately be moved. We intend to move it to the install directory which we created in the previous step.

When executing the command, cmake attempts to locate all relevant libraries and files. On a simple Ubuntu installation, it should usually succeed in doing so. If this fails, for example because the libraries are installed in non-standard locations, it is possible to provide cmake with additional hints where to search for the libraries. For the boost library, such hint would be along the lines of -DBOOST_ROOT=/path/to/boost/library. For the HDF5 library, the hint would be -DHDF5_ROOT=/path/to/hdf5/library.

Furthermore, the SpinParser build environment allows you to specify some additional options:

• -DSPINPARSER_BUILD_TESTS=OFF disables building tests (ON by default).
• -DSPINPARSER_BUILD_DOCUMENTATION=OFF disables building the documentation / developer's reference (ON by default).
• -DSPINPARSER_ENABLE_ASSERTIONS=ON enables some additional memory boundary and consistency checks. Useful when deriving code or building your own extensions, but slows down the application (OFF by default).
• -DSPINPARSER_DISABLE_MPI=ON disables MPI parallelization, which allows code building on systems with no MPI library installed. Can be useful for simplified builds for instrumentation or debugging (OFF by default).
• -DSPINPARSER_DISABLE_OMP=ON disables OpenMP parallelization. Can be useful for simplified builds for instrumentation or debugging (OFF by default).

Once the cmake command has completed, the build files have been generated and we are ready to compile, test, and install the code. This is d