Other new features and fixes¶

reformat¶

The reformat command tells rxffutil to read a (possibly mis-formatted) force-field file from standard input and write it in the format required by the ReaxFF program:

rxffutil reformat < input_ffield_file

The result is written as a ‘ffield’ file in the current directory. The input can be almost free-format but the following points need to be taken into account:

• If you copy-paste force-field parameters from a pdf document (for example, from a publication’s supporting info), then make sure to remove any page numbers that may have been copied together.
• The atom types section header (with the number of atom types in it) must have three comment lines following the line with the number of atom types.
• Likewise, the bond types section must have one comment line following the line with the number of bond types. Any comments provided on input are ignored and the standard comments are written instead.
• Numbers must be separated by at least one space

minmax¶

The minmax command is intended for analyzing existing forcefield files. It will print the number of entries, as well as the minimum, maximum and average values for the given parameters:

rxffutil minmax [--ffdir=/path/to/ff/directory] key ...

Command arguments:

• - -ffdir=/path/to/ff/directory – scan the specified directory for ff files when computing parameter ranges. The $AMSRESOURCES/ForceFields/ReaxFF directory is used if this option is absent.
• key (mandatory) – specifies which parameters to gather data for. Multiple keys may be specified. The syntax of the keys is as follows:
  • gen:i – the i-th general parameter;
  • A:i – the i-th item of the A atom type block;
  • b%AB:i – the i-th item of the A-B bonds block;
  • o%AB:i – the i-th item of the A-B off-diagonal block;
  • v%ABC:i – the i-th item of the A-B-C valence angle block;
  • t%ABCD:i – the i-th item of the A-B-C-D torsion angle block;
  • h%XHY:i – the i-th item of the X-H-Y hydrogen bond block.

The index part of the key (:i) may be omitted, in which case the whole block is considered. In order to match wildcard torsions (indicated by 0 in the ff file) a question mark “?” instead of the atom type may be used. Examples of valid keys:

v%HPtH:1 - first parameter of the H-Pt-H valence angle block
v%HPtH   - all parameters of the H-Pt-H valence angle block
t%?CC?:4 - fourth parameter of the *-C-C-* torsion angle block

Note that some angles may have more than one optimal value (for example 90 and 180 degrees), in which case ReaxFF may have more than one block per key in a force-field file. For such a key, the number of entries may be larger than the number of scanned files. In the following example, the number of entries for a C-O-O-C torsion is larger than that for the C-O bond because twelve force-fields contain two C-O-O-C torsion angles each:

$ rxffutil minmax b%CO:1 t%COOC:1
Key                   N         min         max     average
t%COOC:1             64     -2.0324      3.4682      0.8679
b%CO:1               52     95.6228    197.3588    151.8473

One can see which files contain the given keys using the -vv verbosity option. There are three verbosity levels:

• -v – log ff files as they are opened, read in and parsed;
• -vv – as -v plus print a parameter value for each case of the found key together with the corresponding file and block index within the section;
• -vvv – as -vv plus print a key-block_index pair for every block found when parsing ff files.

For example:

$ rxffutil minmax -vv v%HPtH:1
... [snip] ...
Key                   N         min         max     average
Found v%HPtH:1               95.0000 in c:/adf2018.105/atomicdata/ForceFields/ReaxFF/CHONSFPtClNi.ff block 69
Found v%HPtH:1               57.3916 in c:/adf2018.105/atomicdata/ForceFields/ReaxFF/PtCH.ff block 14
v%HPtH:1              2     57.3916     95.0000     76.1958

pdist¶

The pdist command can be used in addition to minmax to get a better idea about the parameter values distribution:

rxffutil pdist [--ffdir=/path/to/ff/directory] [--npoints=int] key ...

Keys used with the pdist command are required to have a non-empty index part. That is, v%HPtH is not a valid key while v%HPtH:1 is.

The number of points (bins) in the distribution is set by the - -npoints option (20 by default).

params¶

The params command can be used to prepare a params file used by ReaxFF for force-field fitting:

rxffutil params [options] key ...

In additions to - -ffdir, the following options are available:

• - -ff=/path/to/ffield – specify the ffield file for which the params file is to be created. If this option is omitted, the ffield file in he current directory is used. If there is no such file the program will quit.
• - -delta=real – specify a value for the delta (or sigma) column of the params file as a fraction of the corresponding min-max interval. The default value is 0.01.
• The min-max interval for each parameter is determined from parameter values (having the same key) found in the ffdir directory. This range is initially identical to the one printed by the minmax command but it can be modified using the following options:
  • - -scalebound=real – change the parameter range by scaling both boundaries by the specified factor. The boundaries are scaled in such a way that the range is expanded scalebound is greater than 1, or reduced otherwise. In other words, a negative lower bound is multiplied by the factor, while a positive one is divided. Likewise, a positive upper bound is multiplied by the factor, while a negative one is divided by it. This way, the bounds do not change their sign when extending or shrinking the parameter range (the scalebound must be positive);
  • - -scalerange=real may be specified when the - -scalebound option is not used (otherwise it is ignored). If this option is present then the initial range is multiplied by the given factor and the lower and upper bounds are shifted symmetrically. Using this option may change the sign of the parameter boundary, which may lead to undesired consequences;
  • if none of the above options is specified then the lower and upper bounds may be scaled independently using the - -scalemin=real and - -scalemax=real options. When using this option the range can be expanded or shrunk depending on the sign of the boundary value.

For example, to get a params file for optimization of the C-O-O-C torsion angle parameters from the CHO-2016 force-field using MCFFOptimizer one can use the following commands:

$ cp $AMSRESOURCES/ForceFields/ReaxFF/CHO-2016.ff ./ffield
$ rxffutil params --scalebound=1.2 t%COOC:1 t%COOC:2 t%COOC:3 t%COOC:4 t%COOC:5
#     Key          delta         min         max     comment
   6  16   1    0.066007     -2.4389      4.1618     # t%COOC:1 V1
   6  16   2    1.168364    -20.8364     96.0000     # t%COOC:2 V2
   6  16   3    0.030000     -1.8000      1.2000     # t%COOC:3 V3
   6  16   4    0.061995     -8.2829     -2.0833     # t%COOC:4 p_tor1
   6  16   5    0.034717     -3.4800     -0.0083     # t%COOC:5 p_cot1

In this example, the range is expanded by scaling the lower and upper bounds by 20% outwards. Exercise: run this command with and without the - -scalebound option and compare min max values.

When preparing a params file for the CMA-ES optimizer one should use the - -delta option to specify a suitably large initial sigma (typically in the order of 0.1 – 0.25).