kliff.models

class kliff.models.Parameter(input_array: ~numpy.ndarray | float | int, name: str = None, transform_function: ParameterTransform = None, bounds: ~numpy.ndarray = None, index: int = None, opt_mask: [<class 'numpy.ndarray'>, <class 'bool'>] = None)

Parameter class for containing physics-based model parameters.

This class provides utilities for managing model parameters between the “model space” and the “parameter space”. See the glossary below for the definition of these spaces. Modeled on torch.nn.Parameters, it inherits from numpy.ndarray. It is a numpy array with additional attributes such as name, transform, etc.

Glossary:

• Model space: The space in which the model expects the parameters to be in. Currently,

  all models in OpenKIM expect the parameters to be in the affine cartesian space.

• Parameter space: Parameter space is the space in which you want to sample/optimize

  the parameters. Most often parameters are transformed using bijective transformations of the model inputs for ease of optimization/sampling. For example, the log transform is used in searching for the optimal parameters of sloppy model parameters. There can be cases where transformation functions are not bijective, e.g. ceiling function for mapping continuous parameters to discrete values. Parameter space is mostly used for optimization, and not the model itself. If no transform_function is provided then parameter space and model space are same.

All functions that needs input/output in the model space, will use the suffix _model_space and _param_space for the transformed parameter space.

Below is the list of such twinned functions, and their designed use cases: 1. get_numpy_array_model_space and get_numpy_array_param_space: These functions

return the numpy array of parameters in the model space and parameter space. These functions should be used for getting the pure numpy array of parameters where the Parameters class might not work, e.g for feeding values to the model. They are also used in case of comparing the parameter state etc.

2. copy_from_model_space and copy_from_param_space: These functions copy the

   provided array to self in the model space and parameter space. They are useful for copying values during optimization etc. NOTE: These functions expect the incoming array to be of the same type and shape as self, compensated for opt_mask.

3. add_bounds_model_space and add_bounds_param_space: These functions add bounds

   to the parameter in the model space and parameter space.

4. get_bounds_model_space and get_bounds_param_space: These functions return the

   bounds in the model space and parameter space.

5. get_opt_numpy_array_param_space: This function returns the numpy array of parameters

   in the parameter space, with the opt_mask applied. This should be the de-facto method for getting the numpy array of parameters for optimization. At present, it does not have _model_space version, as there are no applications for it. If needed, it can be added later.

name

Name of the parameter.

transform_function

Instance of ParameterTransform object to be applied to the parameter.

index

Index of the parameter in the parameter vector. used for setting the parameter in the KIMPY.

bounds

Bounds for the parameter, must be numpy array of shape n x 2, with [n,0] as lower bound, and [n,1] as the upper bound. If None, no bounds are applied.

opt_mask

A boolean or boolean array of the same shape as the parameter. For a vector parameter opt_mask acts as a binary mask to determine which vector components will be optimized, e.g. for a parameter with value [1., 2., 3.], and opt_mask [True, False, True], only the first and third components will be optimized, and second one will be presumed constant.

name: str

transform_function: ParameterTransform

index: int

bounds: ndarray

opt_mask: Union[ndarray, bool]

transform()

Apply the transform to the parameter.

This method simple applies the function ~:kliff.transforms.ParameterTransform.__call__ to the parameter (or equivalently, ~:kliff.transforms.ParameterTransform.transform).

inverse_transform()

Apply the inverse transform to the parameter.

Simply applies the function :kliff.transforms.ParameterTransform.inverse_transform() in place, to the parameters.

copy_from_param_space(arr)

Copy array to self in the parameter space.

Array can be a numpy array or a Parameter object. This method assumes that the array is of the same type and shape as self, compensated for opt_mask. If not, it will raise an error. This method also assumes that the incoming array is in the same space, as the parameter currently (i.e. “Parameter space”, see glossary above for detail).

Parameters:

arr (ndarray) – Array to copy to self.

