Spin potential

NEP_Spin extends the NEP4 formalism to a local energy surface that depends on both atomic positions and Cartesian spin vectors. The total energy is the only learned scalar output. Atomic forces, virials, magnetic forces, and spin torques are derivatives of this same energy and are not produced by independent response networks.

The current format uses nep, format_version 1, and model nep_spin with spin_version 1 and named parameter and scaler blocks. It uses the order/compression (O/C) descriptor described below. An optional zbl field adds a spin-independent universal ZBL term. Flexible ZBL (zbl 0 0) is not supported. spin_version identifies the descriptor and parameter-layout contract, independently of the file syntax version and spin_order.

Every spin_cutoff value must be positive and no larger than the ordinary NEP radial cutoff. This constraint applies to both training input and model files; different spin cutoffs per atom type are supported within this bound.

Energy model

For atom \(i\), the ordinary structural descriptor \(\boldsymbol{q}^{i,\mathrm{str}}\) is concatenated with a magnetic descriptor \(\boldsymbol{q}^{i,\mathrm{spin}}\):

\[\boldsymbol{q}^{i} = \boldsymbol{q}^{i,\mathrm{str}} \mathbin{\|} \boldsymbol{q}^{i,\mathrm{spin}}.\]

After componentwise scaling, this vector enters the same one-hidden-layer, element-dependent neural network used by ordinary NEP4. The total energy is

\[U(\{\boldsymbol{r}_i,\boldsymbol{s}_i\}) = \sum_i \left[ U_i(\boldsymbol{q}^{i}) + E^0_{Z_i} \right] + U_\mathrm{ZBL},\]

where \(\boldsymbol{r}_i\) is the position, \(\boldsymbol{s}_i\) is a Cartesian magnetic-moment vector in Bohr magnetons (muB), \(Z_i\) denotes the atom type, and \(E^0_{Z_i}\) is a fitted per-type energy baseline. The ZBL term is present when ZBL is enabled and contains no spin dependence. The reference energies use the shared energy_reference convention.

This architecture allows the nonlinear network to combine structural and magnetic coordinates. Therefore, spin_order describes the hierarchy of primitive magnetic contractions supplied to the network; it is not the body order of the final energy.

Spin3 radial channels

Let

\[\boldsymbol{e}_{ij} = \frac{\boldsymbol{r}_j-\boldsymbol{r}_i}{r_{ij}}\]

be the minimum-image unit vector from center atom \(i\) to neighbor \(j\). For each compressed radial channel \(c=1,\ldots,C\), Spin3 forms the type-dependent edge weight

\[w^i_{jc} = \sum_{k=0}^{8} c^{Z_i Z_j}_{ck} f_k(r_{ij}),\]

where

\[f_k(r) = \frac{1}{2}\left[ T_k\left(2(r/r_\mathrm{c}^{\mathrm{spin}}-1)^2-1\right)+1 \right] f_\mathrm{c}(r)\]

and

\[\begin{split}f_\mathrm{c}(r) = \begin{cases} \frac{1}{2}\left[1+\cos(\pi r/r_\mathrm{c}^{\mathrm{spin}})\right], & r\leq r_\mathrm{c}^{\mathrm{spin}},\\ 0, & r>r_\mathrm{c}^{\mathrm{spin}}. \end{cases}\end{split}\]

Thus spin_compress controls a shared latent radial rank rather than selecting individual Hamiltonian terms. All contraction families use the same \(C\) radial channels.

Canonical edge-moment bank

Spin3 organizes each neighbor edge into a canonical collection of scalar, vector, rank-2, and product-tensor objects. Define the symmetric traceless product

\[\mathcal{Q}(\boldsymbol{a},\boldsymbol{b}) = \frac{1}{2}\left( \boldsymbol{a}\otimes\boldsymbol{b} +\boldsymbol{b}\otimes\boldsymbol{a} \right) -\frac{\boldsymbol{a}\cdot\boldsymbol{b}}{3}\boldsymbol{I}.\]

The implementation stores this tensor in five orthonormal components,

\[\operatorname{stf}_5(\boldsymbol{a},\boldsymbol{b}) = \left( \frac{2a_zb_z-a_xb_x-a_yb_y}{\sqrt{6}}, \frac{a_xb_x-a_yb_y}{\sqrt{2}}, \frac{a_xb_y+a_yb_x}{\sqrt{2}}, \frac{a_yb_z+a_zb_y}{\sqrt{2}}, \frac{a_zb_x+a_xb_z}{\sqrt{2}} \right).\]

