MomentTensorPotentialFittingParameters

class MomentTensorPotentialFittingParameters(basis_size=None, inner_cutoff_radii=None, tapering_cutoff_radii=None, outer_cutoff_radii=None, mtp_filename=None, cutoff_function=None, load_energy=None, load_forces=None, load_stress=None, ridge_regression_regularization=None, ridge_regression_cross_validation=None, constant_terms=None, weights=None, forces_cap=None, non_linear_coefficients_parameters=None, data_tags=None, use_element_specific_coefficients=None, use_gpu_acceleration=None)

Class for storing parameters for fitting a moment tensor potential.

Parameters:
  • basis_size (PredefinedBasisSmall | PredefinedBasisBig | int | str) – The basis set size to use. If a filename is given the basis is read for this file.
    Default: PredefinedBasisSmall

  • inner_cutoff_radii (PhysicalQuantity of type length | dict of {tuple (size 2) of Element: PhysicalQuantity of type length}) – The inner cutoff radius for each element pair. If a single value is given, this will be used for all pairs.
    Default: 0.5 * Angstrom

  • tapering_cutoff_radii (PhysicalQuantity of type length | dict of {tuple (size 2) of Element: PhysicalQuantity of type length}) – The tapering cutoff radius for each element pair. If a single value is given, this will be used for all pairs.
    Default: 0.7 * Angstrom

  • outer_cutoff_radii (PhysicalQuantity of type length | dict of {tuple (size 2) of Element: PhysicalQuantity of type length}) – The outer cutoff radius for each element pair. If a single value is given, this will be used for all pairs.
    Default: 5.0 * Angstrom

  • mtp_filename (str) – The filename for the fitted MTP parameter set. An exception is raised if the filename already exists.
    Default: The parameters will be written to a file MTP_parameters.mtp, prefixed by the index of the fit in the list.

  • cutoff_function (CutoffFunctionChebyshevOriginal | CutoffFunctionChebyshevExpansion) – The cutoff function to use.
    Default: CutoffFunctionChebyshevOriginal

  • load_energy (LoadQuantityAlways | LoadQuantityNever | LoadQuantityWhereAvailable) – Whether to use the energy during fitting.
    Default: LoadQuantityWhereAvailable

  • load_forces (LoadQuantityAlways | LoadQuantityNever | LoadQuantityWhereAvailable) – Whether to use the forces during fitting.
    Default: LoadQuantityWhereAvailable

  • load_stress (LoadQuantityAlways | LoadQuantityNever | LoadQuantityWhereAvailable) – Whether to use the stress during fitting.
    Default: LoadQuantityWhereAvailable

  • ridge_regression_regularization (float) – The regularization strength for the ridge regression model.
    Default: 1.0e-3

  • ridge_regression_cross_validation (int) – The number of folds for enabling cross-validation in the ridge regression model.
    Default: No cross-validation.

  • constant_terms (dict of {Element: PhysicalQuantity of type energy}) – The energy of an isolated atom for each species.
    Default: Calculated with the fitting calculator. by MomentTensorPotentialTraining.

  • weights (Sequence of PhysicalQuantity of type (1/energy, length/energy, length**3/energy)) – The weights used for weighting energy, forces and stress [E, F, S] of every training configuration. If the quantity is not used for fitting or absent from the data, the corresponding weight is ignored.
    Default: No weighting.

  • forces_cap (PhysicalQuantity of type energy / length) – Configurations with max. force magnitudes on an atom larger than this value will be discarded from the training data.
    Default: 100.0 * eV / Angstrom

  • non_linear_coefficients_parameters (NonLinearCoefficientsParameters:) – The non-linear coefficients and parameters related to their optimization.
    Default: NonLinearCoefficientsParameters()

  • data_tags (None | str | list) – A single tag or a list of tags identifying the training sets to be used in the fitting. None results in all available training sets being included.
    Default: None

  • use_element_specific_coefficients (bool) – True, if element-specific coefficients should be used, otherwise False.
    Default: False

  • use_gpu_acceleration (bool) – Switch GPU acceleration using CUDA on or off. This accelerates the singular value decomposition (SVD) solver when determining the linear coefficients. This requires running the training on a CUDA-enabled GPU, otherwise it has no effect.
    Default: False.

basisSize()
Returns:

The basis set size to use or the filename to read the basis from.

Return type:

