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.

Use model to select the model family, for example model qnep2 or model qnep3_vdw. Omitting all model selectors selects ordinary nep. Legacy selectors remain supported with deprecation warnings.

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	select the model for training or prediction
model_type	legacy model selection (deprecated)
charge_mode	legacy charge-model selection (deprecated)
flip_charge	reverse charge-output weights when restarting charge-model training
prediction	select between training and prediction (inference)
zbl	outer cutoff for the universal ZBL potential [Ziegler1985]
spin_version	select the spin descriptor version for model nep_spin
spin_cutoff	one spin cutoff or one cutoff per element, bounded by the NEP radial cutoff
spin_basis_size	magnetic radial basis index followed by a reserved second value fixed at zero
spin_l_max	maximum spatial tensor rank used by the spin descriptor
spin_compress	number of shared compressed radial channels
spin_order	highest Spin3 contraction level supplied to the neural network
spin_soc	enable joint spin–space rotation-invariant Spin3 channels
spin_type	atom types with independent spin degrees of freedom
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_m	weight of Cartesian magnetic-force loss term
lambda_m_parallel	weight of parallel magnetic-force RMSE (requires lambda_m_perp)
lambda_m_perp	weight of perpendicular magnetic-force RMSE (requires lambda_m_parallel)
lambda_tau	weight of spin-torque loss term
lambda_spin_response	weight of grouped magnetic-response 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
lambda_d	weight of energy-difference loss term, with the combinations in ediff.in
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.

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

For Spin training, see the spin_version example and the Spin potential documentation.