copy_from_model_space(arr)

Copy arr from model space.

Array can be a numpy array or a Parameter object. This method assumes that the incoming array is in the model space and would need transformation to the parameter space before copying. It is a safer method to use in most cases. If the parameter is not transformed, it will transform it first for maintaining consistency. This method requires the copied array to have consistent opt_mask applied.

Parameters:

arr (array) – Array to copy to self.

get_numpy_array_model_space()

Get a numpy array of parameters in the model space.

This method should be uses for getting the numpy array of parameters where the Parameters class might not work, for feeding values to the model.

Return type:

ndarray

Returns:

A numpy array of parameters in the original space.

get_numpy_array_param_space()

Applies the transform to the parameter, and returns the transformed array.

get_opt_numpy_array_param_space()

Get a masked numpy array of parameters in the transformed space.

This method is similar to :get_numpy_array_param_space but additionally does apply the opt_mask, and returns the array. This ensures the correctness of the array for optimization/other applications. This should be the de-facto method for getting the numpy array of parameters.

Return type:

ndarray

Returns:

A numpy array of parameters in the original space.

copy_at_param_space(arr, index)

Copy values at a particular index or indices in parameter space.

This method directly copies the provided data, and does not perform any checks.

Parameters:

• index (Union[int, List[int]]) – Index or indices to copy the values at.

• arr (Union[int, float, ndarray, List]) – Array to copy to self.

add_transform(transform)

Save a transform object with the parameter.

Parameters:

transform (ParameterTransform) – Instance of ParameterTransform object to be applied to the parameter.

add_bounds_model_space(bounds)

Add bounds to the parameter.

Bounds should be supplied in the model space. The bounds will be transformed if the transform_function is provided to the parameter.

Parameters:

bounds (ndarray) – numpy array of shape (n, 2)

add_bounds_param_space(bounds)

Add bounds to the parameter.

Add bounds to the parameter in parameter space. It does not do any additional checks or perform any transformations.

Parameters:

bounds (ndarray) – numpy array of shape (n, 2)

add_opt_mask(mask)

Set mask for optimizing vector quantities.

It expects an input array of shape (n,), where n is the dimension of the vector quantity to be optimized. This array must contain n booleans indicating which properties to optimize.

Parameters:

mask (Union[ndarray, bool]) – boolean array of same shape as the vector quantity to be optimized

get_bounds_param_space()

Returns bounds array that is used by scipy optimizer.

Return type:

List[Tuple[int, int]]

Returns:

A list of tuples of the form (lower_bound, upper_bound)

get_bounds_model_space()

Get the bounds in the original space.

Return type:

ndarray

Returns:

A numpy array of bounds in the original space.

has_bounds()

Check if bounds are set for optimizing quantities

Return type:

bool

Returns:

True if bounds are set, False otherwise.

as_dict()

Return a dictionary containing the state of the object.

save(filename)

Save the parameter to disk.

classmethod from_dict(state_dict)

Update the object’s attributes based on the provided state dictionary.

Parameters:

state_dict (dict) – The dictionary containing the state of the object. This dictionary should include the “value” key.

classmethod load(filename)

Load a parameter from disk. TODO: non classmethod version

get_opt_param_name_value_and_indices()

Get the name, value, and indices of the optimizable parameters.

Return type:

Tuple[str, Union[float, ndarray], int]

Returns:

A tuple of lists of names, values, and indices of the optimizable parameters.

property lower_bound

Get the lower bounds of the parameter.

Always returns values in parameter space.

Returns:

A numpy array of lower bounds.

property upper_bound

Get the upper bounds of the parameter.

Always returns values in parameter space.

Returns:

A numpy array of upper bounds.

property is_mutable

Check if the parameter is mutable.

Returns:

True if the parameter is mutable, False otherwise.

class kliff.models.ComputeArguments(conf, supported_species, influence_distance, compute_energy=True, compute_forces=True, compute_stress=False)

