Keywords

The following keywords can be used to control RuNNer 2 by including them in the input.nn file. Some keywords are mandatory and RuNNer 2 will stop with an error message if they are not specified. For other keywords, if omitted, reasonable default values will be set by RuNNer 2. In any case the specific settings can be found in the RuNNer 2 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 2 and cannot be executed. During initialization RuNNer 2 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 2 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).

Keyword Suffixes¶

Many keywords can have suffixes that specify to which kind of neural networks the keyword is applied.

Format: keyword_suffix

keyword: The following keywords can be specified by suffixes:

activation
center_feature_maps
default_optimizer
default_optimizer_comm
initialization_method
no_sf_groups
nodes
opt
overlap_matrix
parameter_max
parameter_min
scale_feature_maps
smooth_overlap_matrix
symfunction

suffix:

short: neural network for short-range energy
charge: neural network for environment-dependent atomic charges
hirshv: neural network for environment-dependent Hirshfeld volumes
chi: neural network for environment-dependent atomic electronegativities
hardness: neural network for environment-dependent atomic hardness

Example

opt_short O 1

opt_charges C 2

initialization_method_hirsh xavier eckhoff

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

+++ = essential keyword.

++ = helpful keyword.

+ = minor keyword.

`2body` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

With this keyword a two-body potential is added to the chosen potential energy representation. This means the model is trained to represent the delta between the reference and the two-body potential energy surface. The two-body potential requires the definition of its type and an index matching to the corresponding neighborlist index.

Format: 2body type_two_body 2body_nl_index

type_two_body: (character)

zbl: Ziegler-Biersack-Littmark

2body_nl_index: (integer) Neighbor list index

Hint

Most of the time the two-body potential is used with a different neighborlist than the descriptors, because they will likely need a different cutoff radius.

`activation` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

This keyword specifies which activation functions are used, not only for neural network models, but also for elemental models.

Format: [element_specific]_activation_model_type[[#!runner-config keyword_suffix](#_keyword_suffix)]_[comm] [element_symbol] [committee_member] function

element_specific: (string, optional)

default: Applies this keyword to all elements. If this is not set, you have to specify for which element this keyword is used.

model_type: (string)

nn: activation functions apply to neural network model(s)
elemental: activation function applies to elemental model(s)

comm: (optional)

If using comm, the whole keyword is only applied to one committee member.

element_symbol: (character, optional)

Element symbol of which the activation function should be set. Only relevant if not using the default option.

committee_member: (integer, optional)

If also using comm this specifies the committee member for which the keyword is used.

function: (string)

Type of the activation function which should be set

t or tanh: hyperbolic tangens
st or stanh: hyperbolic tangens scaled by 1.59223
r or relu: rectified linear unit
l or linear: linear
p or softplus: softplus
s or sigmoid: sigmoid
sq or square: square

Hint

Neural networks need as many activation functions as they have dense layers. The last layer is usually linear.

Elemental models can be used without activations. Activations can help regularize the output of those models.

This keyword can be used with all keyword_suffix.

If the comm option is used for one instance of this keyword, it has to be used all the time.

Example

default_activation_nn_short t t l

activation_nn H s s l

default_activation_elemental l

activation_elemental_hardness s

activation_nn_charge_comm Si 3 p s l

`apply_atomic_property_fraction_by_element` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Apply atomic_property_fraction individually for each element. This can be used to ensure that all elements are always properly included in the atom batch.

Format: apply_atomic_property_fraction_by_element (logical, default: False)

This keyword does not have any further options.

Hint

This keyword is only used when training on atomic properties while also using an atomic_property_fraction < 1.0.

`apply_force_fraction_by_element` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Apply force_fraction individually for each element. This can be used to ensure that all elements are always properly included in the force batch.

Format: apply_force_fraction_by_element (logical, default: False)

This keyword does not have any further options.

Hint

This keyword is only used when training on forces (use_forces) while also using an force_fraction < 1.0.

`apply_loss_threshold_factor_by_element` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Apply loss_threshold_factor_forces individually for each element. This can be used to ensure that all elements are always properly included in the force update. For batches, the loss threshold is a weighted average of the individual loss thresholds in the batch. In case of element specific loss thresholds, the cost used is the cost for each element not the cost for the whole dataset.

Format: apply_loss_threshold_factor_by_element (logical, default: False)

This keyword does not have any further options.

Hint

This keyword is only used when training on forces (use_forces) while also using an loss_threshold_factor_forces . Element pure force batches are necessary for the intended functionality otherwise the thresholds will be averaged. Use batch_forces_by_element when batching forces.

`atom_energy` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

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 train the atomic energies are removed from the total energies, in runner_mode predict 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)

Hint

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

Example

atom_energy Zn -1805.01857147

`atomic_property_fraction` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Fraction of training data points of an atomic property that is randomly selected for training in each epoch. A larger fraction increases the number of updates per epoch. This can also be used to balance the importance of different elements.

Format: atomic_property_fraction element fraction

element: (string): Chemical symbol of the element
fraction: (real, default: 1.0): Fraction of atomic property data points (1.0 = 100%)

Hint

This keyword is only used when training on atomic properties. This includes 2G fits in combination with train_on_atomic_energies, 3G fits in combination with train_charges or train_hirshfeld, and 4G fits in combination with train_charges or train_hardness.

Example

atomic_property_fraction C 0.2

`batch_atomic_properties_by_element` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Group atomic property samples by element type when batching. If True, only element-pure batches are created. Please note that this has no immediate effect on the batchsize itself. However, it can be combined with batchsize_elements. For example, in junction with batchsize_elements set to num_atoms_in_structure_batch it means that one update per element per structure is done. This may greatly speed up training, especially for 4G charge fits.

Format: batch_atomic_properties_by_element (logical, default: False)

This keyword does not have any further options.

Hint

This keyword is only used when training on atomic properties. This includes 2G fits in combination with train_on_atomic_energies, 3G fits in combination with train_charges or train_hirshfeld, and 4G fits in combination with train_charges.

`batch_forces_by_element` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Group force samples by element type when batching. If True, only element-pure batches are created. Please note that this has no immediate effect on the batchsize itself.

Format: batch_forces_by_element (logical, default: False)

This keyword does not have any further options.

Hint

This keyword only takes effect when training on forces in combination with use_forces and batchsize_structures > 1.

`batchsize_elements` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

The number of atoms per element that is concurrently passed through a model. Arguments can be either a single integer value specifying the batchsize for all elements, a chemical symbol followed by an integer value, or the string num_atoms_in_structure_batch (all atoms in a structure batch are passed through the model together).

This keyword has two effects:

it determines the size of the second matrix dimension of the parameter and gradient matrix for all models. This has a direct influence on the speed of forward and backward passes. The actual effect strongly depends on the dataset. For optimal OpenMP parallelization, the batchsize should be chosen as large as possible. In a prediction run, technically all atoms of a given element can be passed through the model at once, leading to a single batched forward/backward pass. For modern CPUs, batchsizes that are powers of two are usually most efficient. If there are fewer atoms than the batchsize, the matrices will be padded accordingly by the program.
it determines the number of samples that are averaged for a single update. This is only true for the training of atomic properties (energies, charges, Hirshfeld volumes etc.). For these properties, this averaging reduces the number of updates.

Format 1: batchsize_elements [element] batchsize

element: (string): Chemical symbol of the element. If not given the batchsize is used for all elements.
batchsize: (integer, default: 1): Batchsize for element.

Example

batchsize_elements 6 10

Format 2: batchsize_elements string

string: (string): Can be set to num_atoms_in_structure_batch to set each elements batchsize automatically to the number of atoms of this element in each individual structure batch.

Example

batchsize_elements num_atoms_in_structure_batch

Hint

Format 1 and Format 2 can not be used together.

The element batchsize can not be larger than the number of atoms of this element in the structure batch. If the specified element batchsize exceeds this number, the maximum possible number is used.

`batchsize_forces` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

The number of force vector components (or force vectors if use_force_vectors is true) that are batched together during force training. Arguments can be either a single integer value specifying the batchsize for all elements, or a chemical symbol followed by an integer value. This keyword only influences the short-range training of models if use_forces or use_force_vectors is true. Note that the keyword has no effect on the number of forward/backward passes per update, as we do one forward/backward pass per neighbor atom, not per target force component.

Format: batchsize_forces element batchsize

element: (string, optional): Chemical symbol of the element. If not given, the batchsize is used for all elements.
batchsize: (integer, default: 1): Number of force samples per batch

Hint

The force batchsize can not be larger than the number of forces of this element in the structure batch. If the specified force batchsize exceeds this number, the maximum possible number is used.

Example

batchsize_forces C 4

batchsize_forces 4

`batchsize_structures` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

The number of structures that is put into a single batch during training. Must be a single integer number. The effect of this keyword depends on the target property:

For energy training, it defines how many total energies are averaged for the calculation of a single loss.
For the training of atomic properties, it determines the size of the pool of atoms from which atom batches are drawn. For example, if batchsize_structures 2 is given, one atom batch contains random atoms from two structures.

Format: batchsize_structures batchsize

batchsize: (integer, default: 1): Number of structures per batch

Example

batchsize_structures 4

`bond_threshold` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Threshold at which a bond (i.e. pair-wise distance) is considered too short for good training. If a bond length smaller than the threshold is found in the dataset, a warning is thrown.

Format: bond_threshold threshold

threshold: (real, default: 0.5): Minimum bond length in Bohr units

Hint

This keyword only takes effect when combined with show_bond_warning

Example

bond_threshold 4

`calculate_derivatives` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

This keyword is used to calculate feature derivatives in runner_mode 1.

Format: calculate_derivatives (logical, default: False)

This keyword does not have any further options.

Hint

Calculating derivatives takes much longer. If you only want the features don't use this keyword.

`calculate_forces` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

This keyword is used to predict the forces in runner_mode predict. Additionally, it can be set in runner_mode train to calculate the cost function value of the force during training, even when not training on forces.

Format: calculate_forces (logical, default: False)

This keyword does not have any further options.

Hint

Calculating the force cost during the training impacts performance and should only be done when the force costs are of interest.

`calculate_stress` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

This keyword is used to predict the stress in runner_mode predict.

Format: calculate_stress (logical, default: False)

This keyword does not have any further options.

`center_feature_maps` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Shift the feature values for all features based on neighborlists (e.g. ACSFs) individually for each feature 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. A more detailed description can be found in the API documentation.

Format: center_feature_maps (logical, default: False)

This keyword does not have any further options.

Hint

In a 4G potential, additionally center_global_feature_maps_q can be used. In an ee4G potential, additionally center_global_feature_maps_ee can be used.

`center_global_feature_maps_ee` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Shift the electrostatic potential features in an ee4G potential individually for each feature 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: ` (logical, default:False`)

This keyword does not have any further options.

Hint

This keyword only centers the electrostatic potential features, not the features based on neighborlists (e.g. ACSFs).

`center_global_feature_maps_q` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Shift the feature values of the charge neuron 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: ` (logical, default:False`)

This keyword does not have any further options.

Hint

In an ee4G potential, additionally center_global_feature_maps_ee can be used to also center the electrostatic potential input neurons.

`check_extrapolations` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Performs feature extrapolation checks during the prediction. This can be useful during active learning.

Format: check_extrapolations (logical, default: False)

This keyword does not have any further options.

`constrain_predicted_charges_before_evaluation` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

If atomic charges and electrostatic energies are calculated, the charges are always projected to sum up to the total charge. If electrostatics are not calculated, this keyword is used to decide if the constrained or unconstrained charges are calculated and stored.

Format: constrain_predicted_charges_before_evaluation (logical, default: False)

This keyword does not have any further options.

Hint

This keyword is always set to false when in RuNNer 1 compatibility mode.

`cost_frequency` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Frequency of the cost function (e.g. RMSE) calculation. ThepPrediction for the whole dataset is quite costly. Doing it less frequently can save training time. This is especially true for fast epochs, e.g. with Adam optimizer, small datasets or small training property fractions.

This also implicitely controls the frequency of writing model weights to file. RuNNer always writes weights files in those epochs in which cost_frequency is hit. By default, this means that weight files are written in every epoch.

Format: cost_frequency frequency [initial_epochs]

frequency: (integer, default: 1): Cost function calculation frequency
initial_epochs: (integer, optional, default: 1): Initial epochs of continuous RMSE calculation

Example

cost_frequency 3

`cost_functions` +¶

List of cost functions used for training

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Array of cost functions used for training.

Format: cost_functions function1 [function2 ...]

cost_functions function1 [function2 ...]: (character array, default: rmse): Space-separated list of cost function names

rmse: Root mean squared error
mse: Mean squared error
mae: Mean absolute error

Hint

This is not the loss that is used for the training, but only the cost that is displayed to monitor the training process.

`default_optimizer` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Sets the default optimizer algorithm and hyperparameters for all committee members that do not have explicitly defined optimizers.

Format: default_optimizer type [hyperparameter1=value1 hyperparameter2=value2 ...]

type: (character): Default optimizer algorithm type

kalman - Multi-Stream Kalman Filter (recommended)
kalman_std - Standard Kalman Filter
adam - Adam optimizer
sgd - Stochastic Gradient Descent with momentum
gd - Gradient Descent