For each center \(i\) and channel \(c\), the neighbor reduction builds the following moment bank:

\[\begin{split}\boldsymbol{\rho}^{s}_{ic} &= \sum_j w^i_{jc}\boldsymbol{s}_j,\\ \boldsymbol{\rho}^{r}_{ic} &= \sum_j w^i_{jc}\boldsymbol{e}_{ij},\\ \rho^{rs}_{ic} &= \sum_j w^i_{jc}(\boldsymbol{e}_{ij}\cdot\boldsymbol{s}_j),\\ \boldsymbol{\rho}^{r\times s}_{ic} &= \sum_j w^i_{jc}(\boldsymbol{e}_{ij}\times\boldsymbol{s}_j),\\ \boldsymbol{\rho}^{\mathrm{stf}(rs)}_{ic} &= \sum_j w^i_{jc}\operatorname{stf}_5( \boldsymbol{e}_{ij},\boldsymbol{s}_j),\\ \boldsymbol{\rho}^{\mathrm{stf}(rr)}_{ic} &= \sum_j w^i_{jc}\operatorname{stf}_5( \boldsymbol{e}_{ij},\boldsymbol{e}_{ij}),\\ \boldsymbol{\rho}^{\mathrm{stf}(rr)s}_{ic} &= \sum_j w^i_{jc}\operatorname{stf}_5( \boldsymbol{e}_{ij},\boldsymbol{e}_{ij})\otimes\boldsymbol{s}_j,\\ \boldsymbol{\rho}^{(s\cdot s)s}_{ic} &= \sum_j w^i_{jc}(\boldsymbol{s}_i\cdot\boldsymbol{s}_j) \boldsymbol{s}_j.\end{split}\]

The last two objects have 15 and 3 components, respectively. Together with the scalar and vector entries above, each radial channel has a 38-component canonical moment state. Most density-derived descriptor coordinates are scalar contractions of this bank; the moments themselves are not passed directly to the neural network. Direct one-edge sums and same-edge channel-pair accumulators are reduced separately.

O/C contraction hierarchy

The hierarchy is nested: at fixed \(C\), every order-1 coordinate is a prefix of order 2, and every order-2 coordinate is a prefix of order 3. Representative exact contractions are listed below.

Order 1 contains local and direct-edge magnetic information such as

\[\begin{split}q^{i,\mathrm{spin}}_\mathrm{local} &= |\boldsymbol{s}_i|^2,\\ q^{i,\mathrm{spin}}_{c,\mathrm{dot}} &= \boldsymbol{s}_i\cdot\boldsymbol{\rho}^{s}_{ic} = \sum_j w^i_{jc}(\boldsymbol{s}_i\cdot\boldsymbol{s}_j),\\ q^{i,\mathrm{spin}}_{c,\mathrm{neighbor}} &= \sum_j w^i_{jc}|\boldsymbol{s}_j|^2.\end{split}\]

When joint spin–orbit channels with \(l_\mathrm{max}=2\) are enabled, order 1 also contains the rank-2 contractions

\[\sum_j w^i_{jc}\, \mathcal{Q}(\boldsymbol{s}_i,\boldsymbol{s}_j) :\mathcal{Q}(\boldsymbol{e}_{ij},\boldsymbol{e}_{ij})\]

and

\[\mathcal{Q}(\boldsymbol{s}_i,\boldsymbol{s}_i) :\boldsymbol{\rho}^{\mathrm{stf}(rr)}_{ic}.\]

Order 2 adds edge powers, density norms, and correlations between two magnetic density legs. Examples include

\[\sum_j w^i_{jc}(\boldsymbol{s}_i\cdot\boldsymbol{s}_j)^2, \qquad |\boldsymbol{\rho}^{s}_{ic}|^2, \qquad (\rho^{rs}_{ic})^2, \qquad |\boldsymbol{\rho}^{r\times s}_{ic}|^2,\]

and

\[\boldsymbol{\rho}^{s}_{ic}\cdot \boldsymbol{\rho}^{(s\cdot s)s}_{ic}.\]

For a radial-channel pair \(c\leq d\), Spin3 keeps same-edge and distinct-neighbor correlations separately:

\[\begin{split}S^i_{cd} &= \sum_j w^i_{jc}w^i_{jd} (\boldsymbol{s}_i\cdot\boldsymbol{s}_j)^2,\\ D^i_{cd} &= (\boldsymbol{s}_i\cdot\boldsymbol{\rho}^{s}_{ic}) (\boldsymbol{s}_i\cdot\boldsymbol{\rho}^{s}_{id})-S^i_{cd}\\ &= \sum_{j\neq k}w^i_{jc}w^i_{kd} (\boldsymbol{s}_i\cdot\boldsymbol{s}_j) (\boldsymbol{s}_i\cdot\boldsymbol{s}_k).\end{split}\]

