docs: add mathematical formulas to model classes

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,

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,