Merge branch 'develop' of https://github.com/deepmodeling/abacus-develop into develop

Author: YuLiu98

CMakeLists.txt

@@ -1,7 +1,7 @@
 ########################################
 # CMake build system
 # This file is part of ABACUS
-cmake_minimum_required(VERSION 3.18)
+cmake_minimum_required(VERSION 3.16)
 ########################################
 
 project(ABACUS
@@ -22,7 +22,7 @@ option(BUILD_TESTING "Build ABACUS unit tests" OFF)
 option(GENERATE_TEST_REPORTS "Enable test report generation" OFF)
 
 set(ABACUS_BIN_NAME abacus)
-set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/modules)
+list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/modules)
 set(ABACUS_SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/source)
 set(ABACUS_TEST_DIR ${CMAKE_CURRENT_SOURCE_DIR}/tests)
 set(ABACUS_BIN_PATH ${CMAKE_CURRENT_BINARY_DIR}/${ABACUS_BIN_NAME})
@@ -85,6 +85,7 @@ else() # CUDA not found
 endif()
 
 if(USE_CUDA OR USE_CUSOLVER_LCAO)
+  cmake_minimum_required(VERSION 3.18) # required by `CUDA_ARCHITECTURES` below
   set(CMAKE_CXX_STANDARD 14)
   set(CMAKE_CXX_EXTENSIONS ON)
   set(CMAKE_CXX_STANDARD_REQUIRED ON)

Dockerfile

@@ -1,4 +1,5 @@
-# To build this docker file, run `docker build -t abacus - < Dockerfile`.
+# To build this Dockerfile, run `docker build -t abacus - < Dockerfile`.
+# Pull image with `docker pull ghcr.io/deepmodeling/abacus:latest`.
 FROM ubuntu:latest
 RUN apt update && apt install -y --no-install-recommends libopenblas-dev liblapack-dev libscalapack-mpi-dev libelpa-dev libfftw3-dev libcereal-dev libxc-dev g++ make cmake bc time sudo vim git
 # If you wish to use the LLVM compiler, replace 'g++' above with 'clang libomp-dev'.

docs/CONTRIBUTING.md