Compute property (e.g. energy, forces, and stress) for a configuration.

This is the base class for other compute arguments. Typically, a user will not directly use this.

Parameters:

• conf (Configuration) – atomic configurations

• supported_species (Dict[str, int]) – species supported by the potential model, with chemical symbol as key and integer code as value.

• influence_distance (float) – influence distance (aka cutoff distance) to calculate neighbors

• compute_energy (bool) – whether to compute energy

• compute_forces (bool) – whether to compute forces

• compute_stress (bool) – whether to compute stress

implemented_property = []

compute(params)

Compute the properties required by the compute flags, and store them in self.results.

Parameters:

params (Dict[str, Parameter]) – the parameters of the model.

Example

energy = a_func_to_compute_energy() forces = a_func_to_compute_forces() stress = a_func_to_compute_stress() self.results[‘energy’] = energy self.results[‘forces’] = forces self.results[‘stress’] = stress

get_compute_flag(name)

Check whether the model is asked to compute property.

Parameters:

name (str) – name of the property, e.g. energy, forces, and stresses

Return type:

bool

get_property(name)

Get a property by name.

Parameters:

name (str) – name of the property, e.g. energy, forces, and stresses

Return type:

Any

get_energy()

Potential energy.

Return type:

float

get_forces()

2D array of shape (N,3) of the forces on atoms, where N is the number of atoms in the configuration.

Return type:

ndarray

get_stress()

1D array of the virial stress, in Voigt notation.

Return type:

ndarray

get_prediction()

1D array of prediction from the model for the configuration.

Return type:

ndarray

get_reference()

1D array of reference values for the configuration.

Return type:

ndarray

class kliff.models.Model(model_name=None)

init_model_params(*args, **kwargs)

Return type:

Dict[str, Parameter]

init_influence_distance(*args, **kwargs)

Return type:

float

init_supported_species(*args, **kwargs)

Return type:

Dict[str, int]

get_compute_argument_class()

write_kim_model(path=None)

get_influence_distance()

Return type:

float

get_supported_species()

Return type:

Dict[str, int]

get_model_params()

Return type:

Dict[str, Parameter]