hyperparameter1=value1 ...: (optional): Default optimizer-specific hyperparameters as key=value pairs (same as optimizer)

Hint

This keyword sets the optimizer for all committee members unless overridden by specific optimizer declarations for individual committee members. The hyperparameters specified here will be used as defaults for all committee members. Individual optimizer declarations will override both the algorithm type and hyperparameters for specific committee members. The default optimizer is automatically assigned index 1 and can be referenced by optimizer assignment keywords (opt_short, opt_chi, opt_charge, opt_hardness) using opt_* 1.

Example

# Set Kalman filter as default for all committee members
default_optimizer kalman lambda=0.98 nue=0.9987 p_initial=1.0

# Set Adam as default with custom learning rate
default_optimizer adam learning_rate=1e-4

`default_optimizer_comm` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Alternative syntax for setting the default optimizer for committee-based calculations. This is equivalent to default_optimizer.

Format: default_optimizer_comm type [hyperparameter1=value1 hyperparameter2=value2 ...]

type: (character): Default optimizer algorithm type

kalman - Multi-Stream Kalman Filter (recommended)
kalman_std - Standard Kalman Filter
adam - Adam optimizer
sgd - Stochastic Gradient Descent with momentum
gd - Gradient Descent

hyperparameter1=value1 ...: (optional): Default optimizer-specific hyperparameters as key=value pairs (same as optimizer)

Hint

This keyword is functionally identical to default_optimizer and is provided for backward compatibility or alternative syntax preference. Use either keyword but not both simultaneously.

Example

# Set Kalman filter as default for all committee members
default_optimizer_comm kalman lambda=0.98 nue=0.9987 p_initial=1.0

`disable_blocked_dsymm` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Disables the use of blocked dsymm calls in multithreaded environments. The blocked dsymm implementation is used by default to work around threading issues in certain MKL versions, but can be disabled if it causes performance problems or compatibility issues.

The issue with certain MKL versions is that the calls to dsymm seem to be not thread safe which can cause a sudden explosion in the fits. We implemented our own blocked dsymm implementation, which uses a parallelisation strategy by blocking the matrix. Note that the MKL issue only appears for matrices in a certain size regime.

Format: disable_blocked_dsymm (logical, default: False)

This keyword does not have any further options.

Hint

This is primarily a debugging and performance tuning option. The blocked dsymm implementation is enabled by default and provides improved performance in multithreaded environments. Only disable it if you encounter specific issues.

Example

disable_blocked_dsymm

`dont_use_old_global_scaling` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Overwrites use_old_scaling_global_features_q and use_old_scaling_global_features_ee statements. If set, the corresponding scaling.data files done't have to be provided. This can be useful when using RuNNer 1 fits since no scaling was applied (and no corresponding scaling.data was written) to global features in RuNNer 1.

Format: dont_use_old_global_scaling (logical, default: False)

This keyword does not have any further options.

Hint

This also overwrites the automatic use of use_old_global_scaling_{q,ee4g} from mode predict. This can lead to wrong predictions.

`dont_use_old_scaling` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Overwrite all use_old_scaling statements.

Format: dont_use_old_scaling (logical, default: False)

This keyword does not have any further options.

Hint

This also overwrites the automatic use of use_old_scaling from mode predict. This can lead to wrong predictions. The only purpose of this keyword is debuging in the absence of a scaling.data file.

`dont_use_old_weights` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Overwrite all use_old_weights statements.

Format: dont_use_old_weights (logical, default: False)

This keyword does not have any further options.

Hint

This also overwrites the automatic use of use_old_weights from mode predict. This leads to wrong predictions as random weights are used. The only purpose of this keyword is debuging in the absence of weights.xyz.data files.

`ee4g` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Enables EE4G option of a 4G potential.

Format: ee4g (logical, default: False)

This keyword does not have any further options.

Hint

Only takes effect if nnp_generation is 4.

`elec_method` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Electrostatics method used for the calculation of the electrostatic energies.

Format: elec_method method

method: (character, default: pw): Electrostatics calculation method

pw: plain wave calculator
pair: Pair calculator
ewald: Ewald summation
pppm: Particle-Particle Particle-Mesh calculator

Hint

For non-periodic structures elec_calc is automatically set to pair. The pair calculator can not be used for periodic structures.

`electric_field_prefactor_beta` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Electric Field Prefactor Beta (TODO what does it do? really used in 3G?)

Format: electric_field_prefactor_beta value

value: (real, default: 1.0): Beta prefactor for electric field calculations

`electric_field_prefactor_gamma` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Electric Field Prefactor Gamma

(TODO what does it do? really used in 3G?)

Format: electric_field_prefactor_gamma value

value: (real, default: 1.0): Gamma prefactor for electric field calculations

`electrostatics_precision` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Precision used for the electrostatics calculator.

Format: electrostatics_precision precision

precision: (real, default: 1.0e-9): Precision threshold for electrostatic calculations

Hint

The electrostatic precision value has to be smaller than the value set for iter_tol, otherwise the noise is bigger than the convergence threshold for the iterative solvers.

`elements` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Chemical elements present in the dataset.

Format: elements element1 [element2 ...]

element1 [element2 ...]: (character array): Space-separated list of element symbols

Example

elements C H O N

`energy_fraction` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Fraction of energy data points randomly selected for training in each epoch. 1 = 100% usage of data points. This changes the number of updates per epoch.

Format: energy_fraction fraction

fraction: (real, default: 1.0): Fraction of energy data points (1.0 = 100%)

`enforce_charge_training`¶

Mode 1: • Mode 2: • Mode 3:

Generation 2: • Generation 3: • Generation 4:

If set to true, we will do a charge equilibration during 4G long-range training even if the hardness is fixed. This is the default for training with reference charges. Otherwise we will compute reference electronegativites from the reference charges and train the electronegativity network directly. If you set this to true, you should increase the batch size (i.e. batchsize_elements or num_atoms_in_structure_batch) since the training will be quite slow otherwise. This is since we need to do a Qeq calculation for each update of the electronegativity network.

Format: enforce_charge_training (logical, default: True)

This keyword does not have any further options.

Example

enforce_charge_training

`epochs` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Number of training epochs.

Format: epochs num_epochs

num_epochs: (integer, default: 20): Number of training epochs

`extrapolation_warning_type` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Type of the printed extrapolation warnings.

Format: extrapolation_warning_type type

type: (integer, default: 0)

Warning type

0: Sum
1: n2p2-type
2: n2p2-type, extended (incl. the index of the extrapolating committee member.)

Hint

This keyword only takes effect in combination with check_extrapolations Since the extrapolations of a global feature is dependent on the committee member, be advised to use warning type 2 instead of 1.

`fc_cosine` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Defines a cosine cutoff function with smooth transition between inner and outer cutoff radii. The cutoff function smoothly transitions from 1 at the inner cutoff to 0 at the outer cutoff radius.

Mathematical Formula:

\[f_c(r_{ij}) = \begin{cases} 1 & \text{if } r_{ij} < r_{ci} \\ \frac{1}{2}\left[\cos\left(\frac{\pi(r_{ij} - r_{ci})}{r_{co} - r_{ci}}\right) + 1\right] & \text{if } r_{ci} \leq r_{ij} \leq r_{co} \\ 0 & \text{if } r_{ij} > r_{co} \end{cases}\]

where \(r_{ci}\) is the inner cutoff radius and \(r_{co}\) is the outer cutoff radius.

Format: fc_cosine cutoff_function_index [inner_cutoff] cutoff_radius

cutoff_function_index: (integer): Unique index identifying this cutoff function for use in feature maps/symmetry functions
inner_cutoff: (real): Optional inner cutoff radius in Bohr (function equals 1 below this radius). Defaults to 0.0 when omitted.
cutoff_radius: (real): Outer cutoff radius in Bohr (function equals 0 above this radius)

Hint

The cutoff function index must be unique and is used to reference this cutoff function in symmetry function definitions. The inner cutoff should be smaller than the outer cutoff radius. Omitting the inner cutoff is equivalent to setting it to 0.0.

Example

fc_cosine 1 10.5

fc_cosine 2 2.0 8.0

`fc_hard` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Defines a hard (step function) cutoff function that abruptly transitions from 1 to 0 at the cutoff radius. This cutoff function has no smooth transition region.

Mathematical Formula:

\[f_c(r_{ij}) = \begin{cases} 1 & \text{if } r_{ij} \leq r_{co} \\ 0 & \text{if } r_{ij} > r_{co} \end{cases}\]

where \(r_{co}\) is the cutoff radius.

Format: fc_hard cutoff_function_index cutoff_radius

cutoff_function_index: (integer): Unique index identifying this cutoff function for use in feature maps/symmetry functions
cutoff_radius: (real): Cutoff radius in Bohr (function equals 1 below and 0 above this radius)

Hint

The cutoff function index must be unique and is used to reference this cutoff function in symmetry function definitions. Hard cutoff functions can cause discontinuities in derivatives, which may affect training stability.

Example

fc_hard 1 12.0

fc_hard 3 8.5

`fc_hypertangent` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Defines a hyperbolic tangent cutoff function with smooth transition between inner and outer cutoff radii. This cutoff function provides a smooth transition using the hyperbolic tangent function.

Mathematical Formula:

\[f_c(r_{ij}) = \begin{cases} \tanh^3(1) & \text{if } r_{ij} \leq r_{ci} \\ \tanh^3\left(1 - \frac{r_{ij} - r_{ci}}{r_{co} - r_{ci}}\right) & \text{if } r_{ci} < r_{ij} \leq r_{co} \\ 0 & \text{if } r_{ij} > r_{co} \end{cases}\]

where \(r_{ci}\) is the inner cutoff radius and \(r_{co}\) is the outer cutoff radius.

Format: fc_hypertangent cutoff_function_index [inner_cutoff] cutoff_radius

cutoff_function_index: (integer): Unique index identifying this cutoff function for use in feature maps/symmetry functions
inner_cutoff: (real): Optional inner cutoff radius in Bohr. Defaults to 0.0 when omitted.
cutoff_radius: (real): Outer cutoff radius in Bohr (function equals 0 above this radius)

Hint

The cutoff function index must be unique and is used to reference this cutoff function in symmetry function definitions. The inner cutoff should be smaller than the outer cutoff radius. Omitting the inner cutoff is equivalent to setting it to 0.0.

Example

fc_hypertangent 1 12.0

fc_hypertangent 4 0.5 9.0

`fc_hypertangent_approx` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Defines a hyperbolic tangent cutoff function using a rational approximation for the hyperbolic tangent. This cutoff function follows the same cutoff shape as fc_hypertangent, replacing \(\tanh(x)\) with \(x(27 + x^2)/(27 + 9x^2)\).

Mathematical Formula:

\[f_c(r_{ij}) = \begin{cases} \left(\frac{7}{9}\right)^3 & \text{if } r_{ij} \leq r_{ci} \\ a^3\left(1 - \frac{r_{ij} - r_{ci}}{r_{co} - r_{ci}}\right) & \text{if } r_{ci} < r_{ij} \leq r_{co} \\ 0 & \text{if } r_{ij} > r_{co} \end{cases}\]

where \(a(x) = x(27 + x^2)/(27 + 9x^2)\), \(r_{ci}\) is the inner cutoff radius, and \(r_{co}\) is the outer cutoff radius.

Format: fc_hypertangent_approx cutoff_function_index [inner_cutoff] cutoff_radius

cutoff_function_index: (integer): Unique index identifying this cutoff function for use in feature maps/symmetry functions
inner_cutoff: (real): Optional inner cutoff radius in Bohr. Defaults to 0.0 when omitted.
cutoff_radius: (real): Outer cutoff radius in Bohr (function equals 0 above this radius)

Hint

The cutoff function index must be unique and is used to reference this cutoff function in symmetry function definitions. The inner cutoff should be smaller than the outer cutoff radius. Omitting the inner cutoff is equivalent to setting it to 0.0.

Example

fc_hypertangent_approx 1 12.0

fc_hypertangent_approx 4 0.5 9.0

`fc_polynomial` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Defines a polynomial cutoff function with smooth transition to zero at the cutoff radius. This cutoff function uses a polynomial function to smoothly decay from 1 to 0.

Mathematical Formula:

\[f_c(r_{ij}) = \begin{cases} \left(1 - \frac{r_{ij}^2}{r_{co}^2}\right)^n & \text{if } r_{ij} \leq r_{co} \\ 0 & \text{if } r_{ij} > r_{co} \end{cases}\]

where \(r_{co}\) is the cutoff radius and \(n\) is the polynomial exponent.

Format: fc_polynomial cutoff_function_index exponent cutoff_radius

cutoff_function_index: (integer): Unique index identifying this cutoff function for use in feature maps/symmetry functions
cutoff_radius: (integer): Polynomial exponent (order of the polynomial)
cutoff_radius: (real): Cutoff radius in Bohr (function smoothly transitions to 0 at this radius)

Hint

The cutoff function index must be unique and is used to reference this cutoff function in symmetry function definitions. The polynomial cutoff provides smooth derivatives making it suitable for force training.

Example

