From c5fa88e70f2f253e8c50a67188215be712eee5a8 Mon Sep 17 00:00:00 2001 From: "njzjz-bot (driven by OpenClaw (model: GLM-5))[bot]" <48687836+njzjz-bot@users.noreply.github.com> Date: Mon, 23 Feb 2026 01:22:48 +0000 Subject: [PATCH 1/5] docs: add formulas to atomic model classes Add mathematical formulas to atomic model class docstrings: - DPAtomicModel: descriptor + fitting pipeline - LinearEnergyAtomicModel: linear combination of models - PairTabAtomicModel: pairwise tabulated energy Follow numpydoc convention: parameters in class docstring. --- deepmd/dpmodel/atomic_model/dp_atomic_model.py | 12 ++++++++++++ deepmd/dpmodel/atomic_model/linear_atomic_model.py | 12 ++++++++++++ deepmd/dpmodel/atomic_model/pairtab_atomic_model.py | 9 +++++++++ 3 files changed, 33 insertions(+) diff --git a/deepmd/dpmodel/atomic_model/dp_atomic_model.py b/deepmd/dpmodel/atomic_model/dp_atomic_model.py index 0f5b12bc9c..b5340a5d08 100644 --- a/deepmd/dpmodel/atomic_model/dp_atomic_model.py +++ b/deepmd/dpmodel/atomic_model/dp_atomic_model.py @@ -28,6 +28,18 @@ class DPAtomicModel(BaseAtomicModel): """Model give atomic prediction of some physical property. + The atomic model computes atomic properties by first extracting a descriptor + from the atomic environment, then passing it through a fitting network: + + .. math:: + \mathcal{D}^i = \mathrm{Descriptor}(\mathbf{R}^i, \mathbf{R}_j, \mathrm{types}), + + .. math:: + \mathbf{y}^i = \mathrm{Fitting}(\mathcal{D}^i), + + where :math:`\mathcal{D}^i` is the descriptor for atom :math:`i`, and + :math:`\mathbf{y}^i` is the predicted atomic property (energy, dipole, etc.). + Parameters ---------- descriptor diff --git a/deepmd/dpmodel/atomic_model/linear_atomic_model.py b/deepmd/dpmodel/atomic_model/linear_atomic_model.py index b73dcb77fb..0308d8dba6 100644 --- a/deepmd/dpmodel/atomic_model/linear_atomic_model.py +++ b/deepmd/dpmodel/atomic_model/linear_atomic_model.py @@ -40,6 +40,18 @@ class LinearEnergyAtomicModel(BaseAtomicModel): """Linear model make linear combinations of several existing models. + The linear model combines predictions from multiple atomic models: + + .. math:: + E^i = \sum_{k=1}^{K} w_k \cdot E_k^i, + + where :math:`E_k^i` is the energy predicted by the :math:`k`-th sub-model + for atom :math:`i`, and :math:`w_k` is the corresponding weight. The weights + can be learned or manually specified. + + This is useful for combining different interaction types, e.g., DP + ZBL + for short-range repulsion, or DP + D3 for dispersion corrections. + Parameters ---------- models : list[DPAtomicModel or PairTabAtomicModel] diff --git a/deepmd/dpmodel/atomic_model/pairtab_atomic_model.py b/deepmd/dpmodel/atomic_model/pairtab_atomic_model.py index 6212696ddc..1fd2cc91d7 100644 --- a/deepmd/dpmodel/atomic_model/pairtab_atomic_model.py +++ b/deepmd/dpmodel/atomic_model/pairtab_atomic_model.py @@ -45,6 +45,15 @@ class PairTabAtomicModel(BaseAtomicModel): At this moment, the model does not smooth the energy at the cutoff radius, so one needs to make sure the energy has been smoothed to zero. + The pairwise energy is computed by table lookup and interpolation: + + .. math:: + E^i = \sum_{j \in \mathcal{N}(i)} E_{t_i, t_j}(r_{ij}), + + where :math:`E_{t_i, t_j}(r)` is the tabulated pairwise energy between atom types + :math:`t_i` and :math:`t_j` at distance :math:`r`, obtained via cubic spline + interpolation from the table data. + Parameters ---------- tab_file : str From db4cc8a79723a2a068dc7d79131164df3ca47db3 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 23 Feb 2026 02:22:29 +0000 Subject: [PATCH 2/5] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- deepmd/dpmodel/atomic_model/dp_atomic_model.py | 2 +- deepmd/dpmodel/atomic_model/linear_atomic_model.py | 2 +- deepmd/dpmodel/atomic_model/pairtab_atomic_model.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/deepmd/dpmodel/atomic_model/dp_atomic_model.py b/deepmd/dpmodel/atomic_model/dp_atomic_model.py index b5340a5d08..bddc139351 100644 --- a/deepmd/dpmodel/atomic_model/dp_atomic_model.py +++ b/deepmd/dpmodel/atomic_model/dp_atomic_model.py @@ -26,7 +26,7 @@ @BaseAtomicModel.register("standard") class DPAtomicModel(BaseAtomicModel): - """Model give atomic prediction of some physical property. + r"""Model give atomic prediction of some physical property. The atomic model computes atomic properties by first extracting a descriptor from the atomic environment, then passing it through a fitting network: diff --git a/deepmd/dpmodel/atomic_model/linear_atomic_model.py b/deepmd/dpmodel/atomic_model/linear_atomic_model.py index 0308d8dba6..afe87239d6 100644 --- a/deepmd/dpmodel/atomic_model/linear_atomic_model.py +++ b/deepmd/dpmodel/atomic_model/linear_atomic_model.py @@ -38,7 +38,7 @@ @BaseAtomicModel.register("linear") class LinearEnergyAtomicModel(BaseAtomicModel): - """Linear model make linear combinations of several existing models. + r"""Linear model make linear combinations of several existing models. The linear model combines predictions from multiple atomic models: diff --git a/deepmd/dpmodel/atomic_model/pairtab_atomic_model.py b/deepmd/dpmodel/atomic_model/pairtab_atomic_model.py index 1fd2cc91d7..d52b2a4a47 100644 --- a/deepmd/dpmodel/atomic_model/pairtab_atomic_model.py +++ b/deepmd/dpmodel/atomic_model/pairtab_atomic_model.py @@ -32,7 +32,7 @@ @BaseAtomicModel.register("pairtab") class PairTabAtomicModel(BaseAtomicModel): - """Pairwise tabulation energy model. + r"""Pairwise tabulation energy model. This model can be used to tabulate the pairwise energy between atoms for either short-range or long-range interactions, such as D3, LJ, ZBL, etc. It should not From 4bd11537e2f46a059ed0b9a79f35a348978089b1 Mon Sep 17 00:00:00 2001 From: "njzjz-bot (driven by OpenClaw (model: GLM-5))[bot]" <48687836+njzjz-bot@users.noreply.github.com> Date: Mon, 23 Feb 2026 03:52:26 +0000 Subject: [PATCH 3/5] docs: add 1/2 prefactor to pairtab energy formula The implementation applies 0.5 factor to avoid double-counting pairs. Update formula to E^i = 1/2 * sum E_{t_i,t_j}(r_ij). --- deepmd/dpmodel/atomic_model/pairtab_atomic_model.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/deepmd/dpmodel/atomic_model/pairtab_atomic_model.py b/deepmd/dpmodel/atomic_model/pairtab_atomic_model.py index d52b2a4a47..0e5049bd12 100644 --- a/deepmd/dpmodel/atomic_model/pairtab_atomic_model.py +++ b/deepmd/dpmodel/atomic_model/pairtab_atomic_model.py @@ -48,11 +48,12 @@ class PairTabAtomicModel(BaseAtomicModel): The pairwise energy is computed by table lookup and interpolation: .. math:: - E^i = \sum_{j \in \mathcal{N}(i)} E_{t_i, t_j}(r_{ij}), + E^i = \frac{1}{2} \sum_{j \in \mathcal{N}(i)} E_{t_i, t_j}(r_{ij}), where :math:`E_{t_i, t_j}(r)` is the tabulated pairwise energy between atom types :math:`t_i` and :math:`t_j` at distance :math:`r`, obtained via cubic spline - interpolation from the table data. + interpolation from the table data. The factor of :math:`\frac{1}{2}` avoids + double-counting of pairwise interactions. Parameters ---------- From da653adadf22c7054482aa149e742dd0df1911d7 Mon Sep 17 00:00:00 2001 From: "njzjz-bot (driven by OpenClaw (model: GLM-5))[bot]" <48687836+njzjz-bot@users.noreply.github.com> Date: Mon, 23 Feb 2026 04:50:14 +0000 Subject: [PATCH 4/5] docs: fix grammar - 'make' to 'makes' Fix subject-verb agreement: 'Linear model makes' --- deepmd/dpmodel/atomic_model/linear_atomic_model.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deepmd/dpmodel/atomic_model/linear_atomic_model.py b/deepmd/dpmodel/atomic_model/linear_atomic_model.py index afe87239d6..9b23d4d197 100644 --- a/deepmd/dpmodel/atomic_model/linear_atomic_model.py +++ b/deepmd/dpmodel/atomic_model/linear_atomic_model.py @@ -38,7 +38,7 @@ @BaseAtomicModel.register("linear") class LinearEnergyAtomicModel(BaseAtomicModel): - r"""Linear model make linear combinations of several existing models. + r"""Linear model makes linear combinations of several existing models. The linear model combines predictions from multiple atomic models: From f51f587f7978b547905a102906f5562489d1f3ca Mon Sep 17 00:00:00 2001 From: "njzjz-bot (driven by OpenClaw (model: GLM-5))[bot]" <48687836+njzjz-bot@users.noreply.github.com> Date: Mon, 23 Feb 2026 17:57:28 +0000 Subject: [PATCH 5/5] docs: fix atomic model formulas MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - dp_atomic_model: use α_j for atom types, D for descriptor, F for fitting - linear_atomic_model: remove incorrect statement about learnable weights --- deepmd/dpmodel/atomic_model/dp_atomic_model.py | 8 +++++--- deepmd/dpmodel/atomic_model/linear_atomic_model.py | 3 +-- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/deepmd/dpmodel/atomic_model/dp_atomic_model.py b/deepmd/dpmodel/atomic_model/dp_atomic_model.py index bddc139351..a6c71b0b85 100644 --- a/deepmd/dpmodel/atomic_model/dp_atomic_model.py +++ b/deepmd/dpmodel/atomic_model/dp_atomic_model.py @@ -32,12 +32,14 @@ class DPAtomicModel(BaseAtomicModel): from the atomic environment, then passing it through a fitting network: .. math:: - \mathcal{D}^i = \mathrm{Descriptor}(\mathbf{R}^i, \mathbf{R}_j, \mathrm{types}), + \mathcal{D}^i = \mathcal{D}(\mathbf{R}^i, \mathbf{R}_j, \alpha_j), .. math:: - \mathbf{y}^i = \mathrm{Fitting}(\mathcal{D}^i), + \mathbf{y}^i = \mathcal{F}(\mathcal{D}^i), - where :math:`\mathcal{D}^i` is the descriptor for atom :math:`i`, and + where :math:`\mathcal{D}^i` is the descriptor for atom :math:`i`, + :math:`\alpha_j` is the atom type of neighbor :math:`j`, + :math:`\mathcal{F}` is the fitting network, and :math:`\mathbf{y}^i` is the predicted atomic property (energy, dipole, etc.). Parameters diff --git a/deepmd/dpmodel/atomic_model/linear_atomic_model.py b/deepmd/dpmodel/atomic_model/linear_atomic_model.py index 9b23d4d197..77c64dff42 100644 --- a/deepmd/dpmodel/atomic_model/linear_atomic_model.py +++ b/deepmd/dpmodel/atomic_model/linear_atomic_model.py @@ -46,8 +46,7 @@ class LinearEnergyAtomicModel(BaseAtomicModel): E^i = \sum_{k=1}^{K} w_k \cdot E_k^i, where :math:`E_k^i` is the energy predicted by the :math:`k`-th sub-model - for atom :math:`i`, and :math:`w_k` is the corresponding weight. The weights - can be learned or manually specified. + for atom :math:`i`, and :math:`w_k` is the corresponding weight. This is useful for combining different interaction types, e.g., DP + ZBL for short-range repulsion, or DP + D3 for dispersion corrections.