Keywords
The following keywords can be used to control RuNNer
by including them
in the input.nn
file. Some keywords are mandatory and RuNNer
will
stop with an error message if they are not specified. For other
keywords, if omitted, reasonable default values will be set by RuNNer
.
In any case the specific settings can be found in the RuNNer
output
file. In general the order of the keywords in the input.nn
file is
arbitrary and dependencies will be handeled by RuNNer
by searching the
input.data
file in the right order. Several combinations of keywords
may result in contradictory instructions for RuNNer
and cannot be
executed. During initialization RuNNer
performs a set of checks to
identify such combinations and may either try to correct the settings
for the current run (the input.nn
file is not modified!), in this case
a WARNING is issued and the used settings are written in the output
file. Please regularly check your output file for these warnings. In
case of unresolvable conflicts RuNNer
may stop with an ERROR message.
Due to the large number of possible combinations of keywords there is,
however, a certain probability that some potentially confliciting
keyword combinations will not be detected in the present version (any
report about this is highly appreciated).
Alphabetical List of Keywords
Please be aware that only a few of the available keyword will be needed regularly, and many keyword refer to experimental features or features, which have not been fully implemented yet. The following list of symbols can be used to assess the relevance of a specific keyword:
Legend
++ = very important keyword (frequently used).
+ = important keyword (can be useful).
* = experimental feature (usefulness unclear).
- = not yet fully implemented, probably not working.
-- = deprecated
analyze_composition
Mode 1: • Mode 2: • Mode 3:
Print detailed information about the element composition of the data set in
input.data
.
Format: analyze_composition
(logical
, default: True
)
This keyword does not have any further options.
analyze_error
Mode 1: • Mode 2: • Mode 3:
Print detailed information about the training error.
Format: analyze_error
(logical
, default: False
)
This keyword does not have any further options.
analyze_error_charge_step
Mode 1: • Mode 2: • Mode 3:
When a detailed analysis of the training error with
analyze_error
is performed, this keyword allows for the definition of the interval in which
atoms with the same charge error are grouped together.
Format: analyze_error_charge_step a0
a0
: (real
, default:0.001
)- The interval in which atoms with the same charge error are grouped together (unit: electron charge).
Hint
For this keyword to take effect, please also specify
analyze_error
.
analyze_error_energy_step
Mode 1: • Mode 2: • Mode 3:
When a detailed analysis of the training error with
analyze_error
is performed, this keyword allows for the definition of the interval in which
atoms with the same energy error are grouped together.
Format: analyze_error_energy_step a0
a0
: (real
, default:0.01
)- The interval in which atoms with the same energy error are grouped together (unit: Hartree).
Hint
For this keyword to take effect, please also specify
analyze_error
.
analyze_error_force_step
Mode 1: • Mode 2: • Mode 3:
When a detailed analysis of the training error with
analyze_error
is performed, this keyword allows for the definition of the interval in which
atoms with the same total force error are grouped together.
Format: analyze_error_force_step a0
a0
: (real
, default:0.01
)- The interval in which atoms with the same force error are grouped together (unit: Hartree per Bohr).
Hint
For this keyword to take effect, please also specify
analyze_error
.
atom_energy
++
Mode 1: • Mode 2: • Mode 3:
Specification of the energies of the free atoms. This keyword must be used for
each element if the keyword
remove_atom_energies
is used.
In runner_mode
1
the atomic energies are removed from the total energies, in
runner_mode
3
the atomic energies are added to the fitted energy to yield the correct total
energy. Internally, RuNNer
always works with binding energies, if
remove_atom_energies
is specified.
Format: atom_energy element energy
element
: (string
)- Element symbol.
energy
: (real
, default:0.0
)- Atomic reference energy in Hartree.
Example
atom_energy Zn -1805.01857147
Hint
For this keyword to take effect, please also specify
remove_atom_energies
.
biasweights_max
Mode 1: • Mode 2: • Mode 3:
RuNNer
allows for a separate random initialization of the bias weights at the
beginning of
runner_mode
2
through
separate_bias_ini_short
.
In that case the bias weights are randomly initialized on an interval between
biasweights_max
and biasweights_min
.
Format: biasweights_max a0
a0
: (real
, default:+1.0
)- The maximum value that is assigned to bias weights during initialization of the weights.
Hint
For this keyword to take effect please also specify
separate_bias_ini_short
.
biasweights_min
Mode 1: • Mode 2: • Mode 3:
RuNNer
allows for a separate random initialization of the bias weights at the
beginning of
runner_mode
2
through
separate_bias_ini_short
.
In that case the bias weights are randomly initialized on an interval between
biasweights_max
and biasweights_min
.
Format: biasweights_min a0
a0
: (real
, default:-1.0
)- The maximum value that is assigned to bias weights during initialization of the weights.
Hint
This keyword does not have any effect unless
separate_bias_ini_short
is specified too.
bond_threshold
++
Mode 1: • Mode 2: • Mode 3:
Threshold for the shortest bond in the structure in Bohr units. If a shorter
bond occurs RuNNer
will stop with an error message in
runner_mode
2 and 3. In
runner_mode
1 the
structure will be eliminated from the data set.
Format: bond_threshold a0
a0
: (real
, default:0.5
)- The minimum bond length between any two atoms in the structure (unit: Bohr).
calculate_final_force
Mode 1: • Mode 2: • Mode 3:
Print detailed information about the forces in the training and testing set at the end of the NNP training process.
Format: calculate_final_force
(logical
, default: False
)
This keyword does not have any further options.
Hint
This keyword is only necessary if the
usage of force fitting has not been requested in
runner_mode
2
with the keyword
use_short_forces
.
calculate_forces
++
Mode 1: • Mode 2: • Mode 3:
Calculate the atomic forces in
runner_mode
3 and
write them to the files
runner.out
and
nnforces.out
.
Format: calculate_forces
(logical
, default: False
)
This keyword does not have any further options.
calculate_hessian
++
Mode 1: • Mode 2: • Mode 3:
Calculate the Hessian matrix in
runner_mode
3.
Format: calculate_hessian
(logical
, default: False
)
This keyword does not have any further options.
calculate_stress
++
Mode 1: • Mode 2: • Mode 3:
Calculate the stress tensor (only for periodic systems) in
runner_mode
3 and
write it to the files runner.out
and
nnstress.out
.
This is at the moment only implemented for the short range part and for the
contributions to the stress tensor through vdW interactions.
Format: calculate_stress
(logical
, default: False
)
This keyword does not have any further options.
center_symmetry_functions
++
Mode 1: • Mode 2: • Mode 3:
Shift the symmetry function values individually for each symmetry function such that the average is moved to zero. This may have numerical advantages, because zero is the center of the non-linear regions of most activation functions.
Format: center_symmetry_functions
(logical
, default: False
)
This keyword does not have any further options.
charge_error_threshold
++
Mode 1: • Mode 2: • Mode 3:
Threshold value for the error of the charges in units of the RMSE of the previous epoch. A value of 0.3 means that only charges with an error larger than 0.3RMSE will be used for the weight update. Large values (about 1.0) will speed up the first epochs, because only a few points will be used.
Format: charge_error_threshold a0
a0
: (real
, default:0.0
)- Fraction of charge RMSE that a charge needs to reach to be used in the weight update.
Hint
For this keyword to take effect, you need to use the Kalman filter algorithm.
charge_fraction
++
Mode 1: • Mode 2: • Mode 3:
Defines the random fraction of atomic charges used for fitting the electrostatic
weights in
runner_mode
2.
Format: charge_fraction a0
a0
: (real
, default:0.0
)- Fraction of atomic charges used for fitting of the electrostatic weights. 100% = 1.0.
Hint
This keyword is used in case of
electrostatic_type
1 only.
charge_group
++
Mode 1: • Mode 2: • Mode 3:
Do not update the electrostatic NN weights after the presentation of an individual atomic charge, but average the derivatives with respect to the weights over the specified number of charges for each element.
Format: charge_group i0
i0
: (integer
, default:1
)- Number of atomic charges per group. The maximum is given by
points_in_memory
.
check_forces
*
Mode 1: • Mode 2: • Mode 3:
This keyword allows to check if the sum of all NN force vectors is zero, It is for debugging purposes only, but does not cost much CPU time.
Format: check_forces
(logical
, default: False
)
This keyword does not have any further options.
check_input_forces
*
Mode 1: • Mode 2: • Mode 3:
Check, if the sum of all forces of the training structures is sufficiently close to the zero vector.
Format: check_input_forces a0
a0
: (real
, default:0.0
)- Threshold for the absolute value of the sum of all force vectors per atom.
Source variables lcheckinputforce
and inputforcethreshold
cutoff_type
++
Mode 1: • Mode 2: • Mode 3:
This keyword determines the cutoff function to be used for the symmetry functions.
Format: cutoff_type i0
i0
: (integer
, default:1
)-
Threshold for the absolute value of the sum of all force vectors per atom. Can be one of:
-
0
:- Hard function: \(1\)
-
1
:- Cosine function: \(\frac{1}{2}[\cos(\pi x)+ 1]\)
-
2
:- Hyperbolic tangent function 1: \(\tanh^{3} (1-\frac{R_{ij}}{R_{\mathrm{c}}})\)
-
3
:- Hyperbolic tangent function 2: \((\frac{e+1}{e-1})^3 \tanh^{3}(1-\frac{R_{ij}}{R_{\mathrm{c}}})\)
-
4
:- Exponential function: \(\exp(1-\frac{1}{1-x^2})\)
-
5
:- Polynomial function 1: \((2x -3)x^2+1\)
-
6
:- Polynomial function 2: \(((15-6x)x-10)x^3+1\)
-
7
:- Polynomial function 3: \((x(x(20x-70)+84)-35)x^4+1\)
-
8
:- Polynomial function 4: \((x(x(x(315-70x)-540)+420)-126)x^5+1\)
-
data_clustering
*
Mode 1: • Mode 2: • Mode 3:
Performs an analysis of all symmetry function vectors of all atoms and groups
the atomic environments to clusters with a maximum distance of
a0
between the symmetry function vectors. If
a1
is larger than 1.0 the assignment of each atom will be
printed.
Format: data_clustering a0 a1
a0
: (real
, default:1.0
)- Maximum distance between the symmetry function vectors of two clusters of atomic environments.
a1
: (real
, default:0.0
)- If
a1 > 1.0
, print the group that each atom has been assigned to.
Source variables
ldataclustering
,
dataclusteringthreshold1
and dataclusteringthreshold2
debug_mode
*
Mode 1: • Mode 2: • Mode 3:
If switched on, this option can produce a lot of output and is meant for debugging new developments only!!!
Format: debug_mode
(logical
, default: False
)
This keyword does not have any further options.
detailed_timing
-
Mode 1: • Mode 2: • Mode 3:
Write detailed timing information for the individual parts of RuNNer
at the end of the run. This feature has to be used with some care because often
the implementation of the time measurement lacks behind in code development.
Format: detailed_timing
(logical
, default: False
)
This keyword does not have any further options.
detailed_timing_epoch
-
Mode 1: • Mode 2: • Mode 3:
Write detailed timing information in each epoch in
runner_mode
2.
This feature has to be used with some care because often the implementation of
the time measurement lacks behind in code development.
Format: detailed_timing_epoch
(logical
, default: False
)
This keyword does not have any further options.
detect_saturation
Mode 1: • Mode 2: • Mode 3:
For each training epoch, checks whether the value of a node in any hidden layer
exceeds
saturation_threshold
and prints a warning.
Format: detect_saturation
(logical
, default: False
)
This keyword does not have any further options.
Hint
For this keyword to take effect, please also use
saturation_threshold
.
Hint
Please note that this keyword will only work for three hidden layers or less.
dynamic_force_grouping
Mode 1: • Mode 2: • Mode 3:
Do not update the short-range NN weights after the presentation of an
individual atomic force vector, but average the derivatives with respect to the
weights over the number of force vectors for each element specified by
short_force_group
Format: dynamic_force_grouping
(logical
, default: False
)
This keyword does not have any further options.
Hint
For this keyword to take effect, please also use
short_force_group
.
electrostatic_type
++
Mode 1: • Mode 2: • Mode 3:
This keyword determines the cutoff function to be used for the symmetry functions.
Format: electrostatic_type i0
i0
: (integer
, default:1
)-
Threshold for the absolute value of the sum of all force vectors per atom. Can be one of:
-
1
:- There is a separate set of atomic NNs to fit the atomic charges as a function of the chemical environment.
-
2
:- The atomic charges are obtained as a second output node of the short range atomic NNs. This is not yet implemented.
-
3
:- Element-specific fixed charges are used that are specified in the
input.nn
file by the keywordfixed_charge
.
-
4
:- The charges are fixed but can be different for each atom in the
system. They are specified in the file
charges.in
.
-
element_activation_electrostatic
+
Mode 1: • Mode 2: • Mode 3:
Set the activation function for a specified node of a specified element in the
electrostatic NN. The default is set by the keyword
global_activation_electrostatic
.
Format: element_activation_electrostatic element layer node type
element
: (character
)- The periodic table symbol of the element whose atomic NN the activation function shall be applied to.
layer
: (integer
)- The number of the layer of the target node.
node
: (integer
)- The number of the target node in layer
layer
. type
: (character
)- The kind of activation function. Options are listed under
global_activation_short
.
Source array actfunc_elec(maxnodes_elec, maxnum_layers_elec, nelem)
Example
The line
element_activation_electrostatic Zn 2 1 s
will set the activation function for the Zn electrostatic NN for node 1 in layer 2 to a sigmoid function.
element_activation_pair
Mode 1: • Mode 2: • Mode 3:
Set the activation function for a specified node of a specified element pair in
the pairwise NN. The default is set by the keyword
global_activation_pair
.
Format: element_activation_pair element element layer node type
element
: (character
)- The periodic table symbol of the first pair element whose short-range pair NN the activation function shall be applied to.
element
: (character
)- The periodic table symbol of the second element in the pair whose short-range pair NN the activation function shall be applied to.
layer
: (integer
)- The number of the layer of the target node.
node
: (integer
)- The number of the target node in layer
layer
. type
: (character
)- The kind of activation function. Options are listed under
global_activation_short
.
Source array actfunc_short_pair(maxnodes_short_pair,maxnum_layers_short_pair,npairs)
Example
The line
element_activation_pair Zn Zn 2 1 s
will set the activation function for the Zn Zn short-range pair NN for node 1 in layer 2 to a sigmoid function.
Hint
This keyword only takes effect if
nn_type_short
is set to 2.
element_activation_short
+
Mode 1: • Mode 2: • Mode 3:
Set the activation function for a specified node of a specified element in the
short range NN. The default is set by the keyword
global_activation_short
.
Format: element_activation_short element layer node type
element
: (character
)- The periodic table symbol of the element whose atomic NN the activation function shall be applied to.
layer
: (integer
)- The number of the layer of the target node.
node
: (integer
)- The number of the target node in layer
layer
. type
: (character
)- The kind of activation function. Options are listed under
global_activation_short
.
Source array actfunc_short(maxnodes_short, maxnum_layers_short, nelem)
Example
The line
element_activation_electrostatic Zn 2 1 s
will set the activation function for the Zn short-range NN for node 1 in layer 2 to a sigmoid function.
element_decoupled_forces_v2
+
Mode 1: • Mode 2: • Mode 3:
This is a more sophisticated version of the element decoupled Kalman filter for
force fitting (switched on by the keyword
element_decoupled_kalman
).
Format: element_decoupled_forces_v2
(logical
, default: False
)
This keyword does not have any further options.
element_decoupled_kalman
+
Mode 1: • Mode 2: • Mode 3:
Use the element decoupled Kalman filter for the short range energy and force
update (if use_short_forces
is switched on). This is implemented only for the atomic energy case. A more
sophisticated algorithm for the force fitting can be activated by using
additionally the keyword
element_decoupled_forces_v2
.
One important parameter for force fitting is
force_update_scaling
,
which determines the magnitude of the force update compared to the energy update.
Usually 1.0 is a good default value.
Format: element_decoupled_kalman
(logical
, default: False
)
This keyword does not have any further options.
element_hidden_layers_electrostatic
+
Mode 1: • Mode 2: • Mode 3:
Overwrite the global default number of hidden layers given by
global_hidden_layers_electrostatic
for a specific element. Just a reduction of the number of hidden layers is
possible.
.
Format: element_hidden_layers_electrostatic element layers
element
: (character
)- The periodic table symbol of the element whose atomic NN hidden layer number will be set.
layers
: (integer
)- The number of hidden layers for this element.
Example
element_hidden_layers_electrostatic Zn 1
will reduce the number of hidden layers for the electrostatic NN of the element Zn to 1.
element_hidden_layers_pair
Mode 1: • Mode 2: • Mode 3:
Overwrite the global default number of hidden layers given by
global_hidden_layers_pair
for a specific element. Just a reduction of the number of hidden layers is
possible.
.
Format: element_hidden_layers_pair element element layers
element
: (character
)- The periodic table symbol of the first pair element whose short-range pair NN hidden layer number will be set.
element
: (character
)- The periodic table symbol of the second pair element whose short-range pair NN hidden layer number will be set.
layers
: (integer
)- The number of hidden layers for this element pair.
Example
element_hidden_layers_pair Zn Zn 1
will reduce the number of hidden layers for the short-range pair NN of the element Zn Zn to 1.
element_hidden_layers_short
+
Mode 1: • Mode 2: • Mode 3:
Overwrite the global default number of hidden layers given by
global_hidden_layers_short
for a specific element. Just a reduction of the number of hidden layers is
possible.
Format: element_hidden_layers_short element layers
element
: (character
)- The periodic table symbol of the element whose atomic NN hidden layer number will be set.
layers
: (integer
)- The number of hidden layers for this element.
Example
element_hidden_layers_short Zn 1
will reduce the number of hidden layers for the short-range NN of the element Zn to 1.
element_nodes_electrostatic
+
Mode 1: • Mode 2: • Mode 3:
Overwrite the global default number of nodes in the specified hidden layer of an
elecrostatic NN given by
global_nodes_electrostatic
for a specific element.
Just a reduction of the number of nodes is possible.
Format: element_nodes_electrostatic element layer i0
element
: (character
)- The periodic table symbol of the element.
layer
: (integer
)- The number of the hidden layer for which the number of nodes is set.
i0
: (integer
, default:global_nodes_electrostatic
)- The number of nodes to be set.
Example
element_nodes_electrostatic Zn 1 9
will reduce the number of nodes in hidden layer 1 of the electrostatic NN for the element Zn to 9.
element_nodes_pair
Mode 1: • Mode 2: • Mode 3:
Overwrite the global default number of nodes in the specified hidden layer of a
pair NN given by
global_nodes_pair
for a specific element.
Just a reduction of the number of nodes is possible.
Format: element_nodes_pair element element layer i0
element
: (character
)- The periodic table symbol of the first pair element.
element
: (character
)- The periodic table symbol of the second pair element.
layer
: (integer
)- The number of the hidden layer for which the number of nodes is set.
i0
: (integer
, default:global_nodes_pair
)- The number of nodes to be set.
Example
element_nodes_pair Zn Zn 1 9
will reduce the number of nodes in hidden layer 1 of the pair NN for the element pair Zn Zn to 9.
element_nodes_short
+
Mode 1: • Mode 2: • Mode 3:
Overwrite the global default number of nodes in the specified hidden layer of an
short-range atomic NN given by
global_nodes_short
for a specific element.
Just a reduction of the number of nodes is possible.
Format: element_nodes_short element layer i0
element
: (character
)- The periodic table symbol of the element.
layer
: (integer
)- The number of the hidden layer for which the number of nodes is set.
i0
: (integer
, default:global_nodes_short
)- The number of nodes to be set.
Example
element_nodes_short Zn 1 9
will reduce the number of nodes in hidden layer 1 of the short-range atomic NN for the element Zn to 9.
element_pairsymfunction_short
Mode 1: • Mode 2: • Mode 3:
Set the symmetry functions for one element pair for the short-range pair NN.
The variables are the same as for the keyword
global_pairsymfunction_short
and are explained in more detail there.
Format: element_pairsymfunction_short element element type [parameters] cutoff
element
: (character
)- The periodic table symbol of the first pair element.
element
: (character
)- The periodic table symbol of the second pair element.
type [parameters]
: (integer [reals]
)- The type of symmetry function to be used. Different
parameters
have to be set depending on the choice oftype
. They are explained underglobal_symfunction_short
. cutoff
: (real
, default:None
)- The symmetry function cutoff radius (unit: Bohr).
elements
++
Mode 1: • Mode 2: • Mode 3:
The element symbols of all elements in the system in arbitrary order.
The number of specified elements must fit to the value of the keyword
number_of_elements
.
Format: elements element [element...]
element [element...]
: (character [characters]
)- The periodic table symbols of all the element in the system.
element_symfunction_electrostatic
+
Mode 1: • Mode 2: • Mode 3:
Set the symmetry functions for one element with all possible neighbor element
combinations for the electrostatics NN. The variables are the same as for the
keyword
global_symfunction_electrostatic
and are explained in more detail there.
Format: element_symfunction_electrostatic element type [parameters] cutoff
element
: (character
)- The periodic table symbol of the element.
type [parameters]
: (integer [reals]
)- The type of symmetry function to be used. Different
parameters
have to be set depending on the choice oftype
. They are explained underglobal_symfunction_short
. cutoff
: (real
, default:None
)- The symmetry function cutoff radius (unit: Bohr).
element_symfunction_short
+
Mode 1: • Mode 2: • Mode 3:
Set the symmetry functions for one element with all possible neighbor element
combinations for the short-range NN. The variables are the same as for the
keyword
global_symfunction_short
and are explained in more detail there.
Format: element_symfunction_short element type [parameters] cutoff
element
: (character
)- The periodic table symbol of the element.
type [parameters]
: (integer [reals]
)- The type of symmetry function to be used. Different
parameters
have to be set depending on the choice oftype
. They are explained underglobal_symfunction_short
. cutoff
: (real
, default:None
)- The symmetry function cutoff radius (unit: Bohr).
enable_on_the_fly_input
Mode 1: • Mode 2: • Mode 3:
Read modified input.nn
parameters during
the fitting procedure from a file labeled input.otf
.
Format: enable_on_the_fly_input
(logical
, default: False
)
This keyword does not have any further options.
energy_threshold
++
Mode 1: • Mode 2: • Mode 3:
Set an energy threshold for fitting data. This keyword is only used in
runner_mode
1
for the decision if a point should be used in the training or
test set or if it should be eliminated because of its high energy.
Format: energy_threshold a0
a0
: (real
, default:0.0
)- Threshold for the total energy of a structure (unit: Hartree per atom).
Source variables lfitethres
and fitethres
enforce_max_num_neighbors_atomic
Mode 1: • Mode 2: • Mode 3:
Set an upper threshold for the number of neighbors an atom can have.
Format: enforce_max_num_neighbors_atomic i0
i0
: (integer
, default:None
)- Maximum number of neighbors for one atom.
Source variables lenforcemaxnumneighborsatomic
and max_num_neighbors_atomic_input
enforce_totcharge
++
Mode 1: • Mode 2: • Mode 3:
Rescale the NN atomic charges to get a neutral system. An overall neutral system is required for a correct calculation of the Ewald sum for periodic systems. The additional error introduced by rescaling the NN charges is typically much smaller than the fitting error, but this should be checked.
Format: enforce_totcharge i0
i0
: (integer
, default:0
)- Switch charge rescaling on (
1
) or off (0
).
environment_analysis
Mode 1: • Mode 2: • Mode 3:
Print a detailed analysis of the atomic environments in
trainstruct.data
and teststruct.data
.
Format: environment_analysis
(logical
, default: False
)
This keyword does not have any further options.
epochs
++
Mode 1: • Mode 2: • Mode 3:
The number of epochs for fitting. If 0
is specified, RuNNer
will calculate
the error and terminate without adjusting weights.
ewald_alpha
++
Mode 1: • Mode 2: • Mode 3:
Parameter \(\alpha\) for the Ewald summation. Determines the accuracy of the
electrostatic energy and force evaluation for periodic systems together with
ewald_kmax
and
ewald_cutoff
.
Recommended settings are
(ewald_alpha
= 0.2 and
ewald_kmax
= 10) or
(ewald_alpha
= 0.5 and
ewald_kmax
> 20 ) and a
sufficiently large
ewald_cutoff
.
Format: ewald_alpha a0
a0
: (real
, default:0.0
)- The value of the parameter \(\alpha\) for the Ewald summation.
ewald_cutoff
++
Mode 1: • Mode 2: • Mode 3:
Parameter for the Ewald summation. Determines the accuracy of the
electrostatic energy and force evaluation for periodic systems together with
ewald_kmax
and
ewald_alpha
.
Must be chosen sufficiently large because it determines the number of neighbors
taken into account in the real space part of the Ewald summation (e.g. 15.0 Bohr)
Format: ewald_cutoff a0
a0
: (real
, default:0.0
)- The cutoff radius if the Ewald summation (unit: Bohr).
ewald_kmax
++
Mode 1: • Mode 2: • Mode 3:
Parameter for the reciprocal space part of the Ewald summation.
Determines the accuracy of the electrostatic energy and force evaluation for
periodic systems together with
ewald_alpha
and
ewald_cutoff
.
Recommended settings are
(ewald_alpha
= 0.2 and
ewald_kmax
= 10) or
(ewald_alpha
= 0.5 and
ewald_kmax
> 20 ) and a
sufficiently large
ewald_cutoff
.
Format: ewald_kmax i0
i0
: (integer
, default:0
)- k-space cutoff for the Ewald summation.
ewald_prec
++
Mode 1: • Mode 2: • Mode 3:
This parameter determines the error tolerance in electrostatic energy and force
evaluation for periodic systems when Ewald Summation is used. RuNNer
will
automatically choose the optimized
ewald_alpha
,
ewald_kmax
, and
ewald_cutoff
.
Format: ewald_prec a0
a0
: (real
, default:-1.0
)- The desired precision of the Ewald summation. Recommended values are \(10^{-5}\) to \(10^{-6}\).
Hint
This keyword is mandatory if 3G- and 4G-HDNNPs are used.
find_contradictions
+
Mode 1: • Mode 2: • Mode 3:
This keyword can be used in
runner_mode
2
to test if the symmetry functions are able to distinguish different atomic
environments sufficiently. If two atomic environments of a given element are
very similar, they will result in very similar symmetry function vectors.
Therefore, the length of the difference vector
(\(N\) runs over all individual symmetry functions) will be close to zero. If the environments are really similar, the absolute forces acting on the atom should be similar as well, which is measured by
If the forces are different (\(\Delta F >\) a1
) but the symmetry
functions similar (\(\Delta G <\) a0
) for an atom pair, a
message will be printed in the output file. The optimal choices for
a0
and a1
are system dependent and should be selected such that only the
most contradictory data is found. It is not recommended to keep this keyword
switched on routinely, because it requires substantial CPU time.
Format: find_contradictions a0 a1
a0
: (real
, default:0.0
)- Symmetry function threshold \(\Delta G\).
a1
: (real
, default:0.0
)- Force threshold \(\Delta F\).
Source variables lfindcontradiction
,
deltagthres
, and
deltafthres
fitmode
--
Request batch fitting for the short-range atomic NN. This keyword is not well tested and has been deprecated.
fitting_unit
++
Mode 1: • Mode 2: • Mode 3:
Set the energy unit that is printed to the output files during training in
runner_mode
2.
Format: fitting_unit i0
i0
: (integer
, default:1
)-
Switch for different energy units. Can be one of:
-
1
:- Unit:
eV
. The energy RMSE and MAD in the output file are given in eV/atom, the force error is given in eV/Bohr.
-
2
:- Unit:
Ha
. The energy RMSE and MAD in the output file are given in Ha/atom, the force error is given in Ha/Bohr.
-
fix_weights
*
Mode 1: • Mode 2: • Mode 3:
Do not optimize all weights, but freeze some weights, which are
specified by the keywords
weight_constraint
and
weighte_constraint
.
Format: fix_weights
(logical
, default: False
)
This keyword does not have any further options.
Hint
See also
weight_constraint
and
weighte_constraint
.
fixed_charge
*
Mode 1: • Mode 2: • Mode 3:
Use a fixed charge for all atoms of the specified element independent of the chemical environment.
Format: fixed_charge element a0
element
: (character
)- The periodic table symbol of the element.
a0
: (real
, default:0.0
)- The fixed charge of all atoms of this element (unit: electron charge).
Example
fixed_charge Zn 2.0
Hint
For using fixed charges the keyword
use_fixed_charges
must be set.
fixed_gausswidth
++
Mode 1: • Mode 2: • Mode 3:
This keyword specifies the Gaussian width for calculating the charges and electrostatic energy and forces in 4G-HDNNPs.
Format: fixed_gausswidth element a0
element
: (character
)- The periodic table symbol of the element.
a0
: (real
, default:-99.0
)- The Gaussian width for all atoms of this element (unit: Bohr).
Example
fixed_gausswidth Zn 2.0
will set the Gaussian width of all Zn atoms to 2.0 Bohr.
fixed_short_energy_error_threshold
Mode 1: • Mode 2: • Mode 3:
Only consider points in the weight update during
runner_mode
2 for which the
absolute error of the total energy is higher than
fixed_short_energy_error_threshold
.
Format: fixed_short_energy_error_threshold a0
a0
: (real
, default:0.0
)- The lower threshold for the absolute error of the total energy.
Source variables lfixederrore
and
fixederrore
fixed_short_force_error_threshold
Mode 1: • Mode 2: • Mode 3:
Only consider points in the weight update during
runner_mode
2 for which the
absolute error of the total force is higher than
fixed_short_force_error_threshold
.
Format: fixed_short_force_error_threshold a0
a0
: (real
, default:0.0
)- The lower threshold for the absolute error of the total force.
Source variables lfixederrorf
and
fixederrorf
force_grouping_by_structure
Mode 1: • Mode 2: • Mode 3:
Do not update the short-range NN weights after the presentation of an individual atomic force vector, but average the derivatives with respect to the weights over the number of force vectors per structure.
Format: force_grouping_by_structure
(logical
, default: False
)
This keyword does not have any further options.
force_threshold
++
Mode 1: • Mode 2: • Mode 3:
Set a force threshold for fitting data. If
any force component of a structure in the reference set is larger than
a0
then the point is not used and eliminated from the data set.
Format: force_threshold a0
a0
: (real
, default:0.0
)- The upper threshold for force components (unit: Ha/Bohr)
Source variables lfitfthres
and
fitfthres
force_update_scaling
+
Mode 1: • Mode 2: • Mode 3:
Since for a given structure the number of forces is much larger than the number of energies, the force updates can have a dominant influence on the fits. This can result in poor energy errors. Using this option the relative strength of the energy and the forces can be adjusted. A value of 0.1 means that the influence of the energy is 10 times stronger than of a single force. A negative value will automatically balance the strength of the energy and of the forces by taking into account the actual number of atoms of each structures.
Format: force_update_scaling a0
a0
: (real
, default:1.0
)- The relative strength of the energy and forces for a weight update.
global_activation_electrostatic
++
Mode 1: • Mode 2: • Mode 3:
Set the default activation function for each hidden layer and the output layer in the electrostatic NNs of all elements.
Format: global_activation_electrostatic type [type...]
type [type...]
: (character [characters]
)- The kind of activation function. One
type
has to be given for each layer in the NN. Options are listed underglobal_activation_short
.
Source array actfunc_elec(maxnodes_elec, maxnum_layers_elec, nelem)
Hint
Different activation functions for individual nodes can be specified using
the keyword
element_activation_electrostatic
.
global_activation_pair
Mode 1: • Mode 2: • Mode 3:
Set the default activation function for each hidden layer and the output layer in the NNs of all element pairs.
Format: global_activation_pair type [type...]
type [type...]
: (character [characters]
)- The kind of activation function. One
type
has to be given for each layer in the NN. Options are listed underglobal_activation_short
.
Source array actfunc_short_pair(maxnodes_short_pair,maxnum_layers_short_pair,npairs)
Hint
This keyword is mandatory if
nn_type_short
is set to 2.
global_activation_short
++
Mode 1: • Mode 2: • Mode 3:
Set the activation function for each hidden layer and the output layer in the short range NNs of all elements.
Format: global_activation_short type [type...]
type [type...]
: (character [characters]
)-
The kind of activation function. One
type
has to be given for each layer in the NN. Can be one of:-
c
:- Cosine function: \(\cos(x)\)
-
e
:- Exponential function: \(\exp(-x)\)
-
g
:- Gaussian function: \(\exp(-\alpha x^2)\)
-
h
:- Harmonic function: \(x^2\).
-
l
:- Linear function: \(x\)
-
p
:- Softplus function: \(\ln(1+\exp(x))\)
-
s
:- Sigmoid function v1: \((1-\exp(-x))^{-1}\)
-
S
:- Sigmoid function v2: \(1-(1-\exp(-x))^{-1}\)
-
t
:- Hyperbolic tangent function: \(\tanh(x)\)
-
Source array actfunc_short(maxnodes_short, maxnum_layers_short, nelem)
Example
For a NN with two hidden layers and one output layer three letters have to be given. The line
global_activation_short t t l
will set a hyperbolic tangent activation function for the two hidden layers and a linear activation function for the output node.
Hint
Different activation functions for individual nodes can be specified using
the keyword
element_activation_short
.
global_hidden_layers_electrostatic
++
Mode 1: • Mode 2: • Mode 3:
Set the default number of hidden layers in the electrostatic NNs of all
elements. Internally 1 is added to maxnum_layers_elec
, which also includes
the output layer.
Format: global_hidden_layers_electrostatic layers
layers
: (integer
)- The number of hidden layers.
Source variables maxnum_layers_elec - 1
and
num_layers_elec(nelem)
Hint
The number of hidden layers can be further modified for individual elements by the
keyword
element_hidden_layers_elec
.
global_hidden_layers_pair
Mode 1: • Mode 2: • Mode 3:
Set the default number of hidden layers in the NNs of all element pairs.
Internally 1 is added to maxnum_layers_short_pair
, which also includes
the output layer.
Format: global_hidden_layers_pair layers
layers
: (integer
)- The number of hidden layers.
Source variables maxnum_layers_short_pair - 1
and
num_layers_short_pair(npairs)
Hint
The number of hidden layers can be further modified for individual elements by the
keyword
element_hidden_layers_pair
.
Hint
This keyword is mandatory if
nn_type_short
is set to 2.
global_hidden_layers_short
++
Mode 1: • Mode 2: • Mode 3:
Set the default number of hidden layers in the short-range NNs of all
elements. Internally 1 is added to maxnum_layers_short
, which also includes
the output layer.
Format: global_hidden_layers_short layers
layers
: (integer
)- The number of hidden layers.
Source variables maxnum_layers_short - 1
and
num_layers_short_atomic(nelem)
Hint
The number of hidden layers can be further modified for individual elements by the
keyword
element_hidden_layers_short
.
global_nodes_electrostatic
++
Mode 1: • Mode 2: • Mode 3:
Set the default number of nodes in the hidden layers of the electrostatic NNs
in case of
electrostatic_type
1.
In the array, the entries 1 - (maxnum_layerseelec - 1)
refer to the hidden
layers. The first entry (0) refers to the nodes in the input layer and is
determined automatically from the symmetry functions.
Format: global_nodes_electrostatic i0 [i1...]
i0 [i1...]
: (integer [integers]
)- The number of nodes to be set in each layer.
global_nodes_pair
Mode 1: • Mode 2: • Mode 3:
Set the default number of nodes in the hidden layers of the pairwise NNs
in case of
nn_type_short
2.
Format: global_nodes_pair i0 [i1...]
i0 [i1...]
: (integer [integers]
)- The number of nodes to be set in each layer.
global_nodes_short
++
Mode 1: • Mode 2: • Mode 3:
Set the default number of nodes in the hidden layers of the short-range NNs
in case of
nn_type_short
1.
In the array, the entries 1 - maxnum_layersshort - 1
refer to the hidden
layers. The first entry (0) refers to the nodes in the input layer and is
determined automatically from the symmetry functions.
Format: global_nodes_short i0 [i1...]
i0 [i1...]
: (integer [integers]
)- The number of nodes to be set in each layer.
global_output_nodes_electrostatic
This is an outdated keyword, which is no longer supported.
global_output_nodes_pair
This is an outdated keyword, which is no longer supported.
global_output_nodes_short
This is an outdated keyword, which is no longer supported.
global_pairsymfunction_short
Mode 1: • Mode 2: • Mode 3:
Specification of the global symmetry functions for all element pairs in the pairwise NN.
Format: global_pairsymfunction_short element element type [parameters] cutoff
element
: (character
)- The periodic table symbol of the first pair element.
element
: (character
)- The periodic table symbol of the second pair element.
type [parameters]
: (integer [reals]
)- The type of symmetry function to be used. Different
parameters
have to be set depending on the choice oftype
. They are explained underglobal_symfunction_short
. cutoff
: (real
, default:None
)- The symmetry function cutoff radius (unit: Bohr).
global_symfunction_electrostatic
++
Mode 1: • Mode 2: • Mode 3:
Specification of global symmetry functions for all elements and all element combinations for the electrostatic NN.
Format: global_symfunction_electrostatic type [parameters] cutoff
type [parameters]
: (integer [reals]
)- The type of symmetry function to be used. Different
parameters
have to be set depending on the choice oftype
. They are explained underglobal_symfunction_short
. cutoff
: (real
, default:None
)- The symmetry function cutoff radius (unit: Bohr).
global_symfunction_short
++
Mode 1: • Mode 2: • Mode 3:
Specification of global symmetry functions for all elements and all element combinations for the short-range atomic NN.
Format: global_symfunction_short type [parameters] cutoff
type [parameters]
: (integer [reals]
)-
The type of symmetry function to be used. The functional forms can be found here. Different
parameters
have to be set depending on the choice oftype
:-
1
:- Radial function. Requires no further
parameters
.
-
2
:- Radial function. Requires parameters
eta
andrshift
.global_symfunction_short 2 eta rshift cutoff
-
3
:- Angular function. Requires
parameters
eta
,lambda
, andzeta
.global_symfunction_short 3 eta lambda zeta cutoff
-
4
:- Radial function. Requires parameter
eta
.global_symfunction_short 4 eta cutoff
-
5
:- Cartesian coordinate function. The parameter
eta
will determine the coordinate axis:eta=1.0: X, eta=2.0: Y, eta=3.0: Z
. Nocutoff
required.global_symfunction_short 5 eta
-
6
:- Bond length function. Requires no further
parameters
.global_symfunction_short 6 cutoff
-
7
:- Not implemented.
-
8
:- Angular function. Requires
parameters
eta
, andrshift
.global_symfunction_short 8 eta rshift cutoff
-
9
:- Angular function. Requires
parameters
eta
.global_symfunction_short 9 eta cutoff
-
21
:- Radial spin-dependent function using the spin augmentation function \(M^\mathrm{0^*}\). Requires parameters
eta
andrshift
.global_symfunction_short 21 eta rshift cutoff
-
22
:- Radial spin-dependent function using the spin augmentation function \(M^\mathrm{+}\). Requires parameters
eta
andrshift
.global_symfunction_short 22 eta rshift cutoff
-
23
:- Radial spin-dependent function using the spin augmentation function \(M^\mathrm{-}\). Requires parameters
eta
andrshift
.global_symfunction_short 23 eta rshift cutoff
-
24
:- Angular spin-dependent function using the spin augmentation function \(M^\mathrm{00^*}\). Requires
parameters
eta
,lambda
, andzeta
.global_symfunction_short 24 eta lambda zeta cutoff
-
25
:- Angular spin-dependent function using the spin augmentation function \(M^\mathrm{++}\). Requires
parameters
eta
,lambda
, andzeta
.global_symfunction_short 25 eta lambda zeta cutoff
-
26
:- Angular spin-dependent function using the spin augmentation function \(M^\mathrm{--}\). Requires
parameters
eta
,lambda
, andzeta
.global_symfunction_short 26 eta lambda zeta cutoff
-
27
:- Angular spin-dependent function using the spin augmentation function \(M^\mathrm{+-}\). Requires
parameters
eta
,lambda
, andzeta
.global_symfunction_short 27 eta lambda zeta cutoff
-
28
:- Angular spin-dependent function using the spin augmentation function \(M^\mathrm{++2}\). Requires
parameters
eta
,lambda
, andzeta
.global_symfunction_short 28 eta lambda zeta cutoff
-
29
:- Angular spin-dependent function using the spin augmentation function \(M^\mathrm{++3}\). Requires
parameters
eta
,lambda
, andzeta
.global_symfunction_short 29 eta lambda zeta cutoff
-
30
:- Angular spin-dependent function using the spin augmentation function \(M^\mathrm{--2}\). Requires
parameters
eta
,lambda
, andzeta
.global_symfunction_short 30 eta lambda zeta cutoff
-
31
:- Angular spin-dependent function using the spin augmentation function \(M^\mathrm{--3}\). Requires
parameters
eta
,lambda
, andzeta
.global_symfunction_short 31 eta lambda zeta cutoff
-
cutoff
: (real
, default:None
)- The symmetry function cutoff radius (unit: Bohr).
growth_mode
*
Mode 1: • Mode 2: • Mode 3:
If this keyword is used, not the full training set will be used in each epoch. First, only a few points will be used, and after a specified number of epochs further points will be included and so on.
Format: growth_mode i0 i1
i0
: (integer
, default:0
)- Number of points that will be added to the training set every
i1
steps. i1
: (integer
, default:0
)- Number of steps to wait before increasing the number of training points.
Source variables lgrowth
,
ngrowth
, and
growthstep
,
Example
The line
growth_mode 11 6
will add 11 more points to the effective training set every 6 epochs until the full training set is used.
initialization_only
Mode 1: • Mode 2: • Mode 3:
With this keyword, which is active only in
runner_mode
2,
RuNNer
will stop
after the initialization of the run before epoch 0, i.e. no fit will be done.
This is meant as an automatic stop of the program in case only the analysis
carried out in the initialization of
runner_mode
2
is of interest.
Format: initialization_only
(logical
, default: False
)
This keyword does not have any further options.
ion_forces_only
-
Mode 1: • Mode 2: • Mode 3:
If this keyword is set, for structures with a nonzero net charge only the forces will be used for fitting, the energies will be omitted. This keyword is currently implemented only for the atomic short range part.
Format: ion_forces_only
(logical
, default: False
)
This keyword does not have any further options.
joint_energy_force_update
*
Mode 1: • Mode 2: • Mode 3:
This is an experimental keyword not fully tested. For each atom only one weight update is done for an averaged set of gradients calculated from the energy and all forces (not yet working well).
Format: joint_energy_force_update
(logical
, default: False
)
This keyword does not have any further options.
kalman_damp_charge
Mode 1: • Mode 2: • Mode 3:
Reduce the effective RMSE on the charges for the Kalman filter update of the weights in the electrostatic NN.
Format: kalman_damp_charge a0
a0
: (real
, default:1.0
)- Fraction of charge RMSE that is considered for the weight update. 100% = 1.0.
Hint
This keyword is used in case of
electrostatic_type
1
and
optmode_charge
1
only.
kalman_damp_force
Mode 1: • Mode 2: • Mode 3:
Reduce the effective RMSE on the forces for the Kalman filter update of the weights in the short-range NN.
Format: kalman_damp_force a0
a0
: (real
, default:1.0
)- Fraction of force RMSE that is considered for the weight update. 100% = 1.0.
Hint
This keyword is used in case for
optmode_short_force
1
only.
kalman_damp_short
Mode 1: • Mode 2: • Mode 3:
Reduce the effective RMSE on the energies for the Kalman filter update of the weights in the short-range NN.
Format: kalman_damp_short a0
a0
: (real
, default:1.0
)- Fraction of energy RMSE that is considered for the weight update. 100% = 1.0.
Hint
This keyword is used for
optmode_short_energy
1
only.
kalman_epsilon
Mode 1: • Mode 2: • Mode 3:
Set the initialization parameter for the correlation matrix of the Kalman filter according to
\(\epsilon\) is often set to the order of \(10^{-3}\) to \(10^{-2}\).
Format: kalman_epsilon a0
a0
: (real
, default:1.0
)- Value of \(\epsilon\).
Hint
This keyword is mandatory if
use_noisematrix
is used.
kalman_lambda_charge
+
Mode 1: • Mode 2: • Mode 3:
Kalman filter parameter \(\lambda\) for the electrostatic NN weight updates.
Format: kalman_lambda_charge a0
a0
: (real
, default:1.0
)- Value of \(\lambda\).
Hint
This keyword is mandatory for
optmode_charge
1.
kalman_lambda_charge_constraint
--
This keyword has been deprecated and is unlikely to work.
kalman_lambda_short
+
Mode 1: • Mode 2: • Mode 3:
Kalman filter parameter \(\lambda\) for the short range NN weight updates.
Format: kalman_lambda_short a0
a0
: (real
, default:1.0
)- Value of \(\lambda\).
Hint
This keyword is mandatory for
optmode_short_energy
1.
kalman_nue_charge
+
Mode 1: • Mode 2: • Mode 3:
Kalman filter parameter \(\lambda_0\) for the electrostatic NN weight updates.
Format: kalman_nue_charge a0
a0
: (real
, default:None
)- Value of \(\lambda_0\).
Hint
This keyword is mandatory for
optmode_charge
1.
kalman_nue_charge_constraint
--
This keyword has been deprecated and is unlikely to work.
kalman_nue_short
+
Mode 1: • Mode 2: • Mode 3:
Kalman filter parameter \(\lambda_0\) for the short range weight updates.
Format: kalman_nue_short a0
a0
: (real
, default:None
)- Value of \(\lambda_0\).
Hint
This keyword is mandatory for
optmode_short_energy
1
and
optmode_short_force
1
kalman_q0
Mode 1: • Mode 2: • Mode 3:
It is possible to add artificial process noise for the Kalman filter in the form of
with either a fixed \(q(t)=q(0)\) or annealing from a higher \(q(0)\) to \(q_{\mathrm{min}}\) following a scheme like
The value of \(q(0)\) is usually set between \(10^{-6}\) and \(10^{-2}\).
It is recommended for the user to do some test for each new system, altering
kalman_q0
,
kalman_qmin
and
kalman_qtau
to obtain the optimal
performance for minimizing the root mean square error.
Hint
This keyword is mandatory if
use_noisematrix
is used.
kalman_qmin
Mode 1: • Mode 2: • Mode 3:
Parameter \(q_{\mathrm{min}}\) for adding artificial process noise to the Kalman
filter noise matrix. See kalman_q0
for a more detailed explanation.
Format: kalman_qmin a0
a0
: (real
, default:0.0
)- Value of \(q_{\mathrm{min}}\).
Hint
This keyword is mandatory if
use_noisematrix
is used.
kalman_qtau
Mode 1: • Mode 2: • Mode 3:
Parameter \(\tau_q\) for adding artificial process noise to the Kalman
filter noise matrix. See kalman_q0
for a more detailed explanation.
Hint
This keyword is mandatory if
use_noisematrix
is used.
max_energy
Mode 1: • Mode 2: • Mode 3:
Set an upper threshold for the consideration of a structure during the weight
update. If the total energy is above
max_energy
]
the data point will be ignored.
Format: max_energy a0
a0
: (real
, default:10000.0
)- Maximum energy of a structure to be considered for the weight update (unit: Hartree).
max_force
Mode 1: • Mode 2: • Mode 3:
Set an upper threshold for the consideration of a structure during the weight
update. If any force component is above
max_force
]
the data point will be ignored.
Format: max_force a0
a0
: (real
, default:10000.0
)- Maximum force component of a structure to be considered for the weight update (unit: Hartree/Bohr).
md_mode
--
Mode 1: • Mode 2: • Mode 3:
The purpose of this keyword is to reduce the output to enable the incorporation
of RuNNer
into a MD code.
Format: md_mode
(logical
, default: False
)
This keyword does not have any further options.
mix_all_points
++
Mode 1: • Mode 2: • Mode 3:
Randomly reorder the data points in the data set at the beginning of each new epoch.
Format: mix_all_points
(logical
, default: False
)
This keyword does not have any further options.
nguyen_widrow_weights_electrostatic
Mode 1: • Mode 2: • Mode 3:
Initialize the electrostatic NN weights according to the scheme proposed by Nguyen and Widrow. The initial weights and bias values in the hidden layer are chosen such that the input space is evenly distributed over the nodes. This may speed up the training process. nguyen_widrow_weights_ewald is an alternative name of the keyword.
Format: nguyen_widrow_weights_electrostatic
(logical
, default: False
)
This keyword does not have any further options.
nguyen_widrow_weights_short
Mode 1: • Mode 2: • Mode 3:
Initialize the short-range NN weights according to the scheme proposed by Nguyen and Widrow. The initial weights and bias values in the hidden layer are chosen such that the input space is evenly distributed over the nodes. This may speed up the training process.
Format: nguyen_widrow_weights_short
(logical
, default: False
)
This keyword does not have any further options.
nn_type_elec
This keyword has the same meaning as
electrostatic_type
and the same options. Only one of these keywords can be used.
nn_type_short
++
Mode 1: • Mode 2: • Mode 3:
Specify the NN type of the short-range part.
Format: nn_type_short i0
i0
: (integer
, default:None
)-
Set the short-range NN type. Can be one of:
-
1
:- Behler-Parrinello atomic NNs. The short range energy is constructed as a sum of environment-dependent atomic energies.
-
2
:- Pair NNs. The short range energy is constructed as a sum of environment-dependent pair energies.
-
Hint
This keyword is mandatory.
nnp_gen
++
Mode 1: • Mode 2: • Mode 3:
This keyword specifies the generation of HDNNP that will be constructed.
Format: nnp_gen i0
i0
: (integer
, default:None
)-
Set the short-range and electrostatics NN type. Can be one of:
-
2
:- 2G-HDNNPs only include the short-range part (Behler-Parrinello
atomic NNs). Users should also specify
use_short_nn
.
-
3
:- 3G-HDNNPs include both the short-range part and the long-range
electrostatic part.
Users are advised to first construct a representation for the
electrostatic part by specifying
use_electrostatics
and then switch to the short range part by setting bothuse_short_nn
anduse_electrostatics
.
-
4
:- 4G-HDNNPs include both the short-range part and the long-range
electrostatic part.
Users are advised to first construct a representation for the
electrostatic part by specifying
use_electrostatics
and then switch to the short range part by setting bothuse_short_nn
anduse_electrostatics
.
-
Source variables nn_type_short
and
nn_type_elec
.
Hint
This keyword is mandatory. Please also consider reading the workflow recommendation.
noise_charge
Mode 1: • Mode 2: • Mode 3:
Introduce artificial noise on the atomic charges in the training process by setting a lower threshold that the absolute charge error of a data point has to surpass before being considered for the weight update.
Format: noise_charge a0
a0
: (real
, default:0.0
)- Noise charge threshold (unit: Hartree per atom). Must be positive.
noise_energy
Mode 1: • Mode 2: • Mode 3:
Introduce artificial noise on the atomic energies in the training process by setting a lower threshold that the absolute energy error of a data point has to surpass before being considered for the weight update.
Format: noise_energy a0
a0
: (real
, default:0.0
)- Noise energy threshold (unit: electron charge). Must be positive.
noise_force
Mode 1: • Mode 2: • Mode 3:
Introduce artificial noise on the atomic forces in the training process by setting a lower threshold that the absolute force error of a data point has to surpass before being considered for the weight update.
Format: noise_force a0
a0
: (real
, default:0.0
)- Noise force threshold (unit: Hartree per Bohr). Must be positive.
normalize_nodes
+
Mode 1: • Mode 2: • Mode 3:
Divide the accumulated sum at each node by the number of nodes in the previous layer before the activation function is applied. This may help to activate the activation functions in their non-linear regions.
Format: normalize_nodes
(logical
, default: False
)
This keyword does not have any further options.
number_of_elements
++
Mode 1: • Mode 2: • Mode 3:
Specify the number of chemical elements in the system.
Format: number_of_elements i0
i0
: (integer
, default:None
)- Number of elements.
Hint
This keyword is mandatory. For each element there must be an entry for the
keyword elements
.
optmode_charge
++
Mode 1: • Mode 2: • Mode 3:
Specify the optimization algorithm for the atomic charges in case of
electrostatic_type
1.
Format: optmode_charge i0
i0
: (integer
, default:1
)-
Set the atomic charge optimization algorithm. Can be one of:
-
1
:- Kalman filter.
-
2
:- Reserved for conjugate gradient, not implemented.
-
3
:- Steepest descent. Not recommended.
-
optmode_short_energy
++
Mode 1: • Mode 2: • Mode 3:
Specify the optimization algorithm for the short-range energy contributions.
Format: optmode_short_energy i0
i0
: (integer
, default:1
)-
Set the short-range energy optimization algorithm. Can be one of:
-
1
:- Kalman filter.
-
2
:- Reserved for conjugate gradient, not implemented.
-
3
:- Steepest descent. Not recommended.
-
optmode_short_force
++
Mode 1: • Mode 2: • Mode 3:
Specify the optimization algorithm for the short-range forces.
Format: optmode_short_force i0
i0
: (integer
, default:1
)-
Set the short-range force optimization algorithm. Can be one of:
-
1
:- Kalman filter.
-
2
:- Reserved for conjugate gradient, not implemented.
-
3
:- Steepest descent. Not recommended.
-
pairsymfunction_short
parallel_mode
-
Mode 1: • Mode 2: • Mode 3:
This flag controls the parallelization of some subroutines.
Format: parallel_mode i0
i0
: (integer
, default:1
)-
Set the short-range force optimization algorithm. Can be one of:
-
1
:- Serial version.
-
2
:- Parallel version.
-
Hint
This feature is not fully implemented yet and should be used only by developers.
points_in_memory
++
Mode 1: • Mode 2: • Mode 3:
This keyword controls memory consumption and IO and is therefore important to
achieve an optimum performance of RuNNer
. Has a different meaning depending on
the current
runner_mode
.
Format: points_in_memory i0
i0
: (integer
, default:200
)- In
runner_mode
1 this is the maximum number of structures in memory at a time.
Inrunner_mode
3 this is the number of atoms for which the symmetry functions are in memory at once. In parallel runs these atoms are further split between the processes.
precondition_weights
Mode 1: • Mode 2: • Mode 3:
Shift the weights of the atomic NNs right after the initialization so that the standard deviation of the NN energies is the same as the standard deviation of the reference energies.
Format: precondition_weights
(logical
, default: False
)
This keyword does not have any further options.
Hint
This keyword effects short-range, pairwise, and electrostatic NNs alike.
prepare_md
--
This keyword is not fully implemented yet. The purpose is to write the full configuration of RuNNer to an output file for interfacing with an external MD program.
print_all_deshortdw
*
Mode 1: • Mode 2: • Mode 3:
For debugging only. Prints the derivatives of the short range energy with
respect to the short range NN weight parameters after each update.
This derivative array is responsible for the weight update. The
derivatives (the array deshortdw
) are written to the file debug.out
.
Format: print_all_deshortdw
(logical
, default: False
)
This keyword does not have any further options.
Warning
Caution: Use this only for small data sets and few epochs, otherwise your hard disk will be immediately full.
print_all_dfshortdw
*
Mode 1: • Mode 2: • Mode 3:
For debugging only. Prints the derivatives of the short range forces
with respect to the short range NN weight parameters after each update.
This derivative array is responsible for the weight update. The
derivatives (the array dfshortdw(maxnum_weightsshort)
) are written to
the file debug.out
.
Format: print_all_dfshortdw
(logical
, default: False
)
This keyword does not have any further options.
Warning
Caution: Use this only for small data sets and few epochs, otherwise your hard disk will be immediately full.
print_all_electrostatic_weights
*
Mode 1: • Mode 2: • Mode 3:
For debugging only. Print the electrostatic NN weight parameters after each
update, not only once per epoch to a file. The weights (the array
weights_ewald()
) are written to the file debug.out
.
Format: print_all_electrostatic_weights
(logical
, default: False
)
This keyword does not have any further options.
Warning
Caution: Use this only for small data sets and few epochs, otherwise your hard disk will be immediately full.
print_all_short_weights
Mode 1: • Mode 2: • Mode 3:
For debugging only. Print the short range NN weight parameters after each
update, not only once per epoch to a file. The weights (the array
weights_short()
) are written to the file debug.out
.
Format: print_all_short_weights
(logical
, default: False
)
This keyword does not have any further options.
Warning
Caution: Use this only for small data sets and few epochs, otherwise your hard disk will be immediately full.
print_convergence_vector
Mode 1: • Mode 2: • Mode 3:
During training, print a measure for the convergence of the weight vector. The output is:
CONVVEC element epoch C1 C2 wshift wshift2
C1
and C2
are two-dimensional coordinates of projections of the
weight vectors for plotting qualitatively the convergence of the
weights. wshift
is the length (normalized by the number of weights) of
the difference vector of the weights between two epochs. wshift2
is
the length (normalized by the number of weights) of the difference
vector between the current weights and the weights two epochs ago.
Format: print_convergence_vector
(logical
, default: False
)
This keyword does not have any further options.
print_date_and_time
Mode 1: • Mode 2: • Mode 3:
Print in each training epoch the date and the real time in an extra line.
Format: print_date_and_time
(logical
, default: False
)
This keyword does not have any further options.
print_force_components
*
Mode 1: • Mode 2: • Mode 3:
For debugging only. Prints in
runner_mode
3
the contributions of all atomic energies to the force components of each atom.
Format: print_force_components
(logical
, default: False
)
This keyword does not have any further options.
print_mad
+
Mode 1: • Mode 2: • Mode 3:
Print a line with the mean absolute deviation as an additional output line next
to the RMSE in
runner_mode
2.
Usually the MAD is smaller than the RMSE as outliers do not have such a large
impact.
Format: print_mad
(logical
, default: False
)
This keyword does not have any further options.
print_sensitivity
Mode 1: • Mode 2: • Mode 3:
Perform sensitivity analysis on the symmetry functions of the neural network. The sensitivity is a measure of how much the NN output changes with the symmetry functions, i.e. the derivative. It will be analyzed upon weight initialization and for each training epoch in all short-range, pair, and electrostatic NNs there are.
Format: print_sensitivity
(logical
, default: False
)
This keyword does not have any further options.
random_number_type
++
Mode 1: • Mode 2: • Mode 3:
Specify the type of random number generator used in RuNNer
. The seed can be
given with the keyword
random_seed
.
Format: random_number_type i0
i0
: (integer
, default:5
)-
Set the random number generator type. Can be one of:
-
1-4
:- Deprecated.
-
5
:- Normal distribution of random numbers.
-
6
:- Normal distribution of random numbers with the
xorshift
algorithm. This is the recommended option.
-
random_order_training
--
This keyword has been deprecated in favor of
mix_all_points
random_seed
++
Mode 1: • Mode 2: • Mode 3:
Set the integer seed for the random number generator used at many places in
RuNNer
.
In order to ensure that all results are reproducible, the same seed will result
in exactly the same output at all times (machine and compiler dependence cannot
be excluded).
This seed value is used for all random number generator in RuNNer
, but
internally for each purpose a local copy is made first to avoid interactions
between the different random number generators.
Please see also the keyword
random_number_type
.
read_kalman_matrices
++
Mode 1: • Mode 2: • Mode 3:
Restart a fit using old Kalman filter matrices from the files
kalman.short.XXX.data
and kalman.elec.XXX.data
. XXX
is the nuclear
charge of the respective element. Using old Kalman matrices will reduce
the oscillations of the errors when a fit is restarted with the Kalman
filter. The Kalman matrices are written to the files using the keyword
save_kalman_matrices
Format: read_kalman_matrices
(logical
, default: False
)
This keyword does not have any further options.
Warning
Caution: When using an old Kalman matrix for restart, don't change the number of weight parameters to be optimized, e.g. by fixing some weights.
read_unformatted
Mode 1: • Mode 2: • Mode 3:
Read old NN weights and/or an old Kalman matrix from an unformatted input file.
Format: read_unformatted
(logical
, default: False
)
This keyword does not have any further options.
regularize_fit_param
Mode 1: • Mode 2: • Mode 3:
This keyword switches on L2 regularization, mainly for the electrostatic part in 4G-HDNNPs.
Format: regularize_fit_param a0
a0
: (real
, default:0.0
)- Regularization parameter. Recommended setting is \(10^{-6}\).
remove_atom_energies
++
Mode 1: • Mode 2: • Mode 3:
Remove the energies of the free atoms from the total energies per atom to reduce
the absolute values of the target energies. This means that when this keyword is
used, RuNNer
will fit binding energies instead of total energies. This is
expected to facilitate the fitting process because binding energies are closer
to zero.
Format: remove_atom_energies
(logical
, default: False
)
This keyword does not have any further options.
Hint
If set, the atomic energies of all elements need to be specified by a
set of
atom_energy
keywords.
remove_vdw_energies
*
Mode 1: • Mode 2: • Mode 3:
Subtract van-der-Waals dispersion energy and forces from the reference data before fitting a neural network potential.
Format: remove_vdw_energies
(logical
, default: False
)
This keyword does not have any further options.
Hint
If this keyword is used the following keywords need to be given as well:
vdw_type
vdw_cutoff
,vdw_coefficient
for each unique pair of elements in the data set,vdw_radius
for each element in the data set,vdw_screening
,
repeated_energy_update
++
Mode 1: • Mode 2: • Mode 3:
If this keyword is set, the weights of the short-range NN are updated a second time after the force update with respect to the total energies in the data set. This usually results in a more accurate potential energy fitting at the cost of slightly detiorated forces.
Format: repeated_energy_update
(logical
, default: False
)
This keyword does not have any further options.
reset_kalman
Mode 1: • Mode 2: • Mode 3:
Re-initialize the correlation matrix of the Kalman filter at each new training epoch.
Format: reset_kalman
(logical
, default: False
)
This keyword does not have any further options.
restrict_weights
Mode 1: • Mode 2: • Mode 3:
Restrict the weights of the NN to the interval
[-restrictw +1.0
, restrictw - 1.0
].
Format: restrict_weights a0
a0
: (real
, default:-100000
)- Boundary value for neural network weights. Must be positive.
runner_mode
++
Mode 1: • Mode 2: • Mode 3:
Choose the operating mode of RuNNer
.
Format: runner_mode i0
a0
: (integer
, default:None
)-
The chosen mode of
RuNNer
. Can be one of:-
1
:- Preparation mode. Generate the symmetry functions from structures
in the
input.data
file.
-
2
:- Fitting mode. Determine the NN weight parameters.
-
3
:- Production mode. Application of the NN potential, prediction of the
energy and forces of all structures in the
input.data
file.
-
Hint
This keyword is mandatory in all RuNNer
modes.
save_kalman_matrices
*
Mode 1: • Mode 2: • Mode 3:
Save the Kalman filter matrices to the files kalman.short.XXX.data
and
kalman.elec.XXX.data
. XXX
is the nuclear charge of the respective
element. The Kalman matrices are read from the files using the keyword
read_kalman_matrices
.
Format: save_kalman_matrices
(logical
, default: False
)
This keyword does not have any further options.
Hint
This keyword is only active if the Kalman filter is used as optimization algorithm.
Hint
Caution: The files can be large.
scale_max_elec
+
Mode 1: • Mode 2: • Mode 3:
Rescale the electrostatic symmetry functions to an interval given by
For further details please see
scale_symmetry_functions
.
Format: scale_max_elec a0
a0
: (real
, default:1.0
)- Upper boundary value for rescaling the electrostatic symmetry functions.
scale_max_short
Mode 1: • Mode 2: • Mode 3:
Rescale the electrostatic symmetry functions to an interval given by
For further details please see
scale_symmetry_functions
.
Format: scale_max_short a0
a0
: (real
, default:1.0
)- Upper boundary value for rescaling the electrostatic symmetry functions.
scale_max_short_atomic
+
Mode 1: • Mode 2: • Mode 3:
Rescale the short-range symmetry functions to an interval given by
For further details please see
scale_symmetry_functions
.
Format: scale_max_short_atomic a0
a0
: (real
, default:1.0
)- Upper boundary value for rescaling the short-range symmetry functions.
scale_max_short_pair
Mode 1: • Mode 2: • Mode 3:
Rescale the short-range pairwise symmetry functions to an interval given by
For further details please see
scale_symmetry_functions
.
Format: scale_max_short_pair a0
a0
: (real
, default:1.0
)- Upper boundary value for rescaling the short-range pairwise symmetry functions.
scale_min_elec
+
Mode 1: • Mode 2: • Mode 3:
Rescale the electrostatic symmetry functions to an interval given by
For further details please see
scale_symmetry_functions
.
Format: scale_min_elec a0
a0
: (real
, default:0.0
)- Lower boundary value for rescaling the electrostatic symmetry functions.
scale_min_short_atomic
+
Mode 1: • Mode 2: • Mode 3:
Rescale the short-range symmetry functions to an interval given by
For further details please see
scale_symmetry_functions
.
Format: scale_min_short_atomic a0
a0
: (real
, default:0.0
)- Lower boundary value for rescaling the short-range symmetry functions.
scale_min_short_pair
+
Mode 1: • Mode 2: • Mode 3:
Rescale the short-range pairwise symmetry functions to an interval given by
For further details please see
scale_symmetry_functions
.
Format: scale_min_short_pair a0
a0
: (real
, default:0.0
)- Lower boundary value for rescaling the short-range pairwise symmetry functions.
scale_symmetry_functions
++
Mode 1: • Mode 2: • Mode 3:
Rescale symmetry functions to a certain interval (the default interval is 0 to
1). This has numerical advantages if the orders of magnitudes of different
symmetry functions are very different. If the minimum and maximum value for a
symmetry function is the same for all structures, rescaling is not possible and
RuNNer
will terminate with an error. The interval can be specified by the
keywords
for the short range / pairwise NN and by
for the electrostatic NN.
Format: scale_symmetry_functions
(logical
, default: False
)
This keyword does not have any further options.
Hint
If non-default boundaries are given, a combination with the keyword
center_symmetry_functions
is not possible.
screen_electrostatics
separate_bias_ini_short
Mode 1: • Mode 2: • Mode 3:
Request a separate random initialization of the bias weights at the beginning of
runner_mode 2
on an interval between
biasweights_min
and biasweights_max
.
Format: separate_bias_ini_short
(logical
, default: False
)
This keyword does not have any further options.
Warning
This keyword requires the use of keywords
biasweights_max
and
biasweights_min
separate_kalman_short
Mode 1: • Mode 2: • Mode 3:
Use a different Kalman filter correlation matrix for the energy and force update.
Format: separate_kalman_short
(logical
, default: False
)
This keyword does not have any further options.
Hint
The keyword element_decoupled_kalman
will enforce a similar behaviour.
short_energy_error_threshold
++
Mode 1: • Mode 2: • Mode 3:
Threshold value for the error of the energies in units of the RMSE of the previous epoch. A value of 0.3 means that only charges with an error larger than 0.3*RMSE will be used for the weight update. Large values (about 1.0) will speed up the first epochs, because only a few points will be used.
Format: short_energy_error_threshold a0
a0
: (real
, default:0.0
)-
Fraction of energy RMSE that a point needs to reach to be used in the weight update.
Hint
For this keyword to take effect, you need to use the Kalman filter algorithm.
Hint
If you, instead, want to set a fixed threshold, please refer to
fixed_short_energy_error_threshold
.
short_energy_fraction
++
Mode 1: • Mode 2: • Mode 3:
Defines the random fraction of energies used for fitting the short range weights.
Format: short_energy_fraction a0
a0
: (real
, default:1.0
)-
Fraction of energies used for short-range fitting. 100% = 1.0.
short_energy_group
++
Mode 1: • Mode 2: • Mode 3:
Do not update the short range NN weights after the presentation of an individual atomic charge, but average the derivatives with respect to the weights over the specified number of structures for each element.
Format: short_energy_group i0
i0
: (integer
, default:1
)- Number of structures per group. The maximum is given by
points_in_memory
.
short_force_error_threshold
++
Mode 1: • Mode 2: • Mode 3:
Threshold value for the error of the atomic forces in units of the RMSE of the previous epoch. A value of 0.3 means that only forces with an error larger than 0.3*RMSE will be used for the weight update. Large values (about 1.0) will speed up the first epochs, because only a few points will be used.
Format: short_force_error_threshold a0
a0
: (real
, default:0.0
)-
Fraction of force RMSE that a point needs to reach to be used in the weight update.
Hint
For this keyword to take effect, you need to use the Kalman filter algorithm.
short_force_fraction
++
Mode 1: • Mode 2: • Mode 3:
Defines the random fraction of forces used for fitting the short range weights.
Format: short_force_fraction a0
a0
: (real
, default:1.0
)-
Fraction of force used for short-range fitting. 100% = 1.0.
short_force_group
++
Mode 1: • Mode 2: • Mode 3:
Do not update the short range NN weights after the presentation of an individual atomic force, but average the derivatives with respect to the weights over the specified number of forces for each element.
Format: short_force_group i0
i0
: (integer
, default:1
)- Number of structures per group. The maximum is given by
points_in_memory
.
shuffle_weights_short_atomic
Mode 1: • Mode 2: • Mode 3:
Randomly shuffle some weights in the short-range atomic NN after a defined number of epochs.
Format: shuffle_weights_short_atomic i0 a0
i0
: (integer
, default:10
)- The weights will be shuffled every
i0
epochs. a0
: (real
, default:0.1
)- Treshold that a random number has to pass so that the weights at handled will be shuffled. This indirectly defines the number of weights that will be shuffled.
Source variables lshuffle_weights_short_atomic
,
nshuffle_weights_short_atomic
, and
shuffle_weights_short_atomic
.
silent_mode
This keyword has not been implemented yet.
steepest_descent_step_charge
+
Mode 1: • Mode 2: • Mode 3:
Step size for steepest descent fitting of the atomic charges.
Format: steepest_descent_step_charge a0
a0
: (real
, default:0.01
)- Charge steepest descent step size.
Hint
This keyword is relevant only if the steepest descent optimization algorithm
has been selected with
optmode_charge
3.
steepest_descent_step_energy_short
+
Mode 1: • Mode 2: • Mode 3:
Step size for steepest descent fitting of the short-range energy.
Format: steepest_descent_step_energy_short a0
a0
: (real
, default:0.01
)- Short-range energy steepest descent step size.
Hint
This keyword is relevant only if the steepest descent optimization algorithm
has been selected with
optmode_charge
3.
steepest_descent_step_force_short
+
Mode 1: • Mode 2: • Mode 3:
Step size for steepest descent fitting of the short-range forces.
Format: steepest_descent_step_force_short a0
a0
: (real
, default:0.01
)- Short-range force steepest descent step size.
Hint
This keyword is relevant only if the steepest descent optimization algorithm
has been selected with
optmode_charge
3.
symfunction_correlation
Mode 1: • Mode 2: • Mode 3:
Determine and print Pearson's correlation of all pairs of symmetry functions.
Format: symfunction_correlation
(logical
, default: False
)
This keyword does not have any further options.
symfunction_electrostatic
++
Mode 1: • Mode 2: • Mode 3:
Specification of the symmetry functions for a specific element with a specific neighbor element combination for the electrostatic NN.
Format: symfunction_electrostatic element [element...] type [parameters] cutoff
element [element...]
: (character [characters]
)- The periodic table symbol of the elements. One neighbor
[element]
has to be given for radial symmetry functions, two for angular symmetry functions. type [parameters]
: (integer [reals]
)- The type of symmetry function to be used. Different
parameters
have to be set depending on the choice oftype
. They are explained underglobal_symfunction_short
. cutoff
: (real
, default:None
)- The symmetry function cutoff radius (unit: Bohr).
symfunction_short
++
Mode 1: • Mode 2: • Mode 3:
Specification of the symmetry functions for a specific element with a specific neighbor element combination for the short-range NN.
Format: symfunction_short element [element...] type [parameters] cutoff
element [element...]
: (character [characters]
)- The periodic table symbol of the elements. One neighbor
[element]
has to be given for radial symmetry functions, two for angular symmetry functions. type [parameters]
: (integer [reals]
)- The type of symmetry function to be used. Different
parameters
have to be set depending on the choice oftype
. They are explained underglobal_symfunction_short
. cutoff
: (real
, default:None
)- The symmetry function cutoff radius (unit: Bohr).
test_fraction
++
Mode 1: • Mode 2: • Mode 3:
Threshold for splitting between training and testing set in
runner_mode
1.
Format: test_fraction a0
a0
: (real
, default:0.01
)- Splitting ratio. A value of e.g. 0.1 means that 10% of the structures
in the
input.data
file will be used as test set and 90% as training set.
Hint
The specific splitting can be modified by changing the value of
random_seed
.
total_charge_error_threshold
*
This keyword has been deprecated and is unlikely to work.
update_single_element
*
Mode 1: • Mode 2: • Mode 3:
During training, only the NN weight parameters for the NNs of a specified element will be updated. In this case the printed errors for the forces and the charges will refer only to this element. The total energy error will remain large since some NNs are not optimized.
Format: update_single_element i0
i0
: (integer
, default:None
)- The nuclear charge of the element whose NN should be updated.
Source variables lupdatebyelement
and
elemupdate
.
Example
update_single_element 30
will optimize only the weights for the NNs describing Zn.
update_worst_charges
*
Mode 1: • Mode 2: • Mode 3:
To speed up the fits for each block specified by
points_in_memory
first the worst charges are determined. Only these charges are then used for the
weight update for this block of points, no matter if the fit would be reduced
during the update.
Format: update_worst_charges a0
a0
: (real
, default:None
)- The percentage of worst charges to be considered for the weight update. A value of 0.1 here means to identify the worst 10%.
Source variables luseworstq
and
worstq
.
Hint
This keyword can be combined with
charge_error_threshold
to eliminate unnecessary updates.
update_worst_short_energies
*
Mode 1: • Mode 2: • Mode 3:
To speed up the fits for each block specified by
points_in_memory
first the worst energies are determined. Only these points are then used for the
weight update for this block of points, no matter if the fit would be reduced
during the update.
Format: update_worst_short_energies a0
a0
: (real
, default:None
)- The percentage of worst energies to be considered for the weight update. A value of 0.1 here means to identify the worst 10%.
Source variables luseworste
and
worste
.
Hint
This keyword can be combined with
short_energy_error_threshold
to eliminate unnecessary updates.
update_worst_short_forces
*
Mode 1: • Mode 2: • Mode 3:
To speed up the fits for each block specified by
points_in_memory
first the worst forces are determined. Only these points are then used for the
weight update for this block of points, no matter if the fit would be reduced
during the update.
Format: update_worst_short_forces a0
a0
: (real
, default:None
)- The percentage of worst forces to be considered for the weight update. A value of 0.1 here means to identify the worst 10%.
Source variables luseworstf
and
worstf
.
Hint
This keyword can be combined with
short_force_error_threshold
to eliminate unnecessary updates.
use_atom_charges
++
Mode 1: • Mode 2: • Mode 3:
Use atomic charges for fitting.
%At the moment this flag will be switched
%on automatically by RuNNer
if electrostatic NNs are requested. In
%future versions of RuNNer
this keyword will be used to control
%different origins of atomic charges.
Format: use_atom_charges
(logical
, default: False
)
This keyword does not have any further options.
use_atom_spins
++
Mode 1: • Mode 2: • Mode 3:
Use atomic spins for high-dimensional neural network spin prediction.
Format: use_atom_spins
(logical
, default: False
)
This keyword does not have any further options.
use_atom_energies
Mode 1: • Mode 2: • Mode 3:
Check if sum of specified atomic energies is equal to the total energy of each structure.
Format: use_atom_energies
(logical
, default: False
)
This keyword does not have any further options.
use_charge_constraint
*
This keyword has been deprecated and is unlikely to work.
use_damping
*
Mode 1: • Mode 2: • Mode 3:
In order to avoid too large (too positive or too negative) weight parameters, this damping scheme can be used. An additional term is added to the absolute energy error.
- For the short range energy the modification is:
errore=(1.d0-dampw)errore + (dampwsumwsquared) /dble(totnum_weightsshort)
- For the short range forces the modification is:
errorf=(1.d0-dampw)errorf+(dampwsumwsquared) /dble(num_weightsshort(elementindex(zelem(i2))))
- For the short range forces the modification is:
error=(1.d0-dampw)*error + (dampwsumwsquared) /dble(num_weightsewald(elementindex(zelem_list(idx(i1),i2))))
Format: use_damping a0
a0
: (real
, default:None
)- The damping parameter.
use_electrostatic_nn
++
This keyword has been deprecated. Please use
electrostatic_type
and
use_electrostatics
from now on.
use_electrostatics
++
Mode 1: • Mode 2: • Mode 3:
Calculate long range electrostatic interactions explicitly. The type of
atomic charges is specified by the keyword
electrostatic_type
.
Format: use_electrostatics
(logical
, default: False
)
This keyword does not have any further options.
use_fixed_charges
*
Mode 1: • Mode 2: • Mode 3:
Do not use a NN to calculate the atomic charges, but use fixed charges
for each element independent of the chemical environment.
electrostatic_type
.
Format: use_fixed_charges
(logical
, default: False
)
This keyword does not have any further options.
Hint
If this keyword is used, the fixed charges for all elements in the system must
be specified by the keyword
fixed_charge
.
use_gausswidth
++
Mode 1: • Mode 2: • Mode 3:
Use Gaussian for modeling atomic charges during the construction of 4G-HDNNPs.
Format: use_gausswidth
(logical
, default: False
)
This keyword does not have any further options.
Hint
If this keyword is used, the Gaussian width for all elements in the system
must be specified by the keyword
fixed_gausswidth
.
use_noisematrix
Mode 1: • Mode 2: • Mode 3:
Use noise matrix for fitting the short range weight with the short range NN weights with Kalman filter.
Format: use_noisematrix
(logical
, default: False
)
This keyword does not have any further options.
use_old_scaling
Mode 1: • Mode 2: • Mode 3:
Restart a fit with old scaling parameters for the short-range and electrostatic
NNs. The symmetry function scaling factors are read from scaling.data
.
Format: use_old_scaling
(logical
, default: False
)
This keyword does not have any further options.
use_old_weights_charge
++
Mode 1: • Mode 2: • Mode 3:
Restart a fit with old weight parameters for the electrostatic NN.
The files weightse.XXX.data
must be present. If the training data set is
unchanged, the error of epoch 0 must be the same as the error of the previous
fitting cycle.
Format: use_old_weights_charge
(logical
, default: False
)
This keyword does not have any further options.
use_old_weights_short
++
Mode 1: • Mode 2: • Mode 3:
Restart a fit with old weight parameters for the short-range NN. This
keyword is active only in mode 2. The files weights.XXX.data
must be present.
If the training data set is unchanged, the error of epoch 0 must be the same as
the error of the previous fitting cycle. However, if the training data is
different, the file scaling.data
changes and either one of the keywords
scale_symmetry_functions
or
center_symmetry_functions
is used, the RMSE will be different.
Format: use_old_weights_short
(logical
, default: False
)
This keyword does not have any further options.
use_omp_mkl
Mode 1: • Mode 2: • Mode 3:
Make use of the OpenMP threading in Intels MKL library.
Format: use_omp_mkl
(logical
, default: False
)
This keyword does not have any further options.
use_short_forces
++
Mode 1: • Mode 2: • Mode 3:
Use forces for fitting the short range NN weights. In
runner_mode
1, the
files trainforces.data
, testforces.data
, trainforcese.data
and
testforcese.data
are written.
In
runner_mode
2,
these files are needed to use the short range forces for optimizing the
short range weights. However, if the training data is different, the file
scaling.data
changes and either one of the keywords
scale_symmetry_functions
or
center_symmetry_functions
is used, the RMSE will be different.
Format: use_short_forces
(logical
, default: False
)
This keyword does not have any further options.
use_short_nn
++
Mode 1: • Mode 2: • Mode 3:
Use the a short range NN. Whether an atomic or pair-based energy expression is
used is determined via the keyword
nn_type_short
.
Format: use_short_nn
(logical
, default: False
)
This keyword does not have any further options.
use_systematic_weights_electrostatic
Mode 1: • Mode 2: • Mode 3:
Overwrite the randomly initialized weights of the electrostatic NNs with systematically calculated weights. The weights are evenly distributed over the interval between the minimum and maximum of the weights after the random initialization.
Format: use_systematic_weights_electrostatic
(logical
, default: False
)
This keyword does not have any further options.
use_systematic_weights_short
Mode 1: • Mode 2: • Mode 3:
Overwrite the randomly initialized weights of the short-range and pairwise NNs with systematically calculated weights. The weights are evenly distributed over the interval between the minimum and maximum of the weights after the random initialization.
Format: use_systematic_weights_short
(logical
, default: False
)
This keyword does not have any further options.
use_vdw
*
Switch dispersion corrections in RuNNer mode 3 on or off. If this keyword is used the following keywords need to be given as well:
-
1:
vdw_coefficient
for each unique pair of elements in the data set. -
2:
vdw_cutoff
, -
3:
vdw_radius
for each element in the data set, -
4:
vdw_screening
, -
5:
vdw_type
.
Source variable: lvdw
(logical, default = F)
vdw_coefficient
*
vdw_coefficient
element1
element2
value
where element1
and element2
are character strings and value
is a
real number.
Specification of the pairwise \(C_{6ij}\) dispersion coefficients.
Mandatory keyword if the keyword use_vdw
is used.
-
\(\texttt{vdw\_type}=1\) (Tkatchenko-Scheffler method): a coefficient must be provided for each unique element pair in the data set.
-
\(\texttt{vdw\_type}=2\) (Grimme DFT-D2 correction): a coefficient must be provided for each same-element pair in the data set.
Source array: vdw_coefficients(nelem, nelem)
(real, default = None)
vdw_cutoff
*
where value
is a real number.
Specification of the cutoff radius to be used in the calculation of the
dispersion correction. This keyword must be used if the keyword
use_vdw
is used. Format example: vdw_cutoff 94.5
. The unit should be
\([a_0]\).\
Source variable: vdw_cutoff
(real, default = 0.0)
vdw_radius
*
vdw_radius element value
where element
is a character string and value
is a real number.\
Specification of the van der Waals radius of element
. This keyword
must be used for each element if the keyword use_vdw
is used. Format
example: vdw_radius C 0.76836936
. The unit should be \([a_0]\).\
Source array: vdw_radius(nelem)
(real, default = None)
vdw_screening
*
Mode 1: • Mode 2: • Mode 3:
Specification of the shape parameters of the Fermi-screening function in the employed DFT-D2 dispersion correction expression.
Format: vdw_screening s_6 d s_R
s_6
: (real
,default
0.0)- The global scaling parameter \(s_6\) in the screening function.
d
: (real
,default
0.0)- The exchange-correlation functional dependent damping parameter. More information can be found in the theory section.
s_R
: (real
,default
0.0)- Range separation parameter.
Example
vdw_screening 1.0 20.0 0.94
The parameters are dimensionless.
Hint
This keyword must be used if the keyword
use_vdw
is used.
vdw_type
*
Mode 1: • Mode 2: • Mode 3:
Specification of the type of dispersion correction to be employed.
Format: vdw_type i0
i0
: (integer
,default
0)-
Type of vdW correction scheme. Can be one of:
-
1
:- Simple, environment-dependent dispersion correction inspired by the Tkatchenko-Scheffler scheme.
-
2
:- Grimme DFT-D2 correction.
-
3
:- Grimme DFT-D3 correction.
-
Hint
This keyword must be used if the keyword
use_vdw
is used.
weight_analysis
Mode 1: • Mode 2: • Mode 3:
Print analysis of weights in
runner_mode
2.
Format: weight_analysis
(logical
, default: False
)
This keyword does not have any further options.
weight_constraint
+
Mode 1: • Mode 2: • Mode 3:
Specify, which short range NN weights shall not be optimized. This keyword can
be used several times to specify various groups of weights. The order is
relevant in that each specification will be overwritten by the following one.
Using the options free
and fixed
various constraints can be set.
Format: weight_constraint element selection [counts] type
element
: (string
)- The periodic table symbol of the element whose atomic NN the constraint applies to.
selection [id1 id2 ...]
: (string
, [integers
])-
Which part of the NN the constraint shall be applied to. Can be one of:
-
all
:- All short-range NN weights of the chosen
element
.
-
interlayer layer layer
: (integers
)- All short-range NN weights between layers
layer
1 andlayer
2.
-
bias layer node
: (integers
)- Bias weight at node
node
in layerlayer
.
-
weight layer node layer node
: (integers
)- Weight connecting
node
1 inlayer
1 withnode
2 inlayer
2.
-
node layer node
: (integers
)- All short-range weights connected to node
node
in layerlayer
.
-
type
: (string
)-
The kind of constraint that will be applied. Can be one of:
-
free
:- Fix all short-range NN weights of the chosen element except for
the ones in
selection
.
-
fixed
:- Keep
selection
fixed while optimizing all other weights of the chosenelement
's atomic electrostatic NN.
-
Examples
The following groups of weights are accepted:
-
Fix all short-range NN weights for the NN of oxygen:
weight_constraint O all fixed
-
Optimize all short-range NN weights for the NN of oxygen connecting the nodes in layers 1 and 2:
weight_constraint O interlayer 1 2 free
-
Optimize the short-range bias weight at node 2 in layer 1 for the NN of zinc:
weight_constraint Zn bias 1 2 free
-
Optimize the short-range NN weight connecting node 3 in layer 1 with node 4 in layer 2 for the NN of zinc:
weight_constraint Zn weight 1 3 2 4 free
-
Optimize all short-range NN weights connecting node 1 in layer 2 with all nodes in the previous and subsequent layers for the NN of zinc:
weight_constraint Zn node 2 1 free
Hint
This keyword requires the use of the keyword fix_weights
.
weighte_constraint
+
Mode 1: • Mode 2: • Mode 3:
Specify, which electrostatic NN weights shall not be optimized. This keyword can
be used several times to specify various groups of weights. The order is
relevant in that each specification will be overwritten by the following one.
Using the options free
and fixed
various constraints can be set.
Format: weighte_constraint element selection [counts] type
element
: (string
)- The periodic table symbol of the element whose atomic NN the constraint applies to.
selection [id1 id2 ...]
: (string
, [integers
])-
Which part of the NN the constraint shall be applied to. Can be one of:
-
all
:- All electrostatic NN weights of the chosen
element
.
-
interlayer layer layer
: (integers
)- All electrostatic NN weights between layers
layer
1 andlayer
2.
-
bias layer node
: (integers
)- Bias weight at node
node
in layerlayer
.
-
weight layer node layer node
: (integers
)- Weight connecting
node
1 inlayer
1 withnode
2 inlayer
2.
-
node layer node
: (integers
)- All electrostatic weights connected to node
node
in layerlayer
.
-
type
: (string
)-
The kind of constraint that will be applied. Can be one of:
-
free
:- Fix all electrostatic NN weights of the chosen element except for
the ones in
selection
.
-
fixed
:- Keep
selection
fixed while optimizing all other weights of the chosenelement
's atomic electrostatic NN.
-
Examples
The following groups of weights are accepted:
-
Fix all electrostatic NN weights for the NN of oxygen:
weighte_constraint O all fixed
-
Optimize all electrostatic NN weights for the NN of oxygen connecting the nodes in layers 1 and 2:
weighte_constraint O interlayer 1 2 free
-
Optimize the electrostatic bias weight at node 2 in layer 1 for the NN of zinc:
weighte_constraint Zn bias 1 2 free
-
Optimize the electrostatic NN weight connecting node 3 in layer 1 with node 4 in layer 2 for the NN of zinc:
weighte_constraint Zn weight 1 3 2 4 free
-
Optimize all electrostatic NN weights connecting node 1 in layer 2 with all nodes in the previous and subsequent layers for the NN of zinc:
weighte_constraint Zn node 2 1 free
Hint
This keyword requires the use of the keyword
fix_weights
.
weights_max
++
Mode 1: • Mode 2: • Mode 3:
Set an upper limit for the random initialization of the short-range NN weights.
Format: weights_max a0
a0
: (real
, default:+1.0
)- This number defines the maximum value for initial random short range weights.
Hint
This keyword is active only if an electrostatic NN is used, i.e. for
electrostatic_type
1.
weights_min
++
Mode 1: • Mode 2: • Mode 3:
Set a lower limit for the random initialization of the short-range NN weights.
Format: weights_min a0
a0
: (real
, default:-1.0
)- This number defines the minimum value for initial random short range weights.
weightse_max
++
Mode 1: • Mode 2: • Mode 3:
Set an upper limit for the random initialization of the electrostatic NN weights.
Format: weightse_max a0
a0
: (real
, default:+1.0
)- This number defines the maximum value for initial random electrostatic
weights. This keyword is active only if an electrostatic
NN is used, i.e. for
electrostatic_type
1.
weightse_min
++
Mode 1: • Mode 2: • Mode 3:
Set a lower limit for the random initialization of the electrostatic NN weights.
Format: weightse_min a0
a0
: (real
, default:-1.0
)- This number defines the minimum value for initial random electrostatic
weights. This keyword is active only if an electrostatic
NN is used, i.e. for
electrostatic_type
1.
write_fit_statistics
Mode 1: • Mode 2: • Mode 3:
Format: write_fit_statistics
(logical
, default: False
)
This keyword does not have any further options.
write_pdb
--
This is an outdated keyword, which is no longer supported.
write_pov
--
This is an outdated keyword, which is no longer supported.
write_pwscf
--
This is an outdated keyword, which is no longer supported.
write_temporary_weights
*
Mode 1: • Mode 2: • Mode 3:
Write temporary weights after each data block defined by points_in_memory
to
files tmpweights.XXX.out
and tmpweightse.XXX.out
. XXX is the nuclear charge.
This option is active only in runner_mode
2 and meant to store
intermediate weights in very long epochs.
Format: write_temporary_weights
(logical
, default: False
)
This keyword does not have any further options.
write_traincharges
++
Mode 1: • Mode 2: • Mode 3:
In runner_mode
2
write the files traincharges.YYYYYY.out
and testcharges.YYYYYY.out
for each
epoch. YYYYYY
is the number of the epoch.
The files are written only if the electrostatic NN is used in case of
electrostatic_type
1.
This can generate many large files and is intended for a detailed analysis of
the fits.
Format: write_traincharges
(logical
, default: False
)
This keyword does not have any further options.
write_trainforces
++
Mode 1: • Mode 2: • Mode 3:
In runner_mode
2
write the files
trainforces.YYYYYY.out
and
testforces.YYYYYY.out
for each epoch. YYYYYY
is the number of the epoch. The
files are written only if the short range NN is used and if the forces are used
for training (keyword
use_short_forces
).
This can generate many large files and is intended for a detailed analysis of
the fits.
Format: write_trainforces
(logical
, default: False
)
This keyword does not have any further options.
write_symfunctions
-
Mode 1: • Mode 2: • Mode 3:
In runner_mode
3 write the file symfunctions.out
containing
the unscaled and non-centered symmetry functions values of all atoms in the
predicted structure.
The format is the same as for the files
function.data
and
testing.data
with the exception that no energies are given. The purpose of this file is code
debugging.
Format: write_symfunctions
(logical
, default: False
)
This keyword does not have any further options.
write_binding_energy_only
+
Mode 1: • Mode 2: • Mode 3:
In
runner_mode
2
write only the binding energy instead of total energies in
the files
trainpoints.XXXXXX.out
and
testpoints.XXXXXX.out
for each epoch.
Format: write_binding_energy_only
(logical
, default: False
)
This keyword does not have any further options.
write_trainpoints
++
Mode 1: • Mode 2: • Mode 3:
In
runner_mode
2
write the files
trainpoints.XXXXXX.out
and
testpoints.XXXXXX.out
for each epoch. XXXXXX
is the number of the
epoch. The files are written only if the short range NN is used. This
can generate many large files and is intended for a detailed analysis of
the fits.
Format: write_trainpoints
(logical
, default: False
)
This keyword does not have any further options.
write_unformatted
Mode 1: • Mode 2: • Mode 3:
Write output without any formatting.
Format: write_unformatted
(logical
, default: False
)
This keyword does not have any further options.
write_weights_epoch
++
Mode 1: • Mode 2: • Mode 3:
Determine in which epochs the files YYYYYY.short.XXX.out
and
YYYYYY.elec.XXX.out
are written.
Format: write_weights_epoch i1
i1
: (integer
, default:1
)- Frequency of weight output.
Example
With
write_weights_epoch 5
the weight files will be written for every 5th epoch only.
write_xyz
--
This is an outdated keyword, which is no longer supported.