fc_polynomial 1 3 12.0

fc_polynomial 5 4 10.5

`fc_vdw` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Defines a van der Waals cutoff function with inner and outer cutoff radii and buffer zones. This specialized cutoff function is designed for van der Waals interactions with flexible transition regions.

Mathematical Formula:

\[f_c(r_{ij}) = \begin{cases} 0 & \text{if } r_{ij} \leq r_{ci} \text{ or } r_{ij} > r_{co} \\ 3r_{bi}^2 - 2r_{bi}^3 & \text{if } r_{ci} < r_{ij} \leq r_{ci} + d_{bi} \\ 1 & \text{if } r_{ci} + d_{bi} < r_{ij} \leq r_{co} - d_{bo} \\ 1 - 3r_{bo}^2 + 2r_{bo}^3 & \text{if } r_{co} - d_{bo} < r_{ij} \leq r_{co} \end{cases}\]

where: - \(r_{bi} = \frac{r_{ij} - r_{ci}}{d_{bi}}\) (inner buffer region) - \(r_{bo} = \frac{r_{ij} - r_{co} + d_{bo}}{d_{bo}}\) (outer buffer region) - \(r_{ci}\) is the inner cutoff radius, \(r_{co}\) is the outer cutoff radius - \(d_{bi}\) is the inner buffer width, \(d_{bo}\) is the outer buffer width

Format: fc_vdw cutoff_function_index inner_cutoff cutoff_radius inner_cutoff_buffer outer_cutoff_buffer

cutoff_function_index: (integer): Unique index identifying this cutoff function for use in feature maps/symmetry functions
inner_cutoff: (real): Inner cutoff radius in Bohr
cutoff_radius: (real): Outer cutoff radius in Bohr
inner_cutoff_buffer: (real): Buffer zone width for inner cutoff transition in Bohr
outer_cutoff_buffer: (real): Buffer zone width for outer cutoff transition in Bohr

Hint

The cutoff function index must be unique and is used to reference this cutoff function in symmetry function definitions. This cutoff function is specifically designed for van der Waals corrections and requires all four distance parameters. The inner cutoff should be smaller than the outer cutoff radius.

Example

fc_vdw 1 2.0 15.0 1.0 2.0

fc_vdw 6 1.5 12.0 0.5 1.5

`feature_extrapolation_threshold` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Threshold for local feature extrapolations during prediction. Local features, such as symmetry functions or overlap matrices, whose absolute difference between its value and the min/max values observed during training are above this threshold throw a warning.

Format: feature_extrapolation_threshold threshold

threshold: (real, default: 1.0e-4): Extrapolation threshold value

Hint

For this keyword to take effect check_extrapolations has to be given.

`feature_map_default` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Use default feature maps for all models (Short-range, electrostatic, hardness, ...) instead of model-specific feature maps. Symmetry functions can then be specified by symfunction without any suffix.

Format: feature_map_default (logical, default: False)

This keyword does not have any further options.

`feature_minmax_threshold` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Gives a threshold for minimal difference between minimum and maximum of a feature. This is done to avoid division by zero during the scaling of the features.

Format: feature_minmax_threshold threshold

threshold: (real, default: 1.0e-5): Minimum difference threshold

Hint

The threshold has to be set to a value greater than 0.

`fitting_unit_energy` +¶

Mode 1: • Mode 2: • Mode 3:

Generation 2: • Generation 3: • Generation 4:

Sets the energy unit of the cost functions during fitting.

Format: fitting_unit <conversion_factor> <unit_name>

conversion_factor: (real, default: \(1000\,\,\cdot\) \(\mathrm{eV}/E_\mathrm{h}\)): Conversion factor to internal units
unit_name: (string, default: meV): Name of the unit

Example

To get the RMSE in hartree use: fitting_unit_energy 1.0 hartree

To get in eV instead of meV use: fitting_unit_energy 27.2114 eV

`fitting_unit_length` +¶

Mode 1: • Mode 2: • Mode 3:

Generation 2: • Generation 3: • Generation 4:

Sets the length unit of the cost functions during fitting.

Format: fitting_unit_length <conversion_factor> <unit_name>

conversion_factor: (real, default: 1.0): Conversion factor to internal units
unit_name: (string, default: bohr): Name of the unit

Example

fitting_unit_length 0.529177 Angstrom

`fix_biases` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

This keyword can be used to fix certain bias parameters of a neural network. Those biases are then not updated during training.

Format: fix_biases_[comm] element_symbol [committee_member] layer_id bias_id

element_symbol: (str): Element for which the neural network bias is fixed
committee_member: (integer, optional): If also using comm this specifies the committee member for which the keyword is used.
layer_id: (int): Hidden layer in which the bias is fixed
bias_id: (int): ID of the fixed bias in its layer. Set to -1 to address all biases in this layer.

Example

fix_biases H 2 14

fix_biases_comm H 4 1 24

fix_biases C 2 -1

`fix_weights` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

This keyword can be used to fix certain weight parameters of a neural network. Those weights are then not updated during training.

Format: fix_weights _[comm] element_symbol [committee_member] layer_id weight_id

element_symbol: (str): Element for which the neural network weight is fixed
committee_member: (integer, optional): If also using comm this specifies the committee member for which the keyword is used.
layer_id: (int): Hidden layer in which the weight is fixed
weight_id: (int): ID of the fixed weight in its layer. Set to -1 to address all weights in this layer.

Example

fix_weights H 1 7

fix_weights_comm H 2 1 -1

`fixed_gausswidth` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Width of the Gaussian charges used to calculate the electrostatics. The width describes the gaussians standard deviation in bohr. The default values are covalent radii taken from WebElements.

Format: fixed_gausswidth element width

element: (string): Chemical symbol of the element
width: (real): Gaussian width parameter

Hint

A gausswidth of 0.0 gives point charges. Point charges are not the default!

Example

fixed_gausswidth H 1

fixed_gausswidth C 1.5

`force_fraction` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Fraction of force data points randomly selected for training in each epoch. 1 = 100% usage of force components. This changes the number of updates per epoch. Together with force_update_scaling this keyword can be used to balance the effect of energy and force updates.

Format: force_fraction element fraction

element: (string): Chemical symbol of the element
fraction: (real, default: 1.0): Fraction of force data points (1.0 = 100%)

`force_training_sum_neighbors_derivatives` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Whether to sum up the contributions of each neighbor derivative during force training. If True, one backward pass will be performed for each atom in the structure. This can improve performance without changing the results.

Format: force_training_sum_neighbors_derivatives (logical, default: False)

This keyword does not have any further options.

Hint

This should be set to True if you expect to have less atoms than neighbors for the structures in your dataset (e.g. bulk water).

`force_update_scaling` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Scaling factor for the force loss and loss gradients.

Format: force_update_scaling element scaling

element: (string): Chemical symbol of the element
scaling: (real, default: 1.0): Scaling factor

Hint

The primary use case for this keyword is the balancing between force and energy updates and, e.g., using less force updates with force_fraction, but with a higher force_update_scaling. This keyword can also be used to balance the importance of force updates on different elements.

Example

force_update_scaling C 3.0

`format_ascii` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Enable ASCII format output of features computed in runner_mode precompute.

Format: format_ascii (logical, default: False)

This keyword does not have any further options.

Hint

If human readability is not important, the much faster format_binary should be used. format_binary also allows to write the feature derivatives and to start a training from the precalculated features. Both output types are not exclusive and can be used together.

`format_binary` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Enable binary format output of features and feature drivatives computed in runner_mode precompute. Binary features and feature derivatives can later be used to start a training run.

Format: format_binary (logical, default: False)

This keyword does not have any further options.

Hint

In nearly all cases it is faster to directly train in runner_mode train instead of writing and reading from a file! Also note that the files can get quite big and could block the bandwidth of your cluster for a long time when downloading.

`global_feature_extrapolation_threshold` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Threshold for global feature extrapolations during prediction. Global features, such as QEq charges or electrostatcially embedded potentials, whose absolute difference between its value and the min/max values observed during training are above this threshold throw a warning.

Format: feature_extrapolation_threshold threshold

threshold: (real, default: 1.0e-4): Extrapolation threshold value

Hint

For this keyword to take effect check_extrapolations has to be given.

`gradient_clipping_norm_boundary` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Norm boundary value for the gradient. Gradients with a higher norm are scaled to the boundary norm. This helps prevent exploding gradients.

Format: gradient_clipping_norm_boundary value

value: (real, default: 20.0): Norm boundary value

Hint

The default value is only applied when the keyword is set.

`gradient_clipping_value_boundary`¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Gradients are clipped to the interval [-value, +value] to prevent exploding gradients.

Format: gradient_clipping_value_boundary value

value: (real, default: 5.0): Upper boundary value

Hint

The default value is only applied when the keyword is set.

`hirshfeld_vdw_damp_parm` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

A damping function parameter of the Hirshfeld Van-der-Waals correction.

Format: hirshfeld_vdw_damp_parm parameter

parameter: (real, default: 20.0): Damping parameter

`hirshfeld_vdw_sr` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Scaling factor \(s_r\) of the damping function of the Hirshfeld Van-der-Waals correction.

Format: hirshfeld_vdw_sr scaling

scaling: (real, default: 1.0): Scaling factor

`initialization_method` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Specifies the methods used for initialization of the neural networks. This can be combined with precondition_method. Some initialization methods use information about the trainingset. The initialization of the parameters connecting the last hidden layer to the output nodes and the output nodes bias can be set seperately from all other weights.

Format: initialization_method hidden_layer_method [output_layer_method] [preconditioning]

hidden_layer_method: (string, default: uniform)

Method used to initialize parameters up to last hidden layer.

uniform: uniform initialization between parameter_min and parameter_max.
legacy_xavier or legacy_glorot: Xavier initialization method as used in RuNNer 1 and described in PHYSICAL REVIEW B 102,174102 (2020) and J. Chem. Phys. 153, 164107 (2020). This is not the widely used method known in the literature as Xavier initialization. All biases are set to 0.0, all weights are drawn out of \(\frac{1}{\sqrt{N_\text{input}}}\cdot \mathcal{U} (-1, 1)\).
lecun_normal: Lecun normal initialization with the goal to yield approximately unit variance of the activations of all nodes. All biases are set to 0.0. All weights are drawn out of \(\mathcal{N} (-\frac{1}{\sqrt{N_\text{input}}}, +\frac{1}{\sqrt{N_\text{input}}})\).
lecun_uniform or legacy_xavier_modified or legacy_glorot_modified: Lecun uniform initialization with the goal to yield approximately unit variance of the activations of all nodes. All biases are set to 0.0. All weights are drawn out of \(\sqrt{\frac{3}{N_\text{input}}} \cdot \mathcal{U}(-1, 1)\).
xavier or glorot: Xavier initialization as described in Proceedings of the Thirteenth International Conference on Artificial Intelligence and Statistics, PMLR 9:249-256, 2010. Note that this is not equivalent to the method of the same name in RuNNer 1. The goal of this initialization is to preserve activation variance and gradient variance. All biases are set to 0.0. All weights are drawn out of \(\sqrt{\frac{6}{N_\text{input} + N_\text{layer}}} \cdot \mathcal{U}(-1,1)\).
xavier_modifiedor glorot_modified: Equivalent to legacy_xavier_modified, but based on the correct xaviermethod, not on legacy_xavier. All biases are set to 0.0. All weights are drawn out of \(\sqrt{\frac{18}{N_\text{input} + N_\text{layer}}} \cdot \mathcal{U}(-1,1)\).
nguyen_widrow: Nguyen-Widrow initialization as described in D. Nguyen, B. Widrow in 1990 IJCNN international joint conference on neural networks, IEEE, 1990, pp. 21–26.
nguyen_widrow_legacy or nguyen_widrow_runner1: Nguyen-Widrow initialization as was implemented in RuNNer 1.
read: read parameters from file. This can be used to restart a fit from old results.

output_layer_method: (string, default: hidden_layer_method)

Method used to initialize parameters after last hidden layer. All hidden_layer_method keywords can be used except nguyen_widrow, nguyen_widrow_legacy, and nguyen_widrow_runner1. If those keywords are used for the hidden layers, the default for the output layer is set to uniform. Additional keywords that can be used for the output layer:

eckhoff: Performs a least square fit of the stoichiometries and the trainingset structure properties (e.g. energy) to get elementwise solutions for the average atomic properties. The output bias of the atomic neural network is then set to the solution of the least square fit. Additionally, the initialization of the weights leading to the output neuron are scaled to approximately reproduce the correct range of target values by multiplying them with \(\frac{\text{target_range}}{\sqrt{N_\text{input}}}\). Details are listed in this paper and in this paper.
eckhoff_modified: The output nodes bias is initialized in the same way as with eckhoff. The weights are scaled to reproduce the targets standard deviation, not its range. The multiplication factor is: \(\frac{\text{target_std}}{0.885 \cdot \sqrt{N_\text{input}}}\) This initialization is intended to be used with the scaled hyperbolic tangent activation_function.

preconditioning: (string)

If hidden_layer_method is read one can add precondition_method to be default by using

precondition_anyway

Hint

This keyword can be used with suffixes.

