This guide helps you install ABACUS with basic features. For DeePKS, DeePMD and Libxc support, or building with
make, please refer to the advanced installation guide after going through this page. We recommend building ABACUS with
cmake to avoid dependency issues. We recommend compiling ABACUS(and possibly its requirements) from the source code using the latest compiler for the best performace. You can also deploy ABACUS without building by Docker or conda. Please note that ABACUS only supports Linux; for Windows users, please consider using WSL or docker.
To compile ABACUS, please make sure that the following prerequisites are present:
GCC version 5 or later is always required. Intel compilers also use GCC headers and libraries(ref).
These requirements support the calculation of plane-wave basis in ABACUS. For LCAO basis calculation, additional components are required:
Some of these packages can be installed with popular package management system, such as
sudo apt update && sudo apt install -y libopenblas-openmp-dev liblapack-dev libscalapack-mpi-dev libelpa-dev libfftw3-dev libcereal-dev libxc-dev g++ make cmake bc git
Installing ELPA by apt only matches requirements on Ubuntu 22.04. For earlier linux distributions, you should build ELPA from source.
We recommend Intel® oneAPI toolkit (former Intel® Parallel Studio) as toolchain. The Intel® oneAPI Base Toolkit contains Intel® oneAPI Math Kernel Library (aka
FFTW3. The Intel® oneAPI HPC Toolkit contains Intel® MPI Library, and C++ compiler(including MPI compiler).
Please note that building
elpawith a different MPI library may cause conflict. Don’t forget to set environment variables before you start!
cmakewill use Intel MKL if the environment variable
Please refer to our guide on installing requirements.
Get ABACUS source code
Of course a copy of ABACUS source code is required, which can be obtained via one of the following choices:
Clone the whole repo with git:
git clone https://github.com/deepmodeling/abacus-develop.git
Clone the minimum required part of repo:
git clone https://github.com/deepmodeling/abacus-develop.git --depth=1
Download the latest source code without git:
Get the source code of a stable version here
If you have connection issues accessing GitHub, please try out our official Gitee repo: e.g.
git clone https://gitee.com/deepmodeling/abacus-develop.git
The basic command synopsis is:
cd abacus-develop cmake -B build [-D <var>=<value>] ...
Here, ‘build’ is the path for building ABACUS; and ‘-D’ is used for setting up some variables for CMake indicating optional components or requirement positions.
CMAKE_INSTALL_PREFIX: the path of ABACUS binary to install;
CMAKE_CXX_COMPILER: C++ compiler; usually
g++(GNU C++ compiler) or
icpc(Intel C++ compiler). Can also set from environment variable
CXX. It is OK to use MPI compiler here.
MPI_CXX_COMPILER: MPI wrapper for C++ compiler; usually
mpiicpc(for Intel MPI).
Requirements: Unless indicated, CMake will try to find under default paths.
MKLROOT: If environment variable
cmakewill take MKL as a preference, i.e. not using
FFTW. To disable MKL, unset environment variable
MKLROOT, or pass
LAPACK_DIR: Path to OpenBLAS library
libopenblas.so(including BLAS and LAPACK)
SCALAPACK_DIR: Path to ScaLAPACK library
ELPA_DIR: Path to ELPA install directory; should be the folder containing ‘include’ and ‘lib’.
Note: If you install ELPA from source, please add a symlink to avoid the additional include file folder with version name:
ln -s elpa/include/elpa-2021.05.002/elpa elpa/include/elpa. This is a known behavior of ELPA.
FFTW3_DIR: Path to FFTW3.
CEREAL_INCLUDE_DIR: Path to the parent folder of
cereal/cereal.hpp. Will download from GitHub if absent.
Libxc_DIR: (Optional) Path to Libxc.
Note: Building Libxc from source with Makefile does NOT support using it in CMake here. Please compile Libxc with CMake instead.
Components: The value for these variables should be ‘ON’, ‘1’ or ‘OFF’, ‘0’. The default value is given below.
ENABLE_LCAO=ON: Enable LCAO calculation. If SCALAPACK, ELPA or CEREAL is absent and only require plane-wave calculations, the feature of calculating LCAO basis can be turned off.
ENABLE_LIBXC=OFF: Enable Libxc to suppport variety of functionals. If
ENABLE_LIBXCwill set to ‘ON’.
USE_OPENMP=ON: Enable OpenMP support. Building ABACUS without OpenMP is not fully tested yet.
BUILD_TESTING=OFF: Build unit tests.
ENABLE_COVERAGE=OFF: Build ABACUS executable supporting coverage analysis. This feature has a drastic impact on performance.
ENABLE_ASAN=OFF: Build with Address Sanitizer. This feature would help detecting memory problems. Only supports GCC.
Here is an example:
CXX=mpiicpc cmake -B build -DCMAKE_INSTALL_PREFIX=~/abacus -DELPA_DIR=~/elpa-2016.05.004/build -DCEREAL_INCLUDEDIR=~/cereal/include
Build and Install
After configuring, build and install by:
cmake --build build -j`nproc` cmake --install build
You can change the number after
-j on your need: set to the number of CPU cores(
nproc) to reduce compilation time.
Please set OpenMP threads by setting environment variable:
Entering a directory containing input files, including parameters, structure file, and pseudo potential files:
Use 4 MPI processes to run, for example:
mpirun -n 4 abacus
The total thread count(i.e. OpenMP per-process thread count * MPI process count) should not exceed the number of cores in your machine.
Please refer to hands-on guide for more instructions.
Note: Some Intel CPU has a feature named Hyper-Threading(HT). This feature enables one physical core switch fastly between two logical threads. It would benefits from I/O bound tasks: when a thread is blocked by I/O, the CPU core can work on another thread. However, it helps little on CPU bound tasks, like ABACUS and many other scientific computing softwares. We recommend using the physical CPU core number. To determine if HT is turned on, execute
lscpu | grep 'per core'and see if ‘Thread(s) per core’ is 2.
Please note that containers target at developing and testing, but not massively parallel computing for production. Docker has a bad support to MPI, which may cause performance degradation.
We’ve built a ready-for-use version of ABACUS with docker here. For a quick start: pull the image, prepare the data, run container. Instructions on using the image can be accessed in Dockerfile. A mirror is available by
docker pull registry.dp.tech/deepmodeling/abacus.
We also offer a pre-built docker image containing all the requirements for development. Please refer to our Package Page.
The project is ready for VS Code development container. Please refer to Developing inside a Container. Choose
Open a Remote Window -> Clone a Repository in Container Volume in VS Code command palette, and put the git address of
ABACUS when prompted.
Install by conda
Conda is a package management system with separated environment, not requiring system privileges. A pre-built ABACUS binary with all requirements is available at deepmodeling conda channel. Install ABACUS by the commands below:
# We recommend installing ABACUS in a new environment to avoid potential conflicts: conda create -n abacus_env abacus -c deepmodeling -c conda-forge conda activate abacus_env # ABACUS is ready to go: mpirun -n 4 abacus
For more details on building a conda package of ABACUS, please refer to the conda recipe file online.