ParAMS

General

Start ParAMS

  • Open AMSjobs, and select SCM → ParAMS
  • From the command-line, run $AMSBIN/params -gui. To open a file, run for example $AMSBIN/params -gui job_collection.yaml.

By default ParAMS opens a Lennard-Jones project. Switch to ReaxFF or GFN1-xTB in the Parameters menu.

Overview

The ParAMS GUI lets you set up training and validation sets, run ReaxFF and DFTB parametrizations, and view the results. It is a GUI for the ParAMS Python library.

Get started with the ParAMS GUI: See the tutorials.

The ParAMS GUI shows you the

  • Jobs, containing structures and settings for the jobs to be run during the parametrization
  • Training set, defining the loss function to be minimized
  • Validation set, an optional data set that can be used to evaluate over/underfitting
  • Engines, a collection of settings that can be used for (a) running reference jobs, (b) viewing reference job settings, or (c) setting the engine settings for the jobs during the parametrization (augments the AMS settings defined in the Jobs).
  • Parameters, a table of parameters with allowed ranges for the parameters
  • Settings, settings for the parametrization (e.g. which optimizer to use)
  • Info, detailed information about jobs and training set entries. (read-only)
  • Graphs, graphs with details about the parametrization results
  • Results, text output files with details about the parametrization results (read-only)

When saving, you will enter the name of a directory. The directory name must end with .params, otherwise the extension will be added. In the directory, the saved files are called

  • job_collection.yaml
  • training_set.yaml
  • validation_set.yaml
  • engines.yaml (ParAMS also sometimes uses the name job_collection_engines.yaml)
  • parameters.yaml (ParAMS also sometimes uses the name parameter_interface.yaml)

File handling

Open

Use the Open command in the File menu to open a specific file. Alternatively, one can start $AMSBIN/params -gui via the command line and specify the file to open as argument.

The current setup will be cleared (that is, the New command is automatically used).

ParAMS will try to determine what kind of file you have selected to open. It will also read all related files in the same directory having any of the file names listed above.

Merge

When using the Merge command in the File menu, the selected file will be added to the current ParAMS window. Only the selected file will be imported.

Job names and training/validation sets need to be unique. If you import jobs with already existing names, then the new jobs will be renamed by adding a suffix _1, _2 etc.

Save

First it will be suggested to save with the same names as has been used while opening.

If you do not like that (probably you want to save your original files), click ‘No’. You will be asked to select a directory in which to save the files. All files will have their default names.

Revert

If you have unsaved changes, you can revert to the last save point using File -> Revert. There is no other Undo functionality.

Note that for running parametrizations, the table of parameters is updated on-the-fly.

Tables

The Jobs, Training Set, Validation Set, Engines, and Parameters are shown as tables.

Header menus: sort and filter

On top of the tables is an header. All the items in the header are pull-down menus, you can use them to sort the table (by the values in the corresponding column).

For some headers you can also filter by specific types. You can select which types of data to show, one or more types, or all.

Selection

To make selections in the tables use your mouse.

Left click: set the selection to the clicked line,
Shift-left click: extend the selection up to and including the clicked line,
Control-left or right click: toggle the clicked line in/out the selection.

The backspace key: delete the selected lines.
The Escape key: clear the selection.

All lines in the Training Set correspond to one or more systems (molecules). If only one system is selected (or multiple lines with the same system) it is displayed on the left. When a single line with an Energy term is selected, all systems in that energy expression are shown on the left. Use your arrow keys (left and right) to go through the different systems in the energy expression.

You can move the selected line in the tables using up and down arrow keys.

Import reference calculations

The easiest way to import reference results is to either

  • Select the finished calculation in AMSjobs and choose Job → Add to ParAMS
  • In the ParAMS GUI, choose Jobs → Add Jobs and browse to the ams.rkf file from an AMS calculation, the OUTCAR file from a VASP calculation, or the .out file from a Quantum ESPRESSO calculation

This will bring up a results importer dialog, where you can choose for example which frames to import and which properties to extract (energy, forces, charges, …).

In this way, you will add entries to the Jobs, Training Set, and Engines.

For details, see the ParAMS documentation.

