Skip to content

Commit bf982ab

Browse files
authored
docs: add mathematical formulas to fitting classes (#5256)
## Summary Add detailed mathematical formulas to fitting class docstrings following numpydoc convention. ## Changes Added formulas to the following classes: - **DipoleFitting**: Dipole computation from rotation matrix - Formula: μ = M · R where M is fitting network output and R is rotation matrix - **PolarFitting**: Polarizability tensor with diagonal/full fitting modes - Diagonal fitting: α = R^T · diag(p) · R - Full matrix fitting: α = R^T · P · R ## Convention Following numpydoc convention, parameters are documented in class docstrings, not in `__init__` docstrings. ## Statistics - 2 files changed - 41 insertions(+) - 1 deletion(-) Authored by OpenClaw (model: GLM-5) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Expanded mathematical documentation for dipole computation from model outputs and rotation matrices; clarified notation and step-by-step calculations. * Added detailed explanations of polarizability tensor fitting for both diagonal and full-matrix approaches, including how rotation information integrates with network outputs. * Clarified assumptions and computation flow; no functional behavior changes. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
1 parent 43b5809 commit bf982ab

2 files changed

Lines changed: 47 additions & 1 deletion

File tree

deepmd/dpmodel/fitting/dipole_fitting.py

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,24 @@
3434
@BaseFitting.register("dipole")
3535
@fitting_check_output
3636
class DipoleFitting(GeneralFitting):
37-
r"""Fitting rotationally equivariant diploe of the system.
37+
r"""Fitting rotationally equivariant dipole of the system.
38+
39+
The dipole :math:`\boldsymbol{\mu}` is computed from the fitting network output
40+
and the rotation matrix:
41+
42+
.. math::
43+
\boldsymbol{\mu}^i = \mathbf{M}^i \cdot \mathbf{R}^i,
44+
45+
where :math:`\mathbf{M}^i \in \mathbb{R}^{1 \times m_1}` is the output of the fitting
46+
network for atom :math:`i`, :math:`\mathbf{R}^i \in \mathbb{R}^{m_1 \times 3}` is
47+
the rotation matrix from the descriptor, and :math:`m_1` is the embedding width
48+
(the dimension of the rotation matrix). The fitting network is:
49+
50+
.. math::
51+
\mathbf{M}^i = \mathcal{L}^{(n)} \circ \mathcal{L}^{(n-1)} \circ \cdots \circ \mathcal{L}^{(0)}(\mathcal{D}^i),
52+
53+
where :math:`\mathcal{D}^i` is the descriptor and each layer :math:`\mathcal{L}^{(k)}`
54+
is a fully connected layer with an activation function.
3855
3956
Parameters
4057
----------

deepmd/dpmodel/fitting/polarizability_fitting.py

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,35 @@
4444
class PolarFitting(GeneralFitting):
4545
r"""Fitting rotationally equivariant polarizability of the system.
4646
47+
The polarizability tensor :math:`\boldsymbol{\alpha} \in \mathbb{R}^{3 \times 3}` is
48+
computed from the fitting network output and the rotation matrix
49+
:math:`\mathbf{R}^i \in \mathbb{R}^{m_1 \times 3}` from the descriptor,
50+
where :math:`m_1` is the embedding width (the dimension of the rotation matrix):
51+
52+
**Diagonal fitting** (when `fit_diag=True`):
53+
54+
.. math::
55+
\boldsymbol{\alpha}^i = \mathbf{R}^{i,T} \cdot \mathrm{diag}(\mathbf{p}^i) \cdot \mathbf{R}^i,
56+
57+
where :math:`\mathbf{p}^i \in \mathbb{R}^{m_1}` is the diagonal elements of the
58+
local-frame polarizability predicted by the fitting network.
59+
60+
**Full matrix fitting** (when `fit_diag=False`):
61+
62+
.. math::
63+
\boldsymbol{\alpha}^i = \mathbf{R}^{i,T} \cdot \mathbf{P}^i \cdot \mathbf{R}^i,
64+
65+
where :math:`\hat{\mathbf{P}}^i \in \mathbb{R}^{m_1 \times m_1}` is the raw output of
66+
the fitting network, and :math:`\mathbf{P}^i = \frac{1}{2}(\hat{\mathbf{P}}^i + \hat{\mathbf{P}}^{i,T})`
67+
is the symmetrized version. Since :math:`\mathbf{P}^i` is symmetric, the resulting
68+
:math:`\boldsymbol{\alpha}^i` is guaranteed to be a symmetric tensor (matrix products
69+
of the form :math:`A^T S A` preserve symmetry).
70+
71+
The fitting network is:
72+
73+
.. math::
74+
\mathbf{p}^i \text{ (or } \mathbf{P}^i) = \mathcal{L}^{(n)} \circ \cdots \circ \mathcal{L}^{(0)}(\mathcal{D}^i).
75+
4776
Parameters
4877
----------
4978
ntypes

0 commit comments

Comments
 (0)