FAQs¶

General & Setup¶

For which systems can RuNNer 2 be used?¶

RuNNer 2 supports periodic and non-periodic structures, including liquids, metals, alloys, interfaces, ...

Note: Systems containing more than 4 different elements can be computationally expensive due to the nature of atom-centered symmetry functions. For these complex systems, we recommend using weighted symmetry functions or the overlap matrix.

Can I work with RuNNer 2 on my laptop?¶

Yes! While High-Performance Computing (HPC) clusters provide faster results, RuNNer 2 is fully capable of running on a standard laptop.

Which operating systems are supported?¶

RuNNer 2 supports most Linux distributions, Windows 11 (via WSL), and MacOS.

Are there tutorials for RuNNer 2 somewhere online?¶

Link tutorials, notebooks from workshop, notebooks from lecture exercises. Tutorials for prediction, and 2G, 3G, and 4G potentials can be found here.

How can I contribute to the code?¶

Details about our development, including CI, coding conventions etc., can be found here.

How can I convert my structures to the input.data format?¶

The easiest way is to use ASE. The runnerase tutorials can be found here.

My question is not answered here, what do I do?¶

For further questions concerning the usage of RuNNer please check out the RuNNer category in the MatSci discourse. For code-related questions and bug reports please feel free to open up an issue on Gitlab.

Training & Optimization¶

Why should I use committee training?¶

Committee training offers several advantages:

1. You can run Molecular Dynamics simulations on the averaged potential of the committee, which is significantly more stable than a single potential.
2. The standard deviation across committee members serves as a reliable measure of the potential's uncertainty, which is useful for active learning.
3. It allows you to test multiple training settings in a single run.

The number of committee members can be set with num_committee_members.

Why does the training error decrease while the test error increases?¶

This phenomenon is known as overfitting. It occurs when the model "memorizes" the training data but loses the ability to generalize to new data. You should use the weights from the epoch where your most critical property had the lowest test error. RuNNer automatically generates opt.weights.out files corresponding to the epoch where the cost of the optimal_epoch_property was lowest.

Training progress is very slow. How can I increase the initial stepsize?¶

If you are using a Kalman Filter, try to increase your p_initial value. You can increase this value (typically between \(10^0\) and \(10^9\)) until the fit becomes unstable ("explodes") in the first few epochs, then dial it back slightly.

My error "explodes" (values become extremely large) after a few epochs, what should I do?¶

If you are using a Kalman Filter, try to lower your p_initial value to reduce stepsize.

Why should I use the Kalman Filter instead of standard optimizers like Adam?¶

The Kalman Filter is a highly efficient optimizer for High-Dimensional Neural Network Potentials . Because HDNNPs typically use smaller neural networks compared to other machine learning applications (e.g., image recognition), we can afford the higher computational cost of the Kalman Filter compared to, e.g., Adam. Of course RuNNer 2 also includes more standard optimizers.

I am using a predefined architecture, but it runs much slower in RuNNer 2. Why?¶

This is likely due to the optimizer. If you are using the Kalman Filter, it is more computationally intensive per epoch than optimizers like Adam, even though it may require fewer epochs overall. You can either switch RuNNer 2 to use Adam or, preferably, reduce your neural network size (e.g., 2-3 hidden layers, <100 nodes per layer) to take advantage of the Kalman Filter's efficiency.

Can I train a committee where each member has a different train/test split?¶

Not in a single run. Currently, all committee members share the same feature calculations and data splits. You can generate a "manual" committee with different splits by performing multiple independent RuNNer fits, changing the random seeds for each run.

Can I construct a potential using only energies, without reference forces?¶

Yes, this is possible. Just comment out use_forces in the input.nn.

Can I use transfer learning?¶

Yes, certain weights and biases can be frozen during optimization using the fix_weights and fix_biases keywords.

What are these prec_calc_*_norm and post_calc_*_norm keywords?¶

If you have browsed across the possible keywords in this documentation, you might have come across the prec_calc_*_norm and post_calc_*_norm keywords. These keywords enable the user to specifically normalize the respective training samples (e.g. energies, force components, charges) and the loss and loss gradients derived from them. This due to the fact that n2p2, for which we wanted RuNNer to be consistent with as well, and RuNNer compute the loss and loss gradients for the energy and force samples by default differently. In n2p2, training is performed on the total energies and on the total force components, while in RuNNer training is performed on the total energies and force components divided by the number of atoms in the respective structure. Furthermore, RuNNer divides per default the gradients of the energy and force loss with the number of atoms in the respective structure.

To account for these differences, the following keywords have been introduced:

• prec_calc_[training target]_norm: Inverse normalization factor \(\alpha\) for the prediction \(y_{\rm pred}\) and reference value \(y_{\rm ref}\) of the respective training sample \(i\) before the calculation of the loss.

  \[ \Delta y^{\rm norm}_{i} = \frac{y_{i,{\rm pred}} - y_{i,{\rm ref}}}{\alpha} \]
  • Available options for \(\alpha\):
    • none: equal to 1.0.
      • For energy samples, none yields the average total energy per atom.
    • num_atoms: Refers to the number of atoms in the structure of the respective training sample.
    • 1_over_num_atoms: equal to 1.0 / num_atoms.
      • For energy samples, 1_over_num_atoms yields the total energy of structure.

  Training target	RuNNer default	n2p2 default
  energy	none	1_over_num_atoms
  forces	num_atoms	none
  property (e.g. 3G charges, Hirshfeld volumes)	none	none
  charges (i.e. 4G charges)	none	none

