Installation guide

This document will walk you through the necessary installation procedures, divided in the following steps:

  1. Installation of the build tools and dependencies;

  2. Compilation of the Fortran source and installation;

  3. Installation of the Python packages;

  4. Installation of the pseudopotential library.

TL;DR

To get going right away you can try copy pasting the command below. If it doesn’t work or you would like additional information, you may jump to the section installation of the build tools and dependencies.

Install spack

git clone https://github.com/spack/spack.git
cd spack
git checkout v0.17.1
source share/spack/setup-env.sh

Install dependencies with spack (may take an hour or so)

cd /path/to/code
spack env activate .
spack compiler find
spack external find openmpi
spack install

Install NanoDCAL+ or RESCU+

cd /path/to/code
PREFIX=/path/to/install make cleanbuild
make install

Install RESCUPy

python -m venv venv
source venv/bin/activate
cd /path/to/code/rescupy
pip install .

Complete the installation following installation of the pseudopotential library.

Installation of the build tools and dependencies

This section shows how to install the build tools and dependencies necessary to operate NanoDCAL+ and RESCU+. There are two ways to do so:

  • Using spack, which is more or less plug and play and what you should start with;

  • Manually, which you may turn to if spack doesn’t work for some reason. We still provide some scripts to easy the procedure.

Installation using spack

This section shows how to install the build tools and dependencies using the spack package manager.

Get spack from the github repository typing git clone https://github.com/spack/spack.git. We suggest checking out a specific version (v0.17.1). To do so

git checkout v0.17.1

Add spack to your environment as follows source spack/share/spack/setup-env.sh. You may add the last command to your .bashrc to make this permanent.

Activate the package extension.

cd $RESCU_DIR
spack env activate .

GCC and OpenMPI are usually already installed on computing platforms. You may tell spack to use preinstalled compilers and libraries as follows

spack find compiler
spack external find openmpi

Next, concretize the environment and let spack build the dependencies as follows

spack concretize -f
spack install -j8

You may adjust the build parallelism using the -j option (here I use 8 cores). If something goes sideways, try to find a local version (e.g. with perl) and reconcretize

spack external find perl
spack concretize -f

Building everything can take an hour or so (depending on your processor, disk IO speed and what is already installed on your system).

Manual installation

Installation of the build tools

Before delving into RESCU+’s installation procedures, you should install or update the following building tools (version numbers are indicative, more recent versions usually work and previous versions may also work):

gcc, make, cmake and Python are usually part of any functional Linux installation. If you cannot find gcc, make, cmake or Python, contact your system administrator and ask him to install it.

openmpi is frequently found on Linux platforms and its compiler wrappers are necessary to compile RESCU+. If you need help installing openmpi contact your system administrator or our support team.

Next, we install ninja, Meson, FoBiS and ford. The first two form a fast and user friendly build system, which is used to compile and install RESCU+. FoBiS and ford are modern Fortran build and documentation tools respectively, and they are used to install certain dependencies.

ninja, Meson, FoBiS and ford are installed using as follows. Step in the install directory and run

bash install_dep.sh --library meson --buildpath /tmp --prefix $HOME/.local

The Python packages will be installed in $HOME/.local, and hence you should add the following line to your .bashrc if you’d like to find the programs in the future.

export PATH=$PATH:$HOME/.local/bin

Installation of the dependencies

RESCU+ is built on top of several libraries which must be installed before compiling the program. Here is a list of the required libraries:

  1. BLAS/LAPACK (blas)

  2. ScaLAPACK (scalapack)

  3. ELPA (elpa)

  4. FFTW (fftw)

  5. HDF5 (hdf5)

  6. JSON-FORTRAN (json-fortran)

  7. LibXC (libxc)

  8. Zofu (zofu)

The script install/install_dep.sh may help you install the libraries from source. install_dep.sh has three options:

  • --buildpath (mandatory) specifies a working directory;

  • --prefix (mandatory) specifies where to install the library.

  • --force (optional) Force installation even if valid pkg-config file is found. Ensure that this install is being prioritised by pkg-config using the command pkg-config --debug --libs THELIBRARY. It should show $PREFIX/lib/pkgconfig/THELIBRARY.pc as the file being read.

  • --library (optional) specifies which library to install;

  • --local (optional) install libraries from local source files;

  • --sources (optional) location of the source files for a local install;

For each library, it will:

  1. Download the source, usually a tarball, to the location given by --buildpath;

  2. Build the library from source, using make, meson, etc.

  3. Install the library to the location given by --prefix and update the corresponding pkg-config entry.