If eckhoff is used the regularization parameter can be changed by stating weight_init_regularization.

If runner_mode is predict, the initialization is overwritten to be read.

Examples

initialization_method_charges read

initialization_method read precondition_anyway

initialization_method_short xavier

initialization_method lecun_uniform lecun_uniform

initialization_method nguyen_widrow

initialization_method glorot eckhoff

`iter_tol` +++¶

Convergence threshold for the iteratve Qeq solver.

Format: iter_tol tolerance

tolerance: (real, default: 1.0e-7): Convergence tolerance

Hint

If the threshold is set too low the charge equilibration can take much longer. Since the charge equilibration can be the time limiting step, this does matter.

The value of iter_tol has to be higher than the value of the electrostatics_precision. Otherwise the electrotatic noise will be higher than the convergence threshold of the QeQ solver.

`loss_threshold_factor_atomic_properties` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Factor with which the atomic property cost is multiplied to give the atomic property loss threshold. Atomic property updates are then only done on properties with a loss above the loss threshold.

Format: loss_threshold_factor_atomic_properties factor

factor: (real, default: 0.0): Threshold factor

Hint

This reduces the number of updates per epoch.

Example

loss_threshold_factor_atomic_properties 0.1

`loss_threshold_factor_energy` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Factor with which the energy cost is multiplied to give the energy loss threshold. Energy updates are then only done on energies with a loss above the loss threshold.

Format: loss_threshold_factor_energy factor

factor: (real, default: 0.0): Threshold factor

Hint

This reduces the number of updates per epoch.

Example

loss_threshold_factor_energy 0.1

`loss_threshold_factor_forces` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Factor with which the force cost is multiplied to give the force loss threshold. Force updates are then only done on forces with a loss above the loss threshold.

Format: loss_threshold_factor_forces factor

element: (string): Chemical symbol of the element
factor: (real, default: 0.0): Threshold factor

Hint

Can reduce number updates with already well represented points. For elemental threshold also set apply_loss_threshold_factor_by_element and read the explanation carefully.

Example

loss_threshold_factor_forces 1

loss_threshold_factor_forces H 3

`lower_cost_threshold` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

If the cost (i.e. the RSME) for all committee members is below the the training is stopped. This is checked for each epoch after the specified epoch. It compares the cost with whatever the is set to (i.e. the energy train MAE or the force test RMSE and so on).

Format: lower_cost_threshold value epoch

value: (real): Cost threshold value
epoch: (integer): Starting epoch for threshold check

Hint

This keyword uses the same units as the input.data file (Ha), not as the cost function output (meV)!

This keyword is used to save computational ressources. If a fit is already good enough after less than the maximum number of epochs, all following unnessecary epochs are skiped.

The specified epoch can vary with the frequency of calculatiion of the cost function.

In the same way a upper_cost_threshold can be set to stop training when fits explode during the training.

Example

lower_cost_threshold 1.0 3

`max_ram_size` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Maximum RAM usage limit for calculations. The needed RAM usage of RuNNer is estimated and the dataset chunked in a way to achieve RAM requirements lower than the limit. It makes a huge speed difference if one or multiple chunks are used, so if you currently are using two chunks, see if you can increase max_ram_size. You can see the current number of chunks in the header section of the RuNNer output.

Format: max_ram_size <specifier> [unit]

specifier: (real | str, default: available): Either Maximum RAM size in unit or one of the strings available or total.
unit: (string, default: MiB): Unit of RAM size. One of MB, GB, TB or MiB, GiB, TiB. Where 1 GB is 1000 MB and 1 GiB is 1024 MiB.

Hint

You have to divide your aiming RAM by amount of mpi processes.

You can reduce you RAM requirements by using neighborlist_statistics_run

Example

max_ram_size 1024 For 1GiB

max_ram_size 1 GB For 1 GB

max_ram_size available Use all available RAM (determined when the program starts)

`model_type_charges` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Type of model used for electrostatics.

Format: model_type_charges model_type

model_type: (character, default: hdnn): Model type for electrostatics

hdnn
elemental

Hint

elemental does not train charges at all! It only uses element specific values.

Example

model_type_charges hdnn

`model_type_chi` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Type of model used for electrostatics.

Format: model_type_chi model_type

model_type: (character, default: hdnn): Model type for electrostatics

hdnn
elemental

Hint

elemental does not train chi at all! It only uses element specific values.

Example

model_type_chi hdnn

`model_type_hardness` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Type of model used for the hardness in a 4G potential.

Format: model_type_hardness model_type

model_type: (character, default: hdnn): Model type for hardness

hdnn
elemental

Hint

elemental does not train charges at all! It only uses element specific values.

Example

model_type_hardness elemental

`model_type_hirshfeld` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Type of model used for Hirshfeld volumes.

Format: model_type_hirshfeld model_type

model_type: (character, default: hdnn): Model type for Hirshfeld volumes

hdnn
elemental

Hint

elemental does not train charges at all! It only uses element specific values.

Example

model_type_hirshfeld hdnn

`model_type_short` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Type of model used for short-range energy.

Format: model_type_short model_type

model_type: (character, default: hdnn): Model type for short-range interactions

hdnn
elemental

Hint

elemental does not train charges at all! It only uses element specific values.

Example

model_type_short hdnn

`neighborlist_allocation_margin` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Multiplication factor applied to the the storage size of the neighbor list upon allocation. Can improve performance in LAMMPS simulations by decreasing the number of neighbor list reallocations. Increases memory usage.

Format: neighborlist_allocation_margin margin

margin: (real, default: 1.2): Multiplication factor.

Hint

This keyword only takes effect in LAMMPS simulations.

Example

neighborlist_allocation_margin 1.0

`neighborlist_statistics_run` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

If enabled the neigborlist will be constructed in two steps:

1. All neighbors are counted.

2. The neigborlist is populated.

This makes it possible to avoid resizing of the neighborlist, which can result in a memory usage spike.

Format: neighborlist_statistics_run (logical, default: False)

This keyword does not have any further options.

Hint

Only use this option if you are limited by RAM. Otherwise, the default option is faster.

Example

neighborlist_statistics_run

`nnp_generation` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Specifies the NNP Generation.

2G: short range NN
3G: combine short range and local NN (e.g. electrostatic potentials based on environment dependent charges)
4G: combine short range and global NN (e.g. electrostatic potentials with charge equilibration)

Format: nnp_generation (generation)

generation: (integer, default: 2): NNP generation number (2, 3, or 4)

Example

nnp_generation 4

`no_charge_neuron` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Deactivate the use of a charge neuron as a feature of the short-range neural network of a 4G potential.

Format: no_charge_neuron (logical, default: False)

This keyword does not have any further options.

`no_predict_charges` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Disable prediction of charges. This is only meaningful in the 4G case. There, only electronegativities and hardnesses are predicted if this option is activated.

Format: no_predict_charges (logical, default: False)

This keyword does not have any further options.

`no_predict_electrostatics` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Disables the prediction of electrostatic interactions. This means that electrostatic contributions are not subtracted from the total energy, saving time if only charges are of interest. Thus, the globally-dependent short-range part is trained to approximate the full total energy.

Format: no_predict_electrostatics (logical, default: False)

This keyword does not have any further options.

`no_predict_short_range` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Disables the prediction of short-range interactions.

Format: no_predict_short_range (logical, default: False)

This keyword does not have any further options.

Hint

todo

Example

no_predict_short_range

`no_sf_groups` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Format: no_sf_groups (logical, default: False)

This keyword does not have any further options.

Hint

Just makes the code slower and should only used for debugging of the symmetry function groups.

`no_shuffle_atomic_properties` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Do not shuffle atomic properties during training.

Format: no_shuffle_atomic_properties (logical, default: False)

This keyword does not have any further options.

Hint

Debugging tool. Should not be used normally.

`no_shuffle_forces` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Do not shuffle forces for training.

Format: no_shuffle_forces (logical, default: False)

This keyword does not have any further options.

Hint

Debugging tool. Should not be used normally.

`no_shuffle_structures` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Do not shuffle structures for training.

Format: no_shuffle_structures (logical, default: False)

This keyword does not have any further options.

Hint

Debugging tool. Should not be used normally.

`nodes` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Specifies the number of nodes in the hidden layers of neural networks. The nodes can be set separately for different committee members, elements, or types of model.

