7. ParAMS Main Script

7.1. ParAMS 2023 main script

The ParAMS main script $AMSBIN/params reads the input file params.in and executes the Task given in that file.

You should normally just run $AMSBIN/params without any other command-line options. However, below are some special subprograms and command-line flags that you may find useful:

Table 7.1 Main Script Commands Overview

Command

Description

-h / --help

Print an overview of all commands and their descriptions.

check

Check the current working directory for consistency.
Load all files and report any possible issues.

convert

Convert old params.conf.py to params.in. Usage:
$AMSBIN/params convert -c path/to/params.conf.py -o path/to/save/params.in

gui

Start the GUI

plot DATFILE

Plot any *.txt file produced by an optimization.

Table 7.2 Main Script Optional Arguments

Command

Description

Default value

-c / --config

Path to the params configuration file to use
(for use only together with convert)

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

7.2. ParAMS 2022 Configuration File

Important

The configuration file params.conf.py is no longer used in ParAMS 2023. The information is provided here for users of ParAMS 2022.

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.

To run ParAMS 2022 (not 2023, see above):

$AMSBIN/params optimize

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

7.2.2. List of variables in params.conf.py

Variable

Description

Default

batch_size

see Optimization

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)