Source

In the following, we explain how to clone the RuNNer source code from the Git repository and build the program from source. We provide two separate build systems:

• make: robust and well-tested. Produces a highly optimized executable (-O3).
• cmake: highly automated discovery of library and include paths. Produces a slightly less optimized executable by default (-O2). Use this if you are familiar and comfortable with cmake or are facing trouble with the make-based system.

Getting the source code¶

git clone https://gitlab.com/runner-suite/runner2.git
# or via SSH:
git clone git@gitlab.com:runner-suite/runner2.git

Dependencies¶

No matter which build system you choose, you need to install a few dependencies before compiling RuNNer. Luckily, because RuNNer is written in pure Fortran it needs only few, very stable, libraries. These dependencies are:

• a Fortran compiler
• a C compiler (gcc or any standard C compiler accessible via cc)
• BLAS and LAPACK libraries
• (optional for 4G) a FFTW library

Their installation varies depending on your operating system.

Fortran compiler¶

The most basic requirement is a Fortan compiler. We support and test:

• gfortran >= 9.0.0: the open-source GNU fortran compiler. Generates a fast executable and provides supreme debugging information for developers. Older compiler versions may work with some tinkering but usually do not support all of the language features we use.
• ifx >= 2024.0.0: The latest LLVM version of the proprietary Intel Fortran compiler, provided through the Intel oneAPI. Generates the fastest executable on most platforms. Earlier versions are buggy and should be avoided (see note).
• ifort: The legacy Intel Fortran compiler. Often still found on HPC clusters as part of the provided modules. Performance varies greatly between versions.

Your compiler must support modern Fortran features (Fortran 2008+). The configure script checks for compatibility and will inform you if your compiler does not meet this requirement.

Linux and WSL¶

Many package managers include gfortran in their base installation. On e.g. Ubuntu, it can be installed via

apt-get install gfortran

On RHEL/Rocky/CentOS:

sudo dnf install gcc-gfortran

For optimal performance, we recommend installing the Intel oneAPI. The Fortran compiler is provided as part of the HPC toolkit. It is sufficient to install the Fortran essentials.

MacOS (x86_64 and ARM)¶

Install Homebrew if not already installed, then:

# Install Xcode Command Line Tools if not already installed
xcode-select --install

# Install gfortran and other tools via Homebrew
brew install gcc make cmake

BLAS and LAPACK libraries¶

Math-heavy operations are deferred to a linear algebra package. We test and support (in order of preference):

• Intel Math Kernel Library (MKL) through the oneAPI: proprietary, but exhibits the best performance. Strongly recommended.
• macOS Accelerate Framework: Automatically detected on macOS.
• OpenBLAS and Netlib LAPACK: OpenBLAS usually shows better threading than the Netlib implementation.
• Netlib BLAS and LAPACK: reference implementations of the BLAS and LAPACK API.

Linux and WSL¶

Open-source implementations like Netlib BLAS or OpenBLAS can often be installed through your package manager. For example, on Ubuntu

apt-get install libblas-dev liblapack-dev # Netlib reference implementation
apt-get install libopenblas-dev liblapack-dev # OpenBLAS backend for LAPACK.

On RHEL/Rocky/CentOS:

sudo dnf install lapack-devel openblas-devel

The MKL is provided in the Intel oneAPI base toolkit. The installer script usually works exceptionally well. Please refer to the official Intel documentation for details.

MacOS (x86_64 and ARM)¶

The configure script will automatically detect macOS and use the Accelerate framework for BLAS/LAPACK operations.

FFTW library¶

Fourth-generation potentials with linear-scaling electrostatics require the solution of equations in Fourier space. For this, we rely on a FFTW library. We test and support:

• KISS FFTW: minimal FFTW implementation. Surprisingly speedy, but no match for FFTW3 or MKL FFTW.
• FFTW3: a prominent open-source implementation. Stable OpenMP scaling behavior.
• Intel MKL FFTW through the Intel oneAPI: proprietary. Usually yields better performance than FFTW3, but sometimes exhibits convergence issues related to OpenMP scaling.

