Installation guide

Getting the software

Please visit our client portal (portal.nanoacademic.com) to download the software. You will need to register and login to access the software. The software is distributed as a zip file. Unzip the file in a directory of your choice. This directory is useful to keep around but is not necessary to run the software after installation is complete.

unzip rescuplus-2024.4.1.zip -d rescuplus_2024.4.1
cd rescuplus-2024.4.1

Installation of the build tools and dependencies

Toolchain matrix

RESCU+ only supports Linux based systems at the moment. We are continually testing RESCU+ on different platforms and toolchains. Please consult the following table to see if your platform is tested. Note that similar major versions (first number) of the compilers and MPI implementations should also work. We test on Ubuntu for debian based systems and Rocky Linux for RedHat based systems.

Note: Cluster installations should use the toolchains provided by the cluster. The following table is for single node installations.

Operating System	Compiler	MPI	Status	Notes
Ubuntu 20.04	GCC 9.4.0	OpenMPI 4.0.3	Working
Ubuntu 22.04	GCC 11.4.0	OpenMPI 4.1.2	Partial	Runtime crashes have been reported with mpi processes > 4
Rocky Linux 8	GCC 8.5.0	OpenMPI 4.1.1	Working
Rocky Linux 9	GCC 11.4.1	OpenMPI 4.1.1	Partial	Runtime crashes have been reported with mpi processes > 4

Note: Intel compilers are not supported at the moment due to API differences. But we are working on adding support for them.

If you use RESCU+ on a different platform or encounter any issues, please let us know by opening a ticket on our Support Portal or sending an email to our support email. We will prioritise new toolchains based on your feedback.

Compilers and MPI installation

Clusters

If you are using a cluster, you should use the toolchains provided by the cluster. There have been reports of runtime issues with GCC versions > 9. We are working on resolving these issues, but for now, we recommend using GCC 8 or 9 if available.

Ubuntu (20.04/22.04)

sudo apt install build-essential gcc g++ gfortran openmpi-bin openmpi-common libopenmpi-dev cmake

Rocky Linux (8/9)

sudo dnf groupinstall 'Development Tools'
sudo dnf install cmake gcc-gfortran openmpi openmpi-devel
module load mpi

Anaconda environment (Experimental)

We are actively developing an anaconda package for RESCU+ to simplify single node installations. This will include a toolchain that can be used to compile the software. Cluster installs should use the toolchains provided by the cluster. You can use the current experimental environment as follows:

conda env create -f environment.yml -n rescuplus # or your preferred environment name
conda activate rescuplus

Building the dependencies and RESCU+

RESCU+ is built on top of several libraries which must be installed before compiling the program. Our build system will automatically download and build the dependencies (an internet connection is required). Here is a list of the required libraries for information purposes:

BLAS/LAPACK (blas)
ScaLAPACK (scalapack)
ELPA (elpa)
FFTW (fftw)
HDF5 (hdf5)
JSON-FORTRAN (json-fortran)
LibXC (libxc)
Zofu (zofu)
DFTD3 (dftd3)

Regular installation

RESCU+ uses a CMake based build system to compile the software. CMAKE_INSTALL_PREFIX is set to the path where the software will be installed. The default directory is /usr/local which usually needs root permissions. Setting it to a user owned directory like $HOME/.local/nanoacademic allows you to install without root access. In this case, the bin directory under the install prefix must be added to your PATH variable to run the software. The following commands will install RESCU+ in the directory $HOME/.local/nanoacademic:

INSTALL_PREFIX=$HOME/.local/nanoacademic # or your preferred install directory
# Configure the build
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=$INSTALL_PREFIX
# Build the software
cmake --build build --target install # this can take a long time
export PATH=$INSTALL_PREFIX/bin:$PATH # add this to your .bashrc or .bash_profile to make the change permanent

The build process can also be parallelized by adding the -j flag to the cmake --build command. For example, to use 4 threads, you can run cmake --build build --target install -j 4.

You can add the last line to your .bashrc to make the change permanent. Be sure the replace $INSTALL_PREFIX with the prefix you chose.

Anaconda environment (Alternative/Experimental)

conda activate rescuplus # environment must be activated
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX
cmake --build build --target install

Installation of the Python interface

RESCU+ includes a python interface. It can be installed with the following commands.

Regular installation

We suggest creating a virtual environment to install the python interface. The following commands will install the python interface in the current environment.

python -m venv nanotools_venv # the last argument is the directory name
source nanotools_venv/bin/activate
pip install . # in the rescuplus directory

Anaconda environment (Alternative/Experimental)

conda activate rescuplus # or your environment name
pip install .

Installation of the pseudopotential library

RESCU+ can read pseudopotentials 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 on the Nanoacademic portal to a permanent location. Finally, set the environment variable 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 the current working directory $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

Building the documentation

Up to date documentation is always available at our documentation portal. However, if you want to build the documentation locally, you can do so by running the following commands:

source venv/bin/activate # or conda activate rescuplus
pip install .[docs] # this installs the optional documentation dependencies
# pip install .\[docs\] # note you may need to escape the brackets in certain shell
cd docs/rescuplus_docs/
make html

Troubleshooting

Large memory requirements for compilation

fatal error: Killed signal terminated program f95

RESCU+ can take a lot of memory (RAM) to compile. If you encounter this error, you can try to increase the swap space on your system or compiling on a machine with more memory and a similar architecture. You could also try compiling a debug build with the -DCMAKE_BUILD_TYPE=Debug flag to reduce the memory usage. However, this is not the most optimized build and will make the software slower.

Getting Help

RESCU+ is a feature-rich software and we are here to help you. If you encounter any issues, please open a ticket on our Support Portal or send an email to Nanoacademic support