You may also import structures from AMSinput or AMSmovie:

  • AMSinput: use the ‘Add To ParAMS’ menu command (in the File menu). This also copies the calculation settings to the added Job (for example, maximum number of geometry optimization iterations).
  • AMSmovie: use the ‘Add To ParAMS’ menu command (in the File menu) to add the current frame. You can do this repeatedly.

If you import from AMSinput or AMSmovie, you will manually need to add the training set entries and reference values.

Jobs

A job is a molecule or a crystal, together with details on how to run a calculation with it. So it might be a single point calculation, a geometry optimization, with extra details (like constraints, maximum number of geometry iterations, …).

If you select a Job, and if it is the only selected system, the molecule will be shown on the left.

You can use the commands in the View menu to change details of what is shown on the left, just as in other AMS-GUI modules. Use the mouse to rotate, zoom, and select atoms.

In a Job line in the table you can see the details of the system:

  • Job ID,
  • Details
  • Associated engines

If you double-click in the Details column, you will be able to modify the job details:

  • Modify the AMS settings, or set them via AMSinput (click the AMSinput button)
  • Modify the reference engine (expert option, use only if you want to use ParAMS to calculate new reference values)
  • Modify the ParAMS engine
  • Set the system charge
  • Some metadata is shown (read-only)

When saving your setup, the jobs are saved to job_collection.yaml.

To make renaming your SystemIDs easier, there are menu commands:

  • Jobs → Prefix JobIDs - apply a prefix to all selected job ids
  • Jobs → Change JobIDs - search and replace in the selected jo bids. You will be asked for a string to search for, and for a string to replace it with.

Training set

A training set also defines the objective function that will be minimized with the parameter optimization. The objective function consists of many terms, each line in the table is one term.

To add terms to your training set, use a Results Importer in most cases (energy, forces, charges, stress tensor). For geometric data (bond lengths, angles, cell parametesr) use the Add menu. Typically the selected systems and the selected atoms are used when adding terms.

As an example, to add a distance terms to your training set:

  1. select the system for which you want to add a distance term,
  2. select two atoms in the system,
  3. use the Bonds command from the Training Set → Add menu.

One distance term will be created in your training set. When you are going to use a distance term your system will need to be a geometry optimization. If it would be a single point calculation, the distances will always remain the same so this term would just be a constant.

The atom selection determines what distance terms are added:

  • If no atoms are selected (thus step 2 is skipped), all bonds found in the system will be added.
  • If two atoms are selected (as in the example): the distance between those atoms will be added (even if they are not bonded directly).
  • If more than two atoms are selected: all selected bonds in the system will be added (thus existing bonds between selected atoms).

If more than one system is selected, the above is repeated for all selected systems. The atom selection criterion will still be used, note that this makes no sense if the systems do not have the same atoms in the same order. This way of handling the atom selection is used for all geometric tests.

In the distance term line you can see:

  • the Type (‘Geometry: distance’),
  • the job id (some name, identical to the name of the selected job),
  • the Weight (W) (to set the relative contribution of this term to the objective function),
  • the Details (the atom numbers and atom types involved in this particular distance),
  • the Value (the reference value, calculated using the current system),
  • the Prediction (when opening a training set after optimizing, the predicted value of this term).
  • the Loss Contribution (when opening a training set after optimizing, the actual contribution to the objective function of this term).

The Loss Contribution column will be filled with results from the training (read from a data_set_predictions.yaml file). It shows the contribution to the objective function for each term in the training set. It is especially convenient if you sort by this column.

Term types that can be added are evident from the Add menu:

  • distances (Bonds)
  • angles
  • dihedrals (Torsions)
  • several types of charges
  • energy
  • force
  • cell parameters

When saving your setup, the training set is saved in a file called ‘training_set.yaml’.

If you double-click in the Details for a training set entry, you can edit

  • The expression (including tab completion for job entries)
  • Sigma
  • Weight
  • The reference value

If the entry is of type Energy, you can also use the Balance function to automatically balance a reaction energy. See the ParAMS tutorials for details.

Validation Set

The Validation Set works just like the Training Set.

