\(\renewcommand{\AA}{\text{Å}}\)

pair_style uf3 command

Accelerator Variants: uf3/kk

Syntax

pair_style style BodyFlag

  • style = uf3 or uf3/kk

    BodyFlag = Indicates whether to calculate only 2-body or 2 and 3-body interactions. Possible values: 2 or 3

Examples

pair_style uf3 3
pair_coeff * * Nb.uf3 Nb

pair_style uf3 2
pair_coeff * * NbSn.uf3 Nb Sn

pair_style uf3 3
pair_coeff * * NbSn.uf3 Nb Sn

Description

Added in version 27June2024.

The uf3 style computes the Ultra-Fast Force Fields (UF3) potential, a machine-learning interatomic potential. In UF3, the total energy of the system is defined via two- and three-body interactions:

\[\begin{split}E & = \sum_{i,j} V_2(r_{ij}) + \sum_{i,j,k} V_3 (r_{ij},r_{ik},r_{jk}) \\ V_2(r_{ij}) & = \sum_{n=0}^N c_n B_n(r_{ij}) \\ V_3 (r_{ij},r_{ik},r_{jk}) & = \sum_{l=0}^{N_l} \sum_{m=0}^{N_m} \sum_{n=0}^{N_n} c_{l,m,n} B_l(r_{ij}) B_m(r_{ik}) B_n(r_{jk})\end{split}\]

where \(V_2(r_{ij})\) and \(V_3 (r_{ij},r_{ik},r_{jk})\) are the two- and three-body interactions, respectively. For the two-body the summation is over all neighbors J and for the three-body the summation is over all neighbors J and K of atom I within a cutoff distance determined from the potential files. \(B_n(r_{ij})\) are the cubic b-spline basis, \(c_n\) and \(c_{l,m,n}\) are the machine-learned interaction parameters and \(N\), \(N_l\), \(N_m\), and \(N_n\) denote the number of basis functions per spline or tensor spline dimension.

With uf3 style only a single pair_coeff command is used to indicate the UF3 LAMMPS potential file containing all the two- and three-body interactions followed by N additional arguments specifying the mapping of UF3 elements to LAMMPS atom types, where N is the number of LAMMPS atom types:

  • UF3 LAMMPS potential file

  • N elements names = mapping of UF3 elements to atom types

As an example, if a LAMMPS simulation contains 2 atom types (elements ‘A’ and ‘B’), the pair_coeff command will be:

pair_style uf3 3
pair_coeff * * AB.uf3 A B

The AB.uf3 file should contain all two-body (A-A, A-B, B-B) and three-body (A-A-A, A-A-B, A-B-B, B-A-A, B-A-B, B-B-B).

If a value of “2” is specified in the pair_style uf3 command, only the two-body potentials are needed. For 3-body interaction the first atom type is the central atom. We recommend using the generate_uf3_lammps_pots.py script (found here) for generating the UF3 LAMMPS potential file from the UF3 JSON potentials.

UF3 LAMMPS potential file in the potentials directory of the LAMMPS distribution have a “.uf3” suffix. The interaction block in UF3 LAMMPS potential file should start with #UF3 POT and end with # characters. Following shows the format of a generic 2-body and 3-body potential block in UF3 LAMMPS potential file-

#UF3 POT UNITS: units DATE: POT_GEN_DATE AUTHOR: AUTHOR_NAME CITATION: CITE
2B ELEMENT1 ELEMENT2 LEADING_TRIM TRAILING_TRIM
Rij_CUTOFF NUM_OF_KNOTS
BSPLINE_KNOTS
NUM_OF_COEFF
COEFF
#
#UF3 POT UNITS: units DATE: POT_GEN_DATE AUTHOR: AUTHOR_NAME CITATION: CITE
3B ELEMENT1 ELEMENT2 ELEMENT3 LEADING_TRIM TRAILING_TRIM
Rjk_CUTOFF Rik_CUTOFF Rij_CUTOFF NUM_OF_KNOTS_JK NUM_OF_KNOTS_IK NUM_OF_KNOTS_IJ
BSPLINE_KNOTS_FOR_JK
BSPLINE_KNOTS_FOR_IK
BSPLINE_KNOTS_FOR_IJ
SHAPE_OF_COEFF_MATRIX[I][J][K]
COEFF_MATRIX[0][0][K]
COEFF_MATRIX[0][1][K]
COEFF_MATRIX[0][2][K]
.
.
.
COEFF_MATRIX[1][0][K]
COEFF_MATRIX[1][1][K]
COEFF_MATRIX[1][2][K]
.
.
.
#