Linux and WSL¶

MKL FFTW is automatically installed when installing the MKL.

FFTW3 can be installed via your package manager:

sudo apt-get install libfftw3-dev  # Ubuntu/Debian
sudo dnf install fftw-devel        # RHEL/Rocky

Alternatively, FFTW3 can be compiled from source using the same compiler as for the compilation of RuNNer.

MacOS (x86_64 and ARM)¶

brew install fftw
export FFTW_ROOT=/opt/homebrew
export LD_LIBRARY_PATH=/opt/homebrew/lib:$LD_LIBRARY_PATH
export LIBRARY_PATH=/opt/homebrew/lib:$LIBRARY_PATH

Optional components¶

• MPI (Message Passing Interface): For parallel execution. Required when using MPI-wrapped compilers (mpiifort, mpif90). Recommended for training large datasets.
• pFUnit: For running unit tests (development only).

Quick start¶

For most users, the RuNNer 2.0 installation is straightforward:

cd ~/runner2
./configure
make -j

This will:

1. Auto-detect the best available Fortran compiler
2. Find and configure linear algebra libraries
3. Enable MPI if an MPI compiler is detected
4. Generate a GNUmakefile with optimized settings
5. Build the executable (named RuNNer.x or RuNNer_mpi.x)

To also build the shared library libRuNNer.so (needed for the RuNNerASE Python interface):

make lib -j

This produces the libraries libRuNNer.a (static) and libRuNNer.so (shared). In case for MPI=ON the libraries are named libRuNNer_mpi.a and libRuNNer_mpi.so.

Build with ./configure and GNU make¶

# The configure script will generate an optimal Makfile for your system
./configure #PFUNITMK=/path/to/your/PFUNIT.mk
# ./configure will generate a file called GNUmakefile from GNUmakefile.in
make -j

Configure options¶

Compiler selection¶

• FC=: Allowed values: a fortran compiler. Officially supported are (mpi)ifort, ifx and gfortran but others might work as well.

# Use a specific compiler
./configure FC=ifort

# Use a specific compiler with full path
./configure FC=/opt/intel/oneapi/compiler/latest/bin/ifort

Library options¶

• MKL=: Allowed values: ON, OFF
• MPI=: Allowed values: ON, OFF
• STATIC=: Allowed values: ON, OFF
• ACCELERATE=: Allowed values: ON, OFF (macOS only)

./configure MKL=OFF      # Disable MKL (use alternative BLAS/LAPACK)
./configure MPI=OFF      # Disable MPI
./configure STATIC=OFF   # Disable static linking

Advanced options¶

• FFTW_ROOT=: Path to FFTW3 installation (e.g. /path/to/fftw3)
• ARCH=: Architecture optimization (e.g. avx2, avx512). Default is avx2 on x86_64. On HPC clusters avx512 is probably available.
• FEATURES=: Additional preprocessor features (e.g. "ENABLE_PREFACTORS SATURATIONCHECK")
• COMPLETE=: Allowed values: ON, OFF. Enables all compiler flags for additional features.

./configure FFTW_ROOT=/path/to/fftw3
./configure ARCH=avx512
./configure FEATURES="ENABLE_PREFACTORS SATURATIONCHECK"

Combining options¶

Multiple options can be combined:

./configure FC=gfortran MKL=OFF MPI=OFF STATIC=OFF

If you want to run the pFUnit based test you HAVE to set the PFUNITMK variable to the path to your PFUNIT.mk which is part of any pFUnit installation. I.e. ~/pFUnit/build/installed/PFUNIT-4.4/include/PFUNIT.mk

• PFUNITMK=: Allowed values: /path/to/your/PFUNIT.mk

The build options can also be set as environment variables.

Build-time options¶

