Installation

This section provides step-by-step instructions for installation of Tadah!MLIP (MLIP training) and Tadah!LAMMPS (LAMMPS plugin).

Requirements

Both Tadah!MLIP and Tadah!LAMMPS utilize CMake for configuration and building of its components. The Tadah!LAMMPS interface and Tadah!MLIP toolkit require C++11 and C++17 compatible compilers, respectively. LAPACK and ScaLAPACK (Tadah!MLIP MPI version only) must be available on the user’s system.

Other necessary libraries are either included in the codebase or downloaded during the compilation process. The internet connection is required during the installation process.

Installing Tadah!MLIP Software

Tadah!MLIP provides a command-line interface binary, tadah, for developing machine learning interatomic potentials.

Obtaining Source Code

To obtain Tadah!MLIP, clone the main branch using:

git clone https://git.ecdf.ed.ac.uk/tadah/tadah.mlip.git

Configuration and Compilation

Tadah!MLIP uses CMake for configuration and Make for compilation.

The executable tadah is installed in the bin directory by default (${CMAKE_INSTALL_PREFIX}/bin). If MPI is enabled, the executable is named tadah_mpi.

# Navigate to the project directory
cd tadah.mlip

# Create and move into the build directory
mkdir build && cd build

# Configure with CMake
cmake ..

# Compile and install
make && make install

To change the installation location:

cmake .. -DCMAKE_INSTALL_PREFIX=/your/path

Configuration Options

Customize the Tadah!MLIP build using CMake options:

  • TADAH_ENABLE_OPENMP: Enable OpenMP for parallelization (default: OFF).

  • TADAH_BUILD_MPI: Build MPI version (default: OFF).

  • TADAH_MARCH_NATIVE: Use native optimizations (default: OFF).

  • TADAH_ENABLE_FAST_MATH: Enable fast math optimizations (default: OFF).

  • TADAH_ENABLE_HPO: Enable Hyperparameter Optimizer (default: OFF), see Building Tadah!MLIP with Hyperparameter Optimizer.

  • TADAH_LAMMPS_DIR: Absolute path to the LAMMPS directory (required by TADAH_ENABLE_HPO).

  • TADAH_LAMMPS_LIB: Name of the LAMMPS library compiled with Tadah!LAMMPS (required by TADAH_ENABLE_HPO).

Additional CMake options to consider:

  • CMAKE_INSTALL_PREFIX: Set the install directory destination when make install is invoked. A common choice is -DCMAKE_INSTALL_PREFIX=~/.local.

  • BUILD_SHARED_LIBS: Whether to build shared or static Tadah!MLIP libraries (default: ON).

  • BUILD_TESTING: Include tests (default: OFF).

Append any of the flags above to the cmake command with the -D prefix and a value of ON, OFF, or a path, e.g.:

cmake .. \
    -DTADAH_ENABLE_OPENMP=ON \
    -DTADAH_BUILD_MPI=ON \
    -DCMAKE_INSTALL_PREFIX=~/.local

You can string together as many -D<option>=<value> pairs as needed in a single call.

make          # compile
make install  # install to the chosen prefix
make test     # run tests (requires -DBUILD_TESTING=ON)
make docs     # generate local API docs (requires Doxygen)

Go Faster Stripe - Desktop Version

OpenMP is supported if available on your system. Compile Tadah!MLIP with OpenMP support and set the number of threads to match your CPU cores for optimal performance.

export OMP_NUM_THREADS=num_of_cores

Massively Parallel Version

The Tadah!MLIP MPI version is designed for High-Performance Computing (HPC) architectures, making it suitable for handling large datasets like those from the Materials Project. This enables efficient computation and model training at scale.

To enable the MPI version, configure the build with the TADAH_BUILD_MPI option:

cmake .. -DTADAH_BUILD_MPI=ON

This will configure the executable as tadah_mpi, optimized for parallel execution.

Installing LAMMPS Interface

The Tadah!LAMMPS interface is essential for simulations with LAMMPS and Tadah! potentials. It is also required for building Tadah!MLIP with the Hyperparameter Optimizer (HPO) module. The compilation of Tadah! plugin follows typical LAMMPS compilation steps.

  1. Clone the LAMMPS stable version from the GitHub repository:

    git clone -b stable --depth 1 https://github.com/lammps/lammps.git /path/to/lammps

  2. Example LAMMPS serial build with make typically looks like this:

    cd /path/to/lammps/lib
git clone https://git.ecdf.ed.ac.uk/tadah/tadah.lammps.git
cd /path/to/lammps/src
make lib-tadah.lammps
make yes-ml-tadah
make serial

Important

Tadah!LAMMPS is compatible with LAMMPS releases from June 2022 onward. Because the plugin is not yet included in the official LAMMPS distribution, it does not support the LAMMPS CMake build system.

See also

