train.xyz and test.xyz

The train.xyz file contains the training data for the construction of a NEP model, while the optional test.xyz file contains the corresponding test data. Both files use extended xyz file format. Each structure (or configuration or frame) occupies \(N+2\) lines, where \(N\) is the number of atoms in the structure. Grouped magnetic-response data use a separate response.xyz file.

Format for a single structure

Line 1

The first line should only contain one field, which is the number of atoms in the structure \(N\).

Line 2

This line consists of a number of keyword=value pairs separated by spaces. Spaces before and after = are allowed. All the characters are case-insensitive. value can be a single item or a number of items enclosed by double quotes, such as keyword="value_1 value_2 value_3". Here, the different values are separated by spaces and spaces after the left " and before the right " are allowed. For example, one can write keyword=" value_1 value_2 value_3 ".

Essentially any keyword is allowed, but we only read the following ones:

  • lattice="ax ay az bx by bz cx cy cz" is mandatory and gives the cell vectors:

    \[\begin{split}\boldsymbol{a} &= a_x \boldsymbol{e}_x + a_y \boldsymbol{e}_y + a_z \boldsymbol{e}_z \\ \boldsymbol{b} &= b_x \boldsymbol{e}_x + b_y \boldsymbol{e}_y + b_z \boldsymbol{e}_z \\ \boldsymbol{c} &= c_x \boldsymbol{e}_x + c_y \boldsymbol{e}_y + c_z \boldsymbol{e}_z\end{split}\]
  • energy=energy_value such as energy=-123.4 is mandatory and gives the target energy of the structure, which is \(-123.4\) eV in this example.

  • virial="vxx vxy vxz vyx vyy vyz vzx vzy vzz" is optional and gives the \(3\times3\) virial tensor of the structure in eV. Positive and negative values represent compressed and stretched states, respectively.

  • stress="sxx sxy sxz syx syy syz szx szy szz" is optional and gives the \(3\times3\) stress tensor of the structure in eV/Å\(^3\). Positive and negative values represent stretched and compressed states, respectively. If both virial and stress are present, the virial is used. During potential training, the two tensors must agree after conversion to per-atom virials, within \(10^{-3}\) eV/atom for each independent component; otherwise training stops with an input error.

  • weight=relative_weight is optional and gives the relative weight for the current structure in the total loss function.

  • energy_weight=relative_weight is optional and defaults to 1. It multiplies the squared energy error for the current structure, in addition to the weighting specified by weight.

  • charge=total_charge is optional for qnep1, qnep2, qnep3, and qnep3_vdw models. It gives the total charge of the structure in units of elementary charge e and defaults to 0.

  • temperature=temperature_value is required for the nep_temperature model and gives the electronic temperature in kelvin.

  • pbc="T T T" or pbc="F F F" specifies fully periodic or fully nonperiodic boundaries for the long-range models qnep1, qnep2, qnep3, nep_vdw, and qnep3_vdw (see model). The default is T T T. Mixed periodic and nonperiodic directions are not supported for these models.

  • name=label is optional and gives the structure a label, by which ediff.in refers to it. Labels are matched case-insensitively for the letters A to Z and must be unique within a file. A label must not begin with #, + or -, or contain whitespace or any of * / = " ' { }, and a structure has at most one name field. The field is read only when the keyword lambda_d is set, and a label that breaks these rules is then an input error.

  • properties=property_name:data_type:number_of_columns is mandatory but only read the following items:

    • species:S:1 chemical symbol in the periodic table (case-sensitive)

    • pos:R:3 position vector

    • force:R:3 or forces:R:3 target force vector

    • bec:R:9 target Born effective charge (BEC) tensor (optional)

    • adipole:R:3 or atomic_dipole:R:3 target atomic dipole vector in the order \(x,y,z\) (required for model nep_dipole with atomic_v 1)

    • apol:R:9 or atomic_polarizability:R:9 target atomic polarizability tensor in the order \(xx,xy,xz,yx,yy,yz,zx,zy,zz\) (required for model nep_polarizability with atomic_v 1)

    • spin:R:3, spins:R:3, moment:R:3, or moments:R:3 Cartesian magnetic-moment vector in muB (required when spin_version is specified)

    • mforce:R:3 target magnetic-force vector (optional). The aliases mforces, force_mag, forces_mag, magnetic_force, and magnetic_forces are also accepted.

    For atom types excluded by spin_type, training, test and prediction readers set the effective spin to zero and ignore magnetic-force labels. The original files need no modification. Energy and atomic-force labels are preserved, and their positions remain part of the geometric environment.

  • If a dipole model is to be trained, energy, virial, stress, and force will be ignored and one should additionally provide dipole="dx dy dz", which is the dipole vector of the structure.

  • If a polarizability model is to be trained, energy, virial, stress, force, and dipole will be ignored and one should additionally provide pol="pxx pxy pxz pyx pyy pyz pzx pzy pzz", which is the polarizability tensor of the structure.

For atomic dipole or polarizability fitting, set atomic_v to 1 and provide the corresponding atomic property above. The training reader also requires the global dipole or pol field on line 2 in this mode, although the loss is evaluated using the atomic targets. Atomic targets are given directly, without division by the number of atoms.

Starting from line 3

Each line should contain the same number of items, which are determined by the property keywords on line 2.

Units

  • Length and position are expected in units of Ångstrom.

  • The energy is expected in units of eV.

  • Forces are expected in units of eV/Å.

  • Virials are expected in units of eV. The corresponding stress is the negative of the virial divided by the cell volume.

  • Dipole and polarizability can be in arbitrary units (such as the Hartree atomic units) as liked (and remembered) by the user.

  • BEC is in units of elementary charge e.

  • Spin is in Bohr magnetons (muB), and magnetic force is in eV/muB. Magnetic force is the negative Cartesian derivative of energy with respect to spin.

Tips

  • Long-range models use the boundary conditions specified by pbc as described above. Other models assume periodic boundary conditions in all directions. For periodic configurations, when the box thickness in a direction is smaller than twice the radial cutoff distance, the code internally replicates the box in that direction.

  • The minimal number of atoms in a configuration is 1. The user is responsible for choosing a sensible reference energy when preparing the energy data. But this is not crucial as the absolute energies are not relevant in the present context. However, because NEP training uses single precision, accuracy will be lost if any reference energy is smaller than -100 eV/atom. The code will give a warning message in this case.

  • The energy and virial data refer to the total energy and virial for the system. They are not per-atom but per-cell quantities.

  • The BEC is optional. You can also have it only for some structures.