Format: [element_specific]_nodes[#!runner-config keyword_suffix](#_keyword_suffix)]_[comm] [element_symbol] [committee_member] num_nodes_layer1 num_nodes_layer2 ...

element_specific: (string, optional)

default: Applies this keyword to all elements. If this is not set, you have to specify for which element this keyword is used.

comm: (optional)

If using comm, the whole keyword is only applied to one committee member.

element_symbol: (str): Element symbol of which the number of layers should be set

committee_member: (integer, optional)

If also using comm this specifies the committee member for which the keyword is used.

num_nodes: (int): Number of nodes in the hidden layers

Hint

This keyword can be used in combination with keyword_suffix.

The number of hidden layers implied have to be consistent with the number of activation given.

If the comm option is used for one instance of this keyword, it has to be used all the time.

Example

nodes H 20 10

nodes_short_comm 2 C 15 15 15

default_nodes_hardness 25 25

`num_committee_members` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Number of committee members used during prediction and training. When training with a committee size > 1, each members files are automatically written into subfolders named 1, 2, 3, ... During prediction all files are also read from there.

Format: num_committee_members members

members: (integer, default: 1): Number of committee members

Hint

Can save resources in predicting and training.

Features and train test split will be shared in training.

Look at random_seed to see how random seeds work for committees.

Example

num_committee_members 5

`opt` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

This keyword allows you to specify which optimizer (defined by optimizer or default_optimizer) should be used for training which model. The model type is specified by a suffix behind the opt keyword. One optimizer can be used to train multiple models.

Format 1: opt_suffix optimizer_index

optimizer_index: (integer): Index of the optimizer to use for all neural networks of this type (e.g. charge)

Format 2: opt_charge element optimizer_index

element: (string): Chemical symbol of the element
optimizer_index: (integer): Index of the optimizer to use for this element's neural network of this type

Hint

You must use either Format 1 (global assignment) OR Format 2 (per-element assignment) consistently - you cannot mix both formats.

The optimizer_index must correspond to an optimizer defined using optimizer or default_optimizer (which has index 1).

Related keywords

See optimizer, default_optimizer.

Example

# Use optimizer 1 for all charge neural networks
opt_short 1

# Use different optimizers for different elements
opt_charges H 1    # Hydrogen uses optimizer 1
opt_charges C 2    # Carbon uses optimizer 2
opt_charges O 1    # Oxygen uses optimizer 1

`optimal_epoch_property` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

This keyword determines which property and which of the sets is used to determine the best performing epoch. The weights and other output files of this epoch are then also given the prefix opt (e.g. opt.weights.001.out). Also at the end of the training the best epoch is printed in the standard out.

Format: optimal_epoch_property property [dataset]

property: (character)

Property name for optimal epoch selection

energy
force
charge
hirshfeld_volume

dataset: (character, optional, default: test)

Dataset to use

train
test

Hint

Note that this is just a useful information. You always have to check which epoch fits your demands the best.

Example

optimal_epoch_property force test

`optimizer` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • :material-plus-minus-box : Generation 3: • Generation 4:

Defines the optimizer algorithm used for neural network training of the atomic neural network.

Format: optimizer index type [hyperparameter1=value1 hyperparameter2=value2 ...]

index: (integer): Optimizer index (starting from 1) - allows defining multiple optimizer configurations
type: (character): Optimizer algorithm type

kalman - Multi-Stream (Fading-Memory) Kalman Filter (default for most cases)
kalman_std - Multi-Stream Standard Kalman Filter
adam - Adam optimizer
sgd - Stochastic Gradient Descent with momentum
gd - Gradient Descent

hyperparameter1=value1 ...: (optional): Optimizer-specific hyperparameters as key=value pairs

For Multi-Stream (Fading-Memory) Kalman Filter (kalman):

lambda=value - Initial update parameter controlling measurement noise (default: 0.98)
nue=value - Stepsize for lambda updates, acts as forgetting factor (default: 0.9987)
p_initial=value - Initial diagonal correlation matrix value (default: 1.0)
regularize=true/false - Enable matrix regularization (default: false)
reg_eps=value - Regularization epsilon parameter (default: 1e-8)
reg_degenaracy=value - Threshold for detecting degenerate eigenvalues (default: 1e-5)
loss_function=type - Loss function type (default: mae)
write_restart=true/false - Writes P-matrix in optimizer_restart_x_y.data and prints lambda in stdout every epoch.
read_restart=true/false - Reads optimizer_restart_x_y.data and uses it as the initial P-matrix

For Multi-Stream Standard Kalman Filter (kalman_std):

eta_initial=value - Initial learning rate/measurement noise (default: 0.01)
eta_tau=value - Growth constant for eta (default: 2.302)
eta_max=value - Maximum value eta can reach (default: 1.0)
process_noise=true/false - Enable artificial process noise (default: false)
q_initial=value - Initial process noise (default: 0.01, only if process_noise=true)
q_tau=value - Decay constant for q (default: 2.302, only if process_noise=true)
q_min=value - Minimum value q can reach (default: 1e-6, only if process_noise=true)
update_hyperparameters=true/false - Enable hyperparameter updates (default: true)
p_initial=value - Initial diagonal correlation matrix value (default: 1.0)
regularize=true/false - Enable matrix regularization (default: false)
reg_eps=value - Regularization epsilon parameter (default: 1e-8)
reg_degenaracy=value - Threshold for detecting degenerate eigenvalues (default: 1e-5)
loss_function=type - Loss function type (default: mae)

For Adam (adam):

learning_rate=value - Step size (default: 1e-3)
beta1=value - First moment decay rate (default: 0.9)
beta2=value - Second moment decay rate (default: 0.999)
epsilon=value - Small constant for numerical stability (default: 1e-8)
loss_function=type - Loss function type (default: mse)

For SGD (sgd):

learning_rate=value - Step size (default: 1e-3)
momentum=value - Momentum factor (default: 0.9)
loss_function=type - Loss function type (default: mse)

For Gradient Descent (gd):

learning_rate=value - Step size (default: 1e-2)
loss_function=type - Loss function type (default: mse)

Available Loss Functions (loss_function=type):

mse - Mean Squared Error (L2 loss): Penalizes large errors heavily, smooth gradients (default)
mae - Mean Absolute Error (L1 loss): Robust to outliers, linear penalty for errors
rmse - Root Mean Squared Error: Same units as target variable, compromise between MSE and MAE

Hint

The index parameter allows you to define multiple optimizer configurations that can be referenced by optimizer assignment keywords (opt_short, opt_chi, opt_charge, opt_hardness). Each optimizer configuration can be assigned to specific neural network components and elements through those assignment keywords. The Kalman filter is generally recommended for most RuNNer applications. See also default_optimizer for setting a default optimizer.

Example

# Kalman filter with custom hyperparameters
optimizer 1 kalman lambda=0.98 nue=0.9987 p_initial=1.0

# Adam optimizer with custom learning rate
optimizer 2 adam learning_rate=1e-4 beta1=0.9

# SGD with momentum
optimizer 3 sgd learning_rate=1e-3 momentum=0.9

# Gradient descent
optimizer 4 gd learning_rate=1e-2

# Kalman filter with regularization for numerical stability
optimizer 6 kalman lambda=0.95 regularize=true reg_eps=1e-6

`optimizer_comm` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Alternative syntax for defining optimizer algorithms for specific committee members. This is an addition to optimizer.

Format: optimizer_comm opt_index comm_index type [hyperparameter1=value1 hyperparameter2=value2 ...]

opt_index: (integer): Optimizer index (starting from 1)
comm_index: (integer): Committee member index (starting from 1)
type: (character): Optimizer algorithm type

kalman - Multi-Stream Kalman Filter (recommended)
kalman_std - Standard Kalman Filter
adam - Adam optimizer
sgd - Stochastic Gradient Descent with momentum
gd - Gradient Descent

hyperparameter1=value1 ...: (optional): Optimizer-specific hyperparameters as key=value pairs (same as optimizer)

Hint

Unlike optimizer, this keyword allows you to define an optimizer for a specific committee member directly, without needing separate assignment keywords. The first index is the optimizer index, the second is the committee member index.

Example

# Optimizer 1 for committee member 1
optimizer_comm 1 1 kalman lambda=0.98 nue=0.9987 p_initial=1.0

# Optimizer 2 for committee member 2
optimizer_comm 2 2 adam learning_rate=1e-4 beta1=0.9

`overlap_matrix` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Defines Overlap Matrix Fingerprint (OMFP) descriptors as atomic environment features. The overlap matrix descriptor computes eigenvalues of an overlap matrix constructed from atomic orbitals within a cutoff sphere around each central atom. These eigenvalues provide a description of the local chemical environment.

The overlap_matrix keyword can be combined with suffixes to specify model-specific feature maps (e.g., overlap_matrix_short, overlap_matrix_charges, overlap_matrix_hirsh). When using feature_map_default, use the base overlap_matrix keyword without suffixes.

Format: overlap_matrix element num_features num_s_orb num_p_orb scale_flag cutoff_index

element: (string): Element symbol of the central atom (e.g., H, O, C)
num_features: (integer): Number of features (eigenvalues) to extract from the overlap matrix
num_s_orb: (integer): Number of s-orbitals on each atom (typically 1)
num_p_orb: (integer): Number of p-orbital sets (px, py, pz) on each atom (0, 1, or higher)
scale_flag: (logical): Scaling flag (T/F) - whether to scale features relative to all features
cutoff_index: (integer): Index of the cutoff function defined by fc_cosine, fc_hard, etc.

Hint

The overlap matrix is constructed from atomic orbitals (s and p) within the cutoff sphere
Eigenvalues of this matrix serve as atomic environment descriptors
num_features determines how many of the largest eigenvalues are used
If more eigenvalues exist than requested features, the smallest ones are discarded
If fewer eigenvalues exist, the feature vector is zero-padded at the beginning
When using feature_map_default, use overlap_matrix for all models
Without feature_map_default, use model-specific suffixes: overlap_matrix_short, overlap_matrix_charges, etc.
The cutoff_index must correspond to a previously defined cutoff function
Scale flag affects how features are normalized across the dataset

Example

"With feature_map_default"

# Define cutoff function first
fc_cosine 1 0.0 12.0

# Use feature_map_default for all models
feature_map_default

# Basic overlap matrix with s-orbitals only
overlap_matrix Al 120 1 1 T 1

# Overlap matrix with s and p orbitals
overlap_matrix O 50 1 1 F 1

# Different numbers of features for different elements
overlap_matrix H 80 1 0 T 1

"With model-specific suffixes"

# Define cutoff function first
fc_cosine 1 0.0 12.0

# Short-range model (2G, 3G, 4G)
overlap_matrix_short Al 120 1 1 T 1
overlap_matrix_short O 60 1 1 F 1
overlap_matrix_short H 80 1 0 T 1

# Electrostatic model (3G only)
overlap_matrix_charge Al 80 1 1 T 1
overlap_matrix_charge O 40 1 1 F 1
overlap_matrix_charge H 60 1 0 T 1

# Electronegativity model (4G only)
overlap_matrix_chi Al 80 1 1 T 1
overlap_matrix_chi O 40 1 1 F 1
overlap_matrix_chi H 60 1 0 T 1

# Hardness model (4G only)
overlap_matrix_hardness Al 80 1 1 T 1
overlap_matrix_hardness O 40 1 1 F 1
overlap_matrix_hardness H 60 1 0 T 1

# Hirshfeld volume model (3G, 4G only)
overlap_matrix_hirshv Al 100 1 1 T 1
overlap_matrix_hirshv O 50 1 1 F 1
overlap_matrix_hirshv H 70 1 0 T 1

`parameter_max` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Format: parameter_max value

value: (real, default: 1.0) Upper limit of values drawn from uniform distribution for the parameter initialization

Hint

Only takes effect when initialization_method is set to uniform.

Normally, parameter_min should be set to the corresponding negative value.

Example

parameter_max 0.3

`parameter_min` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Format: parameter_min value

value: (real, default: 1.0) Lower limit of values drawn from uniform distribution for the parameter initialization

Hint

Only takes effect when initialization_method is set to uniform.

Normally, parameter_max should be set to the corresponding positive value.

Example

parameter_min 0.3

`post_calc_charge_grads_norm` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Normalization of the 4G charge loss gradients used in the 4G charge training. For further information, please see the FAQs.

Format: post_calc_charge_grads_norm norm_type

norm_type: (character, default: none)

Normalization type for charge loss gradient

num_atoms_batch (i.e. number of atoms in the respective structure batch)
average_num_atoms_batch (i.e. average number of atoms per structure in the respective structure batch)
num_backward_passes_batch
none (i.e. 1.0)

Example

post_calc_charge_grads_norm num_atoms_batch

`post_calc_charge_loss_norm` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Normalization of the 4G charge loss used in the 4G charge training. For further information, please see the FAQs.

Format: post_calc_charge_loss_norm norm_type

norm_type: (character, default: none)

Normalization type for charge loss

num_atoms_batch (i.e. number of atoms in the respective structure batch)
average_num_atoms_batch (i.e. average number of atoms per structure in the respective structure batch)
num_backward_passes_batch
none (i.e. 1.0)

Example

post_calc_charge_loss_norm num_atoms_batch

`post_calc_energy_grads_norm` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Normalization of the energy loss gradients. For further information, please see the FAQs.

Format: post_calc_energy_grads_norm norm_type

norm_type: (character, default: average_num_atoms_batch)

Normalization type for energy gradients

num_atoms_batch (i.e. number of atoms in the respective structure batch)
average_num_atoms_batch (i.e. average number of atoms per structure in the respective structure batch)
num_backward_passes_batch
none (i.e. 1.0)

Example

post_calc_energy_grads_norm num_atoms_batch

`post_calc_energy_loss_norm` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Normalization of the energy loss. For further information, please see the FAQs.

Format: post_calc_energy_loss_norm norm_type

norm_type: (character, default: none)

Normalization type for energy loss

num_atoms_batch (i.e. number of atoms in the respective structure batch)
average_num_atoms_batch (i.e. average number of atoms per structure in the respective structure batch)
num_backward_passes_batch
none (i.e. 1.0)

Example

post_calc_energy_loss_norm num_atoms_batch

`post_calc_force_grads_norm` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Normalization of the force loss gradients. For further information, please see the FAQs.

Format: post_calc_force_grads_norm norm_type

norm_type: (character, default: average_num_atoms_batch)

Normalization type for force gradients

num_atoms_batch (i.e. number of atoms in the respective structure batch)
average_num_atoms_batch (i.e. average number of atoms per structure in the respective structure batch)
num_backward_passes_batch
none (i.e. 1.0)

Example

post_calc_force_grads_norm num_atoms_batch

`post_calc_force_loss_norm` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Normalization of the force loss. For further information, please see the FAQs.

Format: post_calc_force_loss_norm norm_type

norm_type: (character, default: none)

Normalization type for force loss

num_atoms_batch (i.e. number of atoms in the respective structure batch)
average_num_atoms_batch (i.e. average number of atoms per structure in the respective structure batch)
num_backward_passes_batch
none (i.e. 1.0)

Example

post_calc_force_loss_norm num_atoms_batch

`post_calc_property_grads_norm` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Normalization of the atomic property loss gradients used e.g. in the 3G charge training. For further information, please see the FAQs.

Format: post_calc_property_grads_norm norm_type

norm_type: (character, default: none)

Normalization type for property gradient loss

num_atoms_batch (i.e. number of atoms in the respective structure batch)
average_num_atoms_batch (i.e. average number of atoms per structure in the respective structure batch)
num_backward_passes_batch
none (i.e. 1.0)

Example

post_calc_property_grads_norm num_atoms_batch

`post_calc_property_loss_norm` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Normalization of the atomic property loss used e.g. in the 3G charge training. For further information, please see the FAQs.

Format: post_calc_property_loss_norm norm_type

norm_type: (character, default: none)

Normalization type for property loss

num_atoms_batch (i.e. number of atoms in the respective structure batch)
average_num_atoms_batch (i.e. average number of atoms per structure in the respective structure batch)
num_backward_passes_batch
none (i.e. 1.0)

Example

post_calc_property_loss_norm num_atoms_batch

`pre_calc_charge_norm` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Normalization of the predicted and reference 4G charges before the calculation of the loss and loss gradients. For further information, please see the FAQs.

Format: pre_calc_charge_norm norm_type

norm_type: (character, default: none)

Normalization type for charge predictions and references

num_atoms
1_over_num_atoms
none (i.e. 1.0)

Example

pre_calc_charge_norm num_atoms

`pre_calc_energy_norm` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Normalization of the predicted and reference energies before the calculation of the loss and loss gradients. For further information, please see the FAQs.

Format: pre_calc_energy_norm norm_type

norm_type: (character, default: none)

Normalization type for energy predictions and references

num_atoms
1_over_num_atoms (yields the total energy of a structure, since we work with atomic energies by default)
none (i.e. 1.0, which yields the average total energy per atom)

Example

pre_calc_energy_norm num_atoms

`pre_calc_force_norm` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Normalization of the predicted and reference forces before the calculation of the loss and loss gradients. For further information, please see the FAQs.

Format: pre_calc_force_norm norm_type

norm_type: (character, default: num_atoms)

Normalization type for force predictions and references

num_atoms
1_over_num_atoms
none (i.e. 1.0)

Example

pre_calc_force_norm num_atoms

`pre_calc_property_norm` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Normalization of the predicted and reference atomic properties (i.e. 3G charges) before the calculation of the loss and loss gradients. For further information, please see the FAQs.

Format: pre_calc_property_norm norm_type

norm_type: (character, default: none)

Normalization type for property predictions and references

num_atoms
1_over_num_atoms
none (i.e. 1.0)

Example

pre_calc_property_norm num_atoms

`precompute_coulomb_matrices` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Enforces the precalculation of all coulomb matrices for the provided input.data at the start of the program.

Format: precompute_coulomb_matrices (logical, default: False)

This keyword does not have any further options.

Hint

The memory required to store all coulomb matrices is not constrained and can exceed your machine’s physical memory capacity.

SELECT THIS KEYOWRD ONLY IF YOU KNOW WHAT YOU ARE DOING!

The safe way to influence the precomputation of the coulomb matrices is by setting max_ram_size.

`precompute_feature_derivatives` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Enforces the precalculation of all feature derivatives for the provided input.data at the start of the program.

Format: precompute_feature_derivatives (logical, default: False)

This keyword does not have any further options.

Hint

The memory required to store all feature derivatives is not constrained and can exceed your machine’s physical memory capacity.

SELECT THIS KEYOWRD ONLY IF YOU KNOW WHAT YOU ARE DOING!

The safe way to influence the precomputation of the feature derivatives is by setting max_ram_size.

`precompute_features` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Enforces the precalculation of all features for the provided input.data at the start of the program.

Format: precompute_features (logical, default: False)

This keyword does not have any further options.

Hint

The memory required to store all features is not constrained and can exceed your machine’s physical memory capacity.

SELECT THIS KEYOWRD ONLY IF YOU KNOW WHAT YOU ARE DOING!

The safe way to influence the precomputation of the features is by setting max_ram_size.

`precompute_global_feature_derivatives` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Enforces the precalculation of all global feature derivatives for the provided input.data at the start of the program.

Format: precompute_global_feature_derivatives (logical, default: False)

This keyword does not have any further options.

Hint

The memory required to store all global feature derivatives is not constrained and can exceed your machine’s physical memory capacity.

SELECT THIS KEYOWRD ONLY IF YOU KNOW WHAT YOU ARE DOING!

The safe way to influence the precomputation of the global feature derivatives is by setting max_ram_size.

`precompute_global_features` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Enforces the precalculation of all global features for the provided input.data at the start of the program.

Format: precompute_global_features (logical, default: False)

This keyword does not have any further options.

Hint

The memory required to store all global features is not constrained and can exceed your machine’s physical memory capacity.

SELECT THIS KEYOWRD ONLY IF YOU KNOW WHAT YOU ARE DOING!

The safe way to influence the precomputation of the global features is by setting max_ram_size.

`precondition_method` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Specifies the method used for preconditioning the neural networks output bias before training. At the moment the only option is default. In contrast to initialization_method, preconditioning requires an additional full forward-pass at the beginning of the preconditioning. The preconditioning uses information about the trainingset and the output of the forward-pass.

Format: precondition_method method_name

method_name: (string, default:none)

default: This has two effects: It changes the output bias, so that the mean output of the neural networks matches the reference of the trainingset. Also, it scales the weights leading into the output node, so that the standard deviation of the prediction fits the standard deviation of the reference.
none: does nothing

Hint

Preconditioning can be restricted to different types of neural networks by using the suffixes short, elec, hirsh, and elemental, otherwise it affects all neural networks.

Example

precondition_method_short default

precondition_method default

`predict_vdw` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Whether to predict long-range dispersion interactions.

Format: predict_vdw type

type: (character, default: False)

VdW prediction type:

hirshfeld
default

Example

predict_vdw hirshfeld

`prevent_loss_threshold_reset` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Prevent automatic reset of loss thresholds. Normally the loss threshold is adapted if it was set too high and no updates were done.

Format: prevent_loss_threshold_reset (logical, default: False)

This keyword does not have any further options.

`property_threshold` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Apply a threshold to a property of all structures read from the structure data file. Thresholds may either be a global (per structure) or atomic (per atom) property If any atom in a structure falls outside the threshold bounds, the entire structure is excluded from the training dataset.

Thresholds for multi-column properties are applied to all columns of that property (e.g. x-, y-, and z-components of the forces). Structures are removed from the dataset during the first parsing step, and ignored on each subsequent pass-through of the input.data file.

Format: property_threshold type name lnorm min max

type: (character, default: None): Type of the object to which this threshold applies. Supported are either "structure" or "atom".
name: (character, default: None): The name of the threshold. Can be any string, but must match a column specified in the input.data file. This may also be one of the default columns.
lnorm: (logical, default: .false.): Whether to normalize the property by the number of atoms in the structure. Only useful when type = "structure", ignored otherwise.
min: (real, default: -MAX_DBLE): The minimum (inclusive) allowed value for the property.
max: (real, default: MAX_DBLE): The maximum (inclusive) allowed value for the property.

`qeq_method` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Specifies the Qeq method that is used. Iterative ones are faster but might not converge.

Format: qeq_method method

method: (character, default: cg) Qeq calculation method:

direct
sqnm
cg

Hint

If one iterative solver doesn't converge try a different one. For some datasets one works much better than the other.

Example

qeq_method cg

`random_seed` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

The seed for the general random number generator. For committees either give a random seed for each member, or one random seed from which seed for all members will be generated. In this case, the seed for the first committee member corresponds to this seed.

Format: random_seed seed1 [seed2 ...]

seed1 [seed2 ...]: (integer array): Random seed values for each committee member

Hint

Multiple random seeds only work with same number of num_committee_members. You can also only set one random seed. This seed is then not only used as seed for the first committee member, but also for the random generation of the seeds of all remaining committee members.

Example

random_seed 42

random_seed 42 345 567 678 789

`random_seed_force_frac` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Random seed to determine the forces that are drawn from the force fraction. Per default the general random_seed is used (in case of a committee, the random_seed of the first committee member).

Format: random_seed_force_frac seed

seed: (integer, default: value of random_seed): Random seed for force fraction selection

Example

random_seed_force_frac 42

`random_seed_shuffle` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Random seed for shuffling the structures. Per default the general random_seed is used (in case of a committee, the random_seed of the first committee member).

Format: random_seed_shuffle seed

seed: (integer, default: value of random_seed): Random seed for structure shuffling

Example

random_seed_shuffle 42

`random_seed_split` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Random seed for the train/test split. Per default the general random_seed is used (in case of a committee, the random_seed of the first committee member).

Format: random_seed_split seed

seed: (integer, default: value of random_seed): Random seed for train/test splitting

Example

random_seed_split 42

`read_coulomb_matrix` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Load a precalculated coulomb matrix. (TODO when is this helpful?)

Format: read_coulomb_matrix (logical, default: False)

This keyword does not have any further options.

Hint

Needs to be precalculated in mode 1.(TODO keyword)

Example

read_coulomb_matrix

`read_feature_derivatives` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Load precalculated feature derivatives. (TODO when is this helpful?)

Format: read_feature_derivatives (logical, default: False)

This keyword does not have any further options.

Hint

Needs to be precalculated in mode 1.(TODO keyword)

`read_features` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Load precalculated features. This can be helpful if many fits are trained with the same features.

Format: read_features (logical, default: False)

This keyword does not have any further options.

Hint

Needs to be precalculated in mode 1.(TODO keyword)

`read_global_feature_derivatives_ee` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Read precalculated ee4g feature derivatives from file instead of computing them.

Format: read_global_feature_derivatives_ee (logical, default: False)

This keyword does not have any further options.

Hint

You need to precalculate the feature derivatives for your dataset in mode precompute with format_binary. The input.data has to stay the same.

`read_global_feature_derivatives_q` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Read precalculated global feature derivatives from file instead of computing them.

Format: read_global_feature_derivatives_q (logical, default: False)

This keyword does not have any further options.

Hint

You need to precalculate the feature derivatives for your dataset in mode precompute format_binary. The input.data has to stay the same.

`read_global_features_ee` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Read precalculated ee4g features from file instead of computing them.

Format: read_global_features_ee (logical, default: False)

This keyword does not have any further options.

Hint

You need to precalculate the features for your dataset in mode precompute with format_binary. The input.data has to stay the same.

`read_global_features_q` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Read precalculated global features from file instead of computing them.

Format: read_global_features_q (logical, default: False)

This keyword does not have any further options.

Hint

You need to precalculate the features for your dataset in mode precompute format_binary. The input.data has to stay the same.

`remove_atom_energies` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Remove atomic energy contributions. Useful to have a smaller range of energies if the dataset consists of structures with different stochiometries.

Format: remove_atom_energies (logical, default: False)

This keyword does not have any further options.

Hint

You need to set the energies opf each element in the dataset with atom_energy.

`repeated_energy_update` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Perform an energy update after each force update. This can help balancing the number of energy and force updates.

Format: repeated_energy_update (logical, default: False)

This keyword does not have any further options.

Hint

Only takes effect if training on forces with use_forces

`runner_mode` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

RuNNer execution mode.

Format: runner_mode mode

mode: (string, default: train)

RuNNer execution mode. Valid options are:

precompute: Feature calculation
train: Training
predict: Prediction

Hint

Beware some keywords have different effects in both train and predict mode. This is normally done to minimize the number of changes that have to be done to the input.nn between training and prediction.

Example

runner_mode train

`saturation_check` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Perform a saturation check for all nodes.

Format: saturation_check (logical, default: False)

This keyword does not have any further options.

Hint

Even if this keyword is not activated, the code wold slow down because of the number of if statements needed to check for the keyword activation. To prevent this, this keyword only works if RuNNer is compiled with Features complete. This will impact performance even if the keyword is not set to true!

`scale_feature_maps` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Applies scaling to the features to map them to a range of 1.0. The exact details are described in the API documentation.

Format: ` (logical, default:False`)