For building LAMMPS with extra features, visit:

https://lammps.sandia.gov/doc/Build_package.html

Building Tadah!MLIP with Hyperparameter Optimizer

Warning

The HPO module of Tadah!MLIP requires LAMMPS to be compiled with Tadah!LAMMPS and -DLAMMPS_EXCEPTIONS=yes. Note that this setting is the default only for versions from 29 Aug 2024 onwards. For older versions, users must set it manually.

Building Tadah!MLIP with HPO is slightly more challenging, and for this reason, it is not built by default. Please read these notes carefully before proceeding.

To build Tadah!MLIP with HPO, follow these steps:

  1. Compile LAMMPS with the Tadah.LAMMPS Interface (Installing LAMMPS Interface):

    Shared vs. Static Builds:

    It is recommended to build the shared version of LAMMPS (e.g., make mode=shared serial), as shared libraries are typically less problematic during the linking stage.

    • Shared LAMMPS builds produce files like liblammps_serial.so.

    • Static builds are not compiled with position-independent code by default, which prevents linking with a shared Tadah!MLIP build.

    • Recommendation: Build both Tadah!MLIP and LAMMPS as shared libraries unless you have specific requirements.

    Serial vs. MPI:

    • Serial: For single-threaded applications, use commands like make mode=shared serial. The serial LAMMPS version must be linked to the Desktop version of Tadah!.

    • MPI: For parallel applications, compile LAMMPS with MPI support, e.g., make mode=shared mpi. The MPI version of LAMMPS must be linked to the Massively Parallel version of Tadah!.

  2. Configure Tadah! (Configuration and Compilation) using CMake with these additional flags:

    • -DTADAH_ENABLE_HPO=ON

    • -DTADAH_LAMMPS_DIR=/path/to/lammps: This should be the root directory of your LAMMPS installation, not lammps/src.

    • -DTADAH_LAMMPS_LIB=liblammps_name.ext: Replace liblammps_name with the name of your compiled LAMMPS library and .ext with appropriate file extension (.so for shared builds, e.g., liblammps_serial.so for serial or liblammps_mpi.so for MPI; .a for static builds, e.g., liblammps_serial.a).

Libraries and C++ Headers

Note

This section is relevant only if you intend to use the Tadah!API. If you’re using the command line interface (CLI), you can safely skip this section.

Tadah!API installs its headers to ${CMAKE_INSTALL_PREFIX}/include and its libraries to ${CMAKE_INSTALL_PREFIX}/lib (or lib64). If the prefix is a standard location such as /usr or /usr/local nothing extra is required:

g++ my_code.cpp -ltadah.core -o my_code            # headers and libs found automatically

When Tadah! is installed in a private directory you must give the compiler and linker a hint. The quickest way is to add the include and library paths on the command line:

g++ my_code.cpp \
    -I$HOME/.local/include \
    -L$HOME/.local/lib \
    -ltadah -o my_code

Run-time resolution LD_LIBRARY_PATH tells the dynamic loader where to find the shared object after the executable has been built:

export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH
./my_code

If you prefer not to repeat -I/-L flags, set the environment variables once for your shell (or in a module file):

# compile-time
export CPATH=$HOME/.local/include:$CPATH        # headers
export LIBRARY_PATH=$HOME/.local/lib:$LIBRARY_PATH  # libraries

# run-time
export LD_LIBRARY_PATH=$HOME/.local/lib:$LD_LIBRARY_PATH

Keep the scope of these variables as narrow as possible (script, shell session, or environment module) to avoid accidental conflicts with other software.

Compiled Libraries

The following libraries can be compiled, depending on the build settings:

  • libtadah.core

  • libtadah.models

  • libtadah.mlip

  • libtadah.md

  • libtadah.hpo (MPI version: libtadah.mpi.hpo)

Compiling and Linking with Library

For C++ library use, compile with C++17 or higher. Include library headers using the prefix tadah/ and link relevant libraries. For libtadah.mlip it is often the case that both libtadah.models and libtadah.core must be linked as well.

#include <tadah/mlip/atom.h>

Link with libtadah.mlip.

g++ -O3 -std=c++17 -o output_file test.cpp -ltadah.mlip

If the library is outside the standard path:

g++ -O3 -std=c++17 -o output_file test.cpp -I/home/$USER/.local/include -L/home/$USER/.local/lib -ltadah.mlip

Troubleshooting

  1. Permission Denied when running make install

    Run make install with sudo or change the installation path:

    cmake .. -DCMAKE_INSTALL_PREFIX=~/.local
make install

  2. Shared Object ImportError when running tadah

    Update LD_LIBRARY_PATH:

    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your/path/

  3. Compatibility Issues with LAMMPS

    Ensure compatibility with the correct LAMMPS version. See Installing LAMMPS Interface.

  4. New Issues

    Contact support for any unlisted issues.