4. ParAMS Main Script

The ParAMS main script allows command-line execution of most common steps during an optimization with no to minimal coding effort with the help of the params command.

Note

For any of the main params commands to work, at least the following files need to present in the working directory:

  • params.conf.py: The configuration file that will be used by the main script.
    Contains definitions of the parameter interface, optimizer and possibly other user-defined options like file locations or callbacks.
  • trainingset.yaml: Path to the Data Set to be used as a training set during optimization.
  • jobcollection.yaml: Path to the Job Collection to be used during optimization.

All of the above can have a user-defined path and filename: The params.conf.py through the --config argument (see below), the YAML files through the definition in the configuration file.

Below is an overview of currently supported commands by params:

Table 4.1 Main Script Commands Overview
Command Description Comments
-h / --help Print an overview of all commands and their descriptions. Can be used in combination with any other command.
check Check the current working directory for consistency.
Load all files and report any possible issues.		  
genref Generate reference data given a trainingset.yaml and reference_engines.yaml.
Store the reference results in the trainingset.yaml when done.		  
optimize Starts an optimization given the files in the current directory. Will report an error if no reference data is present
in the trainingset.yaml.
run Same as above, but will try to calculate the reference results
if none are present.		  
makeconf Create a params.conf.py template in the current working directory. See below for more details.
export Exports the parameterization project into a compressed archive
suitable for publication.		  
plot DATFILE Plot any *.dat file produced by the Logger callback. Does not require any of the files mentioned above to be present.
For optional arguments, see params plot -h.
printfx [DIRS] Prints the results from multiple optimization directories. Works only with optimizations that used the Logger callback.
Does not require any of the files mentioned above to be present.
clips Checks whether any of the active parameters are hitting the lower (LR) or upper (UR) bounds by checking the last window iterations from trainingset_history.dat.
The clipping criterium is determined by mu - a*sigma < 0 and mu + a*sigma > 1 respectively.		 Has to be called in the optimization directory.
Does not require any of the files mentioned above to be present.

In addition to the above commands, the following optional arguments are available:

Table 4.2 Main Script Optional Arguments
Command Description Default value
-c / --config Path to the params configuration file to use ./params.conf.py
-o / --optdir Path to the optimization working directory ./optimization
--replace By default, if an optimization working directory already exists,
a suffix will be appended to the new directory. Use this argument to
override this behavior and replace the existing directory		 False
-r / --ref-cache When calculating reference values, can be used to load previously
calculated results from this directory		 ./reference_cache
--ignore-cache When calculating reference values, ignore the already existing
results from the reference directory and re-run all reference jobs instead		 False

See also

For a working example of the main script, see Refitting HF Charges with the ACKS2 Model.

4.1. The Configuration File

When using the main script, a configuration (config) file containing all definitions of relevant variables needs to be present in the working directory. A template of the config file can always be generated with params makeconf or, if it is clear which parameter interface needs optimization, params makeconf -i INTERFACE, where INTERFACE can currently be {reaxff, xtb, lennardjones}.

The config file is meant to encourage users to experiment with different settings based on the extensive comments provided, however, the bare minimum that needs to be set is a single interface variable, all other settings are optional (with the exception mentioned above). However, more advanced users can make use of the fact, that the config file is executed as a Python script whenever params is called, meaning that it can also contain more advanced workflows that need execution before an optimization.

Warning

Be cautious when using configuration files from a party that you do not trust: The config file is executed as a Python script and could possibly contain malicious code.