PredefinedBasisSmall | PredefinedBasisBig | int | str

constantTerms()
Returns:

The energy of an isolated atom for each species, or None if it will be calculated with the fitting calculator by MomentTensorPotentialTraining.

Return type:

dict of {Element: PhysicalQuantity of type energy} | None

cutoffFunction()
Returns:

The cutoff function to use.

Return type:

CutoffFunctionChebyshev

dataTags()
Returns:

The tags identifying which datasets are used in the fitting. None includes all available datasets

Return type:

None | list

forcesCap()
Returns:

The forces cap.

Return type:

PHYSICALQUANTITY| of type energy / length.

innerCutoffRadii()
Returns:

The inner cutoff radius for each element pair. If a single value is given, this will be used for all pairs.

Return type:

PhysicalQuantity of type length | dict of {tuple (size 2) of Element: PhysicalQuantity of type length}

loadEnergy()
Returns:

Whether to use the energy during fitting.

Return type:

LoadQuantityAlways | LoadQuantityNever | LoadQuantityWhereAvailable

loadForces()
Returns:

Whether to use the forces during fitting.

Return type:

LoadQuantityAlways | LoadQuantityNever | LoadQuantityWhereAvailable

loadStress()
Returns:

Whether to use the stress during fitting.

Return type:

LoadQuantityAlways | LoadQuantityNever | LoadQuantityWhereAvailable

mtpFilename()
Returns:

The filename for the fitted MTP parameter set, or None if it will be set by MomentTensorPotentialTraining.

Return type:

str | None

nonLinearCoefficientsParameters()
Returns:

The non-linear coefficients and parameters related to their optimization.

Return type:

NonLinearCoefficientsParameters

outerCutoffRadii()
Returns:

The outer cutoff radius for each element pair. If a single value is given, this will be used for all pairs.

Return type:

PhysicalQuantity of type length | dict of {tuple (size 2) of Element: PhysicalQuantity of type length}

ridgeRegressionCrossValidation()
Returns:

The number of folds for enabling cross-validation in the ridge regression model, of None for no cross-validation.

Return type:

int | None

ridgeRegressionRegularization()
Returns:

The regularization strength for the ridge regression model.

Return type:

float

setBasisSize(basis_size)

Method for setting the basis size.

Parameters:

basis_size (PredefinedBasisSmall | PredefinedBasisBig | int | str) – The basis set size to use. If a filename is given the basis is read for this file.

setConstantTerms(constant_terms)

Method for setting the constant terms.

Parameters:

constant_terms (dict of {Element: PhysicalQuantity of type energy}) – The energy of an isolated atom for each species.

setCutoffFunction(cutoff_function)

Method for setting the cutoff function.

Parameters:

cutoff_function (CutoffFunctionChebyshevOriginal | CutoffFunctionChebyshevExpansion) – The cutoff function to use.

setDataTags(data_tags)

Method for setting data tags.

Parameters:

data_tags (None | str | list) – A single tag or a list of tags identifying the training sets to be used in the fitting. None results in all available training sets being included.

setForcesCap(forces_cap)

Method for setting the forces cap.

Parameters:

forces_cap (PhysicalQuantity of type energy / length) – Configurations with max. force magnitudes on an atom larger than this value will be discarded from the training data.

setInnerCutoffRadii(inner_cutoff_radii)

Method for setting the inner cutoff radii.

Parameters:

inner_cutoff_radii (PhysicalQuantity of type length | dict of {tuple (size 2) of Element: PhysicalQuantity of type length}) – The inner cutoff radius for each element pair. If a single value is given, this will be used for all pairs.

setLoadEnergy(load_energy)

Method for setting load_energy.

Parameters:

load_energy (LoadQuantityAlways | LoadQuantityNever | LoadQuantityWhereAvailable) – Whether to use the energy during fitting.

setLoadForces(load_forces)

Method for setting load_forces.

Parameters:

load_forces (LoadQuantityAlways | LoadQuantityNever | LoadQuantityWhereAvailable) – Whether to use the forces during fitting.

setLoadStress(load_stress)

Method for setting load_stress.

Parameters:

load_stress (LoadQuantityAlways | LoadQuantityNever | LoadQuantityWhereAvailable) – Whether to use the stress during fitting.

setMtpFilename(mtp_filename)

Method for setting the MTP filename.

Parameters:

mtp_filename (str) – The filename for the fitted MTP parameter set.

