nep.in

This file specifies hyperparameters used for training neuroevolution potential (NEP) models, the functional form of which is outline here. The NEP approach was proposed in [Fan2021] (NEP1) and later improved in [Fan2022a] (NEP2), [Fan2022b] (NEP3), and [Song2024] (NEP4). Currently, we support NEP3 and NEP4, which can be chosen by the version keyword.

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

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]

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

atomic_v

fit atomic or global virial

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]

Consistency with model files already present

A training run writes nep.txt every output_interval generations, and nep.restart every 100 generations, which is a fixed interval and not affected by output_interval. 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 foundation model named by the fine_tune keyword and 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

The NEP tutorial illustrates the construction of a NEP model. More examples can be found in this repository.