Skip to content

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: image/svg+xml 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.

Source variable lanalyzecomposition


analyze_error

Mode 1: image/svg+xml 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.

Source variable lanalyzeerror


analyze_error_charge_step

Mode 1: image/svg+xml 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).

Source variable lanalyze_error_charge_step

Hint

For this keyword to take effect, please also specify analyze_error.


analyze_error_energy_step

Mode 1: image/svg+xml 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).

Source variable lanalyze_error_energy_step

Hint

For this keyword to take effect, please also specify analyze_error.


analyze_error_force_step

Mode 1: image/svg+xml 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).

Source variable lanalyze_error_force_step

Hint

For this keyword to take effect, please also specify analyze_error.


atom_energy ++

Mode 1: image/svg+xml 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.

Source array atomrefenergies(nelem)

Example

atom_energy Zn -1805.01857147

Hint

For this keyword to take effect, please also specify remove_atom_energies.


biasweights_max

Mode 1: image/svg+xml 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.

Source variable biasweights_max

Hint

For this keyword to take effect please also specify separate_bias_ini_short.


biasweights_min

Mode 1: image/svg+xml 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.

Source variable biasweights_min

Hint

This keyword does not have any effect unless separate_bias_ini_short is specified too.


bond_threshold ++

Mode 1: image/svg+xml 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).

Source variable rmin


calculate_final_force

Mode 1: image/svg+xml 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.

Source variable lfinalforce

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: image/svg+xml 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.

Source variable ldoforces


calculate_hessian ++

Mode 1: image/svg+xml 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.

Source variable ldohessian


calculate_stress ++

Mode 1: image/svg+xml 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.

Source variable ldostress


center_symmetry_functions ++

Mode 1: image/svg+xml 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.

Source variable lcentersym


charge_error_threshold ++

Mode 1: image/svg+xml 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.

Source variable kalmanthresholde

Hint

For this keyword to take effect, you need to use the Kalman filter algorithm.


charge_fraction ++

Mode 1: image/svg+xml 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.

Source variable chargernd

Hint

This keyword is used in case of electrostatic_type 1 only.


charge_group ++

Mode 1: image/svg+xml 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.

Source variable nchargegroup


check_forces *

Mode 1: image/svg+xml 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.

Source variable lcheckf


check_input_forces *

Mode 1: image/svg+xml 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: image/svg+xml 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\)

Source variable cutoff_type


data_clustering *

Mode 1: image/svg+xml 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: image/svg+xml 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.

Source variable ldebug


detailed_timing -

Mode 1: image/svg+xml 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.

Source variable lfinetime


detailed_timing_epoch -

Mode 1: image/svg+xml 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.

Source variable lfinetimeepoch


detect_saturation

Mode 1: image/svg+xml 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.

Source variable ldetect_saturation

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: image/svg+xml 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.

Source variable ldynforcegroup

Hint

For this keyword to take effect, please also use short_force_group.


electrostatic_type ++

Mode 1: image/svg+xml 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 keyword fixed_charge.
  • 4:
    The charges are fixed but can be different for each atom in the system. They are specified in the file charges.in.

Source variable nn_type_elec


element_activation_electrostatic +

Mode 1: image/svg+xml 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: image/svg+xml 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: image/svg+xml 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: image/svg+xml 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.

Source variable ledforcesv2


element_decoupled_kalman +

Mode 1: image/svg+xml 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.

Source variable luseedkalman


element_hidden_layers_electrostatic +

Mode 1: image/svg+xml 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.

Source array num_layers_elec(nelem)

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: image/svg+xml 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.

Source array num_layers_short_pair(npairs)

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: image/svg+xml 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.

Source array num_layers_short_atomic(nelem)

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: image/svg+xml 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.

Source array nodes_elec(0:maxnum_layerselec, nelem)

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: image/svg+xml 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.

Source array nodes_short_pair(0:maxnum_layerspair, nelem)

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: image/svg+xml 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.

Source array nodes_short(0:maxnum_layersshort, nelem)

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: image/svg+xml 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 of type. They are explained under global_symfunction_short.
cutoff: (real, default: None)
The symmetry function cutoff radius (unit: Bohr).

Read in readsymfunctionelementpair(...)


elements ++

Mode 1: image/svg+xml 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.

Source array element(nelem)


element_symfunction_electrostatic +

Mode 1: image/svg+xml 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 of type. They are explained under global_symfunction_short.
cutoff: (real, default: None)
The symmetry function cutoff radius (unit: Bohr).

Read in readsymfunctionelementatomic(...)


element_symfunction_short +

Mode 1: image/svg+xml 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 of type. They are explained under global_symfunction_short.
cutoff: (real, default: None)
The symmetry function cutoff radius (unit: Bohr).

Read in readsymfunctionelementatomic(...)


enable_on_the_fly_input

Mode 1: image/svg+xml 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.

Source variable lenableontheflyinput


energy_threshold ++

Mode 1: image/svg+xml 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: image/svg+xml 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: image/svg+xml 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).

Source [variable] enforcetotcharge


environment_analysis

Mode 1: image/svg+xml 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.

Source variable lenvironmentanalysis


epochs ++

Mode 1: image/svg+xml Mode 2: Mode 3:

The number of epochs for fitting. If 0 is specified, RuNNer will calculate the error and terminate without adjusting weights.