This separation prevents a two-density contraction from conflating repeated use of one neighbor edge with a correlation between distinct neighbors.

Spin3 additionally resolves the distinct-neighbor exchange by spatial angular rank. Define

\[\begin{split}\boldsymbol{A}^{(1)}_{ic} &=\sum_j w^i_{jc}(\boldsymbol{s}_i\cdot\boldsymbol{s}_j) \boldsymbol{e}_{ij},\\ \boldsymbol{A}^{(2)}_{ic} &=\sum_j w^i_{jc}(\boldsymbol{s}_i\cdot\boldsymbol{s}_j) \operatorname{stf}_5(\boldsymbol{e}_{ij},\boldsymbol{e}_{ij}).\end{split}\]

For every \(c\leq d\), the new coordinates are

\[\begin{split}D^{i,(1)}_{cd} &=\boldsymbol{A}^{(1)}_{ic}\cdot\boldsymbol{A}^{(1)}_{id}-S^i_{cd},\\ D^{i,(2)}_{cd} &=\frac{3}{2}\boldsymbol{A}^{(2)}_{ic}\cdot \boldsymbol{A}^{(2)}_{id}-S^i_{cd}.\end{split}\]

The subtraction removes the repeated-edge contribution, while the \(3/2\) factor compensates the norm of the rank-2 STF representation. These blocks distinguish angular exchange environments that have the same scalar distinct-neighbor contraction.

Joint spin–orbit contractions use four learned radial-leg mixing matrices \(A^{(\alpha)}\in\mathbb{R}^{C\times C}\). For any moment family \(\boldsymbol{\rho}\), a projected leg is

\[\overline{\boldsymbol{\rho}}^{(\alpha)}_{ic} = \sum_{d=1}^{C} A^{(\alpha)}_{cd}\boldsymbol{\rho}_{id}.\]

This permits non-collinear contraction legs while retaining one shared radial seam. Representative order-2 joint invariants are

\[\left( \overline{\boldsymbol{\rho}}^{r,(0)}_{ic} \times \overline{\boldsymbol{\rho}}^{r,(1)}_{ic} \right)\cdot \left( \boldsymbol{s}_i\times \overline{\boldsymbol{\rho}}^{s,(0)}_{ic} \right)\]

and

\[\operatorname{axial}\left([ \overline{\mathcal{Q}}^{(0)}_{ic}, \overline{\mathcal{Q}}^{(1)}_{ic} ]\right)\cdot \left( \boldsymbol{s}_i\times \overline{\boldsymbol{\rho}}^{s,(0)}_{ic} \right),\]

where \([\mathcal{A},\mathcal{B}]=\mathcal{A}\mathcal{B}- \mathcal{B}\mathcal{A}\) and axial maps the resulting antisymmetric tensor to an axial vector.

Order 3 adds dot-gated and triple-density contractions. Its direct-edge member is

\[\sum_j w^i_{jc} (\boldsymbol{s}_i\cdot\boldsymbol{s}_j) \left(|\boldsymbol{s}_i|^2+|\boldsymbol{s}_j|^2\right),\]

while representative joint contractions include scalar triple products such as

\[\overline{\boldsymbol{\rho}}^{r,(0)}_{ic}\cdot \left( \overline{\boldsymbol{\rho}}^{s,(1)}_{ic} \times \overline{\boldsymbol{\rho}}^{r\times s,(2)}_{ic} \right).\]

These coordinates supply a symmetry-respecting polynomial basis to a nonlinear energy model. They do not assign a fixed exchange, DMI, anisotropy, or other spin-Hamiltonian coefficient to any individual descriptor channel.

Symmetries

All Spin3 descriptor coordinates are even under global time reversal,

\[\boldsymbol{s}_i\longrightarrow-\boldsymbol{s}_i.\]

With spin_soc 0, the spatial vectors and spin vectors may be rotated independently and the descriptor is invariant under both rotations. With spin_soc 1, the extra channels are invariant under a joint orthogonal transformation of the lattice vectors and axial spin vectors,

\[\boldsymbol{e}_{ij}\longrightarrow R\boldsymbol{e}_{ij}, \qquad \boldsymbol{s}_i\longrightarrow\det(R)R\boldsymbol{s}_i, \qquad R\in O(3).\]

