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