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, GFN1-xTB, ASE and No Parameters 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 keep 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.
Search¶
Both tables have a Search field on the bottom. Use cmd/ctrl-F to go there, or click in the field. While you type, the data shown in the corresponding table will automatically be filtered by whatever you type. The spaces in your search string will automatically be replaced by wild-cards.
Selection¶
To make selections in the tables use your mouse.
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:
select the system for which you want to add a distance term,
select two atoms in the system,
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.
ASE Parameters¶
The GUI cannot be used to create ASE parameters. You need to first create the parameter_interface.yaml file and then load that.
The loaded ASE parameters can be modified as usual.
It is easiest to create the file with a Python script. See the ASE Calculator parametrization tutorial.
No Parameters¶
There no parameters to modify in the GUI.
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.