separate deepspin pair style

deepmodeling · Nov 19, 2024 · faab03e · faab03e
1 parent bf699c2
commit faab03e
Showing 1 changed file with 86 additions and 14 deletions.
diff --git a/doc/third-party/lammps-command.md b/doc/third-party/lammps-command.md
@@ -37,12 +37,10 @@ where `$deepmd_root` is the directory to [install C++ interface](../install/inst
 
 The built-in mode doesn't need this step.
 
-## pair_styles `deepmd` and `deepspin`
+## pair_style `deepmd`
 
-The DeePMD-kit package provides two pair styles: `deepmd` and `deepspin`.
-The `deepmd` pair style is intended for traditional simulations involving interactions between atoms without spin,
-whereas the `deepspin` pair style is specifically designed for simulations within systems that include spin.
-For further details, please refer to the examples [`deepmd`](../../examples/water/lmp/in.lammps) and [`deepspin`](../../examples/spin/lmp/in.force).
+The DeePMD-kit package provides the pair_style `deepmd`, which is intended for traditional simulations involving interactions between atoms without spin.
+For further details, please refer to the examples [`deepmd`](../../examples/water/lmp/in.lammps).
 
 ```lammps
 pair_style deepmd models ... keyword value ...
@@ -69,8 +67,7 @@ pair_style deepmd models ... keyword value ...
     <i>relative</i> value = level
         level = The level parameter for computing the relative model deviation of the force
     <i>relative_v</i> value = level
-        level = The level parameter for computing the relative model deviation of the virial.
-        (Note: the virial is not currently supported in spin models.)
+        level = The level parameter for computing the relative model deviation of the virial
     <i>aparam</i> value = parameters
         parameters = one or more atomic parameters of each atom required for model evaluation
     <i>ttm</i> value = id
@@ -91,26 +88,23 @@ compute    TEMP all temp
 
 pair_style deepmd ener.pb aparam_from_compute 1
 compute    1 all ke/atom
-
-pair_style deepspin spin.pb
-pair_style deepspin spin_0.pb spin_1.pb spin_2.pb out_file md.out out_freq 100
 ```
 
 ### Description
 
 Evaluate the interaction of the system by using [Deep Potential][DP] or [Deep Potential Smooth Edition][DP-SE]. It is noticed that deep potential is not a "pairwise" interaction, but a multi-body interaction.
 
-These two pair styles take the deep potential or deep spin models defined in model files that usually have .pb/.pth/.savedmodel extensions. The model can be trained and frozen from multiple backends by package [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit), which can have either double or single float precision interface.
+This pair style takes the deep potential defined in a model file that usually has .pb/.pth/.savedmodel extensions. The model can be trained and frozen from multiple backends by package [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit), which can have either double or single float precision interface.
 
-The model deviation evaluates the consistency of the force predictions from multiple models. By default, only the maximal, minimal and average model deviations are output. If the `atomic` key is set, the model deviation of force prediction will be output for each atom. For spin models, this includes both force and magnetic force predictions.
+The model deviation evaluates the consistency of the force predictions from multiple models. By default, only the maximal, minimal and average model deviations are output. If the key `atomic` is set, then the model deviation of force prediction of each atom will be output.
 The unit follows [LAMMPS units](#units) and the [scale factor](https://docs.lammps.org/pair_hybrid.html) is not applied.
 
 By default, the model deviation is output in absolute value. If the keyword `relative` is set, then the relative model deviation of the force will be output, including values output by the keyword `atomic`. The relative model deviation of the force on atom $i$ is defined by
 
 $$E_{f_i}=\frac{\left|D_{f_i}\right|}{\left|f_i\right|+l}$$
 
 where $D_{f_i}$ is the absolute model deviation of the force on atom $i$, $f_i$ is the norm of the force and $l$ is provided as the parameter of the keyword `relative`.
-If the keyword `relative_v` is set in pair style `deepmd`, then the relative model deviation of the virial will be output instead of the absolute value, with the same definition of that of the force:
+If the keyword `relative_v` is set, then the relative model deviation of the virial will be output instead of the absolute value, with the same definition of that of the force:
 
 $$E_{v_i}=\frac{\left|D_{v_i}\right|}{\left|v_i\right|+l}$$
 
@@ -125,9 +119,86 @@ If atom names are not set in the `pair_coeff` command, the training parameter {r
 If a mapping value is specified as `NULL`, the mapping is not performed. This can be used when a deepmd potential is used as part of the hybrid pair style. The `NULL` values are placeholders for atom types that will be used with other potentials.
 If the training parameter {ref}`type_map <model/type_map>` is not set, atom names in the `pair_coeff` command cannot be set. In this case, atom type indexes in [`type.raw`](../data/system.md) (integers from 0 to Ntypes-1) will map to LAMMPS atom types.
 
+For systems involving spin, please utilize the `deepspin` pair style as demonstrated [below](#pair_style-deepspin).
+
+### Restrictions
+
+- The `deepmd` pair style is provided in the USER-DEEPMD package, which is compiled from the DeePMD-kit, visit the [DeePMD-kit website](https://github.com/deepmodeling/deepmd-kit) for more information.
+
+## pair_style `deepspin`
+
+The DeePMD-kit package provides the pair_style `deepspin`, which is specifically designed for simulations within systems that include spin.
+For further details, please refer to the examples [`deepspin`](../../examples/spin/lmp/in.force).
+
+```lammps
+pair_style deepspin models ... keyword value ...
+```
+
+- deepspin = style of this pair_style
+- models = frozen model(s) to compute the interaction.
+  If multiple models are provided, then only the first model serves to provide energy, force and magnetic force prediction for each timestep of molecular dynamics,
+  and the model deviation will be computed among all models every `out_freq` timesteps.
+- keyword = _out_file_ or _out_freq_ or _fparam_ or _fparam_from_compute_ or _aparam_from_compute_ or _atomic_ or _relative or \_aparam_ or _ttm_
+
+:::{note}
+Please note that the virial and atomic virial are not currently supported in spin models.
+:::
+
+<pre>
+    <i>out_file</i> value = filename
+        filename = The file name for the model deviation output. Default is model_devi.out
+    <i>out_freq</i> value = freq
+        freq = Frequency for the model deviation output. Default is 100.
+    <i>fparam</i> value = parameters
+        parameters = one or more frame parameters required for model evaluation.
+    <i>fparam_from_compute</i> value = id
+        id = compute id used to update the frame parameter.
+    <i>aparam_from_compute</i> value = id
+        id = compute id used to update the atom parameter.
+    <i>atomic</i> = no value is required.
+        If this keyword is set, the force and magnetic force model deviation of each atom will be output.
+    <i>relative</i> value = level
+        level = The level parameter for computing the relative model deviation of the force and magnetic force
+    <i>aparam</i> value = parameters
+        parameters = one or more atomic parameters of each atom required for model evaluation
+    <i>ttm</i> value = id
+        id = fix ID of fix ttm
+</pre>
+
+### Examples
+
+```lammps
+pair_style deepspin graph.pb
+pair_style deepspin graph.pb fparam 1.2
+pair_style deepspin graph_0.pb graph_1.pb graph_2.pb out_file md.out out_freq 10 atomic relative 1.0
+pair_style deepspin graph_0.pb graph_1.pth out_file md.out out_freq 100
+pair_coeff * * Ni O
+
+pair_style deepspin cp.pb fparam_from_compute TEMP
+compute    TEMP all temp
+
+pair_style deepspin spin.pb aparam_from_compute 1
+compute    1 all ke/atom
+```
+
+### Description
+
+Evaluate the interaction of the system with spin by using [DeepSPIN][DPSPIN] models. It is noticed that deep spin model is not a "pairwise" interaction, but a multi-body interaction.
+
+This pair style takes the deep spin model defined in a model file that usually has .pb/.pth/.savedmodel extensions. The model can be trained and frozen from multiple backends by package [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit), which can have either double or single float precision interface.
+
+The model deviation evaluates the consistency of the force and magnetic force predictions from multiple models. By default, only the maximal, minimal and average model deviations are output. If the key `atomic` is set, then the model deviation of force and magnetic force prediction of each atom will be output.
+The unit follows [LAMMPS units](#units) and the [scale factor](https://docs.lammps.org/pair_hybrid.html) is not applied.
+
+Other settings and output for this pair style is the same as `deepmd` pair style, please see the detailed description [above](#pair_style-deepmd).
+
+:::{note}
+Please note that the virial and atomic virial are not currently supported in spin models.
+:::
+
 ### Restrictions
 
-- The `deepmd` and `deepspin` pair styles are provided in the USER-DEEPMD package, which is compiled from the DeePMD-kit, visit the [DeePMD-kit website](https://github.com/deepmodeling/deepmd-kit) for more information.
+- The `deepspin` pair style is provided in the USER-DEEPMD package, which is compiled from the DeePMD-kit, visit the [DeePMD-kit website](https://github.com/deepmodeling/deepmd-kit) for more information.
 
 ## Compute tensorial properties
 
@@ -236,3 +307,4 @@ If you use these features please cite [D. Tisi, L. Zhang, R. Bertossa, H. Wang,
 
 [DP]: https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.120.143001
 [DP-SE]: https://dl.acm.org/doi/10.5555/3327345.3327356
+[DPSPIN]: https://doi.org/10.1103/PhysRevB.110.064427