This keyword does not have any further options.

Hint

Additionally, centering the features around a value of 0.0 is done by using center_feature_maps.

If you want to reuse scaling factors from an old fit, use use_old_scaling.

`scale_feature_maps_range` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Scales local feature values to the fixed range [min, max] defined by the values given in this keyword. Can not be used in combination with scale_feature_maps. or [#!runner-config center_feature_maps](#center_feature_maps).

Format: scale_feature_maps_range min max

min: (real): Minimum value of the scaled features
max: (real): Maximum value of the scaled features

`scale_global_feature_maps_ee` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Applies scaling to the ee4G features to map them to a range of 1.0. The exact details are described in the API documentation.

Format: ` (logical, default:False`)

This keyword does not have any further options.

Hint

Centering the ee4G features around a value of 0.0 is done by using center_global_feature_maps_ee.

If you want to reuse scaling factors from an old fit, use use_old_scaling_global_features_ee.

`scale_global_feature_maps_q` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Applies scaling to the global charge features of a 4G to map them to a range of 1.0. The exact details are described in the API documentation.

Format: ` (logical, default:False`)

This keyword does not have any further options.

Centering the global features around a value of 0.0 is done by using center_global_feature_maps_q.

If you want to reuse scaling factors from an old fit, use use_old_scaling_global_features_q.

`screening_function` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Cut-off function index of the cutoff function that should be used for the screening function.

Format: screening_function index

index: (integer, default: 1): Cutoff function index for screening

Hint

Index should be identical with the index declared in the declaration of the cutoff function.

Example

screening_function 2

`show_bond_warning` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

List all too short bonds (i.e. pair-wise distances) by structure and atom indices according to the order in input.data.

Format: show_bond_warning (logical, default: False)

This keyword does not have any further options.

Hint

You can set the bondthreshold in bond_threshold

`smooth_overlap_matrix` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Defines "smooth" Overlap Matrix Fingerprint descriptors as atomic environment features. This is an enhanced version of the overlap matrix descriptor that transforms eigenvalues using a smooth mathematical function to ensure well-defined derivatives and consistent feature vectors.

The smooth overlap matrix transforms eigenvalues using:

\[G_j = \frac{1}{N} \sum_{i=1}^{N_{eval}} \sin(F_i \times x_j)\]

where \(F_i\) are the largest eigenvalues, \(x_j\) are grid points, and \(N\) is the number of features. This provides smoother, more differentiable features compared to the standard overlap matrix.

This keyword can be combined with model-specific suffixes (_short, _charges, _chi, _hirsh) when not using feature_map_default. See the Keyword Suffixes section for details.

Format: smooth_overlap_matrix element num_features grid_length num_eval num_s_orb num_p_orb scale_flag cutoff_index

element: (string): Element symbol of the central atom (e.g., H, O, C)
num_features: (integer): Number of features in the smoothed feature vector (grid points)
grid_length: (real): Length of the uniform grid for smooth transformation (typically ~15.0)
num_eval: (integer): Number of largest eigenvalues to use in the smooth transformation
num_s_orb: (integer): Number of s-orbitals on each atom (typically 1)
num_p_orb: (integer): Number of p-orbital sets (px, py, pz) on each atom (0, 1, or higher)
scale_flag: (logical): Scaling flag (T/F) - whether to scale features relative to all features
cutoff_index: (integer): Index of the cutoff function defined by fc_cosine, fc_hard, etc.

Hint

Advantages over regular overlap matrix: Smoother features with well-defined derivatives
The smooth transformation: \(G_j = \frac{1}{N} \sum_{i=1}^{N_{eval}} \sin(F_i \times j \times \text{grid\_spacing})\)
grid_spacing = grid_length / num_features is computed automatically
num_eval should be ≤ num_features (number of eigenvalues to use)
Use when you need differentiable features without discontinuities
More computationally expensive than regular overlap matrix
When using feature_map_default, use smooth_overlap_matrix for all models
Without feature_map_default, use model-specific suffixes. See Keyword Suffixes for details.

Example

"With feature_map_default"

