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.

How are training targets normalized?¶

The pre_calc_*_norm keywords scale each predicted and reference training value before the loss is evaluated. They use the atom count of the sample's own structure, independently of the number of samples in the batch.

Structure-energy training starts with the total energy divided by the number of atoms, \(E/N\). Force training starts with a Cartesian force component, \(F\). The keyword values specify an additional divisor:

Both predictions and references use the same factor. In particular, pre_calc_energy_norm none means energy per atom, while pre_calc_energy_norm 1_over_num_atoms selects total energy.

Direct atomic properties and 4G charges start with the property itself, without an implicit division by \(N\). Their pre-normalization options apply the same additional divisors shown above.

The loss function then combines the scaled errors and averages over the samples in the update. An energy sample is one structure's energy; a force sample is one Cartesian component. For atomic properties and charges, a sample is one atom's property. This sample averaging is separate from normalization by atom count. For example, MSE squares the scaled errors, so dividing each error by \(N\) divides its squared contribution by \(N^2\).

The parameter gradients differentiate the complete loss, including all pre-normalization factors. For a scaled prediction \(p_i=s_i y_i\),

Energy training also includes the conversion to energy per atom. Each sample uses its own structure's factor, including batches with different structure sizes. The scalar loss passed to an atomic-property optimizer is the loss of the entire selected atom batch; element-specific losses decide whether to update. There is no additional atom-count or backward-pass normalization of the loss or its gradients after this calculation.

To use the total-energy and unscaled-force convention documented for n2p2, set:

pre_calc_energy_norm 1_over_num_atoms
pre_calc_force_norm none

The optimizer's loss_function option selects the training loss. The separate cost_functions keyword selects the metrics reported to monitor training.

The former post_calc_*_loss_norm and post_calc_*_grads_norm keywords have been removed for every training target. An input containing any of these keywords, even with none, is rejected with an explanation. Remove those lines from input.nn. Former non-none settings do not have a general equivalent among the pre-normalization options, because scaling individual samples and scaling an entire batch loss are different operations.

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.