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;

  5. Activation procedure.

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.

First, you need GNU compilers and an MPI implementation.

Install spack

git clone https://github.com/spack/spack.git
cd spack
git checkout v0.19.0
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 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 and the activation procedure.

Installation of the build tools and dependencies

This section shows how to install the build tools and dependencies necessary to operate RESCU+. First, you need GNU compilers and an MPI implementation. Then, there are two ways to install the dependencies:

Compilers and MPI installation

Before using either spack or the bash installer, one needs C, C++ and Fortran GNU compilers (version >= 9). On Ubuntu, you can install the GNU compilers as follows

sudo apt update
sudo apt install build-essential g++ gfortran

If you are installing RESCU+ on an HPC system, we strongly suggest using an MPI implementation installed by your system administrator. If you need help installing openmpi because it is unavailable, contact your system administrator or our support team. On Ubuntu, you can install OpenMPI as follows

sudo apt-get install openmpi-bin openmpi-common libopenmpi-dev

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.19.0). To do so

git checkout v0.19.0

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 compiler find 
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
spack install -j8

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 need GNU compilers and an MPI implementation. You will also need Python (version >= 3.8), which you can install (on Ubuntu) as follows:

sudo apt update
sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.8

You then need the following build tools (version numbers are indicative, more recent versions usually work and previous versions may also work):

make and cmake are part of the Linux build-essential package. ninja and meson 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.

You can pip install everything as follows

cd install
bash install_dep.sh --library buildtools --buildpath /tmp/build --prefix $HOME/.nanoacademic/RESCUPLUS

The Python packages will be installed in $HOME/.nanoacademic/RESCUPLUS, 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/.nanoacademic/RESCUPLUS/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)

  9. DFTD3 (dftd3)

The script install/install_dep.sh may help you install the libraries from source. All libraries can be built in one command setting --library to all, e.g.

bash install_dep.sh --library all --buildpath /tmp/build --prefix $HOME/.nanoacademic/RESCUPLUS

Now the explanations, install_dep.sh has the following 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 prioritized 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, cmake, 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/build --prefix $HOME/.nanoacademic/RESCUPLUS

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/build --prefix $HOME/.nanoacademic/RESCUPLUS --local --sources /path/to/sources

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

export PKG_CONFIG_PATH=$HOME/.nanoacademic/RESCUPLUS/lib/pkgconfig

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

We recommend turning off OpenBlas threading feature by setting

export OPENBLAS_NUM_THREADS=1

Compilation of the Fortran source and installation

RESCU+ binaries and libraries are compiled using meson. Simply type

PREFIX=$HOME/.nanoacademic/RESCUPLUS make cleanbuild && make install

For the explanations, Makefile is a simple wrapper around meson. Two variables are worthy of mention

  • PREFIX to specify the install location. You must set 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 can be carried out as follows.

PREFIX=/path/to/install make configure
make build
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 RESCUPLUS_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 RESCUPLUS_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.

Activation procedure

This section provides instructions on how to download your license. To activate RESCU, sign up or sign in your account on the Nanoacademic portal. Go to the product section and click on RESCU+. Then click on the Start Your Free Trial button and you should see a download button next to a serial number. If you purchased a license, you should already see a download button next to a serial number. Download the file license.lic by clicking the download link and copy it in the directory $HOME/.nanoacademic/RESCUPLUS. Alternatively, you may copy it anywhere and set the environment variable RESCUPLUS_LICENSE_PATH as, say

export RESCUPLUS_LICENSE_PATH=/home/user/licenses/license.lic

Similarly, for RESCU+, download the file license.lic by clicking the download link and copy it in the directory $HOME/.nanoacademic/RESCUPLUS. Alternatively, you may copy it anywhere and set the environment variable RESCUPLUS_LICENSE_PATH as, say

export RESCUPLUS_LICENSE_PATH=/home/user/licenses/license.lic

You should be good to go now. If your run into any issue during the license generation, please leave messages on Nanoacademic forum or email support@nanoacademic.com.

Next steps

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