The Workflow of Predicting with RuNNer¶

This chapter gives an overview about runner_mode predict for the different generations of HDNNPs.

Prerequisites¶

• A working RuNNer binary. Take a look at our installation instructions.
• A dataset of structures formatted as input.data.
• a text editor like vim or emacs to edit the settings file input.nn.
• A folder where RuNNer can write output (weights, scaling, split files, logs).

Every prediction needs the following files:

• input.data with the structures that should be predicted
• input.nn with the settings
• weights.XXX.data optimized parameters of the models (replace XXX with atomic number of each element in your dataset)
• scaling.data scaling information for the feature maps used during training.

In principle one can reuse the input.nn from the training (2G, 3G, 4G) and only needs to do little predict-mode-specific changes:

• set runner_mode predict so that RuNNer knows it should predict properties.
• force and stress prediction can be switched on with the calculate_forces and calculate_stress keywords.
• nnp_generation i0 specifies which generation of HDNNPs is constructed. Here, i0 can be either 2 for 2G-, 3 for 3G-, or 4 for 4G-HDNNPs.

RuNNer distinguishes between different type of models which is important in 3G- and 4G-HDNNPs. They can be addressed through different suffices. There are:

• short for short range HDNNP (2G, 3G, 4G)
• charge for charges (3G)
• hirshv for hirshfeld volumes (3G)
• chi for electronegativity (4G)
• hardness for hardness (4G)

The files for weights_[suffix].XXX.data and scaling_[siffx].data use these suffices.

It is possible to share the input features between models by setting the keyword feature_map_default. In this case, they all share a single scaling file which is then simply called scaling.data (no suffix).

2G-HDNNP¶

2G-HDNNP are the least complex and computationally the most efficient method consisting of only one short-range model.

For water one would need the following file structure:

PATH/
├── input.nn
├── input.data
├── scaling_short.data
├── weights_short.001.data
└── weights_short.008.data

scaling_short.data can be directly copied from the identically named output file from the training. The weights can be copied from the desired epoch i.e. 000010.weights_short.001.out or from the opt.weights_short.001.out files selected by RuNNer.

The input.nn looks like this:

runner_mode predict
nnp_generation 2
elements O H

default_nodes 20 20
default_activation_nn t t l

calculate_forces
calculate_stress

fc_cosine 1 12.0
symfunction_short H 2 H 0.001 0.0 1
[...]

The symmetry functions and cutoff functions are truncated. They have to be the same as in the training.

From inside your training folder, run:

# name of the executable may differ depending on how RuNNer is installed
RuNNer.x | tee predict.out

During the prediction, RuNNer will:

• read input.data
• split the dataset into chunks if there is not enough memory.
• compute feature maps and scale according to scaling.data.
• predict the desired properties.
• write atoms.out, structure.out, energy.out, forces.out, stress.out

3G-HDNNP¶

3G-HDNNPs consist of two mainly separate HDNNPs. The first one predicts atomic charges, which are then used to calculate the long-range electrostatic energy. The second one is a short-range model, equivalent in spirit to a 2G-HDNNP, which describes the local chemical environment.

This separation allows 3G models to explicitly treat long-range Coulomb interactions while still retaining the efficiency and locality of the short-range neural network. In practice, this significantly improves the description of systems with pronounced charge interactions, polar bonding, or extended hydrogen-bond networks.

For the electrostatic part we need additional settings to control the calculation of the energy:

• elec_method
• electrostatics_precision

The predicted charges are used as point charges in the electrostatic energy expression. Depending on whether your system is periodic or non-periodic, RuNNer automatically selects or restricts the available electrostatics calculators (see details in the section below).

For water one would need the following file structure:

PATH/
├── input.nn
├── input.data
├── scaling_short.data
├── weights_short.001.data
├── weights_short.008.data
├── scaling_charge.data
├── weights_charge.001.data
└── weights_charge.008.data

or with shared features

PATH/
├── input.nn
├── input.data
├── scaling.data
├── weights_short.001.data
├── weights_short.008.data
├── weights_charge.001.data
└── weights_charge.008.data

During the prediction, RuNNer will:

• read input.data
• split the dataset into chunks if there is not enough memory
• compute feature maps and scale according to scaling.data
• predict the charges with the charge network
• calculate the electrostatic energy from the predicted charges
• predict the short-range energy with the short network and sum it up with the electrostatic energy
• write atoms.out, structure.out, energy.out, forces.out, stress.out, and optionally charge.out (with keyword write_charge_out)

For large periodic systems, the electrostatic part may dominate the total runtime. In such cases, carefully selecting the electrostatics solver and precision is crucial for performance. The short-range model evaluation usually scales linearly with the number of atoms (given a fixed cutoff), while the electrostatic solver may scale differently depending on the method.

To predict only the electrostatic part one can use no_predict_short_range. To additionally predict dispersion interactions use predict_vdw.

4G-HDNNP¶

4G-HDNNPs are constructed from two internally connected HDNNPs and a charge equilibration (QEq) scheme. In contrast to 3G models, 4G models do not directly predict charges. Instead, they predict:

• atomic electronegativities (chi)
• atomic hardness values (hardness)

