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

Source variable kalman_dampq

Hint

This keyword is used in case of electrostatic_type 1 and optmode_charge 1 only.


kalman_damp_force

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

Source variable kalman_dampf

Hint

This keyword is used in case for optmode_short_force 1 only.


kalman_damp_short

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

Source variable kalman_dampe

Hint

This keyword is used for optmode_short_energy 1 only.


kalman_epsilon

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

Set the initialization parameter for the correlation matrix of the Kalman filter according to

\[ P(0)=\epsilon^{-1} \mathcal{I}. \]

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

Source variable kalman_epsilon

Hint

This keyword is mandatory if use_noisematrix is used.


kalman_lambda_charge +

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

Source array kalmanlambdae(nelem)

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

Source array kalmanlambda(nelem)

Hint

This keyword is mandatory for optmode_short_energy 1.


kalman_nue_charge +

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

Source variable kalmannuee

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

Source variable kalmannue

Hint

This keyword is mandatory for optmode_short_energy 1 and optmode_short_force 1


kalman_q0

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

It is possible to add artificial process noise for the Kalman filter in the form of

\[ Q(t) =q(t)\mathcal{I}, \]

with either a fixed \(q(t)=q(0)\) or annealing from a higher \(q(0)\) to \(q_{\mathrm{min}}\) following a scheme like

\[ q(t) = \max(q_{0}e^{-t/\tau_{q}}, q_{\mathrm{min}}). \]

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.

Format: kalman_q0 a0

a0: (real, default: 0.0)
Value of \(q(0)\).

Source variable kalman_q0

Hint

This keyword is mandatory if use_noisematrix is used.


kalman_qmin

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

Source variable kalman_qmin

Hint

This keyword is mandatory if use_noisematrix is used.


kalman_qtau

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

Format: kalman_qtau a0

a0: (real, default: 0.0)
Value of \(\tau_q\).

Source variable kalman_qtau

Hint

This keyword is mandatory if use_noisematrix is used.


max_energy

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

Source variable maxenergy


max_force

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

Source variable maxforce


md_mode --

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

Source variable lmd


mix_all_points ++

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

Source variable lmd


nguyen_widrow_weights_electrostatic

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

Source variable lnwweightse


nguyen_widrow_weights_short

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

Source variable lnwweights


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

Source variable nn_type_short

Hint

This keyword is mandatory.


nnp_gen ++

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

Source variable noiseq


noise_energy

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

Source variable noisee


noise_force

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

Source variable noisef


normalize_nodes +

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

Source variable lnormnodes


number_of_elements ++

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

Source variable nelem

Hint

This keyword is mandatory. For each element there must be an entry for the keyword elements.


optmode_charge ++

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

Source variable optmodeq


optmode_short_energy ++

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

Source variable optmodee


optmode_short_force ++

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

Source variable optmodef


pairsymfunction_short


parallel_mode -

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

Source variable paramode

Hint

This feature is not fully implemented yet and should be used only by developers.


points_in_memory ++

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

Source variable nblock


precondition_weights

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

Source variable lprecond

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.


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

Source variable pstring(3)

Warning

Caution: Use this only for small data sets and few epochs, otherwise your hard disk will be immediately full.


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

Source variable pstring(4)

Warning

Caution: Use this only for small data sets and few epochs, otherwise your hard disk will be immediately full.


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

Source variable pstring(2)

Warning

Caution: Use this only for small data sets and few epochs, otherwise your hard disk will be immediately full.


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

Source variable pstring(1)

Warning

Caution: Use this only for small data sets and few epochs, otherwise your hard disk will be immediately full.


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

Source variable lprintconv


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

Source variable lprintdateandtime


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

Source variable lprintforcecomponents


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

Source variable lprintmad


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

Source variable lsens


random_number_type ++

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

Source variable nran


random_order_training --

This keyword has been deprecated in favor of mix_all_points


random_seed ++

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

Format: random_seed i0

i0: (integer, default: 200)
Seed value.

Source variable iseed


read_kalman_matrices ++

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

Source variable lrestkalman

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

Source variable lreadunformatted

regularize_fit_param

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

Source variable restrictw


remove_atom_energies ++

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

Source variable lremoveatomenergies

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

Source variable lremovevdwenergies

Hint

If this keyword is used the following keywords need to be given as well:


repeated_energy_update ++

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

Source variable lrepeate


reset_kalman

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

Source variable lresetkalman


restrict_weights

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

Source variable restrictw


runner_mode ++

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

Source variable mode

Hint

This keyword is mandatory in all RuNNer modes.


save_kalman_matrices *

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

Source variable lsavekalman

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

Source variable scmax_elec


scale_max_short

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

Source variable scmax_elec


scale_max_short_atomic +

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

Source variable scmax_short_atomic


scale_max_short_pair

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

Source variable scmax_short_pair


scale_min_elec +

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

Source variable scmin_elec


scale_min_short_atomic +

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

Source variable scmin_short_atomic


scale_min_short_pair +

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

