docs: add mathematical formulas to atomic model classes

deepmd/dpmodel/atomic_model/dp_atomic_model.py

@@ -26,7 +26,21 @@
 
 @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:
+
+    .. math::
+        \mathcal{D}^i = \mathcal{D}(\mathbf{R}^i, \mathbf{R}_j, \alpha_j),
+
+    .. math::
+        \mathbf{y}^i = \mathcal{F}(\mathcal{D}^i),
+
+    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
     ----------

deepmd/dpmodel/atomic_model/linear_atomic_model.py

@@ -38,7 +38,18 @@
 
 @BaseAtomicModel.register("linear")
 class LinearEnergyAtomicModel(BaseAtomicModel):
-    """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:
+
+    .. 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.
+
+    This is useful for combining different interaction types, e.g., DP + ZBL
+    for short-range repulsion, or DP + D3 for dispersion corrections.
 
     Parameters
     ----------

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
@@ -45,6 +45,16 @@ 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 = \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. The factor of :math:`\frac{1}{2}` avoids
+    double-counting of pairwise interactions.
+
     Parameters
     ----------
     tab_file : str