From bf699c2673d6e7610ff3f900c7cf23e0b029ef8a Mon Sep 17 00:00:00 2001 From: Duo <50307526+iProzd@users.noreply.github.com> Date: Mon, 18 Nov 2024 20:59:57 +0800 Subject: [PATCH] doc: update spin doc --- doc/model/train-energy-spin.md | 4 ++++ doc/third-party/lammps-command.md | 23 ++++++++++++++--------- examples/spin/lmp/in.force | 2 +- 3 files changed, 19 insertions(+), 10 deletions(-) diff --git a/doc/model/train-energy-spin.md b/doc/model/train-energy-spin.md index eda4ffa835..98e2b603da 100644 --- a/doc/model/train-energy-spin.md +++ b/doc/model/train-energy-spin.md @@ -79,6 +79,10 @@ $$L = p_e L_e + p_{fr} L_{fr} + p_{fm} L_{fm} + p_v L_v$$ where $L_e$, $L_{fr}$, $L_{fm}$ and $L_v$ denote the loss in energy, atomic force, magnatic force and virial, respectively. $p_e$, $p_{fr}$, $p_{fm}$ and $p_v$ give the prefactors of the energy, atomic force, magnatic force and virial losses. +:::{note} +Please note that the virial and atomic virial are not currently supported in spin models. +::: + The prefectors may not be a constant, rather it changes linearly with the learning rate. Taking the atomic force prefactor for example, at training step $t$, it is given by $$p_{fr}(t) = p_{fr}^0 \frac{ \alpha(t) }{ \alpha(0) } + p_{fr}^\infty ( 1 - \frac{ \alpha(t) }{ \alpha(0) })$$ diff --git a/doc/third-party/lammps-command.md b/doc/third-party/lammps-command.md index 4af3fe5096..11df6feac1 100644 --- a/doc/third-party/lammps-command.md +++ b/doc/third-party/lammps-command.md @@ -37,9 +37,12 @@ where `$deepmd_root` is the directory to [install C++ interface](../install/inst The built-in mode doesn't need this step. -## pair_style `deepmd` +## pair_styles `deepmd` and `deepspin` -The DeePMD-kit package provides the 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). ```lammps pair_style deepmd models ... keyword value ... @@ -66,7 +69,8 @@ pair_style deepmd models ... keyword value ... relative value = level level = The level parameter for computing the relative model deviation of the force relative_v value = level - level = The level parameter for computing the relative model deviation of the virial + level = The level parameter for computing the relative model deviation of the virial. + (Note: the virial is not currently supported in spin models.) aparam value = parameters parameters = one or more atomic parameters of each atom required for model evaluation ttm value = id @@ -87,15 +91,18 @@ 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. -This pair style takes the deep potential defined in a model file that usually has the .pb extension. The model can be trained and frozen by package [DeePMD-kit](https://github.com/deepmodeling/deepmd-kit), which can have either double or single float precision interface. +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. -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 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 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 @@ -103,7 +110,7 @@ By default, the model deviation is output in absolute value. If the keyword `rel $$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, 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 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: $$E_{v_i}=\frac{\left|D_{v_i}\right|}{\left|v_i\right|+l}$$ @@ -118,11 +125,9 @@ 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 ` 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. -Spin is specified by keywords `virtual_len` and `spin_norm`. If the keyword `virtual_len` is set, the distance between virtual atom and its corresponding real atom for each type of magnetic atoms will be fed to the model as the spin parameters. If the keyword `spin_norm` is set, the magnitude of the magnetic moment for each type of magnetic atoms will be fed to the model as the spin parameters. - ### 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. +- 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. ## Compute tensorial properties diff --git a/examples/spin/lmp/in.force b/examples/spin/lmp/in.force index 5421cd517b..0eb146408d 100644 --- a/examples/spin/lmp/in.force +++ b/examples/spin/lmp/in.force @@ -6,7 +6,7 @@ atom_modify map array box tilt large read_data init.data -pair_style deepmd model.pb virtual_len 0.4 spin_norm 1.2737 +pair_style deepspin model.pb pair_coeff * * neighbor 0.1 bin