Machine learning force field calculations: Basics

The machine-learned force fields (MLFF) feature of VASP allows you to generate, improve, modify and apply force fields based on machine learning techniques for your system of interest. Although there are many tunable parameters, i.e. MLFF-related INCAR tags, the default values have been carefully selected to simplify the initial creation of a machine-learned force field. Hence, we hope that only minimal additional effort is required to get started with this feature. Nevertheless, because machine learning involves multiple steps, e.g., at a minimum separate training and application stages, this page tries to explain the basic tags controlling the corresponding modes of operation. If you are already familiar with the basic usage of the MLFF feature, you may want to have a closer look at the best practices page which offers more in-depth advice for tuning MLFF settings. If you need more information about the theory and algorithms please visit the ML theory page.

Important general remarks

On-the-fly learning can be significantly more involved than, e.g., a single-point electronic calculation, because it combines multiple features of VASP. Each part requires a proper setup via the available INCAR tags. A misconfiguration corresponding to one part of the calculation may have severe effects on the quality of the resulting machine-learned force field. In the worst case, successful training may even be impossible. To be more specific, on-the-fly learning requires control over the following aspects:

• Consistent convergence

It is required that all ab initio reference data collected via on-the-fly training is consistent and well-converged with respect to the single-point electronic calculation setup. Mind different temperatures and densities targeted in MD runs. A machine-learned force field can only reproduce a single potential energy landscape!

• Correct setup of molecular dynamics simulations

Consider the choice of thermodynamic ensembles, thermostat and barostat settings and an appropriate time step.

• Proper setup of machine-learned force field parameters

Mind system-dependent parameters like the cutoff radius or atomic environment descriptor resolution.

• Control over data set generation via on-the-fly learning

Monitor and control how much ab initio reference data is harvested via automatic Bayesian threshold determination and sparsification.

• Quality control

Establish reasonable expectations regarding residual training errors. Benchmark the quality of resulting force fields by comparison of predictions with known quantities (from ab initio).

Warning: It is essential to validate the setup of each of these parts. Before trying to generate a machine-learned force field from scratch always familiarize with the pure ab initio calculations first. If this step is fully understood and convergence is under control, then initially try to run a (short) MD simulation without the aid of machine learning. Verify the resulting trajectory meets expectations with respect to conserved quantities, etc. Only then, start with machine-learned force field generation. An incorrect setting in the ab initio or molecular dynamics settings can lead to a complete failure of the force field generation. Consider the following example: an ab initio setup which is not converged with respect to k-points is used as a basis to create a machine-learned force field. Then, even when the MD part is configured correctly the training structures obtained from on-the-fly learning will contain noisy reference forces and an inconsistent potential energy landscape. Eventually, even after collecting a lot of training data the remaining training errors will be significantly higher than what could be achieved with a converged k-points setup. Ultimately, this will result in poor predictive quality of the generated force field.

Parallelization

Currently VASP offers only MPI-parallelization for the MLFF feature. Hence, all operation modes based solely on MLFF code, i.e., prediction-only MD simulations (ML_MODE = run) and local reference configuration reselection (ML_MODE = select) cannot benefit from other parallelization techniques, e.g., OpenACC offloading to GPUs or MPI/OpenMP-hybrid parallelization. However, a typical on-the-fly training performs also ab-initio calculations.

In general, to perform a machine learning force field (MLFF) calculation, you need to set

ML_LMLFF = .TRUE.

in the INCAR file. Then depending on the particular calculation, you need to set the values of additional INCAR tags. In the first few sections, we list the tags that a user may typically encounter. Most of the other input are set to defaults and should be only changed by experienced users in cases where the changes are essential.

In the following, most of the tags are only shown for the angular descriptor (tags containing a 2 in it). Almost every tag has an analogous tag for the radial descriptor (tags containing 1 in it). The usage of these tags is the same for both descriptors.

Type of machine learning calculation

In this section, we describe the modes in which machine learning calculations can be done in VASP and show exemplary INCAR settings. A typical example showing these modes in action is the machine learning of a force field on a material with two phases A and B. Initially, we have no force field of the material, so we choose a small to medium-sized supercell of phase A to generate a new force field from scratch. In this step, ab initio calculations are performed whenever necessary improving the force field in this phase until it is sufficiently accurate. When applied to phase B, the force field learned in phase A might contain useful information about the local configurations. Hence one would run a continuation run and the machine will automatically collect the necessary structure datasets from phase B to refine the force field. In many cases, only a few such structure datasets are required, but it is still necessary to verify this for every case. After the force field is sufficiently trained, one can use it to describe much larger cell sizes. Hence, one can switch off learning on larger cells and use only the force field. This is then orders of magnitude faster than the ab initio calculation. If the sampled atomic environments are similar to the structure datasets used for learning, the force field is transferable for the same constituting elements, but it should be still cautiously judged whether the force field can describe rare events in the larger cell.

On-the-fly force field generation from scratch

To generate a new force field, one does not need any special input files. First, one sets up a molecular dynamics calculation as usual (see molecular dynamics) adding the machine-learning related ones to the INCAR file. To start from scratch add

ML_ISTART = 0

Running the calculation will result in generating the main output files ML_LOGFILE, ML_ABN and ML_FFN files. The latter two are required for restarting from an existing force field.

Continuing on-the-fly learning from already existing force-fields

To continue from a previous run, copy the following files

cp ML_ABN ML_AB

The file ML_AB contains the ab initio reference data.

Next either copy your last structure

cp CONTCAR POSCAR

or start from a completely new POSCAR file. This new POSCAR file is allowed to have completely different elements and a number of atoms for each element.

To proceed with learning and obtain an improved force field set