Source variable scmin_short_pair


scale_symmetry_functions ++

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

Source variable lscalesym

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

Source variable lseparatebiasini

Warning

This keyword requires the use of keywords biasweights_max and biasweights_min


separate_kalman_short

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

Source variable lsepkalman

Hint

The keyword element_decoupled_kalman will enforce a similar behaviour.


short_energy_error_threshold ++

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

Source variable kalmanthreshold

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

Source variable energyrnd


short_energy_group ++

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

Source variable nenergygroup


short_force_error_threshold ++

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

Source variable kalmanthresholdf

Hint

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


short_force_fraction ++

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

Source variable forcernd


short_force_group ++

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

Source variable nforcegroup


shuffle_weights_short_atomic

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

Source variable steepeststepq

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

Source variable steepeststepe

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

Source variable steepeststepe

Hint

This keyword is relevant only if the steepest descent optimization algorithm has been selected with optmode_charge 3.


symfunction_correlation

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

Source variable lpearson_correlation


symfunction_electrostatic ++

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

Read in readsymfunctionelementatomic(...)


symfunction_short ++

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

Read in readsymfunctionelementatomic(...)


test_fraction ++

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

Source variable splitthres

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

Source variable luseatomcharges


use_atom_spins ++

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

Source variable luseatomspins


use_atom_energies

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

Source variable luseatomenergies


use_charge_constraint *

This keyword has been deprecated and is unlikely to work.


use_damping *

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

Source variables ldampw and dampw.


use_electrostatic_nn ++

This keyword has been deprecated. Please use electrostatic_type and use_electrostatics from now on.


use_electrostatics ++

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

Source variable lelec


use_fixed_charges *

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

Source variable lusefixedcharge

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

Source variable lusefixedcharge

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

Source variable lusenoisematrix


use_old_scaling

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

Source variable luseoldscaling


use_old_weights_charge ++

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

Source variable luseoldweightscharge


use_old_weights_short ++

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

Source variable luseoldweightsshort


use_omp_mkl

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

Source variable lompmkl


use_short_forces ++

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

Source variable luseforces


use_short_nn ++

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

Source variable lshort


use_systematic_weights_electrostatic

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

Source variable lsysweightse


use_systematic_weights_short

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

Source variable lsysweightse


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

Source array vdw_screening(3)

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

Source variable nn_type_vdw

Hint

This keyword must be used if the keyword use_vdw is used.


weight_analysis

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

Source variable lweightanalysis


weight_constraint +

Mode 1: image/svg+xml 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 and layer 2.
  • bias layer node: (integers)
    Bias weight at node node in layer layer.
  • weight layer node layer node: (integers)
    Weight connecting node 1 in layer 1 with node 2 in layer 2.
  • node layer node: (integers)
    All short-range weights connected to node node in layer layer.
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 chosen element's atomic electrostatic NN.

Source array wconstraint(maxnum_weights, nelem)

Examples

The following groups of weights are accepted:

  1. Fix all short-range NN weights for the NN of oxygen:

    weight_constraint O all fixed 
    
  2. 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
    
  3. Optimize the short-range bias weight at node 2 in layer 1 for the NN of zinc:

    weight_constraint Zn bias 1 2 free
    

  4. 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
    
  5. 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: image/svg+xml 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 and layer 2.
  • bias layer node: (integers)
    Bias weight at node node in layer layer.
  • weight layer node layer node: (integers)
    Weight connecting node 1 in layer 1 with node 2 in layer 2.
  • node layer node: (integers)
    All electrostatic weights connected to node node in layer layer.
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 chosen element's atomic electrostatic NN.

Source array wconstrainte(maxnum_weights_elec, nelem)

Examples

The following groups of weights are accepted:

  1. Fix all electrostatic NN weights for the NN of oxygen:

    weighte_constraint O all fixed 
    
  2. 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
    
  3. Optimize the electrostatic bias weight at node 2 in layer 1 for the NN of zinc:

    weighte_constraint Zn bias 1 2 free
    

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

Source variable weightse_max

Hint

This keyword is active only if an electrostatic NN is used, i.e. for electrostatic_type 1.


weights_min ++

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

Source variable weights_min


weightse_max ++

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

Source variable weightse_max


weightse_min ++

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

Source variable weightse_min


write_fit_statistics

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

Format: write_fit_statistics (logical, default: False)

This keyword does not have any further options.

Source variable lfitstats


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

Source variable lwritetmpweights


write_traincharges ++

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

Source variable lwritetraincharges


write_trainforces ++

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

Source variable lwritetrainforces


write_symfunctions -

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

Source variable lwritesymfunctions


write_binding_energy_only +

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

Source variable lbindingenergyonly


write_trainpoints ++

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

Source variable lwritetrainpoints


write_unformatted

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

Write output without any formatting.

Format: write_unformatted (logical, default: False)

This keyword does not have any further options.

Source variable lwriteunformatted


write_weights_epoch ++

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

Source variable iwriteweight

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.