1. Quick Guide

Here we are going to install a precompiled version of RESCU which can be run without the MATLAB license.

  1. Obtain the RESCU Code

    Download the binary package version (MCR files) of RESCU code from the Nanoacademic Portal into a local directory, for example, $HOME/rescu_bin.

    Fig. 1.1 An example of MCR versions of RESCU.

    After downloading the package from the client portal, you will find different sets of files depending on your operating system. For Linux, the package includes a bash script (rescu.sh), the executable (rescumat), a test folder (rescu_test/), and a README.md file. For Windows, the package includes a PowerShell script (rescu.ps1), the executable (rescu.exe), an examples folder (RESCU_EXAMPLES/), and a README.md file. In the following guide, you will be shown how to use these files to install and test RESCU on your system.

  2. Add the License File

    Download the license.lic file from the Nanoacademic Portal.

    • On Linux, save it in:

      $HOME/.nanoacademic/RESCU

    • On Windows, place it in:

      C:\Users\<YourUsername>\.nanoacademic\RESCU

    Warning

    If the license is placed in a different location:

    • On Linux: use export RESCU_LICENSE_PATH=/path_to_license/license.lic

    • On Windows: set up the environment variable by adding RESCU_LICENSE_PATH

  3. Matlab Compiler Runtime (MCR)

    Please download MATLAB Compiler Runtime.

    Once downloaded, install the MCR by:

    • On Linux: extract the .zip file and run the installer with sudo ./install from the extracted directory.

    • On Windows: unzip the file and run the setup.exe installer.

    After, follow the RESCU installation instructions included in the package (see the included README.md file).

    By default, for Linux, the location of the MCR should be /usr/local/MATLAB/MATLAB_Runtime/v98, include the additional paths at the environment variable $LD_LIBRARY_PATH, as follows:

    MCRROOT=/usr/local/MATLAB/MATLAB_Runtime/v98
export LD_LIBRARY_PATH=$MCRROOT/runtime/glnxa64:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$MCRROOT/bin/glnxa64:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$MCRROOT/sys/os/glnxa64:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH=$MCRROOT/extern/bin/glnxa64:$LD_LIBRARY_PATH

    Note

    On a Windows machine the MCR is usually installed at C:\Program Files\MATLAB\MATLAB Runtime\v97 and The MATLAB Runtime installer for Windows automatically sets the library path during installation. If not, please, consult the MATLAB Help Center to properly to set the PATH environment variable permanently.

  4. Configuration for Linux

    All necessary files to launch the application are included in the rescu.sh bash script. This script sets the two environment variables mentioned in steps #2 and #3. If you’ve customized any paths (e.g., for the MATLAB runtime), make sure to update the script accordingly. For example, if you use a different MATLAB runtime path, replace the default one with yours. The package also includes a rescu_test folder containing sample input files to test the software.

    To run the bash script, navigate into the rescu_test directory and use the following command:

    ../rescu.sh scf.input

  5. Configuration for Windows

    To start the application on Windows, use the provided PowerShell script rescu.ps1. This script sets the two environment variables mentioned in steps #2 and #3. If you have customized any paths (such as the MATLAB runtime), make sure to update the script to reflect your setup. The package also includes a folder named RESCU_EXAMPLES, which contains example input files for testing the software.

    To run RESCU, navigate to the RESCU_EXAMPLES folder and execute the following command in PowerShell:

    ../rescu.ps1 -i scf.input

    Note

    RESCU is unfortunately not supported on MacOS.

  6. Verifying Installation

    Navigate to the folder where the RESCU binary is located, open a terminal (or Command Prompt on Windows), and run the program. If the installation is successful, you will see the following message:

    **********************************************************************
Some on-line help information
**********************************************************************
For information about the command line flags, type
   "rescu --flag"
For information about all input parameters (including command-line
   flags), type
   "rescu --parameter"
To check the meaning of a given parameter, or search for a parameter
   whose name contains a given string, e.g., 'control', type
   "rescu --parameter ? atom"
For information about all available atomic orbital basis, type
   "rescu --basis"

    Note

    On Windows, use rescu.exe instead of rescu.

  7. Adding rescu binary to System PATH for Easy Access

    Please, follow this process to ensure that the rescu binary can be executed from anywhere in your system.

    • Linux: add the binary directory path ($HOME/rescu_bin) to the PATH variable. Open the shell configuration file (e.g. ~/.bashrc) in a text editor and add the line export PATH="$HOME/rescu_bin:$PATH"; save the file, then apply the changes by running source ~/.bashrc. Finally, verify by typing rescu to check if the command is recognized.

    • Windows: navigate to “Edit environment variables of your account” from the Start menu and click “Environment Variables.” Under “System Variables,” find and edit the Path variable. Add the full directory path to rescu/bin (e.g., C:\Users\<YourUsername>\rescu_bin) by clicking “Edit.” Save the changes, restart your Command Prompt and type rescu to verify if the command is recognized

Important

Users can build RESCU from source with OpenMPI (parallelization), LibXC: (exchange-correlation functionals), ScaLAPACK/LAPACK (linear algebra), and FFTW libraries. Installation instructions, including compiler flags and dependencies, are detailed in the Cluster Installation section documentation.