setNonLinearCoefficientsParameters(non_linear_coefficients_parameters)

Method for setting non_linear_coefficients_parameters.

Parameters:

non_linear_coefficients_parameters (NonLinearCoefficientsParameters:) – The non-linear coefficients and parameters related to their optimization.

setOuterCutoffRadii(outer_cutoff_radii)

Method for setting the outer cutoff radii.

Parameters:

outer_cutoff_radii (PhysicalQuantity of type length | dict of {tuple (size 2) of Element: PhysicalQuantity of type length}) – The outer cutoff radius for each element pair. If a single value is given, this will be used for all pairs.

setRidgeRegressionCrossValidation(ridge_regression_cross_validation)

Method for setting ridge_regression_cross_validation.

Parameters:

ridge_regression_cross_validation (int) – The number of folds for enabling cross-validation in the ridge regression model.

setRidgeRegressionRegularization(ridge_regression_regularization)

Method for setting ridge_regression_regularization.

Parameters:

ridge_regression_regularization (float) – The regularization strength for the ridge regression model.

setTaperingCutoffRadii(tapering_cutoff_radii)

Method for setting the tapering cutoff radii.

Parameters:

tapering_cutoff_radii (PhysicalQuantity of type length | dict of {tuple (size 2) of Element: PhysicalQuantity of type length}) – The tapering cutoff radius for each element pair. If a single value is given, this will be used for all pairs.

setUseElementSpecificCoefficients(use_element_specific_coefficients)

Set the flag to use element-specific coefficients or not.

Parameters:

use_element_specific_coefficients (bool) – If True, element-specific coefficients will be used.

setUseGpuAcceleration(use_gpu_acceleration)

Switch GPU acceleration using CUDA on or off. This accelerates the singular value decomposition (SVD) solver when determining the linear coefficients. This requires running the training on a CUDA-enabled GPU, otherwise it has no effect.

Parameters:

use_gpu_acceleration (bool) – The flag to switch GPU acceleration on or off.

setWeights(weights)

Method for setting the weights.

Parameters:

weights (Sequence of PhysicalQuantity of type (1/energy, length/energy, length**3/energy)) – The weights used for weighting energy, forces and stress [E, F, S] of every training configuration. If the quantity is not used for fitting or absent from the data, the corresponding weight is ignored.

taperingCutoffRadii()
Returns:

The tapering cutoff radius for each element pair. If a single value is given, this will be used for all pairs.

Return type:

PhysicalQuantity of type length | dict of {tuple (size 2) of Element: PhysicalQuantity of type length}

uniqueString()

Return a unique string representing the state of the object.

useElementSpecificCoefficients()
Returns:

True, element-specific coefficients are used, otherwise False.

Return type:

bool

useGpuAcceleration()
Returns:

The flag to enable GPU acceleration using CUDA . This accelerates the singular value decomposition (SVD) solver when determining the linear coefficients. This requires running the training on a CUDA-enabled GPU, otherwise it has no effect.

Return type:

bool

weights()
Returns:

The weights used for weighting energy, forces and stress [E, F, S] of every training configuration.

Return type:

Sequence of size 3

Usage Examples

Setup of MomentTensorPotentialFittingParameters. Note that if optimization of the NonLinearCoefficientsParameters is required it has to be specified here.

# Define non-linear coefficients and enable optimization.
non_linear_coefficients_parameters = NonLinearCoefficientsParameters(
   perform_optimization=True,
   initial_coefficients=Random,
)

# MTP filename.
mtp_filename = 'mtp_parameters.mtp'

# Define parameters to use in the MTP fitting.
fitting_parameters = MomentTensorPotentialFittingParameters(
   basis_size=2000,
   outer_cutoff_radii=4.0*Angstrom,
   mtp_filename=mtp_filename,
   non_linear_coefficients_parameters=non_linear_coefficients_parameters,
   use_element_specific_coefficients=True,
)

Use element-wise inner, tapering, and outer cutoff radii:

inner_cutoff_radii = {
    (Oxygen, Oxygen): 1.0*Ang,
    (Oxygen, Hydrogen): 0.5*Ang,
    (Hydrogen, Hydrogen): 0.5*Ang,
}
tapering_cutoff_radii = {
    (Oxygen, Oxygen): 1.1*Ang,
    (Oxygen, Hydrogen): 0.6*Ang,
    (Hydrogen, Hydrogen): 0.6*Ang,
}
outer_cutoff_radii = {
    (Oxygen, Oxygen): 4.0*Ang,
    (Oxygen, Hydrogen): 4.0*Ang,
    (Hydrogen, Hydrogen): 4.0*Ang,
}