The atomic charges are then obtained by solving a QEq system that enforces global charge conservation and minimizes the electrostatic energy. This makes 4G models physically more consistent and often more transferable, especially for systems with varying charge states or strong polarization effects.

The electrostatic energy is thus determined in two steps:

1. Predict electronegativity and hardness.
2. Solve the QEq equations to obtain charges.
3. Compute the electrostatic energy from the equilibrated charges.

Afterwards, the predicted charges are passed into the short-range model as additional input features. Apart from that, the short-range model is the same as in the previously presented generations.

For water one would need the following file structure:

PATH/
├── input.nn
├── input.data
├── scaling_short.data
├── weights_short.001.data
├── weights_short.008.data
├── qeq_scaling.data
├── weights_hardness.data or weights_hardness.001.data & weights_hardness.008.data
├── scaling_chi.data
├── weights_chi.001.data
└── weights_chi.008.data

During the prediction, RuNNer will:

• read input.data
• split the dataset into chunks if there is not enough memory
• compute feature maps and scale according to the respective scaling files
• scale charges according to qeq_scaling.data
• predict electronegativities (chi) and hardness.
• equilibrate charges using the selected QEq solver
• compute the electrostatic energy from the equilibrated charges
• predict short range energy and sum it up with the electrostatic energy
• write atoms.out, structure.out, energy.out, forces.out, stress.out

Because the Qeq system must be solved for every structure (and, for forces, its derivatives must be evaluated), 4G-HDNNPs are typically more computationally demanding than 3G-HDNNPs. However, they provide a more rigorous treatment of charge redistribution and are often preferable for systems with varying oxidation states, charged defects, or heterogeneous interfaces.

Choice of elec_method and qeq_method¶

This section gives practical guidance on selecting electrostatics and QEq solvers for 3G and 4G models.

Choice of elec_method (3G and 4G)¶

The keyword

elec_method method

controls how the electrostatic energy is computed from the charges.

Available methods:

• pw – plain wave calculator (default)
• pair – pairwise Coulomb summation
• ewald – Ewald summation
• pppm – Particle–Particle Particle–Mesh

Non-periodic systems (clusters, molecules)¶

• RuNNer automatically switches to pair.
• pair is efficient and accurate for finite systems.
• No reciprocal-space treatment is required.

Recommendation:
For isolated molecules or clusters, simply use the default settings. RuNNer will choose pair automatically.

Periodic systems (bulk, surfaces, liquids with PBC)¶

The pair method cannot be used for periodic structures.

• ewald: classical Ewald summation. Robust and accurate. Scales \(\mathcal{O}(N_{\mathrm{atom}}^(3/2))\) with the number of atoms in your system. Good choice for small to medium systems.
• pppm: Particle-Particle-Particle mesh method. Theoretical scaling is \(\mathcal{O}(N_{\mathrm{atom}} \log^2\left(N_{\mathrm{atom}}\right))\) Usually faster for large periodic systems.
• pw: Plain-wave method. Theoretical scaling is \(\mathcal{O}(N_{\mathrm{atom}} \log^2\left(N_{\mathrm{atom}}\right))\). This is the default in RuNNer since it is usually the most efficient choice for large-scale periodic systems.

Practical advice:

• For small periodic cells (tens to a few hundred atoms):
  → ewald is often the fastest choice.
• For large periodic simulations (hundreds to thousands of atoms): → pw or pppm are typically more efficient.

We strongly suggest to run tests for a representative example of your system of choice.

The keyword electrostatics_precision should be tightened if: - energy conservation in MD is critical, - very accurate forces are required, - highly charged systems are simulated.

Keep in mind that tighter precision increases computational cost.

Choice of qeq_method (4G only)¶

The keyword

qeq_method method

selects the solver for the charge equilibration equations.

Available methods:

• direct – direct (matrix-based) solver
• sqnm – iterative SQNM-based solver
• cg – conjugate gradient (default)

General considerations¶

The QEq system must be solved for every structure. The choice of solver affects:

• numerical stability
• convergence behavior
• runtime for large systems

direct¶

• Most robust.
• No convergence issues.
• Computationally more expensive.
• Memory scales quadratically with system size.

Recommendation:
Use for small systems or debugging convergence problems.

cg (default)¶

• Iterative conjugate gradient solver.
• Usually fast and memory efficient.
• May fail to converge for some datasets.

Recommendation:
Start with cg. It is the best compromise for most applications.

sqnm¶

• Iterative solver alternative.
• In some datasets converges faster than cg.
• In others may behave worse.

Recommendation:
If cg does not converge or is slow, try sqnm.

Practical Decision Strategy¶

For 3G periodic bulk systems: 1. Start with default pw. 2. If runtime is large → try pppm. 3. For smaller systems or if unsure → ewald.

For 4G large periodic systems: 1. elec_method pw 2. qeq_method cg 3. If convergence problems occur → try sqnm. 4. If iterative solvers fail → switch to ewald and direct for debugging.

For molecules and clusters: - elec_method will automatically be pair. - In 4G: use cg, switch only if convergence issues appear.

Always inspect the STDOUT (predict.out) for: - convergence messages from QEq, - electrostatics timing,

This diagnostic information is essential when optimizing performance for large-scale simulations.