docs(quick_start): Update easy_install.md

QuantumMisaka · QuantumMisaka · commit c43f2fa02c8d · 2025-11-19T09:21:53.000+08:00
- 添加通过git更新到最新版本的详细步骤
- 扩展工具链安装说明，包括GCC-AMD和AOCC-AOCL支持
- 重新组织conda安装部分，增加开发环境配置说明
- 优化文档结构，将手动安装部分后移
diff --git a/docs/quick_start/easy_install.md b/docs/quick_start/easy_install.md
@@ -1,6 +1,6 @@
 # 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 try [toolchain](#install-requirements-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.
+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-requirements-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.
 
 ## Get ABACUS source code
 
@@ -12,6 +12,34 @@ ABACUS source code can be obtained via one of the following choices:
 - 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
 
@@ -34,65 +62,83 @@ These requirements support the calculation of plane-wave basis in ABACUS. For LC
 - [CEREAL](https://uscilab.github.io/cereal/).
 - [ELPA](https://elpa.mpcdf.mpg.de/) >= 2017 (optional).
 
-## Install requirements
+## Install ABACUS with requirements 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
+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
 
-Some of these packages can be installed with popular package management system, such as `apt` and `yum`:
+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
-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
-```
+# 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
 
-> Installing ELPA by apt only matches requirements on Ubuntu 22.04. For earlier linux distributions, you should build ELPA from source.
+# Run
+conda activate abacus_env
+OMP_NUM_THREADS=1 mpirun -n 4 abacus
 
-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.
+# Update
+conda update -n abacus_env abacus -c conda-forge
+```
 
-Please refer to our [guide](https://github.com/deepmodeling/abacus-develop/wiki/Building-and-Running-ABACUS) on installing requirements.
+> 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).
 
-## Install requirements by toolchain
+> ABACUS supports `OpenMPI` and `MPICH` variant. Install `mpich` or `openmpi` package to switch MPI library if required.
 
-We offer a set of [toolchain](https://github.com/deepmodeling/abacus-develop/tree/develop/toolchain)
-scripts to compile and install all the requirements
-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].sh* and ABACUS itself by running *build_abacus_[gnu,intel].sh* script in the toolchain directory in both `GNU` and `Intel-oneAPI` toolchain.
-Sometimes, ABACUS by toolchain installation may have better efficient performance due to the suitable compiled dependencies.
+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).
 
-Users should read the README in toolchain directory for most of the information before use, and a tutorial for using this toolchain can be accessed in [bohrium-notebook](https://nb.bohrium.dp.tech/detail/5215742477) as reference.
+> Note: The [deepmodeling conda channel](https://anaconda.org/deepmodeling/abacus) offers historical versions of ABACUS.
 
-> Notice: the toolchain is under development, please let we know if you encounter any problem in using this toolchain by raising issue or contacting us.
+### Developing with conda
 
+It is possible to build ABACUS from source based on the conda environment.
 
-## Update to latest release by git
+```bash
+conda create -n abacus_env abacus -c conda-forge
+conda activate abacus_env
+export CMAKE_PREFIX_PATH=$CONDA_PREFIX:$CMAKE_PREFIX_PATH
 
-Please check the [release page](https://github.com/deepmodeling/abacus-develop/releases) for the release note of a new version.
+# 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.
 
-It is OK to download the new source code from beginning following the previous step.
+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`
+```
 
-You can update your cloned git repo (from Github or Gitee) in-place with the following commands:
+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`.
 
-```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
-```
+## Install ABACUS manually
 
-Then proceed to the [Build and Install](#build-and-install) part. If you encountered errors, try remove the `build` directory first and reconfigure.
+### Install requirements
 
-To use the codes under active development:
+Some of these packages can be installed with popular package management system via root permission if you have, such as `apt` and `yum`:
 
 ```bash
-git checkout develop
-git pull
+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
 ```
 
-## Configure
+> 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:
 
@@ -139,7 +185,7 @@ Here is an example:
 CXX=mpiicpx cmake -B build -DCMAKE_INSTALL_PREFIX=~/abacus -DELPA_DIR=~/elpa-2025.01.001/build -DCEREAL_INCLUDE_DIR=~/cereal/include
 ```
 
-## Build and Install
+### Build and Install
 
 After configuring, build and install by:
 
@@ -150,7 +196,9 @@ 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
+## 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/`.)*
@@ -165,6 +213,14 @@ If ABACUS is installed by toolchain, there will be an environment script in the
 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
@@ -215,64 +271,16 @@ For online development environment, we support [GitHub Codespaces](https://githu
 
 We also support [Gitpod](https://www.gitpod.io/): [Open in Gitpod](https://gitpod.io/#https://github.com/deepmodeling/abacus-develop)
 
-## 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`.
-
 ## Command line options
 
 Users can check the version of ABACUS by running the command `abacus --version`, the result will be like:
 ```
-ABACUS version v3.6.5
+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.6.5
+                              ABACUS v3.9.0.2
 
                Atomic-orbital Based Ab-initio Computation at UStc
 
