Installation guide¶
This document will walk you through the necessary installation procedures, divided in the following steps:
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.
Install spack
git clone https://github.com/spack/spack.git
cd spack
git checkout v0.17.1
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 NanoDCAL+ or 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.
Installation of the build tools and dependencies¶
This section shows how to install the build tools and dependencies necessary to operate NanoDCAL+ and RESCU+. There are two ways to do so:
Using spack, which is more or less plug and play and what you should start with;
Manually, which you may turn to if
spack
doesn’t work for some reason. We still provide some scripts to easy the procedure.
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.17.1
).
To do so
git checkout v0.17.1
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 find compiler
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
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 should install or update the following building tools (version numbers are indicative, more recent versions usually work and previous versions may also work):
gcc (7.5.0)
openmpi (3.1.2)
make (4.1)
cmake (3.10.3)
Python (3.6.9)
ninja (1.7.1)
meson (0.57.0)
FoBiS (3.0.2)
ford (6.0.0)
gcc
, make
, cmake
and Python
are usually part of any functional Linux installation.
If you cannot find gcc
, make
, cmake
or Python
, contact your system administrator and ask him to install it.
openmpi
is frequently found on Linux platforms and its compiler wrappers are necessary to compile RESCU+.
If you need help installing openmpi
contact your system administrator or our support team.
Next, we install ninja
, Meson
, FoBiS
and ford
.
The first two 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, and they are used to install certain dependencies.
ninja
, Meson
, FoBiS
and ford
are installed using as follows.
Step in the install directory and run
bash install_dep.sh --library meson --buildpath /tmp --prefix $HOME/.local
The Python packages will be installed in $HOME/.local
, 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/.local/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:
BLAS/LAPACK (blas)
ScaLAPACK (scalapack)
ELPA (elpa)
FFTW (fftw)
HDF5 (hdf5)
JSON-FORTRAN (json-fortran)
LibXC (libxc)
Zofu (zofu)
The script install/install_dep.sh
may help you install the libraries from source. install_dep.sh
has three 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 prioritised by pkg-config using the commandpkg-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:
Download the source, usually a tarball, to the location given by
--buildpath
;Build the library from source, using
make
,meson
, etc.Install the library to the location given by
--prefix
and update the correspondingpkg-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 --prefix $HOME/.local
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 --prefix $HOME/.local --local --sources /path/to/sources
All libraries can be built in one command setting --library
to all
, e.g.
bash install_dep.sh --library all --buildpath /tmp --prefix $HOME/.local
This will also reinstall ninja
, Meson
, FoBiS
and ford
if necessary.
Finally, you can update you pkg-config cache permanently by adding the following line to your .bashrc
export PKG_CONFIG_PATH=$HOME/.local/lib/pkgconfig
, assuming that you set --prefix
to $HOME/.local
.
Compilation of the Fortran source and installation¶
RESCU+ binaries and libraries are compiled using Meson
.
We wrote a simple Makefile
wrapper around meson for your convenience.
Two variables are worthy of mention
PREFIX
to specify the install location. We suggest settingPREFIX
to a location where you have write access;BUILDTYPE
to specify the build typerelease (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 should be carried out as follows.
If you manually installed the dependencies (i.e. you didn’t use
spack
), set the environment variableLD_LINK_PATH
to the location where you installed the dependencies (e.g.export LD_LINK_PATH=$HOME/.local/lib
).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.
Automatic installation (Recommended)¶
RESCUPy includes a wheel to pull all the required dependencies. You can install RESCUPy as follows. From the RESCU+ root directory
cd rescupy
pip install .
If the install is successful you should now be able to import rescupy
$ 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
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 NANODCALPLUS_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 NANODCALPLUS_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
.