ML_ISTART = 1

in the INCAR file.

Force field calculations without learning

Once a sufficiently accurate force field has been generated, one can use it to predict properties. Copy the force field information

cp ML_FFN ML_FF

The file ML_FFN holds the force field parameters. One can also use different POSCAR files, e.g., a larger supercell. In the INCAR file, select only force-field based calculations by setting

ML_ISTART = 2

Reference total energies

To obtain the force field, one needs a reference for total energy. For ML_ISCALE_TOTEN=2 this reference energy is set to the average of the total energy of the training data. This is the default setting and we advise one to use this setting if not needed otherwise.

If needed, reference atomic calculations can be performed (see Calculation of atoms). One can then specify to use the atomic energy and give reference energies for all atoms by setting the following variables in the INCAR file

ML_ISCALE_TOTEN=1
ML_EATOM_REF = E_at1 E_at2 ...

If the tag ML_EATOM_REF is not specified, default values of 0.0 eV/atom are assumed.

Cut-off radius

The following tags define the cut-off radii for each central atom

ML_RCUT1
ML_RCUT2

The defaults should be only changed if the structural distances require it, e.g., two atoms on a surface that are further away than the default. In that case, the cut-off radii should be set slightly larger than the distance between these two atoms.

Weighting of energy, forces, and stress

In most cases, the force field can be optimized to reproduce one of the target observables more accurately by weighting the desired quantity more strongly. Of course, at the same time, other observables are less well reproduced. Empirically up to a certain weight ratio (typically 10-20), the improvement of the more strongly weighted observable was much greater than the accuracy loss of the other observables. The optimum ratio depends on the material and the parameters of the force field, hence it has to be determined for each case. The weights of the energies, forces and stresses can be changed using ML_WTOTEN, ML_WTIFOR and ML_WTSIF, respectively. The default value is 1.0 for each. Since the input tags define the ratio of the weights, it suffices to raise the value of only one observable.

We advise to use ML_WTOTEN$\ge$10 whenever energies are important.

Note, however, that increasing ML_WTOTEN tends to lead to overfitting, that is, seemingly the errors for the energy decrease for the training set, but not always does this improvement carry over to an independent test set. It is therefore advised to also evaluate the performance of the MLFF on an independent test set, and to increase ML_WTOTEN only up to the point where the improvements carry over to the test set. Finally, note that changing the ratios is best done in post-processing, by refitting a pre-existing ML_AB file.

Caution: number of structures and basis functions

The maximum number of structure datasets ML_MCONF and basis functions (local reference configurations) ML_MB potentially constitutes a memory bottleneck, because the required arrays are allocated statically at the beginning of the calculation. It is advised not to use too large numbers initially. For ML_ISTART=0, the defaults are ML_MCONF=1500 and ML_MB=1500. For ML_ISTART=1 and 3, the values are set to the number of entries read from the ML_AB file plus a small overhead. If at any point during the training either the number of structure datasets or the size of the basis set exceeds its respective maximum number, the calculation stops with an error message. Since the ML_ABN is continuously written during on-the-fly learning, not all is lost though. Simply copy the ML_ABN to ML_AB and CONTCAR to POSCAR, increase ML_MCONF or ML_MB, and continue training (see restart the calculation).

VASP output

When the machine learning force field code is switched on some of the output files in VASP can be modified or augmented.

OUTCAR

Additional lines for the predicted energies, forces, and stresses appear in the OUTCAR file. They are analogous to the ab initio output except that they contain the ML keyword.

OSZICAR

The entries in the OSZICAR file are also written if a force field only is employed. In this case, the E0 entry contains the same as the F entry since the MLFF does not predict the entropy. The rest is analogous to the ab initio output.

Example input for silicon

This is an example INCAR file for a very basic machine learning calculation of silicon.

# machine learning
ML_LMLFF         = .TRUE.
ML_ISTART        = 0                             # 0 or 1, depends whether there is an existing ML_AB file

# electronic degrees of freedom
ENCUT            = 325                           # increase ENCUT by 30 % for accurate stress
PREC             = Normal                        # for ML, it is not advised to use Fast to avoid error propagation
ALGO             = Fast                          # Fast is usually robust, if it fails move back to ALGO = Normal
LREAL            = A                             # real space projection is usually faster for large systems
ISMEAR           = 0 ;   SIGMA = 0.1             # whatever you desire, for insulators never use ISMEAR>0
EDIFF            = 1E-05                         # it is preferred to make the calculations accurate

# technical flags, update when changing number of cores
NELM             = 100 ; NELMIN = 6              # set the mininum number of iterations to 6 to avoid early break
LCHARG           = .FALSE.                       # avoid writing files
LWAVE            = .FALSE.
NWRITE           = 0                             # write less to avoid huge OUTCAR

# MD
ISYM             = 0                             # no symmetry, we are at finite temperature
POTIM            = 2                             # This is very system dependent, for H to not exceed 0.5 fs, B-F about 1 fs, Na-Cl 2 fs, etc.
IBRION           = 0                             # MD
ISIF             = 3                             # you really want volume changes during MD in the training to get elastic tensors right
NSW              = 20000                         # honestly the larger the merrier, 50000 is strongly recommended
TEBEG            = 100 ; TEEND = 800 K           # max desired temperature times 1.3
MDALGO           = 3                             # use Langevin thermostat
LANGEVIN_GAMMA   = 10.0                          # friction coef. for atomic DoFs for each species
LANGEVIN_GAMMA_L = 10.0                          # friction coef. for the lattice DoFs
NBLOCK           = 10 ;  KBLOCK = 1000           # pair correlation function every 10 steps; write files every 10 x 1000 steps

---