Format: epochs i0

i0: (integer, default: 0)
Number of epochs.

Source variable nepochs


ewald_alpha ++

Mode 1: image/svg+xml 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.

Source variable ewaldalpha


ewald_cutoff ++

Mode 1: image/svg+xml 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).

Source variable ewaldcutoff


ewald_kmax ++

Mode 1: image/svg+xml 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.

Source variable ewaldkmax


ewald_prec ++

Mode 1: image/svg+xml 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}\).

Source variable ewaldprec

Hint

This keyword is mandatory if 3G- and 4G-HDNNPs are used.


find_contradictions +

Mode 1: image/svg+xml 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

\[ \Delta G = \sqrt{\sum_{i=1}^N (G_{i,1}-G_{i,2})^2} \,,\notag \]

(\(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

\[ \begin{align} \Delta F &= |\sqrt{F_{1,x}^2+F_{1,y}^2+F_{1,z}^2} -\sqrt{F_{2,x}^2+F_{2,y}^2+F_{2,z}^2}|\,,\notag\\ &= |F_1-F_2| \notag\,. \end{align} \]

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: image/svg+xml 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.

Source variable fitting_unit


fix_weights *

Mode 1: image/svg+xml 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.

Source variable lfixweights


fixed_charge *

Mode 1: image/svg+xml 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).

Source array fixedcharge(nelem)

Example

fixed_charge Zn 2.0
will set the charge on all Zn atoms to 2.0.

Hint

For using fixed charges the keyword use_fixed_charges must be set.


fixed_gausswidth ++

Mode 1: image/svg+xml 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).

Source array fixedgausswidth(nelem)

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: image/svg+xml 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: image/svg+xml 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: image/svg+xml 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.

Source variable lfgroupbystruct


force_threshold ++

Mode 1: image/svg+xml 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: image/svg+xml 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.

Source variable scalefactorf


global_activation_electrostatic ++

Mode 1: image/svg+xml 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 under global_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: image/svg+xml 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 under global_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: image/svg+xml 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: image/svg+xml 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: image/svg+xml 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: image/svg+xml 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: image/svg+xml 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.

Source array nodes_elec(0:maxnum_layerselec, nelem)


global_nodes_pair

Mode 1: image/svg+xml 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.

Source array nodes_short_pair(0:maxnum_layerspair, nelem)


global_nodes_short ++

Mode 1: image/svg+xml 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.

Source array nodes_short(0:maxnum_layersshort, nelem)


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: image/svg+xml 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 of type. They are explained under global_symfunction_short.
cutoff: (real, default: None)
The symmetry function cutoff radius (unit: Bohr).

Read in readsymfunctionelementpair(...)


global_symfunction_electrostatic ++

Mode 1: image/svg+xml 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 of type. They are explained under global_symfunction_short.
cutoff: (real, default: None)
The symmetry function cutoff radius (unit: Bohr).

Read in readsymfunctionelementatomic(...)


global_symfunction_short ++

Mode 1: image/svg+xml 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 of type:

  • 1:
    Radial function. Requires no further parameters.
  • 2:
    Radial function. Requires parameters eta and rshift.
    global_symfunction_short 2 eta rshift cutoff
    
  • 3:
    Angular function. Requires parameters eta, lambda, and zeta.
    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. No cutoff 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, and rshift.
    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 and rshift.
    global_symfunction_short 21 eta rshift cutoff
    
  • 22:
    Radial spin-dependent function using the spin augmentation function \(M^\mathrm{+}\). Requires parameters eta and rshift.
    global_symfunction_short 22 eta rshift cutoff
    
  • 23:
    Radial spin-dependent function using the spin augmentation function \(M^\mathrm{-}\). Requires parameters eta and rshift.
    global_symfunction_short 23 eta rshift cutoff
    
  • 24:
    Angular spin-dependent function using the spin augmentation function \(M^\mathrm{00^*}\). Requires parameters eta, lambda, and zeta.
    global_symfunction_short 24 eta lambda zeta cutoff
    
  • 25:
    Angular spin-dependent function using the spin augmentation function \(M^\mathrm{++}\). Requires parameters eta, lambda, and zeta.
    global_symfunction_short 25 eta lambda zeta cutoff
    
  • 26:
    Angular spin-dependent function using the spin augmentation function \(M^\mathrm{--}\). Requires parameters eta, lambda, and zeta.
    global_symfunction_short 26 eta lambda zeta cutoff
    
  • 27:
    Angular spin-dependent function using the spin augmentation function \(M^\mathrm{+-}\). Requires parameters eta, lambda, and zeta.
    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, and zeta.
    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, and zeta.
    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, and zeta.
    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, and zeta.
    global_symfunction_short 31 eta lambda zeta cutoff
    
cutoff: (real, default: None)
The symmetry function cutoff radius (unit: Bohr).

Read in readsymfunctionelementatomic(...)


growth_mode *

Mode 1: image/svg+xml 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: image/svg+xml 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.

Source variable linionly


ion_forces_only -

Mode 1: image/svg+xml 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.

Source variable lionforcesonly


joint_energy_force_update *

Mode 1: image/svg+xml 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.

Source variable ljointefupdate


kalman_damp_charge

Mode 1: image/svg+xml Mode 2: