# Easy Installation 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](../advanced/install.md)** 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 use [toolchain](#install-by-toolchain) to install ABACUS and dependencies in a source-code compilation way with convience. You can also deploy ABACUS **without building** by [Docker](#container-deployment) or [conda](#install-by-conda). Please note that ABACUS only supports Linux; for Windows users, please consider using [WSL](https://learn.microsoft.com/en-us/windows/wsl/) or docker. For a scripted one-click setup that provisions WSL2 and installs ABACUS inside it automatically, see [Windows One-Click Installer](./advanced/windows_installer.md). ## Get ABACUS source code ABACUS source code 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: `wget https://github.com/deepmodeling/abacus-develop/archive/refs/heads/develop.zip` - Get the source code of a stable version [here](https://github.com/deepmodeling/abacus-develop/releases) - If you have connection issues accessing GitHub, please try out our official [Gitee repo](https://gitee.com/deepmodeling/abacus-develop/): e.g. `git clone https://gitee.com/deepmodeling/abacus-develop.git`. This Gitee repo is updated synchronously with GitHub. ## Update to latest release by git Please check the [release page](https://github.com/deepmodeling/abacus-develop/releases) for the release note of a new version. It is OK to download the new source code from beginning following the previous step. You can update your cloned git repo (from Github or Gitee) in-place with the following commands: ```bash git remote -v # Check if the output contains the line below # origin https://github.com/deepmodeling/abacus-develop.git (fetch) # The remote name is marked as "upstream" if you clone the repo from your own fork. # Replace "origin" with "upstream" or the remote name corresponding to deepmodeling/abacus-develop if necessary git fetch origin git checkout v3.x.x # Replace the tag with the latest version, like v3.10.0 git describe --tags # Verify if the tag has been successfully checked out ``` Then proceed to the [Build and Install](#build-and-install) part. If you encountered errors, try remove the `build` directory first and reconfigure. To use the codes under active development: ```bash git checkout develop git pull ``` ## Prerequisites To compile ABACUS, please make sure that the following prerequisites are present: - [CMake](https://cmake.org/) >= 3.16 . - C++ compiler, supporting C++11. You can use [Intel® C++ compiler](https://software.intel.com/enus/c-compilers) or [GCC](https://gcc.gnu.org/). > GCC version 5 or later is always required. Intel compilers also use GCC headers and libraries[(ref)](https://www.intel.com/content/www/us/en/develop/documentation/cpp-compiler-developer-guide-and-reference/top/compatibility-and-portability/gcc-compatibility-and-interoperability.html#gcc-compatibility-and-interoperability_GUID-52CB6FE0-83DA-4028-9EF4-0DFAF1652736). - MPI library. The recommended versions are [Intel MPI](https://software.intel.com/enus/mpi-library), [MPICH](https://www.mpich.org/) or [Open MPI](https://www.open-mpi.org/). - Fortran compiler if you are building `BLAS`, `LAPACK`, `ScaLAPACK`, and `ELPA` from source file. You can use [Intel® Fortran Compiler](https://www.intel.com/content/www/us/en/developer/tools/oneapi/fortran-compiler.html) or [GFortran](https://gcc.gnu.org/fortran/). - [BLAS](http://www.netlib.org/blas/). You can use [OpenBLAS](https://www.openblas.net/). - [LAPACK](http://www.netlib.org/lapack/). - [FFTW3](http://www.fftw.org/). These requirements support the calculation of plane-wave basis in ABACUS. For LCAO basis calculation, additional components are required: - [ScaLAPACK](http://www.netlib.org/scalapack/). - [CEREAL](https://uscilab.github.io/cereal/). - [ELPA](https://elpa.mpcdf.mpg.de/) >= 2017 (optional). ## Install by toolchain We offer a set of [toolchain](https://github.com/deepmodeling/abacus-develop/tree/develop/toolchain) scripts to compile and install all the requirements and ABACUS itself automatically and suitable for machine characteristic in an online or offline way. The toolchain can be downloaded with ABACUS repo, and users can easily compile the requirements by running *toolchain_[gnu,intel,gcc-aocl,aocc-aocl].sh* and ABACUS itself by running *build_abacus_[gnu,intel,gcc-aocl,aocc-aocl].sh* script in the toolchain directory in `GNU`, `Intel-oneAPI` , `GCC-AMD AOCL` and `AMD AOCC-AOCL` toolchain. Sometimes, ABACUS by toolchain installation may have better efficient performance due to the suitable compiled dependencies. One should read the [README in toolchain](https://github.com/deepmodeling/abacus-develop/tree/develop/toolchain/README.md) for most of the information before use, and related tutorials can be accessed via ABACUS WeChat platform. ## Install by conda Conda is a package management system with a separated environment, not requiring system privileges. You can refer to [DeepModeling conda FAQ](https://docs.deepmodeling.com/faq/conda.html) for how to setup a conda environment. A pre-built ABACUS binary with all requirements is available at [conda-forge](https://anaconda.org/conda-forge/abacus). It supports advanced features including Libxc, LibRI, and DeePKS. Conda will install the GPU-supported version of ABACUS if a valid GPU driver is present. Please refer to [the advanced installation guide](../advanced/install.md) for more details. ```bash # Install # We recommend installing ABACUS in a new environment to avoid potential conflicts: conda create -n abacus_env abacus "libblas=*=*mkl" mpich -c conda-forge # Run conda activate abacus_env OMP_NUM_THREADS=1 mpirun -n 4 abacus # Update conda update -n abacus_env abacus -c conda-forge ``` > If OpenBLAS gives warning about OpenMP threads, please install conda package `"openblas=*=openmp*"` or `"libblas=*=*mkl"`. See [switching BLAS implementation in conda](https://conda-forge.org/docs/maintainer/knowledge_base.html#switching-blas-implementation). > ABACUS supports `OpenMPI` and `MPICH` variant. Install `mpich` or `openmpi` package to switch MPI library if required. For more details on building a conda package of ABACUS locally, please refer to the [conda recipe file](https://github.com/deepmodeling/abacus-develop/blob/develop/conda/meta.yaml). > Note: The [deepmodeling conda channel](https://anaconda.org/deepmodeling/abacus) offers historical versions of ABACUS. ### Developing with conda It is possible to build ABACUS from source based on the conda environment. ```bash conda create -n abacus_env abacus -c conda-forge conda activate abacus_env export CMAKE_PREFIX_PATH=$CONDA_PREFIX:$CMAKE_PREFIX_PATH # By default OpenBLAS is used; run `conda install "blas=*=mkl" mkl_fft mkl-devel -c conda-forge` to switch implementation. export MKLROOT=$CONDA_PREFIX # If Intel MKL is required. export CMAKE_PREFIX_PATH=`python -c 'import torch;print(torch.utils.cmake_prefix_path)'`:$CMAKE_PREFIX_PATH # If DEEPKS support is required; # usually expands to `$CONDA_PREFIX/lib/python3.1/site-packages/torch/share/cmake` ``` And, follow the instructions in [Build and Install](#build-and-install) part above withou manually setting paths to dependencies. See [the advanced installation guide](../advanced/install.md) for more features. Make sure the environment variables are set before running `cmake`. Possible command: `cmake -B build -DENABLE_MLALGO=ON -DENABLE_LIBXC=ON -DENABLE_LIBRI=ON`. ## Install ABACUS manually ### Install requirements Some of these packages can be installed with popular package management system via root permission if you have, such as `apt` and `yum`: ```bash 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 pkgconf ``` > 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](https://software.intel.com/content/www/us/en/develop/tools/oneapi/commercial-base-hpc.html) (former Intel® Parallel Studio) as toolchain. The [Intel® oneAPI Base Toolkit](https://software.intel.com/content/www/us/en/develop/tools/oneapi/all-toolkits.html#base-kit) contains Intel® oneAPI Math Kernel Library (aka `MKL`), including `BLAS`, `LAPACK`, `ScaLAPACK` and `FFTW3`. The [Intel® oneAPI HPC Toolkit](https://software.intel.com/content/www/us/en/develop/tools/oneapi/all-toolkits.html#hpc-kit) contains Intel® MPI Library, and C++ compiler(including MPI compiler). > Please note that building `elpa` with a different MPI library may cause conflict. > Don't forget to [set environment variables](https://software.intel.com/content/www/us/en/develop/documentation/get-started-with-intel-oneapi-render-linux/top/configure-your-system.html) before you start! `cmake` will use Intel MKL if the environment variable `MKLROOT` is set. Please refer to our [guide](https://github.com/deepmodeling/abacus-develop/wiki/Building-and-Running-ABACUS) on installing requirements. ### Configure The basic command synopsis is: ```bash cd abacus-develop cmake -B build [-D =] ... ``` 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; `/usr/local/bin/abacus` by default - Compilers - `CMAKE_CXX_COMPILER`: C++ compiler; usually `g++`(GNU C++ compiler) or `icpx`(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 `mpicxx` or `mpiicpx`(for Intel toolkits) or `mpiicpc`(for classic Intel Compiler Classic MPI before 2024.0). - Requirements: Unless indicated, CMake will try to find under default paths. - `MKLROOT`: If environment variable `MKLROOT` exists, `cmake` will take MKL as a preference, i.e. not using `LAPACK`, `ScaLAPACK` and `FFTW`. To disable MKL, unset environment variable `MKLROOT`, or pass `-DMKLROOT=OFF` to `cmake`. - `LAPACK_DIR`: Path to OpenBLAS library `libopenblas.so`(including BLAS and LAPACK) - `SCALAPACK_DIR`: Path to ScaLAPACK library `libscalapack.so` - `ELPA_DIR`: Path to ELPA install directory; should be the folder containing 'include' and 'lib'. > Note: In ABACUS v3.5.1 or earlier, 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` to help the build system find ELPA headers. - `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: In ABACUS v3.5.1 or earlier, Libxc built from source with Makefile is NOT supported; please compile Libxc with CMake instead. - `LIBRI_DIR`: (Optional) Path to LibRI. - `LIBCOMM_DIR`: (Optional) Path to LibComm. - Components: The values of these variables should be 'ON', '1' or 'OFF', '0'. The default values are 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](../advanced/install.md#add-libxc-support) to suppport variety of functionals. If `Libxc_DIR` is defined, `ENABLE_LIBXC` will set to 'ON'. - `ENABLE_LIBRI=OFF`: [Enable LibRI](../advanced/install.md#add-libri-support) to suppport variety of functionals. If `LIBRI_DIR` and `LIBCOMM_DIR` is defined, `ENABLE_LIBRI` will set to 'ON'. - `USE_OPENMP=ON`: Enable OpenMP support. Building ABACUS without OpenMP is not fully tested yet. - `BUILD_TESTING=OFF`: [Build unit tests](../advanced/install.md#build-unit-tests). - `ENABLE_GOOGLEBENCH=OFF`: [Build performance tests](../advanced/install.md#build-performance-tests) - `ENABLE_MPI=ON`: Enable MPI parallel compilation. If set to `OFF`, a serial version of ABACUS will be compiled. It now supports both PW and LCAO. - `ENABLE_COVERAGE=OFF`: Build ABACUS executable supporting [coverage analysis](../CONTRIBUTING.md#generating-code-coverage-report). This feature has a drastic impact on performance. - `ENABLE_ASAN=OFF`: Build with Address Sanitizer. This feature would help detecting memory problems. - `USE_ELPA=ON`: Use ELPA library in LCAO calculations. If this value is set to OFF, ABACUS can be compiled without ELPA library. Here is an example: ```bash CXX=mpiicpx cmake -B build -DCMAKE_INSTALL_PREFIX=~/abacus -DELPA_DIR=~/elpa-2025.01.001/build -DCEREAL_INCLUDE_DIR=~/cereal/include ``` ### Build and Install After configuring, build and install by: ```bash 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. ## Run ABACUS ### Load ABACUS If ABACUS is installed into a custom directory using `CMAKE_INSTALL_PREFIX`, please add it to your environment variable `PATH` to locate the correct executable. *(Note: `my-install-dir` should be changed to the location of your installed abacus:`/home/your-path/abacus/bin/`.)* ```bash export PATH=/my-install-dir/:$PATH ``` If ABACUS is installed by toolchain, there will be an environment script in the toolchain directory named as *abacus_env.sh*. You can source it to set the environment variables. ```bash source /path/to/abacus/toolchain/abacus_env.sh ``` If ABACUS is installed by conda, please make sure the conda environment is activated before running ABACUS. ```bash conda activate abacus_env ``` ### Run with Parallelism Setting Please set OpenMP threads by setting environment variable: ```bash export OMP_NUM_THREADS=1 ``` Enter a directory containing a `INPUT` file. Please make sure structure, pseudo potential, or orbital files indicated by `INPUT` is at the correct location. ```bash cd abacus-develop/examples/force/pw_Si2 ``` Use 4 MPI processes to run, for example: ```bash 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. To use 4 threads and 4 MPI processes, set the environment variable `OMP_NUM_THREADS` before running `mpirun`: ```bash OMP_NUM_THREADS=4 mpirun -n 4 abacus ``` In this case, the total thread count is 16. > Notice: If the MPI library you are using is OpenMPI, which is commonly the case, when you set the number of processes to 1 or 2, OpenMPI will default to `--bind-to core`. This means that no matter how many threads you set, these threads will be restricted to run on 1 or 2 CPU cores. Therefore, setting a higher number of OpenMP threads might result in slower program execution. Hence, when using `mpirun -n` set to 1 or 2, it is recommended to set `--bind-to none` to avoid performance degradation. For example:`OMP_NUM_THREADS=6 mpirun --bind-to none -n 1 abacus`. The detailed binding strategy of OpenMPI can be referred to at https://docs.open-mpi.org/en/v5.0.x/man-openmpi/man1/mpirun.1.html#quick-summary. ABACUS will try to determine the number of threads used by each process if `OMP_NUM_THREADS` is not set. However, it is **required** to set `OMP_NUM_THREADS` before running `mpirun` to avoid potential performance issues. Please refer to [hands-on guide](./hands_on.md) 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. ## Container Deployment > 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](https://github.com/deepmodeling/abacus-develop/pkgs/container/abacus). For a quick start: pull the image, prepare the data, run container. Instructions on using the image can be accessed in [Dockerfile](../../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](https://github.com/orgs/deepmodeling/packages?repo_name=abacus-develop). The project is ready for VS Code development container. Please refer to [Developing inside a Container](https://code.visualstudio.com/docs/remote/containers#_quick-start-try-a-development-container). Choose `Open a Remote Window -> Clone a Repository in Container Volume` in VS Code command palette, and put the [git address](https://github.com/deepmodeling/abacus-develop.git) of `ABACUS` when prompted. For online development environment, we support [GitHub Codespaces](https://github.com/codespaces): [Create a new Codespace](https://github.com/codespaces/new?machine=basicLinux32gb&repo=334825694&ref=develop&devcontainer_path=.devcontainer%2Fdevcontainer.json&location=SouthEastAsia) We also support [Gitpod](https://www.gitpod.io/): [Open in Gitpod](https://gitpod.io/#https://github.com/deepmodeling/abacus-develop) ## Command line options Users can check the version of ABACUS by running the command `abacus --version`, the result will be like: ``` ABACUS version v3.9.0.2 ``` Users may check the correctness of the setting of parameters in the `INPUT` file by running the command `abacus --check-input`, the result will be like: ``` ABACUS v3.9.0.2 Atomic-orbital Based Ab-initio Computation at UStc Website: http://abacus.ustc.edu.cn/ Documentation: https://abacus.deepmodeling.com/ Repository: https://github.com/abacusmodeling/abacus-develop https://github.com/deepmodeling/abacus-develop Commit: unknown Tue Jun 18 14:20:31 2024 MAKE THE DIR : OUT.ABACUS/ ---------------------------------------------------------- INPUT parameters have been successfully checked! ---------------------------------------------------------- ``` Warnings will be given if there are any errors in the `INPUT` file.