deepmodeling · njzjz · Jul 24, 2026 · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026
diff --git a/doc/README b/doc/README
@@ -1 +1,3 @@
-To run the HTML documentation build, doxygen have to be installed.
+Building the documentation requires Python 3.11 or newer because the `docs`
+extra uses MyST-Parser 5.1 and Sphinx 8. Doxygen must also be installed to build
+the HTML documentation.
diff --git a/doc/backend.md b/doc/backend.md
@@ -45,9 +45,8 @@ The `.pd` extension is used for model checkpoint storage, which is commonly util
 
 ### DP {{ dpmodel_icon }}
 
-:::{note}
-This backend is only for development and should not take into production.
-:::
+> [!NOTE]
+> This backend is only for development and should not take into production.
 
 - Model filename extension: `.dp`, `.yaml`, `.yml`
 

diff --git a/doc/conf.py b/doc/conf.py
@@ -201,6 +201,7 @@
     "https://cdnjs.cloudflare.com/ajax/libs/mathjax/3.2.0/es5/tex-mml-chtml.min.js"
 )
 myst_enable_extensions = [
+    "alert",
     "dollarmath",
     "colon_fence",
     "substitution",

diff --git a/doc/data/system.md b/doc/data/system.md
@@ -50,9 +50,8 @@ In general, we always use the following convention of units:
 
 ## Mixed type
 
-:::{note}
-Only the [DPA-1](../model/train-se-atten.md) and [DPA-2](../model/dpa2.md) descriptors support this format.
-:::
+> [!NOTE]
+> Only the [DPA-1](../model/train-se-atten.md) and [DPA-2](../model/dpa2.md) descriptors support this format.
 
 In the standard data format, only those frames with the same fingerprint (i.e. the number of atoms of different elements) can be put together as a unified system.
 This may lead to sparse frame numbers in those rare systems.

diff --git a/doc/development/create-a-model-pt.md b/doc/development/create-a-model-pt.md
@@ -1,10 +1,9 @@
 # Create a model in other backends {{ pytorch_icon }} {{ dpmodel_icon }}
 
-:::{note}
-**Supported backends**: PyTorch {{ pytorch_icon }}, DP {{ dpmodel_icon }}
-
-In the following context, we use the PyTorch backend as the example, while it also applies to other backends listed above.
-:::
+> [!NOTE]
+> **Supported backends**: PyTorch {{ pytorch_icon }}, DP {{ dpmodel_icon }}
+>
+> In the following context, we use the PyTorch backend as the example, while it also applies to other backends listed above.
 
 If you'd like to create a new model that isn't covered by the existing DeePMD-kit library, but reuse DeePMD-kit's other efficient modules such as data processing, trainer, etc, you may want to read this section.
 

diff --git a/doc/development/type-embedding.md b/doc/development/type-embedding.md
@@ -86,6 +86,5 @@ build -> _pass_filter -> _filter -> _filter_lower
 
 In `fitting net`, it takes the descriptor vector as input, whose dimension is \[natoms, $M_1\times M_2$\]. Because we need to involve information on the centric atom in this step, we need to generate a matrix named `atype_embed` (of dim [natoms, nchanl]), in which each row is the type embedding vector of the specific centric atom. The input is sorted by type of centric atom, we also know the number of a particular atom type (stored in `natoms[2+i]`), thus we get the type vector of the centric atom. In the build phase of the fitting net, it will check whether type embedding exists in `input_dict` and fetch them. After that, call `embed_atom_type` function to look up the embedding vector for the type vector of the centric atom to obtain `atype_embed`, and concat input with it ([input, atype_embed]). The modified input goes through `fitting` net\` to get predicted energy.
 
-:::{note}
-You can't apply the compression method while using atom-type embedding.
-:::
+> [!NOTE]
+> You can't apply the compression method while using atom-type embedding.
diff --git a/doc/env.md b/doc/env.md
@@ -1,8 +1,7 @@
 # Runtime environment variables
 
-:::{note}
-For build-time environment variables, see [Install from source code](./install/install-from-source.md).
-:::
+> [!NOTE]
+> For build-time environment variables, see [Install from source code](./install/install-from-source.md).
 
 ## All interfaces
 

diff --git a/doc/environment.yml b/doc/environment.yml
@@ -4,7 +4,7 @@ channels:
   - defaults
 dependencies:
   - doxygen>=1.9.1
-  - python=3.10
+  - python=3.11
   - pip>=20.1
   - pip:
       - ..[docs,cpu,torch]

diff --git a/doc/freeze/compress.md b/doc/freeze/compress.md
@@ -1,8 +1,7 @@
 # Compress a model {{ tensorflow_icon }} {{ pytorch_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}
 
 ## Theory
 

diff --git a/doc/inference/cxx.md b/doc/inference/cxx.md
@@ -1,8 +1,7 @@
 # C/C++ interface
 
-:::{note}
-See [Environment variables](../env.md) for the runtime environment variables.
-:::
+> [!NOTE]
+> See [Environment variables](../env.md) for the runtime environment variables.
 
 ## C++ interface
 

diff --git a/doc/inference/embedding.md b/doc/inference/embedding.md
@@ -4,13 +4,12 @@ A trained model can export learned representations ("embeddings") for downstream
 analysis, such as clustering, visualization, or training auxiliary models. A
 single forward pass produces the embeddings without computing forces or virials.
 
-:::{note}
-**Supported backends**: PyTorch {{ pytorch_icon }}, for energy models (including
-DPA4/SeZM and DP+ZBL / linear combinations, where the embedding comes from the
-descriptor-fitting sub-model). It also works for other descriptor-fitting models
-(dipole, polarizability, dos, property), though the `structural_feature` is only
-physically meaningful for energy models. Spin models are not supported.
-:::
+> [!NOTE]
+> **Supported backends**: PyTorch {{ pytorch_icon }}, for energy models (including
+> DPA4/SeZM and DP+ZBL / linear combinations, where the embedding comes from the
+> descriptor-fitting sub-model). It also works for other descriptor-fitting models
+> (dipole, polarizability, dos, property), though the `structural_feature` is only
+> physically meaningful for energy models. Spin models are not supported.
 
 Three embeddings are produced for each frame:
 

diff --git a/doc/inference/nodejs.md b/doc/inference/nodejs.md
@@ -1,8 +1,7 @@
 # Node.js interface
 
-:::{note}
-See [Environment variables](../env.md) for the runtime environment variables.
-:::
+> [!NOTE]
+> See [Environment variables](../env.md) for the runtime environment variables.
 
 If [Node.js interface is installed](../install/install-nodejs.md), one can use the Node.js interface for model inference, which is a wrapper of [the header-only C++ API](./cxx.md).
 

diff --git a/doc/inference/python.md b/doc/inference/python.md
@@ -1,8 +1,7 @@
 # Python interface
 
-:::{note}
-See [Environment variables](../env.md) for the runtime environment variables.
-:::
+> [!NOTE]
+> See [Environment variables](../env.md) for the runtime environment variables.
 
 One may use the python interface of DeePMD-kit for model inference, an example is given as follows
 
@@ -34,14 +33,13 @@ descriptors = dp.eval_descriptor(coord, cell, atype)
 
 where `descriptors` is the descriptor matrix of the system. This can also be done using the command line interface `dp eval-desc` as described in the [test documentation](../test/test.md).
 
-:::{note}
-`eval_descriptor` is the descriptor-only interface supported across backends. In
-the PyTorch backend, [`eval_embedding`](embedding.md) additionally returns the
-descriptor, per-atom feature, and per-structure feature in a single forward pass.
-PyTorch descriptor/embedding APIs accept `dtype="fp32"`, `"fp64"`, or `"native"`;
-`eval_descriptor` defaults to `native`, while `eval_embedding` defaults to
-`fp32`.
-:::
+> [!NOTE]
+> `eval_descriptor` is the descriptor-only interface supported across backends. In
+> the PyTorch backend, [`eval_embedding`](embedding.md) additionally returns the
+> descriptor, per-atom feature, and per-structure feature in a single forward pass.
+> PyTorch descriptor/embedding APIs accept `dtype="fp32"`, `"fp64"`, or `"native"`;
+> `eval_descriptor` defaults to `native`, while `eval_embedding` defaults to
+> `fp32`.
 
 Furthermore, one can use the python interface to calculate model deviation.
 
@@ -62,9 +60,8 @@ Otherwise, TensorFlow or PyTorch will never release the memory, and this may lea
 
 ## External neighbor list algorithm {{ tensorflow_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}
 
 The native neighbor list algorithm of the DeePMD-kit is in $O(N^2)$ complexity ($N$ is the number of atoms).
 While this is not a problem for small systems that quantum methods can afford, the large systems for molecular dynamics have slow performance.

diff --git a/doc/install/build-conda.md b/doc/install/build-conda.md
@@ -1,10 +1,8 @@
 # Building conda packages
 
-::::{danger}
-
-:::{deprecated} 3.0.0
-The official channel has been deprecated since 3.0.0.
-Refer to [conda-forge documentation](https://conda-forge.org/docs/maintainer/adding_pkgs/) for how to contribute and build packages locally.
-:::
-
-::::
+> [!CAUTION]
+>
+> :::{deprecated} 3.0.0
+> The official channel has been deprecated since 3.0.0.
+> Refer to [conda-forge documentation](https://conda-forge.org/docs/maintainer/adding_pkgs/) for how to contribute and build packages locally.
+> :::
diff --git a/doc/install/easy-install-dev.md b/doc/install/easy-install-dev.md
@@ -22,9 +22,8 @@ pip install -U --pre deepmd-kit[gpu,cu12,lmp,torch] --extra-index-url https://de
 
 ## Download pre-compiled C Library {{ tensorflow_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}
 
 The [pre-compiled C library](./install-from-c-library.md) can be downloaded from [here](https://nightly.link/deepmodeling/deepmd-kit/workflows/package_c/master/libdeepmd_c-0-libdeepmd_c.tar.gz.zip), or via a shell command:
 

diff --git a/doc/install/easy-install.md b/doc/install/easy-install.md
@@ -4,14 +4,12 @@ There are various easy methods to install DeePMD-kit. Choose one that you prefer
 
 After your easy installation, DeePMD-kit (`dp`) and LAMMPS (`lmp`) will be available to execute. You can try `dp -h` and `lmp -h` to see the help. `mpirun` is also available considering you may want to train models or run LAMMPS in parallel.
 
-:::{note}
-Note: The off-line packages and conda packages require the [GNU C Library](https://www.gnu.org/software/libc/) 2.17 or above. The GPU version requires [compatible NVIDIA driver](https://docs.nvidia.com/deploy/cuda-compatibility/index.html#minor-version-compatibility) to be installed in advance. It is possible to force conda to [override detection](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-virtual.html#overriding-detected-packages) when installation, but these requirements are still necessary during runtime.
-You can refer to [DeepModeling conda FAQ](https://docs.deepmodeling.com/faq/conda.html) for more information.
-:::
+> [!NOTE]
+> Note: The off-line packages and conda packages require the [GNU C Library](https://www.gnu.org/software/libc/) 2.17 or above. The GPU version requires [compatible NVIDIA driver](https://docs.nvidia.com/deploy/cuda-compatibility/index.html#minor-version-compatibility) to be installed in advance. It is possible to force conda to [override detection](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-virtual.html#overriding-detected-packages) when installation, but these requirements are still necessary during runtime.
+> You can refer to [DeepModeling conda FAQ](https://docs.deepmodeling.com/faq/conda.html) for more information.
 
-:::{note}
-Python 3.10 or above is required for Python interface.
-:::
+> [!NOTE]
+> Python 3.10 or above is required for Python interface.
 
 ## Install DeePMD-kit in 1s
 
@@ -57,15 +55,13 @@ Read [conda-forge FAQ](https://conda-forge.org/docs/user/tipsandtricks.html#inst
 
 ### Official channel (deprecated)
 
-::::{danger}
-
-:::{deprecated} 3.0.0
-The official channel has been deprecated since 3.0.0, due to the challenging work of building dependencies for [multiple backends](../backend.md).
-Old packages will still be available at https://conda.deepmodeling.com.
-Maintainers will build packages in the conda-forge organization together with other conda-forge members.
-:::
-
-::::
+> [!CAUTION]
+>
+> :::{deprecated} 3.0.0
+> The official channel has been deprecated since 3.0.0, due to the challenging work of building dependencies for [multiple backends](../backend.md).
+> Old packages will still be available at https://conda.deepmodeling.com.
+> Maintainers will build packages in the conda-forge organization together with other conda-forge members.
+> :::
 
 ## Install with docker
 
@@ -195,9 +191,8 @@ pip install deepmd-kit
 
 The supported platform includes Linux x86-64 and aarch64 with GNU C Library 2.28 or above, macOS x86-64 and arm64, and Windows x86-64.
 
-:::{Warning}
-If your platform is not supported, or you want to build against the installed backends, or you want to enable ROCM support, please [build from source](install-from-source.md).
-:::
+> [!WARNING]
+> If your platform is not supported, or you want to build against the installed backends, or you want to enable ROCM support, please [build from source](install-from-source.md).
 
 [The LAMMPS module](../third-party/lammps-command.md) and [the i-PI driver](../third-party/ipi.md) are provided on Linux and macOS for the TensorFlow, PyTorch, and JAX backend. The LAMMPS module loads the installed TensorFlow and/or PyTorch runtime libraries dynamically, so it does not require both backends to be installed. To install LAMMPS and/or i-PI, add `lmp` and/or `ipi` to extras:
 

diff --git a/doc/install/install-from-c-library.md b/doc/install/install-from-c-library.md
@@ -1,8 +1,7 @@
 # Install from pre-compiled C library {{ tensorflow_icon }} {{ pytorch_icon }} {{ jax_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}, JAX {{ jax_icon }}
 
 DeePMD-kit provides pre-compiled C library package (`libdeepmd_c.tar.gz`) in each [release](https://github.com/deepmodeling/deepmd-kit/releases). It can be used to build the [LAMMPS plugin](./install-lammps.md) and the [i-PI driver](./install-ipi.md), as well as many [third-party software packages](../third-party/out-of-deepmd-kit.md), without building TensorFlow and DeePMD-kit on one's own.
 It can be downloaded via the shell command:

diff --git a/doc/install/install-from-source.md b/doc/install/install-from-source.md
@@ -260,11 +260,10 @@ It will print the help information like
 
 ### Install horovod and mpi4py {{ tensorflow_icon }}
 
-:::{warning}
-Horovod has not released a new version for a long time.
-As of December 2025, the latest Horovod release does not support the latest TensorFlow versions.
-You can check the patches required to support the latest TensorFlow at [conda-forge/horovod-feedstock](https://github.com/conda-forge/horovod-feedstock/blob/main/recipe/meta.yaml).
-:::
+> [!WARNING]
+> Horovod has not released a new version for a long time.
+> As of December 2025, the latest Horovod release does not support the latest TensorFlow versions.
+> You can check the patches required to support the latest TensorFlow at [conda-forge/horovod-feedstock](https://github.com/conda-forge/horovod-feedstock/blob/main/recipe/meta.yaml).
 
 [Horovod](https://github.com/horovod/horovod) and [mpi4py](https://github.com/mpi4py/mpi4py) are used for parallel training. For better performance on GPU, please follow the tuning steps in [Horovod on GPU](https://github.com/horovod/horovod/blob/master/docs/gpus.rst).
 

diff --git a/doc/install/install-gromacs.md b/doc/install/install-gromacs.md
@@ -4,14 +4,12 @@ orphan: true
 
 # GROMACS patch was removed from DeePMD-kit
 
-::::{danger}
-
-:::{deprecated} v3.2.0
-The in-tree GROMACS patch was removed from the DeePMD-kit repository in v3.2.0 and is no longer maintained.
-
-For supported production workflows, use the official [LAMMPS interface](./install-lammps.md).
-
-If you need a GROMACS-based workflow, see the third-party overview in [Running MD with GROMACS](../third-party/gromacs.md) and [Interfaces out of DeePMD-kit](../third-party/out-of-deepmd-kit.md).
-:::
-
-::::
+> [!CAUTION]
+>
+> :::{deprecated} v3.2.0
+> The in-tree GROMACS patch was removed from the DeePMD-kit repository in v3.2.0 and is no longer maintained.
+>
+> For supported production workflows, use the official [LAMMPS interface](./install-lammps.md).
+>
+> If you need a GROMACS-based workflow, see the third-party overview in [Running MD with GROMACS](../third-party/gromacs.md) and [Interfaces out of DeePMD-kit](../third-party/out-of-deepmd-kit.md).
+> :::
diff --git a/doc/install/install-lammps.md b/doc/install/install-lammps.md
@@ -135,10 +135,9 @@ If everything works fine, you will end up with an executable `${deepmd_root}/bin
 ${deepmd_root}/bin/lmp -h
 ```
 
-:::{note}
-If `${tensorflow_root}`, `${deepmd_root}`, or the path to TensorFlow Python package if applicable is different from the prefix of LAMMPS, you need to append the library path to [`RUNPATH`](https://man7.org/linux/man-pages/man8/ld.so.8.html) of `liblammps.so`. For example, use patchelf >= 0.13
-
-```sh
-patchelf --add-rpath "${tensorflow_root}/lib" liblammps.so
-```
-:::
+> [!NOTE]
+> If `${tensorflow_root}`, `${deepmd_root}`, or the path to TensorFlow Python package if applicable is different from the prefix of LAMMPS, you need to append the library path to [`RUNPATH`](https://man7.org/linux/man-pages/man8/ld.so.8.html) of `liblammps.so`. For example, use patchelf >= 0.13
+>
+> ```sh
+> patchelf --add-rpath "${tensorflow_root}/lib" liblammps.so
+> ```
diff --git a/doc/model/change-bias.md b/doc/model/change-bias.md
@@ -1,8 +1,7 @@
 # Change the model output bias for trained model {{ tensorflow_icon }} {{ pytorch_icon }}
 
-:::{note}
-**Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}
-:::
+> [!NOTE]
+> **Supported backends**: TensorFlow {{ tensorflow_icon }}, PyTorch {{ pytorch_icon }}
 
 The output bias of a trained model typically originates from the statistical results of the training dataset.