Getting Started with NESSi

Getting the Code

The latest stable release of the NESSi package is NESSi-1.0.2 and can be cloned from the GitHub repository:

https://github.com/nessi-cntr/nessi

git clone https://github.com/nessi-cntr/nessi

Download the archive:

Note

This will be updated for v2.0.0.

Installation

The NESSi repository (nessi) contains two folders:

Dependencies for libcntr:

eigen3

required

HDF5

optional, recommended

FFTW3

optional, needed for steady state code

libcntr is compiled and installed using CMake. Several CMake variables must be set (-Dvar=value). While CMake can be called directly, it is more convenient to create a configuration script:

Example configure.sh:

CC=[C compiler] CXX=[C++ compiler]
cmake \
  -DCMAKE_INSTALL_PREFIX=[install directory] \
  -DCMAKE_BUILD_TYPE=[Debug|Release] \
  -Domp=[ON|OFF] \
  -Dhdf5=[ON|OFF] \
  -Dmpi=[ON|OFF] \
  -DBUILD_DOC=[ON|OFF] \
  -Dness=[ON|OFF] \
  -DCMAKE_INCLUDE_PATH=[include directory] \
  -DCMAKE_LIBRARY_PATH=[library directory] \
  -DCMAKE_CXX_FLAGS="[compiling flags]" \
  ..

In the first line the C and C++ compilers are set (tested with GNU gcc/g++ and Intel icc/icpc). The installation directory (example: /home/opt) is provided via CMAKE_INSTALL_PREFIX.

CMAKE_BUILD_TYPE=Debug enables assertions and checks; Release is recommended for production runs.

Optional features:

  • omp=ON — enable OpenMP parallelization

  • mpi=ON — enable MPI routines

  • ness=ON — enable steady-state routines (requires OpenMP + FFTW with --enable-threads)

  • hdf5=ON — use the hdf5 library (recommended version ≥ 1.12)

Paths to required libraries are provided via CMAKE_INCLUDE_PATH and CMAKE_LIBRARY_PATH.

You must include the following compilation flag:

-std=c++11

Compiling and installing

Create a build directory (e.g. cbuild), then run:

sh ../configure.sh

Compile:

make

Install:

make install

Supported Platforms

We have tested installation on:

  • macOS (MacPorts)

  • macOS (Homebrew)

  • Linux (Ubuntu, Debian, CentOS, Arch Linux)

Detailed instructions follow.

macOS with MacPorts

Install dependencies:

sudo port install gcc9 eigen3-devel hdf5
sudo port install openmpi-devel-gcc9

Install Doxygen:

sudo port install doxygen graphviz

Python packages (numpy, scipy, matplotlib, h5py) can be installed via pip or MacPorts.

Example configure.sh:

CC=mpicc CXX=mpicxx
cmake \
  -DCMAKE_INSTALL_PREFIX=$HOME/opt \
  -DCMAKE_INSTALL_NAME_DIR=$HOME/opt/lib \
  -DCMAKE_BUILD_TYPE=Release \
  -Domp=ON \
  -Dhdf5=ON \
  -Dmpi=ON \
  -DBUILD_DOC=ON \
  -Dness=ON \
  -DCMAKE_INCLUDE_PATH=/opt/local/include \
  -DCMAKE_LIBRARY_PATH=/opt/local/lib \
  -DCMAKE_CXX_FLAGS="-std=c++11 -O3" \
  ..

macOS with Homebrew

Unlink legacy Python:

brew unlink python@2

Install dependencies:

brew install eigen hdf5 open-mpi
brew install doxygen graphviz

Example configure.sh:

CC=mpicc CXX=mpicxx
cmake \
  -DCMAKE_INSTALL_PREFIX=$HOME/opt \
  -DCMAKE_INSTALL_NAME_DIR=$HOME/opt/lib \
  -DCMAKE_BUILD_TYPE=Release \
  -Domp=OFF \
  -Dhdf5=ON \
  -Dmpi=ON \
  -DBUILD_DOC=ON \
  -Dness=ON \
  -DCMAKE_INCLUDE_PATH=/usr/local/include \
  -DCMAKE_LIBRARY_PATH=/usr/local/lib \
  -DCMAKE_CXX_FLAGS="-std=c++11 -O3" \
  ..

Note: omp=OFF because Apple clang does not support OpenMP directly. Workarounds exist (see here).

Linux

On Debian/Ubuntu:

apt-get install -y --allow-unauthenticated libhdf5-serial-dev libopenmpi-dev libeigen3-dev doxygen graphviz cmake

On Arch Linux:

pacman -Sy --noconfirm hdf5 gcc openmpi eigen doxygen graphviz make cmake

Example configure.sh (paths usually not needed):

CC=mpicc CXX=mpicxx
cmake \
  -DCMAKE_INSTALL_PREFIX=$HOME/opt \
  -DCMAKE_BUILD_TYPE=Release \
  -Domp=ON \
  -Dhdf5=ON \
  -Dmpi=ON \
  -DBUILD_DOC=ON \
  -Dness=ON \
  -DCMAKE_INCLUDE_PATH="" \
  -DCMAKE_LIBRARY_PATH="" \
  -DCMAKE_CXX_FLAGS="-std=c++11 -O3" \
  ..

If $HOME/opt/lib is in LD_LIBRARY_PATH, no CMAKE_INSTALL_NAME_DIR is needed.

Creating a Custom Program

Minimal working example:

#include <sys/stat.h>
#include <iostream>
#include "cntr/cntr.hpp"

int main(int argc, char *argv[]) {
    GREEN G;
    int Nt   = 100; // # of timesteps
    int Ntau = 100; // # of imaginary-time steps
    int size = 3;   // GF size

    G = GREEN(Nt, Ntau, size, FERMION);

    std::cout << "Number of timesteps: " << G.nt() << std::endl;
    std::cout << "Number of Matsubara points: " << G.ntau() << std::endl;
    std::cout << "Size of Greens function: " << G.size1() << std::endl;

    return 0;
}

Test Suite and Documentation

To run the test suite (Catch framework):

make test

After completion:

All tests passed

To test MPI routines:

make test_mpi

Documentation is generated automatically when BUILD_DOC=ON is set in the configure script. After building, the HTML docs are at:

doc/html/index.html