echo_model_params(filename=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Return type:

str

read_opt_params(filename)

set_params_mutable(list_of_params)

Set all the optimizable parameters from list of names of parameters :type list_of_params: List[str] :param list_of_params: List of string names of parameters

Example

model.set_params_mutable([“A”, “B”, “sigma”])

set_opt_params(**kwargs)

set_one_opt_param(name, settings)

echo_opt_params(filename=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Echo the optimizing parameter to a file.

get_num_opt_params()

Count and return number of optimizable parameters. Utilizes Parameter class.

Return type:

int

get_opt_params()

Get optimizable parameters, concatenated as a single numpy array. Obtained numpy array is the state for the optimizer to optimize. Utilizes Parameter class.

Return type:

ndarray

update_model_params(params)

Copy and update the parameter from incoming params array. This method utilizes the parameters internal function to copy the parameter in a consistent manner.

Parameters:

params (Union[ndarray, List[Union[float, int, Parameter]]]) – numpy array with the shape of optimized parameter concatenated array.

get_opt_param_name_value_and_indices(index)

Return type:

Tuple[str, Union[float, ndarray], int]

get_formatted_param_bounds()

Get the lower and upper bounds of optimizing parameters, to be supplied directly to the scipy optimizer.

Return type:

Tuple[Tuple[int, int]]

Returns:

tuple with bounds values. Unbound variables are provided with value (None, None)

opt_params_has_bounds()

Whether bounds are set for any of the parameters.

Return type:

bool

Returns:

boolean true if any of the parameters are marked mutable.

save(filename='trained_model.yaml')

Save a model to disk.

Parameters:

filename (Path) – Path where to store the model.

load(filename='trained_model.yaml')

Load a model on disk into memory.

Parameters:

filename (Path) – Path where the model is stored.

named_parameters()

Get a dict of parameters that are marked as mutable, and hence can be optimized. The parameter values are subjected to change as per the transformations applied.

Returns:

Dictionary of parameters (~kliff.models.parameters.Parameter)

parameters()

Get a list of parameters that are marked as mutable, and hence can be optimized.

Returns:

List of parameters (~kliff.models.parameters.Parameter)

class kliff.models.LennardJones(model_name='LJ6-12', species=None)

KLIFF built-in Lennard-Jones 6-12 potential model.

This model supports multiple species, where a different set of parameters is used for each species pair. For example if species A, B, and C are provided, then there will be 6 values for each of the epsilon and sigma parameters. The order of the parameters is as follows: A-A, A-B, A-C, B-B, B-C, and C-C.

Parameters:

• model_name (str) – name of the model

• species (Optional[List[str]]) – list of species. If None, there model will create a single value for each parameter, and all species pair will use the same parameters. If a list of species is provided, then the model will create a different set of parameters for each species pair.

• params_transform – parameter transform object. If None, no transformation is performed.

init_model_params()

init_influence_distance()

init_supported_species()

get_compute_argument_class()

class kliff.models.KIMModel(model_name)

A general interface to any KIM model.

Parameters:

model_name (str) – name of a KIM model. Available models can be found at: https://openkim.org. For example SW_StillingerWeber_1985_Si__MO_405512056662_006.

init_model_params()

Return type:

Dict[str, Parameter]

init_influence_distance()

Return type:

float

init_supported_species()

Return type:

Dict[str, int]

get_compute_argument_class()

get_kim_model_params()

Inquire the KIM model to get all the parameters.

Returns:

{name, parameter}, all parameters in a kim model.

create_a_kim_compute_argument()

Create a compute argument for the KIM model.

set_params_mutable(list_of_params)

Set all the optimizable parameters from list of names of parameters :type list_of_params: List[str] :param list_of_params: List of string names of parameters

Example

model.set_params_mutable([“A”, “B”, “sigma”])

set_one_opt_param(name, settings)

Set one parameter that will be optimized.

The name of the parameter should be given as the first entry of a list (or tuple), and then each data line should be given in in a list.

Parameters:

• name (str) – name of a fitting parameter

• settings (List[List[Any]]) – List initial value, flag to fix a parameter, lower and upper bounds of a parameter.

Example

name = ‘A’ settings = [[‘default’, 0, 20], [2.0, ‘fix’], [2.2, ‘inf’, 3.3]] instance.set_one(name, settings)

update_model_params(params)

Update optimizing parameters (a sequence used by the optimizer) to the kim model.

write_kim_model(path=None)

Write out a KIM model that can be used directly with the kim-api.

This function typically write two files to path: (1) CMakeLists.txt, and (2) a parameter file like A.params. path will be created if it does not exist.

Parameters:

path (Optional[Path]) – Path to a directory to store the model. If None, it is set to ./MODEL_NAME_kliff_trained, where MODEL_NAME is the model_name that provided at the initialization of this class.

Note

This only works for parameterized KIMModel models that support the writing of parameters.

static get_model_from_manifest(model_manifest, param_manifest=None, is_model_tarfile=False)

Get the model from a configuration. If it is a valid KIM model, it will return the KIMModel object. If it is a TorchML model, it will return the torch ReverseScriptedModule object in future. Else raise error. If the model is a tarball, it will extract and install the model.

`{todo} Get torchscript model from TorchML driver. `

Example model_manifest: ```yaml

model:

model_path: ./model.tar.gz # path to the model tarball model_name: SW_StillingerWeber_1985_Si__MO_405512056662_006 # KIM model name, installed if missing model_collection: “user”

```

Example param_manifest: ```yaml

parameter:

• A # dict means the parameter is transformed

• B # these are the parameters that are not transformed

• sigma:

  transform_name: LogParameterTransform value: 2.0 bounds: [[1.0, 10.0]]

```

`{note} `parameter` block is usually defined as the children of the `transform` block in trainer configuration file. `

Parameters:

• model_manifest (dict) – configuration object

• param_manifest (Optional[dict]) – parameter transformation configuration

• is_model_tarfile (bool) – whether the model is a tarball

Returns:

Model object

static get_model_driver_name(model_name)

Get the model driver from the model name. It will return the model driver string from the installed KIM API model. If the model is not installed, and the model name is a tarball, it will extract the model driver name from the CMakeLists.txt. This is needed to ensure that it excludes the model drivers that it cannot handle. Example: TorchML driver based models. These models are to be trained using the TorchTrainer.

TODO: This is not a clean solution. I think KIMPY must have a better way to handle this.

Ask Mingjian/Yaser for comment.

Parameters:

model_name (str) – name of the model.

Return type:

Optional[str]

Returns:

Model driver name.

class kliff.models.ModelTorch(descriptor, seed=35)

Base class for machine learning models.

Typically, a user will not directly use this.

Parameters:

• descriptor (Descriptor) – atomic environment descriptor for computing configuration fingerprints. See SymmetryFunction() and Bispectrum().

• seed (int) – random seed.

forward(x)

Use the model to perform computation.

Parameters:

x (Any) – input to the model

write_kim_model(path=None)

Write the model out as a KIM-API compatible one.

Parameters:

path (Optional[Path]) – path to write the model

fit(path)

Fit the model using analytic solution.

Parameters:

path (Path) – path to the fingerprints generated by the descriptor.

save(filename)

Save a model to disk.

Parameters:

filename (Path) – Path to store the model.

load(filename, mode='train')

Load a save model.

Parameters:

• filename (Path) – Path where the model is stored, e.g. kliff_model.pkl

• mode (str) – Purpose of the loaded model. Should be either train or eval.

set_save_metadata(prefix, start, frequency=1)

Set metadata that controls how the model are saved during training.

If this function is called before minimization starts, the model will be saved to the directory specified by prefix every frequency epochs, beginning at the start epoch.

Parameters:

• prefix (Path) – Path to the directory where the models are saved. Model will be named as {prefix}/model_epoch{ep}.pt, where ep is the epoch number.

• start (int) – Epoch number at which begins to save the model.

• frequency (int) – Save the model every frequency epochs.

property descriptor

property device

property dtype

property save_prefix

property save_start

property save_frequency

class kliff.models.NeuralNetwork(descriptor, seed=35)

Neural Network model.

A feed-forward neural network model.

Parameters:

• descriptor (Descriptor) – A descriptor that transforms atomic environment information to the fingerprints, which are used as the input for the neural network.

• seed – Global seed for random numbers.

add_layers(*layers)

Add layers to the sequential model.

Parameters:

layers – torch.nn layers torch.nn layers that are used to build a sequential model. Available ones including: torch.nn.Linear, torch.nn.Dropout, and torch.nn.Sigmoid among others. See https://pytorch.org/docs/stable/nn.html for a full list.

forward(x)

Forward pass through the neural network.

Parameters:

x – input descriptor to the neural network.

Returns:

The output of the neural network.

write_kim_model(path=None, driver_name='DUNN__MD_292677547454_000', dropout_ensemble_size=None)

Write out a model that is compatible with the KIM API.

Parameters:

• path (Optional[Path]) – Path to write the model. If None, defaults to ./NeuralNetwork_KLIFF__MO_000000111111_000.

• driver_name (str) – Name of the model driver.

• dropout_ensemble_size (Optional[int]) – Size of the dropout ensemble. Ignored if not fitting a dropout NN. Otherwise, defaults to 100 if None.

class kliff.models.LinearRegression(*args: Any, **kwargs: Any)

Linear regression model.

forward(x)

Parameters:

x (Tensor) – Descriptors of shape (N, M), where N is the number of descriptors and M is the descriptor size.

fit(path)

Fit the model using analytic solution.