nep.in

This file specifies hyperparameters used for training neuroevolution potential (NEP) models, the functional form of which is outlined here. The NEP approach was proposed in [Fan2021] (NEP1) and later improved in [Fan2022a] (NEP2), [Fan2022b] (NEP3), and [Song2024] (NEP4). Currently, only NEP4 is supported; the version keyword therefore only accepts 4.

File format

In this input file, blank lines and lines starting with # are ignored. One can thus write comments after #.

All other lines need to be of the following form:

keyword parameter_1 parameter_2 ...

Keywords can appear in any order with the exception of the type_weight keyword, which cannot appear before the type keyword.

The type keyword does not have default parameters and must be set. All other keywords have default values.

Keywords

Keyword	Brief description
version	select the NEP version (currently only NEP4)
type	number of atom types and list of chemical species
type_weight	force weights for different atom types
model_type	select to train potential, dipole, or polarizability
charge_mode	select the charge mode for a potential model
prediction	select between training and prediction (inference)
zbl	outer cutoff for the universal ZBL potential [Ziegler1985]
use_typewise_cutoff_zbl	enable typewise cutoff radii for the ZBL part of the model
cutoff	radial (\(r_\mathrm{c}^\mathrm{R}\)) and angular (\(r_\mathrm{c}^\mathrm{A}\)) cutoffs
n_max	size of radial (\(n_\mathrm{max}^\mathrm{R}\)) and angular (\(n_\mathrm{max}^\mathrm{A}\)) basis
basis_size	number of radial (\(N_\mathrm{bas}^\mathrm{R}\)) and angular (\(N_\mathrm{bas}^\mathrm{A}\)) basis functions
l_max	expansion order for angular terms
neuron	number of neurons in the hidden layer (\(N_\mathrm{neu}\))
lambda_1	weight of \(\mathcal{L}_1\)-norm regularization term
lambda_2	weight of \(\mathcal{L}_2\)-norm regularization term
lambda_e	weight of energy loss term
lambda_f	weight of force loss term
lambda_v	weight of virial loss term
lambda_q	weight of total-charge loss term for qNEP models
lambda_z	weight of Born-effective-charge loss term for qNEP models
atomic_v	fit atomic or global virial
lambda_shear	extra weight of shear-virial loss terms
force_delta	bias term that can be used to make smaller forces more accurate
batch	batch size for training
population	population size used in the SNES algorithm [Schaul2011]
generation	number of generations used by the SNES algorithm [Schaul2011]
save_potential	periodically save model checkpoints and, optionally, restart checkpoints
output_interval	interval between regular training-status and model/test-set outputs
output_descriptor	output normalized descriptors in prediction mode
fine_tune	fine tune a model starting from a foundation model
import_q_scaler	import descriptor normalization factors from an existing nep.txt

Consistency with model files already present

A training run writes both nep.txt and nep.restart every output_interval generations. A later run started in the same directory therefore finds these files, and nep checks that the model they describe is the one that nep.in asks for. Both the values given explicitly in nep.in and the defaults filled in for the keywords that are omitted take part in this comparison.

The comparison covers everything recorded in the header of nep.txt: the model type (version, model_type and charge_mode), the number of species and the species themselves in the order they are listed, the zbl setting and its cutoffs, the cutoff values, n_max, basis_size, l_max and neuron. The number of rows in nep.restart is compared against the number of parameters that nep.in implies.

How a mismatch is reported depends on whether the files are inputs to the run:

• If nep.restart is present the run is a resume, and any mismatch is an error. Continuing would otherwise mean reading the restart state of a differently shaped model, which silently corrupts the training. Remove nep.restart to start a new training run instead.

• The same applies when prediction is set, since nep.txt is then the model to predict with.

• If only nep.txt is present it is assumed to be a stale output that this run is about to overwrite. In this case, a mismatch is reported as a warning and the run proceeds. Editing nep.in and retraining in the same directory thus keeps working.

Each mismatch is reported on its own line, naming the keyword, the value used by the current run, whether that value was given in nep.in or is a default, and the value found in the file, for example:

The model in nep.in is inconsistent with nep.txt:
    basis_size_radial: nep.in gives 6 (default), nep.txt gives 8.
    basis_size_angular: nep.in gives 6 (default), nep.txt gives 8.

The same comparison is applied to the nep.txt read by the import_q_scaler keyword, where a mismatch is always an error.

Example

Here is an example nep.in file using all the default parameters:

type          2 Te Pb   # this is a mandatory keyword
version       4         # the only option
cutoff        8 4       # please choose these reasonably
n_max         6 6       # default
basis_size    6 6       # default
l_max         4 1       # default
neuron        30        # default
lambda_e      1.0       # default
lambda_f      1.0       # default
lambda_v      0.1       # default
batch         1000      # default
population    50        # default
generation    100000    # default