# Define cutoff function first
fc_cosine 1 0.0 12.0

# Use feature_map_default for all models
feature_map_default

# Smooth overlap matrix with optimal parameters
smooth_overlap_matrix Al 50 15.0 30 1 1 T 1

# Different grid settings for different elements
smooth_overlap_matrix O 80 20.0 40 1 1 F 1
smooth_overlap_matrix H 40 10.0 25 1 0 T 1

"With model-specific suffixes"

# Define cutoff function first
fc_cosine 1 0.0 12.0

# Short-range model (2G, 3G, 4G)
smooth_overlap_matrix_short Al 60 15.0 40 1 1 T 1
smooth_overlap_matrix_short O 80 20.0 50 1 1 F 1

# Electrostatic model (3G, 4G only)
smooth_overlap_matrix_charge Al 40 12.0 25 1 1 T 1
smooth_overlap_matrix_charge O 60 18.0 35 1 1 F 1

# Hirshfeld volume model (3G, 4G only)
smooth_overlap_matrix_hirshv Al 30 10.0 20 1 0 T 1
smooth_overlap_matrix_hirshv O 45 15.0 30 1 1 F 1

`symfunction` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Defines atomic environment descriptors (symmetry functions) used as neural network inputs. Symmetry functions are translation-, rotation-, and permutation-invariant mathematical functions that describe the local atomic environment around each atom.

For detailed mathematical descriptions and theory, see Symmetry Functions in the Theory section.

The symfunction keyword can be combined with suffixes to specify model-specific feature maps (e.g., symfunction_short, symfunction_charges, symfunction_hirsh). When using feature_map_default, use the base symfunction keyword without suffixes.

Radial Type 2 Format: symfunction element 2 neighbor_element eta Rs cutoff_index

element: (string): Element symbol of the central atom (e.g., H, O, C)
2: (integer): Symmetry function type (2 = radial Gaussian)
neighbor_element: (string): Element symbol of the neighboring atoms
eta: (real): Width parameter of the Gaussian function (controls the width of the radial shell)
Rs: (real): Shift parameter (radial shift of the Gaussian, often 0.0)
cutoff_index: (integer): Index of the cutoff function defined by fc_cosine, fc_hard, etc.

Radial Type 32 Format: symfunction element 2 modifiers=(weighted) eta Rs weight_type x cutoff_index

element: (string): Element symbol of the central atom (e.g., H, O, C)
2: (integer): Symmetry function type (2 = radial Gaussian)
modifiers=(weighted): (string): Modifier (weighted = = weighted prefactor )
eta: (real): Width parameter of the Gaussian function (controls the width of the radial shell)
Rs: (real): Shift parameter (radial shift of the Gaussian, often 0.0)
weight_type: (integer): Type of the weight factor depending on which period and group the elements are.
x: (integer): Max period + 1
cutoff_index: (integer): Index of the cutoff function defined by fc_cosine, fc_hard, etc.

Angular Type 3 Format: symfunction element 3 neighbor1 neighbor2 eta lambda zeta cutoff_index

element: (string): Element symbol of the central atom
3: (integer): Symmetry function type (3 = angular)
neighbor1: (string): Element symbol of the first neighboring atom
neighbor2: (string): Element symbol of the second neighboring atom
eta: (real): Width parameter of the Gaussian function
lambda: (real): Angular parameter (1.0 or -1.0, controls angular behavior)
zeta: (real): Exponent parameter (typically 1.0, 2.0, 4.0, or 16.0)
cutoff_index: (integer): Index of the cutoff function

Angular Type 8 Format: symfunction element 8 neighbor1 neighbor2 theta_shift eta cutoff_index

element: (string): Element symbol of the central atom
3: (integer): Symmetry function type (3 = angular)
neighbor1: (string): Element symbol of the first neighboring atom
neighbor2: (string): Element symbol of the second neighboring atom
theta_shift: (real): Shift of the Gaussian function in degrees
eta: (real): Width parameter of the Gaussian function
cutoff_index: (integer): Index of the cutoff function

Radial Type 33 Format: symfunction element 3 modifiers=(weighted) eta lambda zeta weight_type x gamma cutoff_index

element: (string)

Element symbol of the central atom (e.g., H, O, C)

3: (integer)

Symmetry function type (3 = = angular )

modifiers=(weighted): (string)

Modifier (weighted = = weighted prefactor )

eta: (real)

Width parameter of the Gaussian function (controls the width of the radial shell)

lambda: (real)

Angular parameter (1.0 or -1.0, controls angular behavior)

zeta: (real)

Exponent parameter (typically 1.0, 2.0, 4.0, or 16.0)

weight_type: (integer)

Type of the weight factor depending on which period and group the elements are.

Weight Type	Description (Property Mapped)
1	Constant (Weight = 1)
2	Period Number
-2	`x` - Period Number
3	Main Group Number (s/p-block)
-3	`9` - Main Group Number
4	d-Electron Count (d-block)
-4	`11` - d-Electron Count
5	f-Electron Count (f-block)
-5	`15` - f-Electron Count

x: (integer)

Max period + 1

gamma: (integer)

Coefficient 1 or -1 for linear combination of the radial weighted scaling factors.

cutoff_index: (integer)

Index of the cutoff function defined by fc_cosine, fc_hard, etc.

Hint

Radial functions (type 2) describe the radial distribution of neighboring atoms and can be interpreted as continuous coordination numbers
Angular functions (type 3) describe three-body angular correlations centered at the central atom
When using feature_map_default, use symfunction for all models
Without feature_map_default, use model-specific suffixes: symfunction_short, symfunction_charges, symfunction_hirsh
The cutoff_index must correspond to a previously defined cutoff function
For systematic parameter selection, start with Rs=0.0 for radial functions
For angular functions, common zeta values are 1.0, 2.0, 4.0, and 16.0
Different element combinations require separate symmetry function definitions
Modifiers for weights, efield and spin can be added if compiled with FEATURES=ENABLE_PREFACTORS

Example

"With feature_map_default" Radial functions:

# Define cutoff function first
fc_cosine 1 0.0 12.0

# Use feature_map_default for all models
feature_map_default

# Radial symmetry functions for H-H interactions
symfunction H 2 H 0.001 0.0 1
symfunction H 2 H 0.01  0.0 1
symfunction H 2 H 0.06  0.0 1

symfunction H 2 modifiers=(weighted) 0.30  0.9 -3 5 1

# Radial symmetry functions for H-O interactions
symfunction H 2 O 0.001 0.0 1
symfunction H 2 O 0.03  0.0 1

# Radial symmetry functions for O-O interactions
symfunction O 2 O 0.002 0.0 1

**Angular functions:**
```runner-config
# Angular symmetry functions for H-H-H triplets
symfunction H 3 H H 0.000 1.0 1.0 1
symfunction H 3 H H 0.000 1.0 2.0 1
symfunction H 3 H H 0.000 -1.0 1.0 1

# Angular symmetry functions for H-O-H triplets
symfunction H 3 O H 0.000 1.0 1.0 1
symfunction O 3 H H 0.000 1.0 1.0 1
symfunction H 8 H O 10 0.01 1

# All for H as central atom
symfunction H 3 modifiers=(weighted) 0.001 -1.0 4.0 -2 5 -1 1
```

"With model-specific suffixes" Short-range model (2G, 3G, 4G):

# Define cutoff function first
fc_cosine 1 0.0 12.0

# Radial symmetry functions for short-range model
symfunction_short H 2 H 0.001 0.0 1
symfunction_short H 2 H 0.01  0.0 1
symfunction_short H 2 H 0.06  0.0 1
symfunction_short H 2 O 0.001 0.0 1
symfunction_short O 2 O 0.002 0.0 1

# Angular functions for short-range model
symfunction_short H 3 H H 0.000 1.0 1.0 1
symfunction_short O 3 H H 0.000 1.0 1.0 1
symfunction_short O 3 modifiers=(weighted) 0.03  1.0 1.0  -1 5 1 1

**Electrostatic model (3G only):**
```runner-config
symfunction_charge H 2 H 0.005 0.0 1
symfunction_charge H 2 O 0.01  0.0 1
symfunction_charge O 2 O 0.008 0.0 1

symfunction_charge H 3 H H 0.000 1.0 2.0 1
symfunction_charge O 3 H H 0.000 1.0 1.0 1
```

**Electrostatic model (4G only):**
```runner-config
symfunction_chi H 2 H 0.005 0.0 1
symfunction_chi H 2 O 0.01  0.0 1
symfunction_chi O 2 O 0.008 0.0 1

symfunction_chi H 3 H H 0.000 1.0 2.0 1
symfunction_chi O 3 H H 0.000 1.0 1.0 1
```

**Hirshfeld volume model (3G, 4G only):**
```runner-config
# Symmetry functions for Hirshfeld volume prediction
symfunction_hirshv H 2 H 0.003 0.0 1
symfunction_hirshv H 2 O 0.02  0.0 1
symfunction_hirshv O 2 O 0.005 0.0 1

# Angular functions for Hirshfeld model
symfunction_hirshv H 3 H H 0.000 1.0 4.0 1
symfunction_hirshv O 3 H H 0.000 1.0 2.0 1
```

`symfunction_correlation` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Calculates the pearson correlation coefficient between symmetry functions of each element. Can be used to detect redundant symmetry functions. The correlation matrix is printed at the start of the training in the standard out.

Format: symfunction_correlation (logical, default: False)

This keyword does not have any further options.

Hint

If you only want to get the correlation statistics use epochs 0

`test_fraction` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Fraction used as test set. 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. Which structures exactly are drawn is based on the random_seed_split.

Format: test_fraction fraction

fraction: (real, default: 0.1): Fraction of data used for testing (0.1 = 10%)

Hint

The cost function values of the test fraction can be used to detect overfitting. A good test error alone is not a guarantee for a good potential!

Example

test_fraction 0.2

`train_atomic_properties` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Train a model to predict atomic properties such as charges or Hirshfeld volumes. The property values must be present in the input.data file.

Format: train_atomic_properties property_name model_type unit_conversion_factor unit_name

property_name: (string): Name of the property we want to train on. Must be present in the input.data file.
model_type: (real, default: 1.0): Type of model used for training the atomic property. Can be either hdnn (environment-dependent model) or elemental (constant value per element).
unit_conversion_factor: (real, default: 1.0): Conversion factor to convert the property values from the units used in the input.data file to the written out units. This only affects i/o, not the training itself.
unit_name: (string): The name of the unit of this property. Only affects what is written in the header line before training, not the numbers.

Example

train_atomic_properties charge hdnn 1000 me

`train_charges` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Train the electrostatic charge model.

Format: train_charges (logical, default: False)

This keyword does not have any further options.

Hint

In a 4G you can additionaly train hardness at the same time train_hardness.

`train_chi` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Train the electrostatic charge model.

Format: train_chi (logical, default: False)

This keyword does not have any further options.

Hint

In a 4G you can additionaly train hardness at the same time train_hardness.

`train_hardness` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Train the hardness model in a 4G together with the charges.

Format: train_hardness (logical, default: False)

This keyword does not have any further options.

Hint

Has to be combined with train_charges.

`train_hirshfeld` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Train the Hirshfeld volume model.

Format: train_hirshfeld (logical, default: False)

This keyword does not have any further options.

`train_on_atomic_energies` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Activates the training on provided atomic energies instead of training on the energy of the molecular structure. Atomic energies need to be given in input.data for this purpose.

Format: train_on_atomic_energies (logical, default: False)

This keyword does not have any further options.

Hint

Although working the same as a 3G charge fit, it is grouped as a 2G.

`train_short` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Train the potential energy surface (short-range) model of a 3G or a 4G after the completion of the long-range fit.

Format: train_short (logical, default: False)

This keyword does not have any further options.

`upper_cost_threshold` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

If the cost (i.e. the RSME) for all committee members is above the value the training is stopped. This is checked for each cost calculation after the specified epoch. It compares the cost with whatever the optimal_epoch_property is set to (i.e. the energy train MAE or the force test RMSE and so on).

Format: upper_cost_threshold [threshold epoch]

threshold: (real): Cost threshold value
epoch: (integer, default: 0): Starting epoch for threshold check

Hint

This keyword uses the same units as the input.data file (Ha), not as the cost function output (meV)!

This keyword is used to save computational ressources. If a fit explodes or training is not as good as it should be, all following unnessecary epochs are skiped.

The specified epoch can vary with the frequency of calculatiion of the cost function.

In the same way a lower_cost_threshold can be set to stop training when results are good enough.

Example

upper_cost_threshold 2 3

`use_energy` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Activates energy updates during short-range training.

Format: use_energy (logical, default: False)

This keyword does not have any further options.

Hint

This should always be used for short-range training!

`use_force_vectors` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

When training on forces with a force_fraction under 1.0, normally force components are randomly drawn from all forces in the train set. This keyword means that instead complete force vectors are drawn. Still one force update for each of the 3 force components in each force vector is done.

Format: use_force_vectors (logical, default: False)

This keyword does not have any further options.

Hint

Make sure use_forces is on.

With force_fraction of 1.0 this keyword has no effect.

`use_forces` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Includes force components in training for loss calculation and backward pass.