• post_calc_[training target]_loss_norm: Inverse normalization factor \(\alpha\) for the loss \(\mathcal{L}\).

  \[ \mathcal{L}^{\rm norm} = \frac{\mathcal{L}}{\alpha} \]
  • Available options for \(\alpha\):
    • none: equal to 1.0.
    • num_atoms_batch: Refers to the number of atoms in the structure batch of the respective training sample (i.e. for a structure batch size of one, that corresponds to the number of atoms in the respective structure).
    • average_num_atoms_batch: Refers to the average number of atoms per structure in the structure batch of the respective training sample (i.e. for a structure batch size of one, that corresponds to the number of atoms in the respective structure).
    • num_backward_passes: Number of backward passes required to calculate the loss gradients.

  Training target	RuNNer default	n2p2 default
  energy	none	none
  forces	none	none
  property (e.g. 3G charges, Hirshfeld volumes)	none	none
  charges (i.e. 4G charges)	none	none

• post_calc_[training target]_grads_norm: Inverse normalization factor \(\alpha\) for the loss gradients \(\frac{\delta \mathcal{L}}{\delta \mathbf{\omega}}\).

  \[ \left(\frac{\delta \mathcal{L}}{\delta \mathbf{\omega}}\right)^{\rm norm} = \frac{1}{\alpha}\frac{\delta \mathcal{L}}{\delta \mathbf{\omega}} \]
  • Available options for \(\alpha\):
    • none: equal to 1.0.
    • num_atoms_batch: Refers to the number of atoms in the structure batch of the respective training sample (i.e. for a structure batch size of one, that corresponds to the number of atoms in the respective structure).
    • average_num_atoms_batch: Refers to the average number of atoms per structure in the structure batch of the respective training sample (i.e. for a structure batch size of one, that corresponds to the number of atoms in the respective structure).
    • num_backward_passes: Number of backward passes required to calculate the loss gradients.

  Training target	RuNNer default	n2p2 default
  energy	average_num_atoms_batch	none
  forces	average_num_atoms_batch	none
  property (e.g. 3G charges, Hirshfeld volumes)	none	none
  charges (i.e. 4G charges)	none	none

Physics & Descriptors¶

How do I know which generation of HDNNP (2G, 3G, 4G) I need?¶

• 2G: Starting point for most systems
• 3G: Use this if you expect significant electrostatic effects.
• 4G: Use this if atomic charges depend on structural changes that occur far away (non-local charge transfer).

What is a good initial choice for the symmetry functions?¶

For a new system, we recommend a mix of Type 2 (Radial) and Type 3 (Angular) functions. The easiest way to construct symmetry function parameters for your dataset is via runnerase.

Which units are used by RuNNer?¶

All files use Hartree for energies, Bohr for lengths, and elemental charges, if not stated otherwise.

Can I combine periodic and non-periodic structures in a single training set?¶

This is possible. Note that a numerical consistency between both sets of structures is of utmost importance, by e.g. using the same basis set. For periodic structures, k-point meshes must be well-converged.

Which electrostatic solver and charge equilibration method should I use?¶

• Training:

  • Periodic structures: Ewald calculator + Training charge equilibrator (used automatically)
  • Non-periodic structures: Direct calculator + Training charge equilibrator (used automatically)
  • If your RAM is not sufficient to store the Coulomb matrices, the adequate prediction method should be used.

• Prediction:

  • Non-periodic: Direct calculator + Qeq solver (used automatically)
  • Small periodic: Ewald calculator + Direct solver
  • Large periodic: PW calculator + CG solver

• If you encounter problems with the PW calculator, try PPPM instead.

• If you encounter problems with the CG solver, try SQNM instead.
• The speed of all possible combinations depends on the system, we recommend performing small tests to find the optimal combination for your system.

Which definition of the stress tensor is used in RuNNer 2?¶

The stress tensor \(\sigma\) is defined as \(\sigma_{\mu\nu} = \frac{1}{\Omega} \left.\frac{\partial E}{\partial \epsilon_{\mu\nu}} \right|\_{\epsilon = 0}\) where \(\Omega\) is the cell volume, \(E\) the total energy, and \(\epsilon\) the strain tensor.

What can be stored during precomputation?¶

Mode precompute can write to a file: * feature values * feature derivative values * the Coulomb matrices

When do I have to do a new precomputation?¶

You have to redo the precomputation when you change * the dataset * the descriptors

Troubleshooting & Technical details¶

Why does my fit depend on the number of MPI tasks?¶

MPI parallelization batches updates from all tasks into a single update. Using more tasks effectively increases the batch size and reduces the total number of updates per epoch, which alters the training trajectory. See also this tutorial about MPI / OMP parallelization.

Why does my fit depend on the RAM size?¶

Changing available RAM may alter how the dataset is divided into chunks. Since shuffling and batching occur within chunks, resizing chunks changes the order of data presentation, leading to a different fit.

Some epochs need much more time than others. Why is that?¶

This often happens if you are using a loss threshold factor. This setting causes the number of updates to vary dynamically between epochs based on the error, leading to different times per epoch.

What should I do when my code crashes?¶

• Recompile RuNNer 2 with DEBUG=ON to identify the specific line of code causing the crash.
• Check also different compilers. They can give different error messages for the same error.
• If the bug persists, please open an issue on gitlab using the bug report template.

The numbers are slightly different on a different platform, why?¶

Small numerical differences are expected due to floating-point arithmetic variations between platforms.

• Prediction: Differences should be negligible.
• Training: Small initial differences can accumulate over many updates, leading to noticeably different weights. This is normal behavior for chaotic optimization landscapes.

Can I restart my fit?¶

You can restart your fit with the same weights using initialization_method read. However, this is not the same as continuing the fit, since the optimizer gets reinitialized!

Does RuNNer support GPU acceleration?¶

RuNNer features experimental GPU support via a cuBLAS wrapper. However, for test cases standard CPU calculations are still more cost effective.