Describing long-range electrostatics based on local charges with 3G-HDNNPs¶

Third generation potentials expand the short-ranged 2G-HDNNPs by the description of additional long-ranged effects. In this tutorial, we will explore the description of electrostatic interactions based on environment-dependent atomic charges, which was the original goal of the first 3G-HDNNP¹.

Overview¶

Training a 3G electrostatic model consists of two steps:

1. learn an environment-dependent representation of atomic charges
2. remove Coulomb interaction of learned atomic charges from the reference energy and learn the remaining contributions with a short-range model.

Step 1: learning environment-dependent atomic charges¶

Learning atomic charges from reference values follows the same procedure as the training of any other atomic property. For that reason, the procedure is explained in detail in Learning arbitrary atomic properties with 3G-HDNNPs.

Step 2: training the short-range model¶

Generally, the short-range training for 3G-HDNNPs closely resembles that of 2G-HDNNPs. That is why, both workflows share the same underlying procedures in the source code.

The most important difference is that before training even starts, we evaluate the long-range electrostatic energy and force contributions of the entire training dataset and store it. These contributions are added to the predicted short-range energies and forces whenever we compare to the target values (most importantly loss calculation and cost calculation). This way, our model learns to describe only the remaining contributions within the short-range cutoff sphere.

Preparation¶

After Step 1 has finished, you will likely be left with the following files:

ls charge_training
>>>
    input.data
    input.nn
    opt.weights_charge.006.out
    opt.weights_charge.017.out
    scaling.data
    test_split.data
    train_split.data

In order to move on to short-range training, we will copy these files over to a fresh directory.

cp -r charge_training short_range_training

Some of the files need to be renamed for the next step:

• input.data: this is typical structure input file format of RuNNer. Apart from reference energies (and optionally forces), for 3G-HDNNPs with electrostatics it must also contain atomic reference charges. It can stay the way it is.

• opt.weights_charge.XXX.out: the most central training outcome of Step 1. These files contain the optimized parameters of the charge model for each element in the training dataset. Rename them to weights_charge.XXX.data, because they are now an input instead of an output file.

  Info

  In case you trained an elemental property model instead of a HDNNP, there might only be a single file called weights_charge.out.

• scaling.data: scaling information for the declared feature maps. In case you wish to declare different feature maps for short-range training (e.g. with a smaller cutoff radius), this file must be renamed to scaling_charge.data. Otherwise, it can stay as it is.

  Info

  If you used feature_map_default, this file will always be called scaling.data. If you declared the feature maps for charge training with a suffix (e.g. symfunction_charge) this file may be called scaling_charge.data.

• train_split.data and test_split.data: these files contain the index of structures in the train and test set. Keep them if you wish to reuse this split (encouraged), otherwise a new split can be generated as well.

• input.nn: the RuNNer settings file. It's name is always the same.

input.nn settings¶

Here is how a minimal 3G short-range training input.nn file can look like for the system tetrachloromethane:

# General.
runner_mode train
nnp_generation 3
elements C Cl
random_seed 10
max_ram_size 50000

# Model architecture.
default_nodes 25 20 15
default_activation_nn t t t l

# Initialization.
use_old_scaling
use_old_split
initialization_method_charge read
initialization_method_short xavier eckhoff

# Electrostatic-specific settings.
elec_method pair
screening_function 2
fc_cosine 2 0.0 6.0

# Training target and procedure.
train_short
use_energy
use_forces
epochs 50
test_fraction 0.1

# Optimizer.
optimizer 1 kalman nue=0.9987 p_initial=0.001 lambda=0.98000
optimizer 2 kalman nue=0.9987 p_initial=0.001 lambda=0.98000
opt_short C 1
opt_short Cl 2

# Feature maps
feature_map_default
center_feature_maps
scale_feature_maps
fc_cosine 1 0.0 10.0
symfunction              C 2 Cl      0.90000000       2.19382193      1
[...]

Many of these keywords should already feel familiar to you from 2G-HDNNP training. There are some which warrant further discussion.

nnp_generation 3¶

By specifying generation 3, we automatically let our model know that we wish to precompute certain contributions (in this case electrostatics) and subtract them from the reference values before entering short-range training. Generation 3 supports other long-range contributions (like vdW contributions) to be subtracted as well. However, electrostatics are enabled by default.

Model architecture¶

default_nodes 25 20 15
default_activation_nn t t t l

In this example, we reuse the same architecture for the charge model and the short-range model. This may not always be a smart decisions. Charges from electron density partitioning schemes are often very localized properties and can make due with a much smaller model than the complex potential energy surface. By adding suffices to the keywords (charge and short) it is very easy to separate the two architecture specifications.

default_nodes_charge 5 5
default_activation_nn_charge s s l
default_nodes_short 25 20 15
activation_nn_short t t t l

Initialization¶

use_old_scaling
use_old_split

We request that the previously written scaling.data file is reused, as well as the train/test split data. The scaling data for the charge model feature maps must always be read from file.

use_old_scaling_charge

The charge model is initialized from the optimized weights that are read from file. For the short-range model, any initialization method can be used.

initialization_method_charge read
initialization_method_short xavier eckhoff

Electrostatic-specific settings¶

elec_method pair
fc_cosine 1 0.0 6.0
screening_function 1

These settings are crucial. They control how the electrostatic energy contributions are calculated from the predicted charges. In the case of CCl\(_4\), we are dealing with a gas phase molecule without periodic boundary conditions. For such datasets, we can choose elec_methodpair. For mixed datasets, choose a calculator that supports calculations for periodic structures (like Ewald or PW). The code will automatically switch to the pairwise calculator for all non-periodic structures.

Furthermore, we define a screening function that smoothly screens the electrostatic interactions in the short-range cutoff sphere. This way we avoid spikes in the PES due to diverging Coulomb interactions at small distances. Any cutoff function is suited as a screening function.

Feature maps¶

feature_map_default
center_feature_maps
scale_feature_maps
fc_cosine 2 0.0 10.0
symfunction              C 2 Cl      0.90000000       2.19382193      2
[...]

For performance reasons, it is often beneficial to reuse the charge model feature maps for the short-range part (single precomputation, if possible). However, as for all other keywords, we can separate the behavior of the two models using the suffices charge and short. For example, it is possible to scale only the feature maps of the charge model and leave the short-range model unscaled. The same goes for the declaration of feature maps. In this case, feature_map_default must be deactivated.

center_feature_maps
scale_feature_maps_charge
fc_cosine 2 0.0 10.0
symfunction_charge            C 2 Cl      0.90000000       2.19382193      2
symfunction_short             C 2 Cl      0.90000000       2.19382193      2
[...]

Monitoring output¶

After calculation of the electrostatic contributions, training procedes in exactly the same manner as for a 2G potential. One notable difference is the description of reference statistics printed to STDOUT by RuNNer. In a 2G, reference statistics are printed once for the training and testing set. For a 3G, the reference values depend on the predicted atomic charges, since they control the electrostatic contributions. Therefore, RuNNer prints the statistics for the total reference data first (once for train and test set), and then goes on to show the "effective" reference values (after removal of the electrostatic contributions). These values are written once per committee member.

For covalent systems, it is important to check that the target range and standard deviation are not too different from the original reference values. Electrostatic contributions are typically several orders of magnitude smaller than the short-range contributions in covalently bound systems. For ionic systems, this may not be the case.