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_valuesuch asenergy=-123.4is 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 bothvirialandstressare 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_weightis optional and gives the relative weight for the current structure in the total loss function.energy_weight=relative_weightis optional and defaults to 1. It multiplies the squared energy error for the current structure, in addition to the weighting specified byweight.charge=total_chargeis optional forqnep1,qnep2,qnep3, andqnep3_vdwmodels. It gives the total charge of the structure in units of elementary charge e and defaults to 0.temperature=temperature_valueis required for thenep_temperaturemodel and gives the electronic temperature in kelvin.pbc="T T T"orpbc="F F F"specifies fully periodic or fully nonperiodic boundaries for the long-range modelsqnep1,qnep2,qnep3,nep_vdw, andqnep3_vdw(see model). The default isT T T. Mixed periodic and nonperiodic directions are not supported for these models.name=labelis 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 onenamefield. 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_columnsis mandatory but only read the following items:species:S:1chemical symbol in the periodic table (case-sensitive)pos:R:3position vectorforce:R:3orforces:R:3target force vectorbec:R:9target Born effective charge (BEC) tensor (optional)adipole:R:3oratomic_dipole:R:3target atomic dipole vector in the order \(x,y,z\) (required formodel nep_dipolewithatomic_v 1)apol:R:9oratomic_polarizability:R:9target atomic polarizability tensor in the order \(xx,xy,xz,yx,yy,yz,zx,zy,zz\) (required formodel nep_polarizabilitywithatomic_v 1)spin:R:3,spins:R:3,moment:R:3, ormoments:R:3Cartesian magnetic-moment vector in muB (required when spin_version is specified)mforce:R:3target magnetic-force vector (optional). The aliasesmforces,force_mag,forces_mag,magnetic_force, andmagnetic_forcesare 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
pbcas 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.