The second line indicates whether the block contains data for 2-body (2B) or 3-body (3B) interaction. This is followed by element combination interaction, LEADING_TRIM and TRAILING_TRIM number on the same line. The current implementation is only tested for LEADING_TRIM=0 and TRAILING_TRIM=3. If other values are used LAMMPS is terminated after issuing an error message. The Rij_CUTOFF sets the 2-body cutoff for the interaction described by the potential block. NUM_OF_KNOTS is the number of knots (or the length of the knot vector) present on the very next line. The BSPLINE_KNOTS line should contain all the knots in ascending order. NUM_OF_COEFF is the number of coefficients in the COEFF line. All the numbers in the BSPLINE_KNOTS and COEFF line should be space-separated. Similar to the 2-body potential block, the third line sets the cutoffs and length of the knots. The cutoff distance between atom-type I and J is Rij_CUTOFF, atom-type I and K is Rik_CUTOFF and between J and K is Rjk_CUTOFF.

Note

The current implementation only works for UF3 potentials with cutoff distances for 3-body interactions that follows 2Rij_CUTOFF=2Rik_CUTOFF=Rjk_CUTOFF relation.

The BSPLINE_KNOTS_FOR_JK, BSPLINE_KNOTS_FOR_IK, and BSPLINE_KNOTS_FOR_IJ lines (note the order) contain the knots in increasing order for atoms J and K, I and K, and atoms I and J respectively. The number of knots is defined by the NUM_OF_KNOTS_* characters in the previous line. The shape of the coefficient matrix is defined on the SHAPE_OF_COEFF_MATRIX[I][J][K] line followed by the columns of the coefficient matrix, one per line, as shown above. For example, if the coefficient matrix has the shape of 8x8x13, then SHAPE_OF_COEFF_MATRIX[I][J][K] will be 8 8 13 followed by 64 (8x8) lines each containing 13 coefficients separated by space.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix. They have been optimized to run faster, depending on your available hardware, as discussed on the Accelerator packages page. The accelerated styles take the same arguments and should produce the same results, except for round-off and precision issues.

These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP, and OPT packages, respectively. They are only enabled if LAMMPS was built with those packages. See the Build package page for more info.

You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.

See the Accelerator packages page for more instructions on how to use the accelerated styles effectively.

Mixing, shift, table, tail correction, restart, rRESPA info

For atom type pairs I,J and I != J, where types I and J correspond to two different element types, mixing is performed by LAMMPS as described above from values in the potential file.

This pair style does not support the pair_modify shift, table, and tail options.

This pair style does not write its information to binary restart files, since it is stored in potential file.

This pair style can only be used via the pair keyword of the run_style respa command. It does not support the inner, middle, outer keywords.

Restrictions

The ‘uf3’ pair style is part of the ML-UF3 package. It is only enabled if LAMMPS was built with that package. See the Build package page for more info.

This pair style requires the newton setting to be “on”.

The UF3 LAMMPS potential file provided with LAMMPS (see the potentials directory) are parameterized for metal units.

The single() function of ‘uf3’ pair style only return the 2-body interaction energy.

Default

none

(Xie23) Xie, S.R., Rupp, M. & Hennig, R.G. Ultra-fast interpretable machine-learning potentials. npj Comput Mater 9, 162 (2023). https://doi.org/10.1038/s41524-023-01092-7