# MTP filename.
mtp_filename = 'mtp_parameters.mtp'

# Define parameters to use in the MTP fitting.
fitting_parameters = MomentTensorPotentialFittingParameters(
   basis_size=PredefinedBasisSmall,
   inner_cutoff_radii=inner_cutoff_radii,
   tapering_cutoff_radii=tapering_cutoff_radii,
   outer_cutoff_radii=outer_cutoff_radii,
   mtp_filename=mtp_filename,
   use_element_specific_coefficients=True,
)

Notes

MomentTensorPotentialFittingParameters serves as an input argument for MomentTensorPotentialTraining.

This class specifies the hyper-parameters for the MTP training.

The most important parameters to specify and vary would be the MTP basis, the outer cutoff radii, as well as the NonLinearCoefficientsParameters, which specify the optimization of the element-pair dependent coefficients in the radial functions.

The effect of the basis size is generally that if the number of MTP basis functions is increased the training error is reduced, which improves the accuracy. However, a trade-off is that the extrapolation of the MTP, i.e. the prediction capability for configurations that are further outside the range of the training data, becomes worse. In practice this often means that some simulations, especially of amorphous materials or at high temperatures can become more unstable. If the number of basis is reduced the effect is the opposite: The simulation are typically more stable but the accuracy decreases.

It is recommended to use either the PredefineBasisSmall, or basis sizes between 400 and 800 functions for general purpose applications. If the MTP requires very high accuracy (e.g. for accurate phonon calculations of crystalline materials) one can increase the number of basis functions even more to e.g. around 2000 to 5000. In this case one has to be more careful with MD simulations at high temperature.

If the training data contains multiple elements, better accuracy can be achieved by using element-specific coefficients in the MTP model. This can be enabled by setting use_element_specific_coefficients=True. Using the option will result in slightly longer training and simulation times, but the accuracy gain can be significant, in particular for training data with many different elements, layered materials, or systems, where it is difficult to achieve a low enough training error with the normal MTP version.

The outer cutoff radii of the atomic environment can be chosen as global or as element-pair specific, and they should be chosen to at least include the first shell of neighbors for each element pair. The fit can often be improved by including more neighbor shells in the environments, up to the point where at larger radii the atomic environment becomes too complex to be described accurately by the finite number of MTP basis functions. Therefore, it is recommended to run several fits with different cutoff radii, and use the one that results in both a low error and stable simulations. Typical outer cutoff radii are between 3 and 6 Ang.

The inner cutoff radii determine the inner limit of the atomic neighborhood. Note, that the default value for the inner cutoff radii is set to 0.5 Ang, which works well for most elements, in that it allows to focus the radial functions on the important part of the interaction range.

The tapering cutoff radii determine the range below which the radial functions are smoothly tapered to zero and they should set slightly higher than the inner cutoff radii.

To optimize the hyper-parameters one can set up a list of MomentTensorPotentialFittingParameters with different parameters and choose the parameter set which results in the lowest training and test error, as reported by the nlprint() output of the MomentTensorPotentialTraining object.

Two different kinds of radial function can be chosen: The original polynomial functions used in [1], which are in this implementation orthonormalized via Chebyshev poynomials (default and recommended option), and the Chebyshev expansion as explained in [2]. These are specified by setting the parameter cutoff_function to CutoffFunctionChebyshevOriginal respectively CutoffFunctionChebyshevExpansion.

Optionally, one may specify the isolated atomic energies which are involved in calculating the constant terms in the MTP fitting. If not specified, these energies will be calculated automatically using the same reference calculator as the rest of the training set. If the reference calculator is a DFT calculator it will always use the spin-polarized version of the calculator, keeping all other parameters the same.

The fitting of the linear coefficients can be accelerated by running on a GPU. This is particularly beneficial when the non-linear optimization is switched off via setting perform_optimization=False in the NonLinearCoefficientsParameters. To enable GPU acceleration, the flag use_gpu_acceleration needs to be set to True. To make use of this feature, the calculation needs to be run on a GPU that supports CUDA-11.8, otherwise it will fall back to the default CPU mode.