Training Set → Generate Validation Set lets you move a random subset of the selected training set entries to the validation set.

Training Set → Move To Validation Set moves the selected training set entries to the validation set.

Training Set → Move To Training Set moves the selected validation set entries to the training set.

Mouse interaction

In addition to the general mouse interactions for selection (already mentioned):

  • Double click item to edit
  • Right click to search for jobids
  • Mouse over to see details, error info etc (you will get a popup if you do not move the mouse).

Editing

To edit something, double click on it (or single click on a selected item). Next you can edit it in place, or in a window that appears.

Depending on what you are editing, the changes you make will be applied to the full selection! So when selecting multiple terms and editing the Weight, that field will be set for all your selected items. Similar, when changing runtype options, like runtype or maximum number of iterations, it applies to all selected systems. Constraints are not propagated as they depend on a particular system.

When editing Job IDs, you can use the tab key to cycle through all Job IDs matching what you have been typing. Add a space to use the current suggestion, or type more letters to narrow the search down. This works when changing Job IDs as well as when editing energy expressions.

Warnings and errors

If you hover with your mouse over a red line you will get extra information on why it is red, what kind of error.

For example, checking a distance for a system which is not optimized is useless, or having systems that are not used in any term. For energy expressions there is a check that the stoichiometry is correct (thus the net amount of all atom types should be zero).

Duplicate lines will also be marked as warning/error.

Reference data

Running reference jobs

If some training set entries do not have reference data, the corresponding reference calculation will be run before the parametrization.

To run, use AMSjobs.

Importing results from reference jobs

Use the ‘Get Data From Ref Jobs’ menu command from the ‘Training Set’ menu to update all selected items in the training set with data from the reference jobs (if they are available). If you have no selection, all items in the training set will be updated.

Parameters

For a description of the parameters, please check the parameter interface documentation.

ReaxFF parameters

lgDispersion, ACKS2 or eReaxFF

The ParAMS GUI currently does not support lgDispersion parametrization.

For ACKS2/eReaxFF parametrization, you must set [ ereaxff acks2 ] as the beginning of the header (Parameters → Edit ReaxFF header). It is not enough to just activate the parameters.

Add a ReaxFF block of parameters

ReaxFF parameters come in blocks: GEN, ATM, BND, ANG, OFD, TOR, and HBD. There can be only 1 GEN block.

To add a block: Parameters → Add ReaxFF block, and type e.g. ANG:H.C.H to add a block of parameters describing the angular H-C-H interaction.

Initialize ReaxFF parameters

You can search through all force fields that come with AMS for a given block of parameters, and copy them into your current project.

  • Select one or more parameters in the bottom table.
  • Parameters → Initialize ReaxFF block…
  • Select which blocks to search for

Edit ReaxFF header

The first line in the ffield.ff file is a header. You can change it with Parameters → Edit ReaxFF header.

Editing parameters and optimization details

Each parameter needs

  • an (initial) value
  • the minimum and maximum allowed values
  • to be either Active (optimized) or Not Active (not optimized)

Select one or more parameters using Left Click and Shift Left Click. The Shift Left Click action will extend the set of selected parameters with all parameters inside a rectangle with respect to the first selected parameter. Click on a selected parameter to edit these values (thus if no selection double click on a parameter).

The parameters are saved to parameters.yaml.

Graphs

On the Graphs panel, you can plot three different graphs simultaneously. Each graph has three drop-down menus:

  • Left: The type of graph (running loss, stats, parameter values, PES scan, correlation plot)
  • Middle: Options (e.g. switch between MAE and RMSE, or select Best Training/Best Validation etc.)
  • Right: Data From. Choose to compare to the initial parameters

All graphs show the output from text files that already exist in the parametrization results directory. You can also save the xy-values using File -> Export Graph as XY, or save the graph image with File -> Save Graph as Image

Settings

On the Settings panel, you can add settings from the yellow drop-down. Click the minus button in front of a setting to remove it (to use the default value).

For details about what the various options can be set to, see the ParAMS documentation.

Results

The Results tab lets you choose from various text output files. All the files exist on disk already.

Info

The Info panel shows details about a selected Job, Training Set/Validation Set entry, or Engine.