4.10. Fit spin energy #
Note
Supported backends: TensorFlow , PyTorch , DP
To train a model that takes additional spin information as input, you only need to modify the following sections to define the spin-specific settings, keeping other sections the same as the normal energy model’s input script.
Warning
Note that when adding spin into the model, there will be some implicit modifications automatically done by the program:
In the TensorFlow backend, the
se_e2_a
descriptor will treat those atom types with spin as new (virtual) types, and duplicate their corresponding selected numbers of neighbors (sel) from their real atom types.In the PyTorch backend, if spin settings are added, all the types (with or without spin) will have their virtual types. The
se_e2_a
descriptor will thus double the sel list, while in other descriptors with mixed types (such asdpa1
ordpa2
), the sel number will not be changed for clarity. If you are using descriptors with mixed types, to achieve better performance, you should manually extend your sel number (maybe double) depending on the balance between performance and efficiency.
4.10.1. Spin#
The spin settings are given by the spin section, which sets the magnetism for each type of atoms as described in the following sections.
Note
Note that the construction of spin settings is different between TensorFlow and PyTorch/DP.
4.10.1.1. Spin settings in TensorFlow#
The implementation in TensorFlow only supports se_e2_a
descriptor. See examples in $deepmd_source_dir/examples/spin/se_e2_a/input_tf.json
, the spin section is defined as the following:
"spin" : {
"use_spin": [true, false],
"virtual_len": [0.4],
"spin_norm": [1.2737],
},
use_spin is a list of boolean values indicating whether to use atomic spin for each atom type. True for spin and False for not. The index of this option matches option
type_map <model/type_map>
.virtual_len specifies the distance between virtual atom and the belonging real atom.
spin_norm gives the magnitude of the magnetic moment for each magnatic atom.
4.10.1.2. Spin settings in PyTorch/DP#
In PyTorch/DP, the spin implementation is more flexible and so far supports the following descriptors:
se_e2_a
dpa1
(se_atten
)dpa2
See se_e2_a
examples in $deepmd_source_dir/examples/spin/se_e2_a/input_torch.json
, the spin section is defined as the following with a much more clear interface:
"spin": {
"use_spin": [true, false],
"virtual_scale": [0.3140]
},
use_spin is a list of boolean values indicating whether to use atomic spin for each atom type, or a list of type indexes that use atomic spin. The index of this option matches option
type_map <model/type_map>
.virtual_len defines the scaling factor to determine the virtual distance between a virtual atom representing spin and its corresponding real atom for each atom type with spin. This factor is defined as the virtual distance divided by the magnitude of atomic spin for each atom type with spin. The virtual coordinate is defined as the real coordinate plus spin * virtual_scale. List of float values with shape of
ntypes
orntypes_spin
or one single float value for all types, only used when use_spin is True for each atom type.
Note
It should be noted that the spin models in PyTorch/DP are capable of addressing scenarios where the spin approaches zero (indicating the virtual atom is in close proximity to the real atom) by adjusting the non-zero env_protection parameter within the descriptor. This parameter is set to 0.01 by default in the spin model. It appears that a value of 0.01 is generally sufficient for maintaining model stability. For systems with nearly zero spin, users can also consider tuning this parameter to potentially enhance stability.
4.10.2. Spin Loss#
The spin loss function \(L\) for training energy is given by
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
where \(\alpha(t)\) denotes the learning rate at step \(t\). \(p_{fr}^0\) and \(p_{fr}^\infty\) specifies the \(p_f\) at the start of the training and at the limit of \(t \to \infty\) (set by start_pref_fr and limit_pref_f, respectively), i.e.
The loss section in the input.json
is
"loss" :{
"type": "ener_spin",
"start_pref_e": 0.02,
"limit_pref_e": 1,
"start_pref_fr": 1000,
"limit_pref_fr": 1.0,
"start_pref_fm": 10000,
"limit_pref_fm": 10.0,
"start_pref_v": 0,
"limit_pref_v": 0,
},
The options start_pref_e, limit_pref_e, start_pref_fr, limit_pref_fm, start_pref_v and limit_pref_v determine the start and limit prefactors of energy, atomic force, magnatic force and virial, respectively.
If one does not want to train with virial, then he/she may set the virial prefactors start_pref_v and limit_pref_v to 0.
4.10.3. Data format#
Note
Note that the spin data format is different between TensorFlow and PyTorch/DP.
4.10.3.1. Spin data format in TensorFlow#
In the TensorFlow backend, the spin system data format may contain the following files:
type.raw
set.*/box.npy
set.*/coord.npy
set.*/energy.npy
set.*/force.npy
This system contains Nframes
frames with the same atom number Natoms
and magnetic atom number Nspins
, the total number of element and virtual types contained in all frames is Ntypes
. The box
and energy
files are the same as those in standard formats. The type
file contains the types of both real atoms and virtual atoms. In coord
and force
files, virtual atomic coordinates are integrated with real atomic coordinates, and magnetic forces are combined with atomic forces. Specifically, magnetic forces are obtained from DeltaSpin and virtual atomic coordinates are given by:
where \(\bm{R}_{i^p}\), \(\bm{R}_i\), and \(\bm{S}_i\) denote the virtual atomic coordinate, atomic coordinate and spin, respectively. \(\eta_{\zeta_i}\) and \(\mu_{\vert \bm{S}_i \vert}\) correspond to the virtual_len
and spin_norm
defined in spin settings.
We list the details about spin system data format in TensorFlow backend:
ID | Property | Raw file | Unit | Shape | Description |
---|---|---|---|---|---|
type | Atom type indexes | type.raw | \ | Natoms + Nspins | Integers that start with 0. The first |
coord | Coordinates | coord.raw | Å | Nframes * (Natoms + Nspins) * 3 | The first |
box | Boxes | box.raw | Å | Nframes * 3 * 3 | in the order |
energy | Frame energies | energy.raw | eV | Nframes | |
force | Atomic and magnetic forces | force.raw | eV/Å | Nframes * (Natoms + Nspins) * 3 | The first |
4.10.3.2. Spin data format in PyTorch/DP#
In the PyTorch backend, spin and magnetic forces are listed in separate files, and the data format may contain the following files:
type.raw
set.*/box.npy
set.*/coord.npy
set.*/spin.npy
set.*/energy.npy
set.*/force.npy
set.*/force_mag.npy
This system contains Nframes
frames with the same atom number Natoms
, the total number of element contained in all frames is Ntypes
. Most files are the same as those in standard formats, here we only list the distinct ones:
ID | Property | Raw file | Unit | Shape | Description |
---|---|---|---|---|---|
spin | Magnetic moments | spin.raw | \(\mu_B\) | Nframes * Natoms * 3 | Spin for magnetic atoms and zero for non-magnetic atoms. |
magnetic force | Magnetic forces | force_mag.raw | eV/Å | Nframes * Natoms * 3 | Magnetic forces for magnetic atoms and zero for non-magnetic atoms. |