The same arguments can be passed to make to overrule settings from previous ./configure runs. Additionally you can pass

• DEBUG=: Allowed values: ON, OFF. Adds extensive checks, slower.
• COMPLETE=: Allowed values: ON, OFF. Enables all analysis and debugging features.
• CPPFLAGS_EXTRA=: Allowed values: -DENABLE_PREFACTORS, -DCOMPATIBILITY_MODE_RUNNER1
• V=: If set to any non-empty value the build will be verbose.

make DEBUG=ON      # Enable debug mode
make COMPLETE=ON   # Enable complete analysis mode
make V=1           # Verbose build output

COMPLETE=ON enables all compiler flags for analysis and debugging, including ENABLE_PREFACTORS, ANALYSIS, FC_NO_INNER_CUTOFF, and other diagnostic features. This flag is useful for development and debugging but will significantly affect performance.

-DENABLE_PREFACTORS enables spin and electric field adapted symmetry functions but also yields a slightly slower executable. Use it only if you want to use the spin and electric field adapted symmetry functions.

-DCOMPATIBILITY_MODE_RUNNER1 makes the program yield the same values as RuNNer 1 during force fitting.

Understanding the configure output¶

After running ./configure, you'll see diagnostic output followed by a configuration summary.

Diagnostic phase¶

The script first reports information about your system:

Found Fortran compiler /opt/intel/oneapi/mpi/2021.7.1/bin/mpiifort
check if compiler supports used intrinsics
/opt/intel/oneapi/mpi/2021.7.1/bin/mpiifort supports used intrinsics
Your compiler /opt/intel/oneapi/mpi/2021.7.1/bin/mpiifort is suitable
Found C compiler /usr/bin/cc

This confirms that the compilers have been detected and are compatible with modern Fortran features.

Warnings¶

You may see warnings during configuration. Common ones include:

##########################
WARNING: SWITCHING TO A NON-STATIC BUILD
##########################

This warning appears when the linker doesn't support static linking syntax. A dynamic build will be created instead, which is perfectly fine for most use cases.

##########################
WARNING: If you want to run PFunit-Test set PFUNITMK to /path/to/PFUNIT.mk
##########################

This is informational — pFUnit is only needed for development/testing purposes.

Library detection¶

The script checks for required libraries:

Checking libraries:
Dynamic library libmpi found
Dynamic library libfabric found
Dynamic library libmkl_intel_lp64 found
Dynamic library libmkl_intel_thread found
Dynamic library libmkl_blas95_lp64 found
Dynamic library libmkl_lapack95_lp64 found
Dynamic library libmkl_core found
MKL Found

Verify that the math libraries (MKL, OpenBLAS, or BLAS/LAPACK) are detected. If not, the build will fail during linking.

Configuration summary¶

At the end, a summary shows all configured variables:

#########################################
# Configuration was successful! We set: #
#########################################
FC = /opt/intel/oneapi/mpi/2021.7.1/bin/mpiifort
CC = /usr/bin/cc
STATIC = OFF
DYN =
MPI = ON
MKL = ON
ACCELERATE = OFF
FFTW3 = ON
FEATURES =
LIB = mpi fabric mkl_rt
INC = -I/opt/intel/oneapi/mkl/2022.2.1//include/fftw/
PFUNITMK = (optional)
CUBLAS = OFF

Variable reference:

• FC: Fortran compiler path — verify this is the compiler you intended
• CC: C compiler path
• STATIC: ON = statically linked, OFF = dynamically linked
• MPI: ON = MPI support enabled (produces RuNNer_mpi.x)
• MKL: ON = Intel MKL detected and used for linear algebra
• ACCELERATE: ON = macOS Accelerate framework used (macOS only)
• FFTW3: ON = FFTW3 support enabled
• FEATURES: Additional preprocessor features enabled
• LIB: Libraries that will be linked
• INC: Include paths for header files
• PFUNITMK: Path to pFUnit makefile (for testing)
• CUBLAS: ON = NVIDIA cuBLAS GPU acceleration enabled (experimental)

