1. General¶

1.1. What is ParAMS?¶

ParAMS is a module for ReaxFF and DFTB (GFN1-xTB) parametrization, distributed together with the Amsterdam Modeling Suite.

There is both a graphical user interface (GUI) and a Python library.

To get started, see the Getting Started: Lennard-Jones Potential for Argon tutorial.

Selected features:

Import reference data from AMS, VASP, Quantum ESPRESSO, or experiment
Fit any number of properties: reaction energies, forces, bond lengths, angles, cell parameters, stress tensors, charges, …
Use single points, geometry optimizations, or PES scans during the parametrization
Set custom weights for different training set entries
Use a validation set to prevent overfitting
Choose which parameters to optimize, and set allowed ranges for them
Optimize with CMA-ES or Nelder-Mead
Intuitive output files for creating correlation plots, energy-volume curves, and more
Submit jobs to remote machines using the GUI
Results updated on-the-fly in the GUI with many diagrams

1.2. What’s new in ParAMS 2022?¶

The AMS2022.1 release is the first version to include a GUI for ParAMS. The ParAMS GUI replaces the previous AMStrain module for ReaxFF parametrization.

Other changes:

The Results Importer class provides a shortcut for reading structures, reference results, and engine settings from finished reference job.
The Logger output structure has been changed, with many new useful output files
Job-dependent engine settings using the JCEntry.extra_engine attribute
Parameter interfaces can be stored in text .yaml format
Exact restarts with the CMA-ES optimizer
Support for reading in VASP OUTCAR files and Quantum ESPRESSO .out files
Weights schemes for setting individual datapoint weights for array reference values (for example, to weight large force components less than small force components)
Initialize an empty ReaxFFParameters using ReaxFFParameters(None)
Copy blocks of parameters from ReaxFF force field files
New class names: ReaxParams → ReaxFFParameters, xTBParams → GFN1xTBParameters
New variable names (e.g. in the Optimization class constructor and in params.conf.py): jobcollection → job_collection, enginecollection → engine_collection, dataset → data_set, interface → parameter_interface
Scalar weights for array reference values are interpreted as the sum of weights: weight = 1 for an array of length 3 gives each point a weight of 0.3333 (before, the scalar value was broadcasted so the total weight would be 3).
Faster reading of Job Collections
Support for gzip-compressed job collections and training sets
All extractors have explicit default units and sigma values
Distance, angle, and dihedral extractors use the minimum image convention under periodic boundary conditions by default
The params main script supports validation sets
ParAMS requires a valid license

1.3. Theory of Parameter Fitting: A Lennard-Jones Example¶

Assuming we are interested in calculating the potential energy \({V}(R)\) between two Argon atoms, one suitable model for this task is the Lennard-Jones Potential (LJ), which is given by

(1.1)¶\[\hat{V}(R|\mathrm{\boldsymbol{x}}) = \frac{{x_1}}{R^{12}} - \frac{{x_2}}{R^6},\]

where \(\hat{V}\) is the (predicted) potential energy as a function of the interatomic distance \(R\) and a parameter vector \(\boldsymbol{x}=({x_ 1}, {x_2})^\mathrm{T}\) that modifies the shape of the potential.

If reference data \(\boldsymbol{y} = \{(R_i,V_i)\}\) is available for this problem (either from an experiment or another model), we can measure the quality of the LJ model by a loss function (also called objective or cost function) \(L\), which is a metric operating on the residuals vector \(\boldsymbol{y} - \boldsymbol{\hat{y}} = \{V_i - \hat{V}_i\}\). One example for such a metric is the mean absolute error (MAE):

(1.2)¶\[L_\mathrm{MAE}( \boldsymbol{y} - \boldsymbol{\hat{y}} ) = \frac{1}{N} \sum_{i=1}^N | y_i - \hat{y}_i |.\]

For a case when the LJ model perfectly represents the experimental data, \(\boldsymbol{y} = \boldsymbol{\hat{y}}\), and \(L=0\). In contrast, a larger loss function value represents a mismatch between the predicted and reference values. In such cases the parametric model’s parameters can be fitted, assuming the reference set of systems and energies does not change during the optimization process. We introduce an optimizer which produces an optimized set of parameters \(\boldsymbol{x}^*\) from an initial point \(\boldsymbol{x}_0\) by minimizing \(L\):

(1.3)¶\[O(\boldsymbol{x}_0, L) = \underset{\boldsymbol{x}} {\mathop{\mathrm{arg\,min}}}\, L = \boldsymbol{x}^*.\]

We visualize the influence of two different parameter sets for the Lennard-Jones potential in the figure below: While the initial model parameters (orange curve) might not represent experimental data (discrete marks) very well, an optimization of the parameters with respect to the reference data can provide a viable solution (grey curve).

1.4. General Application¶

In a more generalized description of the package, ParAMS allows its users to fit a variety of parametric (empirical) models that are part of the Amsterdam Modeling Suite. By design, any physico-chemical property \(P\) that can be extracted from one AMS computation (or constructed from multiple), can be fitted with a number of different optimization algorithms. A minimal set up does not require much more additional user input, making setting up of basic workflows easy and accessible.

At the same time ParAMS offers a variety of additional features for the customization of the workflow such as automated and manual definition of the search space and relevant parameter subsets, support for validation sets or additional interaction through callbacks to name a few, resulting in a package that is highly flexible when it comes to advanced user requirements.

Integration with AMS guarantees that the same APIs are supported regardless of the application, making workflows highly reusable and storage of relevant reference data in the human-readable YAML format ensures transparency and reproducibility.