Format: use_forces (logical, default: False)

This keyword does not have any further options.

Hint

The force cost can still be printed in the stdout with calculate_forces, even if not training on forces.

`use_full_dataset_for_scaling` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Use full dataset to calculate the scaling factor and centering subtrahend.

Format: use_full_dataset_for_scaling (logical, default: False)

This keyword does not have any further options.

Hint

If you dont switch it on it uses only the training set.

`use_manual_dgemm` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Force the use of the custom manual DGEMM implementation for rank-1 matrix products (k=1). This custom implementation provides better OpenMP parallelization than the MKL DGEMM on AMD hardware, where MKL does not parallelize well for k=1. This is relevant during Kalman filter training, where k equals the number of MPI tasks (i.e. k=1 for MPI-serial execution).

On AMD hardware, this option is automatically enabled based on CPU vendor detection at startup. This keyword allows forcing the custom DGEMM on non-AMD hardware (e.g. Intel) if desired.

Format: use_manual_dgemm (logical, default: False, auto-enabled on AMD)

This keyword does not have any further options.

Hint

This keyword is independent of disable_blocked_dsymm, which controls a separate blocked DSYMM implementation.

Example

use_manual_dgemm

`use_old_scaling` +++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Reads scaling information about the features from a file. This has to be used when training with scaled / centered features, and then using the resulting potential to predict a new dataset.

Format: ` (logical, default:False`)

This keyword does not have any further options.

Hint

This keyword only leads to reading in the scaling.data file. To actually apply the scaling and / or centering you still have to specify scale_feature_maps or center_feature_maps.

`use_old_scaling_global_features_ee` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Reads scaling information about the ee4G features from a file. This has to be used when training with scaled / centered features, and then using the resulting potential to predict a new dataset.

Format: ` (logical, default:False`)

This keyword does not have any further options.

Hint

This keyword only leads to reading in the ee4g_scaling.data file. To actually apply the scaling and / or centering you still have to specify scale_global_feature_maps_ee or center_global_feature_maps_ee.

`use_old_scaling_global_features_q` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Reads scaling information about the global features from a file. This has to be used when training with scaled / centered features, and then using the resulting potential to predict a new dataset.

Format: ` (logical, default:False`)

This keyword does not have any further options.

Hint

This keyword only leads to reading in the qeq_scaling.data file. To actually apply the scaling and / or centering you still have to specify scale_global_feature_maps_q or center_global_feature_maps_q.

`use_old_split` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Read train/test split from file. This is especially useful when the split was not determined by random_seed_split before.

Format: use_old_split (logical, default: False)

This keyword does not have any further options.

`vdw_calculate_hirsh_grad` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Include the hirshfeld gradient in the calculation of VdW forces. Is generally not included in standard TS implementations.

Format: vdw_calculate_hirsh_grad (logical, default: False)

This keyword does not have any further options.

Hint

This keyword needs vdW training to work.

Example

vdw_calculate_hirsh_grad

`verbosity` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Verbosity level of the RuNNer output.

Format: verbosity level

level: (integer, default: 1)

Verbosity level (higher values = more output)

0: nothing printed, use for interfaces
1: standard output
2: debug

Example

verbosity 1

`weight_decay` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Enable weight decay regularization during training. This can help stop exploding weights.

Format: weight_decay rate type

rate: (real)

Weight decay rate

type: (string)

type of weight decay

normal

Example

weight_decay 0.0001 normal

`weight_init_regularization` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4: Regularization parameter used in the least square fit of initialization_method. The regularization adds a penalty to solutions with high absolute values of the fit, leading to more reasonable avergae atomic energies at the cost of a slightly higher error in the least squares fit. The default value works for most examples and should normally not be changed. Increase the regularization parameter to get lower average absolute atomic energies. Decrease the value to get lower errors at epoch 0. The regularization can be completely turned off by setting the parameter to 0.0.

Format: weight_init_regularization parameter

parameter: (real, default: 0.01): Regularization parameter for weight initialization

Hint

Don't touch it if you are not an expert (At least look into the code).

Example

weight_init_regularization 0.1

`write_atomic_property_out` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Controls whether to write the [property].out file during 3G atomic property training where "property" is the user-defined name of the property that is trained.

Format: write_atomic_property_out (logical, default: False)

This keyword does not have any further options.

`write_atoms_out` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Controls whether to write the atoms.out file during training and prediction.

Format: write_atoms_out (logical, default: False)

This keyword does not have any further options.

Hint

Automatically enabled in mode predict.

`write_charge_out` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Controls whether to write the charges.out file during training and prediction.

Format: write_charge_out (logical, default: False)

This keyword does not have any further options.

Hint

Automatically enabled in mode train when training charges with a 4G, and in mode predict for a 4G.

`write_coulomb_matrix` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Write precalculated coulomb matrix. If you cannot store all coulomb matrix of your whole dataset in the RAM it might be performing better to read a precalculated coulomb matrix instead of calculating it every epoch.

Format: write_coulomb_matrix (logical, default: False)

This keyword does not have any further options. Source array atomrefenergies(nelem)

Hint

Only works in mode precompute. Use read_coulomb_matrix in mode train to read it. Care! Might take TBs of disk space if dataset is large (300 atoms per struc, 10000 structures)

`write_energy_out` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Controls whether to write the energy.out file during training and prediction.

Format: write_energy_out (logical, default: False)

This keyword does not have any further options.

Hint

Automatically enabled in mode predict.

`write_forces_out` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Controls whether to write the forces.out file during training and prediction.

Format: write_forces_out (logical, default: False)

This keyword does not have any further options.

Hint

Automatically enabled in mode predict when calculate_forces is set.

`write_frequency` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Frequency of writing the property output files (e.g. 000000.train.energy.out, 000000.train.forces.out) to disk. Higher number means less files to be stored. This does not influence the frequency of writing model weights. This is implicitely controlled via cost_frequencty.

Format: write_frequency frequency

frequency: (integer, default: -1): Write frequency (-1 disables periodic writing)

Source variable atomrefenergies(nelem)

Example

write_frequency 3

`write_global_features` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Write precalculated global features and/or derivatives. If you do not want to calculate the global features over and over again, it might be performing better to read precalculated global features.

Format: write_global_features (logical, default: False)

This keyword does not have any further options.

Hint

Only works in mode precompute. Use calculate_derivatives to also get the derivatives. Use read_global_features_q, read_global_features_ee, read_global_feature_derivatives_q or read_global_feature_derivatives_ee in mode train to read it. Be careful with the size of the derivatives file!

`write_precomputed_atoms_out`++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Controls whether to write the precomputed.atoms.out file once before training.

Format: write_precomputed_atoms_out (logical, default: False)

This keyword does not have any further options.

`write_precomputed_structure_out`++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Controls whether to write the precomputed.structure.out file once before training.

Format: write_precomputed_structure_out (logical, default: False)

This keyword does not have any further options.

`write_scaling` +¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Write scaling data of training structures of dataset in mode precompute.

Format: write_scaling (logical, default: False)

This keyword does not have any further options.

Hint

Only works in mode precompute. Works on training set. If no test fraction set scaling of whole data set is calculated. use_full_dataset_for_scaling does not work here.

Example

write_scaling

`write_stress_out` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Controls whether to write the stress.out file during training and prediction.

Format: write_stress_out (logical, default: False)

This keyword does not have any further options.

Hint

Automatically enabled in mode predict when calculate_stress is set.

`write_structure_out` ++¶

Mode precompute: • Mode train: • Mode predict:

Generation 2: • Generation 3: • Generation 4:

Controls whether to write the structure.out file during training and prediction.

Format: write_structure_out (logical, default: False)

This keyword does not have any further options.

Hint

Automatically enabled in mode predict. This file contains structural information.

Keywords

Keyword Suffixes¶

Alphabetical List of Keywords¶

2body +¶

activation +++¶

apply_atomic_property_fraction_by_element ++¶

apply_force_fraction_by_element ++¶

apply_loss_threshold_factor_by_element ++¶

atom_energy +++¶

atomic_property_fraction ++¶

batch_atomic_properties_by_element +¶

batch_forces_by_element +¶

batchsize_elements +++¶

batchsize_forces ++¶

batchsize_structures +++¶

bond_threshold ++¶

calculate_derivatives +++¶

calculate_forces +++¶

calculate_stress ++¶

center_feature_maps +++¶

center_global_feature_maps_ee +¶

center_global_feature_maps_q +¶

check_extrapolations +¶

constrain_predicted_charges_before_evaluation +¶

cost_frequency ++¶

cost_functions +¶

default_optimizer ++¶

default_optimizer_comm +¶

disable_blocked_dsymm +¶

dont_use_old_global_scaling +¶

dont_use_old_scaling +¶

dont_use_old_weights +¶

ee4g +++¶

elec_method +++¶

electric_field_prefactor_beta +¶

electric_field_prefactor_gamma +¶

electrostatics_precision ++¶

elements +++¶

energy_fraction ++¶

enforce_charge_training¶

epochs +++¶

extrapolation_warning_type +¶

fc_cosine +++¶

fc_hard +¶

fc_hypertangent ++¶

fc_hypertangent_approx ++¶

fc_polynomial ++¶

fc_vdw ++¶

feature_extrapolation_threshold +¶

feature_map_default ++¶

feature_minmax_threshold +¶

fitting_unit_energy +¶

fitting_unit_length +¶

fix_biases +¶

fix_weights +¶

fixed_gausswidth ++¶

force_fraction +++¶

force_training_sum_neighbors_derivatives +¶

force_update_scaling ++¶

format_ascii +¶

format_binary +¶

global_feature_extrapolation_threshold +¶

gradient_clipping_norm_boundary +¶

gradient_clipping_value_boundary¶

hirshfeld_vdw_damp_parm +¶

hirshfeld_vdw_sr +¶

initialization_method +++¶

iter_tol +++¶

loss_threshold_factor_atomic_properties ++¶

loss_threshold_factor_energy ++¶

loss_threshold_factor_forces ++¶

lower_cost_threshold +¶

max_ram_size +++¶

model_type_charges +¶

model_type_chi +¶

model_type_hardness ++¶

model_type_hirshfeld +¶

model_type_short +¶

neighborlist_allocation_margin ++¶

neighborlist_statistics_run +¶

`2body` +¶

`activation` +++¶

`apply_atomic_property_fraction_by_element` ++¶

`apply_force_fraction_by_element` ++¶

`apply_loss_threshold_factor_by_element` ++¶

`atom_energy` +++¶

`atomic_property_fraction` ++¶

`batch_atomic_properties_by_element` +¶

`batch_forces_by_element` +¶

`batchsize_elements` +++¶

`batchsize_forces` ++¶

`batchsize_structures` +++¶

`bond_threshold` ++¶

`calculate_derivatives` +++¶

`calculate_forces` +++¶

`calculate_stress` ++¶

`center_feature_maps` +++¶

`center_global_feature_maps_ee` +¶

`center_global_feature_maps_q` +¶

`check_extrapolations` +¶

`constrain_predicted_charges_before_evaluation` +¶

`cost_frequency` ++¶

`cost_functions` +¶

`default_optimizer` ++¶

`default_optimizer_comm` +¶

`disable_blocked_dsymm` +¶

`dont_use_old_global_scaling` +¶

`dont_use_old_scaling` +¶

`dont_use_old_weights` +¶

`ee4g` +++¶

`elec_method` +++¶

`electric_field_prefactor_beta` +¶

`electric_field_prefactor_gamma` +¶

`electrostatics_precision` ++¶

`elements` +++¶

`energy_fraction` ++¶

`enforce_charge_training`¶

`epochs` +++¶

`extrapolation_warning_type` +¶

`fc_cosine` +++¶

`fc_hard` +¶

`fc_hypertangent` ++¶

`fc_hypertangent_approx` ++¶

`fc_polynomial` ++¶

`fc_vdw` ++¶

`feature_extrapolation_threshold` +¶

`feature_map_default` ++¶

`feature_minmax_threshold` +¶

`fitting_unit_energy` +¶

`fitting_unit_length` +¶

`fix_biases` +¶

`fix_weights` +¶

`fixed_gausswidth` ++¶

`force_fraction` +++¶

`force_training_sum_neighbors_derivatives` +¶

`force_update_scaling` ++¶

`format_ascii` +¶

`format_binary` +¶

`global_feature_extrapolation_threshold` +¶

`gradient_clipping_norm_boundary` +¶

`gradient_clipping_value_boundary`¶

`hirshfeld_vdw_damp_parm` +¶

`hirshfeld_vdw_sr` +¶

`initialization_method` +++¶

`iter_tol` +++¶

`loss_threshold_factor_atomic_properties` ++¶

`loss_threshold_factor_energy` ++¶

`loss_threshold_factor_forces` ++¶

`lower_cost_threshold` +¶

`max_ram_size` +++¶

`model_type_charges` +¶

`model_type_chi` +¶

`model_type_hardness` ++¶

`model_type_hirshfeld` +¶

`model_type_short` +¶

`neighborlist_allocation_margin` ++¶

`neighborlist_statistics_run` +¶

`nnp_generation` +++¶

`no_charge_neuron` +¶

`no_predict_charges` +¶