The last point is crucial since meson uses pkg-config to find libraries. The install_dep.sh script will append $PREFIX/lib/pkgconfig to the PKG_CONFIG_PATH variable and use the files in there to determine whether the library is already installed or not. The lowercase tag in the parentheses is what you should pass to install_dep.sh in the --library option. For instance, to install BLAS/LAPACK, type

bash install_dep.sh --library blas --buildpath /tmp --prefix $HOME/.local

You may of course skip the installation of any of the libraries if it is already installed and it is properly configured. But note that the order above is important because some libraries are dependent on others. The scripts download the source codes from the Internet. If you do not have Internet access, you may put all the sources in /path/to/sources and call the installer locally as follows

bash install_dep.sh --library blas --buildpath /tmp --prefix $HOME/.local --local --sources /path/to/sources

All libraries can be built in one command setting --library to all, e.g.

bash install_dep.sh --library all --buildpath /tmp --prefix $HOME/.local

This will also reinstall ninja, Meson, FoBiS and ford if necessary.

Finally, you can update you pkg-config cache permanently by adding the following line to your .bashrc

export PKG_CONFIG_PATH=$HOME/.local/lib/pkgconfig

, assuming that you set --prefix to $HOME/.local.

Compilation of the Fortran source and installation

RESCU+ binaries and libraries are compiled using Meson. We wrote a simple Makefile wrapper around meson for your convenience. Two variables are worthy of mention

  • PREFIX to specify the install location. We suggest setting PREFIX to a location where you have write access;

  • BUILDTYPE to specify the build type

    • release (default) builds an optimized version for production runs;

    • debug builds a debug version (it also compiles much quicker);

    • debugoptimized build a debug version which is also optimized.

The installation should be carried out as follows.

  1. If you manually installed the dependencies (i.e. you didn’t use spack), set the environment variable LD_LINK_PATH to the location where you installed the dependencies (e.g. export LD_LINK_PATH=$HOME/.local/lib).

  2. PREFIX=/path/to/install make configure

  3. make build

  4. make install

meson will build RESCU+ in the build directory. If $PREFIX is not in your PATH you will need to append it to invoke the RESCU+ programs.

export PATH=$PREFIX/bin:$PATH

You may perform unit tests to validate the build (this is optional, but recommended). Type make mpi0 to perform sequential unit tests. You should see something like

ninja: Entering directory `build'
[...]
Ok:                 61
Expected Fail:      0
Fail:               0
Unexpected Pass:    0
Skipped:            0
Timeout:            0

Full log written to /tmp/rescu/build/meson-logs/testlog.txt

Type make mpi8 to perform parallel unit tests. All parallel unit tests use 8 processes. If your computer has less than 8 cores, the mpi launcher will need to run in oversubscribe mode, which may be slow and cause some tests to fail due to time out. You should see something like

ninja: Entering directory `build'
[...]
Ok:                 76
Expected Fail:      0
Fail:               0
Unexpected Pass:    0
Skipped:            0
Timeout:            0

Full log written to /tmp/rescu/build/meson-logs/testlog-mpiexec.txt

Installation of the Python packages

Albeit technically a stand-alone program, RESCU+ is more convenient to use through a Python interface: RESCUPy. RESCUPy assumes that the SciPy stack is installed and can be found in the Python path.

Manual installation (Fallback)

If the automatic installation fails, you may install the rescupy dependencies with poetry

cd rescupy
python -m pip install --user poetry
python -m poetry update
python -m poetry install

or with pip

cd rescupy
pip install --user -r requirements.txt

If working in a Python virtual env, remove the --user option.

Next, add rescupy to your PYTHONPATH as follows

export PYTHONPATH=$RESCU_DIR/rescupy:$PYTHONPATH

You can add this line to your .bashrc to make the change permanent.

You should then be able to import rescupy in a Python shell as follows:

$ python
Python 3.6.9 (default, Apr 18 2020, 01:56:04)
[GCC 8.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import rescupy

Installation of the pseudopotential library

RESCUPy can read pseudopotential and atomic orbital basis files generated by Nanobase, i.e. the same as those used by NanoDCAL and RESCU. To install the pseudopotentials, simply untar the pseudopotential archive provided to you with the source code in a known location. Finally, set the environment variable NANODCALPLUS_PSEUDO or RESCUPLUS_PSEUDO to a directory where pseudopotential are found. Note that you may have to change this depending on the calculation. For instance, when using LDA you may set NANODCALPLUS_PSEUDO=path/to/lda/pseudos while when using PBE you may set RESCUPLUS_PSEUDO=path/to/pbe/pseudos. Or simply copy the pseudopotential files you would like to use to $PWD and set RESCUPLUS_PSEUDO=$PWD.

Next steps

You now have a complete RESCU+ installation. You can now try to follow a tutorial