3. 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.
• training_set.yaml: Path to the Data Set to be used as a training set during optimization.
• job_collection.yaml: Path to the Job Collection to be used during optimization.

Below is an overview of params commands:

Table 3.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.
clips	Checks whether any of the active parameters are hitting the lower (LR) or upper (UR) bounds by checking the last window iterations from running_active_parameters.txt. 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.
export	Exports the parameterization project into a compressed archive suitable for publication.
genref	Generate reference data given a training_set.yaml and reference_engines.yaml. Store the reference results in the training_set.yaml when done.
makeconf	Create a params.conf.py template in the current working directory.	See below for more details.
optimize	Starts an optimization given the files in the current directory.	Will report an error if no reference data is present in the training_set.yaml.
plot DATFILE	Plot any *.txt 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.
run	Same as optimize, but will try to calculate the reference results if none are present.

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

Table 3.2 Main Script Optional Arguments

Command	Description	Default value
-c / --config	Path to the params configuration file to use	./params.conf.py
--ignore-cache	When calculating reference values, ignore the already existing results from the reference directory and re-run all reference jobs instead	False
-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

See also

Getting Started: Lennard-Jones Potential for Argon

3.1. The Configuration File

When using the main script, a configuration file (default name params.conf.py) containing all definitions of relevant variables needs to be present in the working directory.

3.1.1. Generate a template config file

A template of the config file can always be generated with one of the following commands:

params makeconf
params makeconf -i reaxff
params makeconf -i xtb
params makeconf -i lennardjones

The config file is meant to encourage users to experiment with different settings based on the extensive comments provided. The bare minimum that needs to be set is a single parameter_interface variable. All other settings are optional (with the exception mentioned above).

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.

3.1.2. List of variables in params.conf.py

Variable	Description	Default
batch_size	see Optimization
callbacks	list of Callback	None
constraints	list of Constraint	None
data_set_names	see Optimization
eval_every	integer how frequently to evaluate validation set	1
job_collection	path to job_collection file	‘job_collection.yaml’
logger_every	integer how often to log output	10
loss	string describing a Loss	‘sse’
max_evaluations	integer	None
maxjobs	see Optimization
maxjobs_shuffle	see Optimization
more_extractors	path to directory with extractors	‘extractors/’ if it exists
optimizer	Optimizer	CMAOptimizer()
parallel	ParallelLevels	None (good default)
plams_workdir_path	path	None
reference_engines	list to engine collection file	‘reference_engines.yaml’ if it exists
reference_jobrunner	JobRunner	None
skip_x0	boolean whether to skip the initial evaluation	False
timeout	integer in seconds	None
training_set	path to training set file	‘training_set.yaml’ (or .pkl or .pkl.gz)
use_pipe	see Optimization
validation	fraction to use for validation set	None
validation_set	path to validation set file	‘validation_set.yaml’ if it exists (or .pkl or pkl.gz)