The spin_type selection defines independent spin coordinates and magnetic descriptor centers. All neighbor types enter geometric moment sums within the spin cutoff. The reader sets excluded types’ effective spins to zero and ignores their magnetic-force labels, so their contributions to moments containing neighbor spins vanish while geometric contributions remain. Original energy and atomic-force labels are retained; input files are unchanged.

Model dimensions

Let \(P=C(C+1)/2\), \(I_X\) be 1 when condition \(X\) is true and 0 otherwise, and define

\[a_C=1+I_{C\geq2},\qquad b_C=1+2I_{C\geq2}.\]

For \(L=l_\mathrm{max}\) and \(S=\texttt{spin\_soc}\), the order-1 Spin3 dimension is

\[D_1=1+2C+2C I_S I_{L\geq2}.\]

The order-2 increment is

\[\begin{split}\Delta D_2 &= 2C +C I_{L\geq1}\left(3I_S+1-I_S\right) +C I_{L\geq2}+C+2P\\ &+a_C C I_S I_{L\geq1} +a_C C I_S I_{L\geq2} +P I_{L\geq1}+P I_{L\geq2},\end{split}\]

and the order-3 increment is

\[\begin{split}\Delta D_3 &= C +a_C C I_S I_{L\geq1}\\ &+b_C C I_S I_{L\geq2} +C I_S I_{L\geq1} I_{C\geq3}.\end{split}\]

Therefore \(D_2=D_1+\Delta D_2\) and \(D_3=D_2+\Delta D_3\). For the common \(L=2\), spin_soc 1 shape, O2-C2 has 43 magnetic coordinates and O3-C2 has 55. The implementation limits the magnetic part to 96 coordinates and requires the combined structural and magnetic dimension to satisfy \(D_\mathrm{str}+D_\mathrm{spin}\leq199\). With the ordinary structural defaults, \(D_\mathrm{str}=42\); the default O3-C2-L2-SOC1 shape therefore gives \(42+55=97\) total coordinates.

The trainable magnetic descriptor parameters comprise \(9C N_\mathrm{typ}^2\) radial coefficients and, for Spin3, \(4C^2\) radial-leg mixing coefficients. These are optimized together with the neural-network parameters by SNES.

Descriptor scaling

Structural coordinates retain the ordinary inverse-range scaler. Magnetic coordinates use \(1/\max(\operatorname{RMS}(q),\operatorname{range}(q),1)\), without centering. Their gain is therefore never larger than one, including for a constant or initially unresolved magnetic channel.

Fresh training computes scaling from ordinary training structures using a fixed, non-degenerate reference parameter vector, independent of the SNES search mean and RNG. Nonconstant spin projection matrices keep descriptor channels distinct. Response-only frames do not enter this calculation. Prediction, restart, and explicit scaler import reuse the stored normalization instead.

Restart behavior

Spin restart restores the scaler from the matching nep.txt. See import_q_scaler for automatic restoration and fresh scaler-only import. The two files must have compatible architecture and element order, and the scaler must be finite and positive.

nep.restart stores the search distribution and energy_reference in the shared restart format, while nep.txt stores a selected candidate model. The search mean and that candidate need not predict the same values. Restart does not rescale parameters or substitute the candidate for the search mean.

A restart begins a new requested generation segment and resets RNG initialization. The restart file does not store global generation progress; it is not an exact replay of an uninterrupted trajectory.

Energy derivatives

The atomic force and the unmasked magnetic derivative are defined by

\[\boldsymbol{F}_k=-\frac{\partial U}{\partial\boldsymbol{r}_k}, \qquad \widetilde{\boldsymbol{M}}_k =-\frac{\partial U}{\partial\boldsymbol{s}_k}.\]

For an atom type enabled by spin_type, the public magnetic force is \(\boldsymbol{M}_k=\widetilde{\boldsymbol{M}}_k\). Excluded types have no independent spin coordinate; their public magnetic force is zero by convention. They still receive atomic forces from the positional derivative of the full energy, including magnetic geometric environments.

Writing \(q^i_\nu\) for either a structural or magnetic descriptor component, the chain rule gives

\[\boldsymbol{F}_k =-\sum_{i,\nu} \frac{\partial U_i}{\partial q^i_\nu} \frac{\partial q^i_\nu}{\partial\boldsymbol{r}_k} -\frac{\partial U_\mathrm{ZBL}}{\partial\boldsymbol{r}_k},\]

\[\widetilde{\boldsymbol{M}}_k =-\sum_{i,\nu} \frac{\partial U_i}{\partial q^i_\nu} \frac{\partial q^i_\nu}{\partial\boldsymbol{s}_k}.\]

