# Installation guide

## Getting the software

Please visit our [client portal (portal.nanoacademic.com)](https://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.

```shell
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](https://nanoacademic.atlassian.net/servicedesk/customer/portal/1) or sending an email to our [support email](mailto:support@nanoacademic.com). 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)

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

#### Rocky Linux (8/9)

```shell
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:

```shell
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:

1. [BLAS/LAPACK](https://www.openblas.net/) (blas)
2. [ScaLAPACK](http://www.netlib.org/scalapack) (scalapack)
3. [ELPA](https://elpa.mpcdf.mpg.de/) (elpa)
4. [FFTW](http://www.fftw.org/) (fftw)
5. [HDF5](https://support.hdfgroup.org/ftp/HDF5/releases) (hdf5)
6. [JSON-FORTRAN](https://github.com/jacobwilliams/json-fortran) (json-fortran)
7. [LibXC](https://libxc.gitlab.io/) (libxc)
8. [Zofu](https://github.com/acroucher/zofu) (zofu)
9. [DFTD3](https://www.chemie.uni-bonn.de/grimme/de/software/dft-d3) (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`:

```shell
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)

```shell
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.

```shell
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)

```shell
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](https://nanoacademic.com/solutions/nanodcal/) and [RESCU](https://nanoacademic.com/solutions/rescu/).
To install the pseudopotentials, simply untar the pseudopotential archive provided on the [Nanoacademic portal](https://portal.nanoacademic.com/) 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](https://portal.nanoacademic.com/).
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

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

## Building the documentation

Up to date documentation is always available at our [documentation portal](https://docs.nanoacademic.com/rescuplus/index.html). However, if you want to build the documentation locally, you can do so by running the following commands:

```shell
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

```bash
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](https://nanoacademic.atlassian.net/servicedesk/customer/portal/1) or send an email to [Nanoacademic support](mailto:support@nanoacademic.com)