Platform-specific instructions¶

Linux with Intel Compilers and MKL¶

This is the recommended setup for production use:

# Load Intel compiler environment (adjust path for your system)
source /opt/intel/oneapi/setvars.sh

# Configure and build
./configure FC=mpiifort
make -j

The script will automatically detect Intel MKL libraries, enable static linking, and optimize for your CPU architecture.

Linux with GNU Compilers¶

# Ensure gfortran and libraries are installed
# On Ubuntu/Debian:
sudo apt-get install gfortran liblapack-dev libopenblas-dev

# On RHEL/Rocky/CentOS:
sudo dnf install gcc-gfortran lapack-devel openblas-devel

# Configure and build
./configure FC=gfortran
make -j        # Compile RuNNer.x and static libRuNNer.a
make lib -j    # Compile shared library libRuNNer.so

macOS¶

macOS users benefit from the built-in Accelerate framework:

# Install dependencies via Homebrew
brew install gcc make cmake fftw libfabric

# Export FFTW path
export FFTW_ROOT=/opt/homebrew
export LD_LIBRARY_PATH=/opt/homebrew/lib:$LD_LIBRARY_PATH
export LIBRARY_PATH=/opt/homebrew/lib:$LIBRARY_PATH

# Configure and build
./configure MKL=OFF FC=gfortran   # serial
./configure MKL=OFF FC=mpif90     # MPI

# Note: use gmake on macOS instead of make
gmake MPI=OFF -j 4        # Serial: RuNNer.x and libRuNNer.a
gmake MPI=OFF lib -j 4    # Serial: libRuNNer.so
gmake MPI=ON -j 4         # MPI: RuNNer_mpi.x and libRuNNer_mpi.a
gmake MPI=ON lib -j 4     # MPI: libRuNNer_mpi.so

HPC Cluster with Modules¶

On HPC systems using environment modules:

# Load required modules (names vary by system)
module load intel/2023.2.0
module load impi/2021.9.0
module load mkl/2023.2.0

# Configure with MPI compiler wrapper
./configure FC=mpiifort
make -j

Build with CMake¶

mkdir build && cd build
# specify fortran compiler, otherwise cmake may not choose the compiler you want.
export FC=gfortran
# enable tests (optionaly):
export CMAKE_PREFIX_PATH=$HOME/src/pFUnit/build:$CMAKE_PREFIX_PATH
cmake .. # opionally you can set `-G Ninja` if you have ninja installed
make -j # or `ninja` if you used `-G Ninja` in the previous step (will build a bit faster)
# optional, executes all tests
ctest

• -DUSE_MPI=: Allowed values:ON, OFF, default ON
• -DUSE_MKL=: Allowed values:ON, OFF, default ON
• -DENABLE_PREFACTORS=: Allowed values:ON, OFF, default OFF
• -DFC_NO_INNER_CUTOFF=: Allowed values:ON, OFF, default OFF
• -DCOMPLETE=: Allowed values:ON, OFF, default OFF - Enables all analysis and debugging features

• -DCMAKE_BUILD_TYPE=: Allowed values:Debug, Release, Static Sets the build type. In a static build MPI, OPENMP and MKL will be disabled since they have dependencies that cannot be linked statically.

• -DBUILD_SHARED_LIBS=: Allowed values:ON, OFF, default OFF

The build options can also be set as environment variables.

Verification¶

After building, verify your installation:

Check the executable¶

./RuNNer.x       # serial version
./RuNNer_mpi.x   # MPI version

RuNNer will terminate with an error message if no input files are found — this is expected and confirms the executable works.

Run unit tests (if pFUnit is installed)¶

./configure PFUNITMK=/path/to/PFUNIT.mk
make tests
make tests_run

make tests and make tests_run can never be run with the -j option

Test MPI build¶

mpirun -np 4 ./RuNNer_mpi.x