The implementation first evaluates \(\partial U_i/\partial q^i_\nu\) through the neural network and then applies the analytical vector–Jacobian product of every Spin3 contraction, moment reduction, and radial basis function. The same position derivative produces the full per-atom virial. No finite-difference force path is used.

The spin torque used for training diagnostics is

\[\boldsymbol{\tau}_i =\boldsymbol{s}_i\times\boldsymbol{M}_i.\]

ZBL contributes to energy, atomic force, and virial but not to magnetic force or torque because it is spin independent.

Spin loss terms

Spin training augments the ordinary NEP loss with magnetic-force and torque RMSE terms,

\[L_\mathrm{spin} = \lambda_\mathrm{m} L_\mathrm{m} + \lambda_\mathrm{tau} L_\mathrm{tau} + \lambda_\mathrm{resp} L_\mathrm{resp},\]

where \(N_\mathrm{m}\) counts labeled active spins and \(N_\mathrm{tau}\) counts only those with \(|\boldsymbol{s}_i|^2 > 10^{-20}\,\mu_\mathrm{B}^2\),

\[\begin{split}L_\mathrm{m} &=\left[ \frac{1}{3N_\mathrm{m}} \sum_i |\boldsymbol{M}^{\mathrm{NEP}}_i- \boldsymbol{M}^{\mathrm{tar}}_i|^2 \right]^{1/2},\\ L_\mathrm{tau} &=\left[ \frac{1}{2N_\mathrm{tau}} \sum_i |\boldsymbol{s}_i\times\boldsymbol{M}^{\mathrm{NEP}}_i- \boldsymbol{s}_i\times\boldsymbol{M}^{\mathrm{tar}}_i|^2 \right]^{1/2}.\end{split}\]

The magnetic-force loss always includes all three Cartesian components and includes zero spins. Both the torque-error sum and its count exclude spins at or below the squared-magnitude threshold, evaluated in double precision. To supervise only spin rotation, set lambda_m 0 and a positive lambda_tau. For nonzero spins, the squared torque error equals the squared transverse magnetic-force error multiplied by \(|\boldsymbol{s}_i|^2\).

Grouped magnetic response

For a grouped rotation path with coordinate \(\theta\), the response generator evaluated for frame \(n\) is

\[G_n =\sum_i \boldsymbol{M}_{ni}\cdot \frac{\partial\boldsymbol{s}_{ni}}{\partial\theta} =-\frac{\partial U_n}{\partial\theta}.\]

The grouped response loss first centers \(G_n\) within each group. Each group contributes equally to the centered-curve Huber loss, independent of its number of scan points. Each group’s uncentered target-response RMS, floored at \(10^{-6}\), normalizes its shape term and a second Huber term comparing group means; the mean term is multiplied by 0.25. response_coordinate defines the path derivative but does not add a separate reliability weight.

The group coordinate is explicit because Cartesian spin snapshots alone do not determine their path ordering or parameterization. The trainer sorts each group and derives \(\partial\boldsymbol{s}/\partial\theta\) from the final constrained-DFT spins with second-order, three-point nonuniform weights applied to sphere-log angular displacements and separate magnitude differences. This preserves longitudinal moment relaxation without injecting the radial chord error of Cartesian interpolation into constant-length rotations. Stencils must resolve angular separations below pi. Atom types excluded by spin_type are masked from the derived tangent. At zero moment, the tangent uses Cartesian differences. Constant-rate great-circle rotations are differentiated exactly apart from floating-point rounding; other paths retain the finite-stencil approximation. Antipodal samples require intermediate frames. Input labels and group metadata are specified in response.xyz; the loss weight is set by lambda_spin_response.

Spin3 uses the shared SNES lifecycle: generation zero prepares training scalers and uses regularization-only fitness. Physical losses are evaluated from the next generation. All magnetic descriptor orders participate throughout training.

Model formats and input

Header in nep.txt	Training mode	Description
nep / model nep_spin	model nep_spin	Current block format with spin_version 1; optional zbl field.

See spin_version and the neighboring spin_* keyword pages for descriptor configuration. See train.xyz and test.xyz for ordinary training labels and response.xyz for grouped-response input.

Training specialization

With nep_compile 1, training specializes both the structural NEP kernels and the magnetic density, descriptor contraction and force kernels for the selected Spin layout. The magnetic kernels share their formulas with the native path. If runtime compilation is unavailable, native kernels remain available. Compilation adds startup time, so very short runs may be slower; nep_compile 0 disables specialization. Prediction uses the native path.