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.


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.


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.

   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".


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.
