kliff.models.parameter

class kliff.models.parameter.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.

exception kliff.models.parameter.ParameterError(msg)