From 310b324a61bfe5dcdffb10aebb1e02f5d063df88 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:08:50 +0000 Subject: [PATCH 1/7] docs: add formulas to model classes Add mathematical formulas to model class docstrings: - DPModelCommon: descriptor + fitting pipeline - SpinModel: virtual atom positions and torque conversion Follow numpydoc convention: parameters in class docstring. --- deepmd/dpmodel/model/dp_model.py | 17 +++++++++++++++++ deepmd/dpmodel/model/spin_model.py | 19 ++++++++++++++++++- 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/deepmd/dpmodel/model/dp_model.py b/deepmd/dpmodel/model/dp_model.py index 0dcf6358f9..07f0f22987 100644 --- a/deepmd/dpmodel/model/dp_model.py +++ b/deepmd/dpmodel/model/dp_model.py @@ -14,6 +14,23 @@ # use "class" to resolve "Variable not allowed in type expression" class DPModelCommon: + r"""Common methods for DP models. + + This class provides common functionality for DeepPot models, including + neighbor selection updates and fitting network access. + + The model prediction pipeline is: + + .. math:: + \mathcal{D} = \mathrm{Descriptor}(\mathbf{R}, \mathrm{types}), + + .. math:: + \mathbf{y} = \mathrm{Fitting}(\mathcal{D}), + + where :math:`\mathcal{D}` is the descriptor and :math:`\mathbf{y}` is the + predicted property (energy, dipole, polarizability, etc.). + """ + @classmethod def update_sel( cls, diff --git a/deepmd/dpmodel/model/spin_model.py b/deepmd/dpmodel/model/spin_model.py index 85e23df3cc..c5b1a89c7d 100644 --- a/deepmd/dpmodel/model/spin_model.py +++ b/deepmd/dpmodel/model/spin_model.py @@ -29,7 +29,24 @@ class SpinModel(NativeOP): - """A spin model wrapper, with spin input preprocess and output split.""" + """A spin model wrapper, with spin input preprocess and output split. + + This model extends a backbone DP model to handle magnetic spin degrees of freedom. + Virtual atoms are created at positions offset from real atoms by their spin vectors: + + .. math:: + \mathbf{r}_i^{\mathrm{virtual}} = \mathbf{r}_i^{\mathrm{real}} + s_i \cdot \boldsymbol{\sigma}_i, + + where :math:`s_i` is a scaling factor and :math:`\boldsymbol{\sigma}_i` is the spin vector. + + The model then computes interactions between real atoms, virtual atoms, and between + real and virtual atoms, enabling the prediction of spin-dependent properties. + + The output forces on virtual atoms are converted to magnetic torques: + + .. math:: + \boldsymbol{\tau}_i = \mathbf{F}_i^{\mathrm{virtual}} \times \boldsymbol{\sigma}_i. + """ def __init__( self, From 10166fc896af4cfcf56bb2175eaf1713d3c2d99d 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 04:11:08 +0000 Subject: [PATCH 2/7] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- deepmd/dpmodel/model/spin_model.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/deepmd/dpmodel/model/spin_model.py b/deepmd/dpmodel/model/spin_model.py index c5b1a89c7d..fde32a1eba 100644 --- a/deepmd/dpmodel/model/spin_model.py +++ b/deepmd/dpmodel/model/spin_model.py @@ -35,9 +35,9 @@ class SpinModel(NativeOP): Virtual atoms are created at positions offset from real atoms by their spin vectors: .. math:: - \mathbf{r}_i^{\mathrm{virtual}} = \mathbf{r}_i^{\mathrm{real}} + s_i \cdot \boldsymbol{\sigma}_i, + \\mathbf{r}_i^{\\mathrm{virtual}} = \\mathbf{r}_i^{\\mathrm{real}} + s_i \\cdot \boldsymbol{\\sigma}_i, - where :math:`s_i` is a scaling factor and :math:`\boldsymbol{\sigma}_i` is the spin vector. + where :math:`s_i` is a scaling factor and :math:`\boldsymbol{\\sigma}_i` is the spin vector. The model then computes interactions between real atoms, virtual atoms, and between real and virtual atoms, enabling the prediction of spin-dependent properties. @@ -45,7 +45,7 @@ class SpinModel(NativeOP): The output forces on virtual atoms are converted to magnetic torques: .. math:: - \boldsymbol{\tau}_i = \mathbf{F}_i^{\mathrm{virtual}} \times \boldsymbol{\sigma}_i. + \boldsymbol{\tau}_i = \\mathbf{F}_i^{\\mathrm{virtual}} \times \boldsymbol{\\sigma}_i. """ def __init__( From af2147d5425c07ed437739f6c736d8bca8cd1bde 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:22:15 +0000 Subject: [PATCH 3/7] fix: use r-string for docstring with backslashes D301: Use r""" if any backslashes in a docstring --- deepmd/dpmodel/model/spin_model.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deepmd/dpmodel/model/spin_model.py b/deepmd/dpmodel/model/spin_model.py index fde32a1eba..fa66f8a73a 100644 --- a/deepmd/dpmodel/model/spin_model.py +++ b/deepmd/dpmodel/model/spin_model.py @@ -29,7 +29,7 @@ class SpinModel(NativeOP): - """A spin model wrapper, with spin input preprocess and output split. + r"""A spin model wrapper, with spin input preprocess and output split. This model extends a backbone DP model to handle magnetic spin degrees of freedom. Virtual atoms are created at positions offset from real atoms by their spin vectors: From 09eae6d1a4ddccb327c7ea4b49ff84fecc72d02e 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 18:49:22 +0000 Subject: [PATCH 4/7] docs: correct DPModelCommon formula to describe reduction and differentiation Model layer sums atomic energies and computes forces/virials by differentiation, not descriptor+fitting pipeline. --- deepmd/dpmodel/model/dp_model.py | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/deepmd/dpmodel/model/dp_model.py b/deepmd/dpmodel/model/dp_model.py index 07f0f22987..bf3f31ebac 100644 --- a/deepmd/dpmodel/model/dp_model.py +++ b/deepmd/dpmodel/model/dp_model.py @@ -19,16 +19,26 @@ class DPModelCommon: This class provides common functionality for DeepPot models, including neighbor selection updates and fitting network access. - The model prediction pipeline is: + The model takes atomic predictions from the atomic model and computes + global properties by reduction and differentiation: + + **Reduction** (for reducible quantities like energy): + + .. math:: + E = \sum_{i=1}^{N} E^i, + + where :math:`E^i` is the atomic energy from the atomic model. + + **Differentiation** (for forces and virials): .. math:: - \mathcal{D} = \mathrm{Descriptor}(\mathbf{R}, \mathrm{types}), + \mathbf{F}_i = -\frac{\partial E}{\partial \mathbf{r}_i}, .. math:: - \mathbf{y} = \mathrm{Fitting}(\mathcal{D}), + \boldsymbol{\Xi} = -\sum_{i=1}^{N} \frac{\partial E^i}{\partial \mathbf{r}_i} \otimes \mathbf{r}_i, - where :math:`\mathcal{D}` is the descriptor and :math:`\mathbf{y}` is the - predicted property (energy, dipole, polarizability, etc.). + where :math:`\mathbf{F}_i` is the force on atom :math:`i` and + :math:`\boldsymbol{\Xi}` is the virial tensor. """ @classmethod From af51104ffb6d1b921af4f9545084f85d199edd51 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 19:06:10 +0000 Subject: [PATCH 5/7] docs: move energy reduction/differentiation formula to EnergyModel DPModelCommon is a generic base class. The energy-specific formulas for reduction (E = sum E^i) and differentiation (forces, virials) belong in EnergyModel. --- deepmd/dpmodel/model/dp_model.py | 21 --------------------- deepmd/dpmodel/model/ener_model.py | 23 +++++++++++++++++++++++ 2 files changed, 23 insertions(+), 21 deletions(-) diff --git a/deepmd/dpmodel/model/dp_model.py b/deepmd/dpmodel/model/dp_model.py index bf3f31ebac..b6db2272b7 100644 --- a/deepmd/dpmodel/model/dp_model.py +++ b/deepmd/dpmodel/model/dp_model.py @@ -18,27 +18,6 @@ class DPModelCommon: This class provides common functionality for DeepPot models, including neighbor selection updates and fitting network access. - - The model takes atomic predictions from the atomic model and computes - global properties by reduction and differentiation: - - **Reduction** (for reducible quantities like energy): - - .. math:: - E = \sum_{i=1}^{N} E^i, - - where :math:`E^i` is the atomic energy from the atomic model. - - **Differentiation** (for forces and virials): - - .. math:: - \mathbf{F}_i = -\frac{\partial E}{\partial \mathbf{r}_i}, - - .. math:: - \boldsymbol{\Xi} = -\sum_{i=1}^{N} \frac{\partial E^i}{\partial \mathbf{r}_i} \otimes \mathbf{r}_i, - - where :math:`\mathbf{F}_i` is the force on atom :math:`i` and - :math:`\boldsymbol{\Xi}` is the virial tensor. """ @classmethod diff --git a/deepmd/dpmodel/model/ener_model.py b/deepmd/dpmodel/model/ener_model.py index ac90d94fc5..37ead8458e 100644 --- a/deepmd/dpmodel/model/ener_model.py +++ b/deepmd/dpmodel/model/ener_model.py @@ -31,6 +31,29 @@ @BaseModel.register("ener") class EnergyModel(DPModelCommon, DPEnergyModel_): + r"""Energy model that predicts total energy and derived quantities. + + The model takes atomic energies from the atomic model and computes + global properties by reduction and differentiation: + + **Reduction** (total energy): + + .. math:: + E = \sum_{i=1}^{N} E^i, + + where :math:`E^i` is the atomic energy from the atomic model. + + **Differentiation** (forces and virials): + + .. math:: + \mathbf{F}_i = -\frac{\partial E}{\partial \mathbf{r}_i}, + + .. math:: + \boldsymbol{\Xi} = -\sum_{i=1}^{N} \frac{\partial E^i}{\partial \mathbf{r}_i} \otimes \mathbf{r}_i, + + where :math:`\mathbf{F}_i` is the force on atom :math:`i` and + :math:`\boldsymbol{\Xi}` is the virial tensor. + """ def __init__( self, *args: Any, From 83a6bd0d7d973675d6135e4de7088bcfe4cd381a 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 19:08:11 +0000 Subject: [PATCH 6/7] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- deepmd/dpmodel/model/ener_model.py | 1 + 1 file changed, 1 insertion(+) diff --git a/deepmd/dpmodel/model/ener_model.py b/deepmd/dpmodel/model/ener_model.py index 37ead8458e..127fd2fa17 100644 --- a/deepmd/dpmodel/model/ener_model.py +++ b/deepmd/dpmodel/model/ener_model.py @@ -54,6 +54,7 @@ class EnergyModel(DPModelCommon, DPEnergyModel_): where :math:`\mathbf{F}_i` is the force on atom :math:`i` and :math:`\boldsymbol{\Xi}` is the virial tensor. """ + def __init__( self, *args: Any, From 6ac195a29ae6c2fe9cb55485bb912039990773c5 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 21:39:32 +0000 Subject: [PATCH 7/7] docs: fix LaTeX backslashes and virial formula - spin_model: use single backslashes in raw string for LaTeX - ener_model: virial formula uses total energy E, not per-atom E^i --- deepmd/dpmodel/model/ener_model.py | 3 ++- deepmd/dpmodel/model/spin_model.py | 6 +++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/deepmd/dpmodel/model/ener_model.py b/deepmd/dpmodel/model/ener_model.py index 127fd2fa17..85fe98c7d8 100644 --- a/deepmd/dpmodel/model/ener_model.py +++ b/deepmd/dpmodel/model/ener_model.py @@ -49,7 +49,8 @@ class EnergyModel(DPModelCommon, DPEnergyModel_): \mathbf{F}_i = -\frac{\partial E}{\partial \mathbf{r}_i}, .. math:: - \boldsymbol{\Xi} = -\sum_{i=1}^{N} \frac{\partial E^i}{\partial \mathbf{r}_i} \otimes \mathbf{r}_i, + \boldsymbol{\Xi} = -\sum_{i=1}^{N} \frac{\partial E}{\partial \mathbf{r}_i} \otimes \mathbf{r}_i + = \sum_{i=1}^{N} \mathbf{r}_i \otimes \mathbf{F}_i, where :math:`\mathbf{F}_i` is the force on atom :math:`i` and :math:`\boldsymbol{\Xi}` is the virial tensor. diff --git a/deepmd/dpmodel/model/spin_model.py b/deepmd/dpmodel/model/spin_model.py index fa66f8a73a..e62442887c 100644 --- a/deepmd/dpmodel/model/spin_model.py +++ b/deepmd/dpmodel/model/spin_model.py @@ -35,9 +35,9 @@ class SpinModel(NativeOP): Virtual atoms are created at positions offset from real atoms by their spin vectors: .. math:: - \\mathbf{r}_i^{\\mathrm{virtual}} = \\mathbf{r}_i^{\\mathrm{real}} + s_i \\cdot \boldsymbol{\\sigma}_i, + \mathbf{r}_i^{\mathrm{virtual}} = \mathbf{r}_i^{\mathrm{real}} + s_i \cdot \boldsymbol{\sigma}_i, - where :math:`s_i` is a scaling factor and :math:`\boldsymbol{\\sigma}_i` is the spin vector. + where :math:`s_i` is a scaling factor and :math:`\boldsymbol{\sigma}_i` is the spin vector. The model then computes interactions between real atoms, virtual atoms, and between real and virtual atoms, enabling the prediction of spin-dependent properties. @@ -45,7 +45,7 @@ class SpinModel(NativeOP): The output forces on virtual atoms are converted to magnetic torques: .. math:: - \boldsymbol{\tau}_i = \\mathbf{F}_i^{\\mathrm{virtual}} \times \boldsymbol{\\sigma}_i. + \boldsymbol{\tau}_i = \mathbf{F}_i^{\mathrm{virtual}} \times \boldsymbol{\sigma}_i. """ def __init__(