@@ -6,7 +6,6 @@ This file provides a guideline for it.
 ## Table of Contents
 
 - [Got a question?](#got-a-question)
-- [Before getting started](#before-getting-started)
 - [Structure of the package](#structure-of-the-package)
 - [Submitting an Issue](#submitting-an-issue)
 - [Comment Style for documentation](#comment-style-for-documentation)
@@ -23,6 +22,7 @@ If you would like to implement a new feature, please submit an issue with a prop
 
 ## Structure of the package
 
+Please refer to [our instructions](./install.md) on how to installing ABACUS.
 The source code of ABACUS is based on several modules. Under the ABACUS root directory, there are the following folders:
 
 - `cmake`: relevant files for finding required packages when compiling the code with cmake;

docs/input-main.md

@@ -24,7 +24,11 @@
 
 - [Electronic structure](#electronic-structure)
 
-    [basis_type](#basis-type) | [ks_solver](#ks-solver) | [nbands](#nbands) | [nbands_sto](#nbands_sto) | [nbands_istate](#nbands-istate) | [nspin](#nspin) | [occupations](#occupations) | [smearing_method](#smearing_method) | [smearing_sigma](#smearing_sigma) | [mixing_type](#mixing-type) | [mixing_beta](#mixing-beta) | [mixing_ndim](#mixing-ndim) | [mixing_gg0](#mixing-gg0) | [gamma_only](#gamma-only) | [printe](#printe) | [scf_nmax](#scf_nmax) | [scf_thr](#scf_thr) | [chg_extrap](#chg_extrap) | [nche_sto](#nche_sto) | [emin_sto](#emin_sto) | [emax_sto](#emax_sto) | [seed_sto](#seed_sto)
+    [basis_type](#basis-type) | [ks_solver](#ks-solver) | [nbands](#nbands) | [nbands_istate](#nbands-istate) | [nspin](#nspin) | [occupations](#occupations) | [smearing_method](#smearing_method) | [smearing_sigma](#smearing_sigma) | [mixing_type](#mixing-type) | [mixing_beta](#mixing-beta) | [mixing_ndim](#mixing-ndim) | [mixing_gg0](#mixing-gg0) | [gamma_only](#gamma-only) | [printe](#printe) | [scf_nmax](#scf_nmax) | [scf_thr](#scf_thr) | [chg_extrap](#chg_extrap)
+
+- [Electronic structure (SDFT)](#electronic-structure-sdft)
+
+    [nbands_sto](#nbands_sto) | [nche_sto](#nche_sto) | [emin_sto](#emin_sto) | [emax_sto](#emax_sto) | [seed_sto](#seed_sto)
 
 - [Geometry relaxation](#geometry-relaxation)
 
@@ -464,14 +468,6 @@ calculations.
   - nspin=1: 1.2\*occupied_bands, occupied_bands+10)
   - nspin=2: max(1.2\*nelec, nelec+20)
 
-#### nbands_sto
-
-- **Type**: Integer
-- **Description**: 
-  - nbands_sto>0: Number of stochastic orbitals to calculate in stochastic DFT (SDFT) or mix stochastic-deterministic (MDFT). More bands obtain more precise results or smaller stochastic errors ($ \propto 1/\sqrt{N_{\chi}}$); 
-  - nbands_sto=0: Complete basis will be used to replace stochastic orbitals with the Chebyshev method (CT) and it will get the results the same as KSDFT without stochastic errors.
-- **Default**: 0
-
 #### nbands_istate
 
 - **Type**: Integer
@@ -570,6 +566,21 @@ calculations.
   - second-order: second-order extrapolation
 - **Default**:atomic
 
+ by time(NULL).
+- **Default**:0
+
+### Electronic structure (SDFT)
+
+This part of variables are used to control the parameters of stochastic DFT (SDFT),  mix stochastic-deterministic DFT (MDFT), or complete-basis Chebyshev method (CT).
+
+#### nbands_sto
+
+- **Type**: Integer
+- **Description**: 
+  - nbands_sto>0: Number of stochastic orbitals to calculate in SDFT and MDFT.  More bands obtain more precise results or smaller stochastic errors ($ \propto 1/\sqrt{N_{\chi}}$); 
+  - nbands_sto=0: Complete basis will be used to replace stochastic orbitals with the Chebyshev method (CT) and it will get the results the same as KSDFT without stochastic errors.
+- **Default**: 0
+
 #### nche_sto
 
 - **Type**: Integer
@@ -593,8 +604,7 @@ calculations.
 - **Type**: Integer
 - **Description**: The random seed to generate stochastic orbitals.
   - seed_sto>=0: Stochastic orbitals have the form of $\exp(i2\pi\theta(G))$, where $\theta$ is a uniform distribution in $(0,1)$. If seed_sto=0, the seed is decided by time(NULL).
-  - seed_sto<=-1: Stochastic orbitals have the form of $\pm1$ with the equal probability. If seed_sto=-1, the seed is decided by time(NULL).
-- **Default**:0
+  - seed_sto<=-1: Stochastic orbitals have the form of $\pm1$ with the equal probability. If seed_sto=-1, the seed is decided
 
 ### Geometry relaxation
 

docs/install.md

@@ -13,34 +13,55 @@
 
 ## Installation
 
+### Container Deployment
+
+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).
+
+We also offer a pre-built docker image containing all the requirements for development. Please refer to our [Package Page](https://github.com/deepmodeling/abacus-develop/pkgs/container/abacus-development-kit).
+
+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.
+
+We also support [gitpod](https://www.gitpod.io/) to offer an ready-to-use online development environment.
+[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/deepmodeling/abacus-develop)
+
 ### Prerequisites
 
-ABACUS current supports Linux. To compile ABACUS, please make sure that the following prerequisites are
-present:
+ABACUS currently supports Linux. `Dockerfile`s under the root directory of our repo will come in handy.
+
+To compile ABACUS, please make sure that the following prerequisites are present:
 
 - C++ compiler, supporting C++11. You can use [Intel® C++ compiler](https://software.intel.com/enus/c-compilers) or [GCC](https://gcc.gnu.org/).
 - MPI compiler. The recommended version are [Intel MPI](https://software.intel.com/enus/mpi-library) or [MPICH](https://www.mpich.org/).
 - Fortran compiler for building `BLAS`, `LAPACK` and `ScaLAPACK`. You can use[Intel® Fortran Compiler](https://www.intel.com/content/www/us/en/developer/tools/oneapi/fortran-compiler.html) [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/).
 - [ScaLAPACK](http://www.netlib.org/scalapack/).
-- [FFTW](http://www.fftw.org/).
-- [ELPA](https://elpa.mpcdf.mpg.de/).
+- [FFTW3](http://www.fftw.org/).
+- [ELPA](https://elpa.mpcdf.mpg.de/) >= 2017.
 - [CEREAL](https://uscilab.github.io/cereal/).
 
+These packages can be installed with popular package management system, such as `apt` and `yum`:
+
+```bash
+sudo apt update && sudo apt install -y libopenblas-dev liblapack-dev libscalapack-mpi-dev libelpa-dev libfftw3-dev libcereal-dev libxc-dev g++ make cmake bc git
+```
+
+> Please double-check the installed version of ELPA!
+
 Alternatively, you can choose [Intel® oneAPI toolkit](https://software.intel.com/content/www/us/en/develop/tools/oneapi/commercial-base-hpc.html) (former 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`,  - this means that no Fortran compiler required anymore. 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 noted that building `elpa` with a different MPI library may cause conflict between MPI libraries. 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.
 
 If you have trouble building requirements, our Dockerfiles in root path offer a reference, or read the section below to use a pre-built container.
-[back to top](#download-and-install)
 
-### Container Deployment
+And of course, a copy of ABACUS source code is required:
 
-We offer a pre-built docker image containing all the requirements - you only need to clone and compile `abacus` in the container. Please refer to our [Package Page](https://github.com/deepmodeling/abacus-develop/pkgs/container/abacus-development-kit).
+- 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/): replacing 'github.com' with 'gitee.com' works for all the links above. e.g. `git clone https://gitee.com/deepmodeling/abacus-develop.git`
 
-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.
 
-We also support [gitpod](https://www.gitpod.io/) to offer an ready-to-use online development environment.
-[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/deepmodeling/abacus-develop)
+[back to top](#download-and-install)
 
 ### Build and install ABACUS with CMake