kliff.models#

class kliff.models.Parameter(value, fixed=None, lower_bound=None, upper_bound=None, name=None, index=None)[source]#

Potential parameter.

To follow the KIM model paradigm, a parameter is a list of floats that can be adjusted to fit the potential to some parameters.

This class is mainly by physically-motivated potentials.

Parameters
  • value (Union[Sequence[float], ndarray]) – parameter values, should be a list of float or a 1D array.

  • fixed (Optional[Sequence[bool]]) – whether parameter component should be fixed (i.e. not used for fitting). Should have the same length of value. Default to not fixed for all components.

  • lower_bound (Optional[Sequence[float]]) – lower bound of the allowed value for the parameter. Default to None, i.e. no lower bound is applied.

  • upper_bound (Optional[Sequence[float]]) – upper bound of the allowed value for the parameter. Default to None, i.e. no lower bound is applied.

  • name (Optional[str]) – name of the parameter.

  • index (Optional[int]) – integer index of the parameter.

property value: List[float]#

Parameter value.

Return type

List[float]

set_value(index, v)[source]#

Set the value of a component.

property fixed: List[bool]#

Whether each parameter component is fixed or not (i.e. allow to fitting or not).

Return type

List[bool]

set_fixed(index, v)[source]#

Set the fixed status of a component of the parameter.

Parameters
  • index (int) – index of the component

  • v (bool) – fix status

property lower_bound: List[float]#

Lower bound of parameter.

Return type

List[float]

set_lower_bound(index, v)[source]#

Set the lower bound of a component of the parameter.

Parameters
  • index (int) – index of the component

  • v (float) – lower bound value

property upper_bound: List[float]#

Upper bound of parameter.

Return type

List[float]

set_upper_bound(index, v)[source]#

Set the upper bound of a component of the parameter.

Parameters
  • index (int) – index of the component

  • v (float) – upper bound value

property name: str#

Name of the parameter.

Return type

str

property index: int#

Integer index of the parameter.

Return type

int

as_dict()[source]#

A JSON serializable dict representation of an object.

classmethod from_dict(d)[source]#
Parameters

d – Dict representation.

Returns

MSONable class.

REDIRECT = {}#
to_json()#

Returns a json string representation of the MSONable object.

Return type

str

unsafe_hash()#

Returns an hash of the current object. This uses a generic but low performance method of converting the object to a dictionary, flattening any nested keys, and then performing a hash on the resulting object

classmethod validate_monty(v)#

pydantic Validator for MSONable pattern

class kliff.models.OptimizingParameters(model_params)[source]#

A collection of parameters that will be optimized.

This can be all the parameters of a model or a subset of the parameters of a model. The behavior of individual component of a parameter can also be controlled. For example, keep the 2nd component of a parameters fixed, while optimizing the other components.

It interacts with optimizer to provide initial guesses of parameter values; it also receives updated parameters from the optimizer and update model parameters.

Parameters

model_params (Dict[str, Parameter]) – {name, parameter} all the parameters of a model. The attributes of these parameters will be modified to reflect whether it is optimized.

read(filename)[source]#

Read the parameters that will be optimized from a file.

Each parameter is a 1D array, and each component of the parameter array should be listed in a new line. Each line can contains 1, 2, or 3 elements, described in details below:

1st element: float or DEFAULT

Initial guess of the parameter component. If DEFAULT (case insensitive), the value from the calculator is used as the initial guess.

The 2nd and 3rd elements are optional.

If 2 elements are provided:

2nd element: FIX (case insensitive)

If FIX, the corresponding component will not be optimized.

If 3 elements are provided:

2nd element: float or INF (case insensitive)

Lower bound of the parameter. INF indicates that the lower bound is negative infinite, i.e. no lower bound is applied.

3rd element: float or INF (case insensitive)

Upper bound of the parameter. INF indicates that the upper bound is positive infinite, i.e. no upper bound is applied.

Instead of reading fitting parameters from a file, you can also setting them using a dictionary by calling the set() method.

Parameters

filename (Path) – path to file that includes the fitting parameters.

Example

# put the below in a file, say model_params.txt and you can read the fitting # parameters by this_class.read(filename=”model_params.txt”)

A DEFAULT 1.1

B DEFAULT FIX 1.1 FIX

C DEFAULT 0.1 INF 1.0 INF 2.1 2.0 FIX

set(**kwargs)[source]#

Set the parameters that will be optimized.

One or more parameters can be set. Each argument is for one parameter, where the argument name is the parameter name, the value of the argument is the settings(including initial value, fix flag, lower bound, and upper bound).

The value of the argument should be a list of list, where each inner list is for one component of the parameter, which can contain 1, 2, or 3 elements. See ~kliff.model.parameter.OptimizingParameters.read() for the options of the elements.

Example

instance.set(A=[[‘DEFAULT’], [2.0, 1.0, 3.0]], B=[[1.0, ‘FIX’], [2.0, ‘INF’, 3.0]])

set_one(name, settings)[source]#

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]]) – initial value, flag to fix a parameter, lower and upper bounds of a parameter.

Example

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

echo_opt_params(filename=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, echo_size=True)[source]#

Get the optimizing parameters as a string and/or print to file (stdout).

Parameters
  • filename (Union[Path, TextIO, None]) – Path to the file to output the optimizing parameters. If None, print to stdout.

  • echo_size (bool) – Whether to print the size of parameters. (Each parameter may have one or more components).

Return type

str

Returns

Optimizing parameters as a string.

get_num_opt_params()[source]#

Number of optimizing parameters.

This is the total number of model parameter components. For example, if the model has two parameters set to be optimized and each have two components, this will be four.

Return type

int

get_opt_params()[source]#

Nest all optimizing parameter values (except the fixed ones) to a 1D array.

The obtained values can be provided to the optimizer as the starting parameters.

This is the opposite operation of update_model_params().

Returns

A 1D array of nested optimizing parameter values.

Return type

opt_params

update_opt_params(params)[source]#

Update the optimizing parameter values from a sequence of float.

This is the opposite operation of get_opt_params().

Parameters

params (Sequence[float]) – updated parameter values from the optimizer.

Return type

Dict[str, Parameter]

get_opt_param_name_value_and_indices(index)[source]#

Get the name, value, parameter_index, and component_index of optimizing parameter in slot index.

Parameters

index (int) – slot index of the optimizing parameter

Return type

Tuple[str, float, int, int]

get_opt_params_bounds()[source]#

Get the lower and upper bounds of optimizing parameters.

Return type

List[Tuple[int, int]]

has_opt_params_bounds()[source]#

Whether bounds are set for some parameters.

Return type

bool

as_dict()[source]#

A JSON serializable dict representation of an object.

classmethod from_dict(d)[source]#
Parameters

d – Dict representation.

Returns

MSONable class.

REDIRECT = {}#
to_json()#

Returns a json string representation of the MSONable object.

Return type

str

unsafe_hash()#

Returns an hash of the current object. This uses a generic but low performance method of converting the object to a dictionary, flattening any nested keys, and then performing a hash on the resulting object

classmethod validate_monty(v)#

pydantic Validator for MSONable pattern

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

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)[source]#

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)[source]#

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)[source]#

Get a property by name.

Parameters

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

Return type

Any

get_energy()[source]#

Potential energy.

Return type

float

get_forces()[source]#

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()[source]#

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

Return type

ndarray

get_prediction()[source]#

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

Return type

ndarray

get_reference()[source]#

1D array of reference values for the configuration.

Return type

ndarray

class kliff.models.Model(model_name=None, params_transform=None)[source]#

Base class for all physics-motivated models.

Typically, a user will not directly use this.

Parameters
  • model_name (Optional[str]) – name of the model.

  • params_transform (Optional[ParameterTransform]) – optional transformation of parameters. Let’s call the parameters initialized in init_model_params() as original parameter space. Sometimes, it’s easier to work in another parameter (e.g. optimizers can perform better in the log space). Then we can use this parameter transformation class to transform between the original parameter space and the new easy-to-work space. Typically, a model only knows how to work in its original space to compute, e.g. energy and forces, so we need to inverse transform parameters back to original space (after an optimizer update its value in the log space). A params_transform instance should implement both a transform and an inverse_transform method to accomplish the above tasks. Note, all the parameters of this (the Model) class (e.g. self.model_params, and self.opt_params) are in the transformed easy-to-work space.

init_model_params(*args, **kwargs)[source]#

Initialize the parameters of the model.

Should return a dictionary of parameters.

Example

model_params = {“sigma”: Parameter([0.5]

“epsilon”: Parameter([0.4])

return model_params

Return type

Dict[str, Parameter]

init_influence_distance(*args, **kwargs)[source]#

Initialize the influence distance (aka cutoff distance) of the model.

This is used to compute the neighbor list of each atom.

Example

return 5.0

Return type

float

init_supported_species(*args, **kwargs)[source]#

Initialize the supported species of the model.

Should return a dict with chemical symbol as key and integer code as value.

Example

return {“C:0, “O”:1}

Return type

Dict[str, int]

get_compute_argument_class()[source]#
write_kim_model(path=None)[source]#
get_influence_distance()[source]#

Return influence distance (aka cutoff distance) of the model.

Return type

float

get_supported_species()[source]#

Return supported species of the model, a dict with chemical symbol as key and integer code as value.

Return type

Dict[str, int]

get_model_params()[source]#

Return all parameters of the model.

Return type

Dict[str, Parameter]

echo_model_params(filename=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, params_space='original')[source]#

Echo the model parameters.

Parameters
  • filename (Union[Path, TextIO, None]) – Path to write the model parameter info (e.g. sys.stdout). If None, do not write.

  • params_space (str) – In which space to show the parameters, options are original and transformed.

Return type

str

Returns

model parameter info in a string

read_opt_params(filename)[source]#

Read optimizing parameters from a file.

Each parameter is a 1D array, and each component of the parameter array should be listed in a new line. Each line can contain 1, 2, or 3 elements, described in details below:

1st element: float or DEFAULT

Initial guess of the parameter component. If DEFAULT (case insensitive), the value from the calculator is used as the initial guess.

The 2nd and 3rd elements are optional.

If 2 elements are provided:

2nd element: FIX (case insensitive)

If FIX, the corresponding component will not be optimized.

If 3 elements are provided:

2nd element: float or INF (case insensitive)

Lower bound of the parameter. INF indicates that the lower bound is negative infinite, i.e. no lower bound is applied.

3rd element: float or INF (case insensitive)

Upper bound of the parameter. INF indicates that the upper bound is positive infinite, i.e. no upper bound is applied.

Instead of reading fitting parameters from a file, you can also setting them using a dictionary by calling the set_opt_params() or set_one_opt_params() method.

Parameters

filename (Path) – path to file that includes the fitting parameters.

Example

# put the below in a file, say model_params.txt and you can read the fitting # parameters by this_class.read(filename=”model_params.txt”)

A DEFAULT 1.1

B DEFAULT FIX 1.1 FIX

C DEFAULT 0.1 INF 1.0 INF 2.1 2.0 FIX

set_opt_params(**kwargs)[source]#

Set the parameters that will be optimized.

One or more parameters can be set. Each argument is for one parameter, where the argument name is the parameter name, the value of the argument is the settings(including initial value, fix flag, lower bound, and upper bound).

The value of the argument should be a list of list, where each inner list is for one component of the parameter, which can contain 1, 2, or 3 elements.

See ~kliff.model.model.Model.read_opt_params() for the options of the elements.

Example

instance.set(A=[[‘DEFAULT’], [2.0, 1.0, 3.0]], B=[[1.0, ‘FIX’], [2.0, ‘INF’, 3.0]])

set_one_opt_param(name, settings)[source]#

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]]) – initial value, flag to fix a parameter, lower and upper bounds of a parameter.

Example

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

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

Echo the optimizing parameter to a file.

get_num_opt_params()[source]#

Number of optimizing parameters.

This is the total number of model parameter components. For example, if the model has two parameters set to be optimized and each have two components, this will be four.

Return type

int

get_opt_params()[source]#

Nest all optimizing parameter values (except the fixed ones) to a 1D array.

The obtained values can be provided to the optimizer as the starting parameters.

This is the opposite operation of update_model_params().

Returns

A 1D array of nested optimizing parameter values.

Return type

opt_params

update_model_params(params)[source]#

Update the optimizing parameter values from a sequence of float.

This is the opposite operation of get_opt_params().

Note, self.model_params will be updated as well, since self.opt_params is initialized from self.model_params without copying the Parameter instance.

Parameters

params (Sequence[float]) – updated parameter values from the optimizer.

get_opt_param_name_value_and_indices(index)[source]#

Get the name, value, parameter_index, and component_index of optimizing parameter in slot index.

Parameters

index (int) – slot index of the optimizing parameter

Return type

Tuple[str, float, int, int]

get_opt_params_bounds()[source]#

Get the lower and upper bounds of optimizing parameters.

Return type

List[Tuple[int, int]]

has_opt_params_bounds()[source]#

Whether bounds are set for some parameters.

Return type

bool

save(filename='trained_model.yaml')[source]#

Save a model to disk.

Parameters

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

load(filename='trained_model.yaml')[source]#

Load a model on disk into memory.

Parameters

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

class kliff.models.LennardJones(model_name='LJ6-12', params_transform=None)[source]#

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

init_model_params()[source]#

Initialize the parameters of the model.

Should return a dictionary of parameters.

Example

model_params = {“sigma”: Parameter([0.5]

“epsilon”: Parameter([0.4])

return model_params

init_influence_distance()[source]#

Initialize the influence distance (aka cutoff distance) of the model.

This is used to compute the neighbor list of each atom.

Example

return 5.0

init_supported_species()[source]#

Initialize the supported species of the model.

Should return a dict with chemical symbol as key and integer code as value.

Example

return {“C:0, “O”:1}

get_compute_argument_class()[source]#
echo_model_params(filename=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, params_space='original')#

Echo the model parameters.

Parameters
  • filename (Union[Path, TextIO, None]) – Path to write the model parameter info (e.g. sys.stdout). If None, do not write.

  • params_space (str) – In which space to show the parameters, options are original and transformed.

Return type

str

Returns

model parameter info in a string

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

Echo the optimizing parameter to a file.

get_influence_distance()#

Return influence distance (aka cutoff distance) of the model.

Return type

float

get_model_params()#

Return all parameters of the model.

Return type

Dict[str, Parameter]

get_num_opt_params()#

Number of optimizing parameters.

This is the total number of model parameter components. For example, if the model has two parameters set to be optimized and each have two components, this will be four.

Return type

int

get_opt_param_name_value_and_indices(index)#

Get the name, value, parameter_index, and component_index of optimizing parameter in slot index.

Parameters

index (int) – slot index of the optimizing parameter

Return type

Tuple[str, float, int, int]

get_opt_params()#

Nest all optimizing parameter values (except the fixed ones) to a 1D array.

The obtained values can be provided to the optimizer as the starting parameters.

This is the opposite operation of update_model_params().

Returns

A 1D array of nested optimizing parameter values.

Return type

opt_params

get_opt_params_bounds()#

Get the lower and upper bounds of optimizing parameters.

Return type

List[Tuple[int, int]]

get_supported_species()#

Return supported species of the model, a dict with chemical symbol as key and integer code as value.

Return type

Dict[str, int]

has_opt_params_bounds()#

Whether bounds are set for some parameters.

Return type

bool

load(filename='trained_model.yaml')#

Load a model on disk into memory.

Parameters

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

read_opt_params(filename)#

Read optimizing parameters from a file.

Each parameter is a 1D array, and each component of the parameter array should be listed in a new line. Each line can contain 1, 2, or 3 elements, described in details below:

1st element: float or DEFAULT

Initial guess of the parameter component. If DEFAULT (case insensitive), the value from the calculator is used as the initial guess.

The 2nd and 3rd elements are optional.

If 2 elements are provided:

2nd element: FIX (case insensitive)

If FIX, the corresponding component will not be optimized.

If 3 elements are provided:

2nd element: float or INF (case insensitive)

Lower bound of the parameter. INF indicates that the lower bound is negative infinite, i.e. no lower bound is applied.

3rd element: float or INF (case insensitive)

Upper bound of the parameter. INF indicates that the upper bound is positive infinite, i.e. no upper bound is applied.

Instead of reading fitting parameters from a file, you can also setting them using a dictionary by calling the set_opt_params() or set_one_opt_params() method.

Parameters

filename (Path) – path to file that includes the fitting parameters.

Example

# put the below in a file, say model_params.txt and you can read the fitting # parameters by this_class.read(filename=”model_params.txt”)

A DEFAULT 1.1

B DEFAULT FIX 1.1 FIX

C DEFAULT 0.1 INF 1.0 INF 2.1 2.0 FIX

save(filename='trained_model.yaml')#

Save a model to disk.

Parameters

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

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]]) – initial value, flag to fix a parameter, lower and upper bounds of a parameter.

Example

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

set_opt_params(**kwargs)#

Set the parameters that will be optimized.

One or more parameters can be set. Each argument is for one parameter, where the argument name is the parameter name, the value of the argument is the settings(including initial value, fix flag, lower bound, and upper bound).

The value of the argument should be a list of list, where each inner list is for one component of the parameter, which can contain 1, 2, or 3 elements.

See ~kliff.model.model.Model.read_opt_params() for the options of the elements.

Example

instance.set(A=[[‘DEFAULT’], [2.0, 1.0, 3.0]], B=[[1.0, ‘FIX’], [2.0, ‘INF’, 3.0]])

update_model_params(params)#

Update the optimizing parameter values from a sequence of float.

This is the opposite operation of get_opt_params().

Note, self.model_params will be updated as well, since self.opt_params is initialized from self.model_params without copying the Parameter instance.

Parameters

params (Sequence[float]) – updated parameter values from the optimizer.

write_kim_model(path=None)#
class kliff.models.KIMModel(model_name, params_transform=None)[source]#

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.

  • params_transform (Optional[ParameterTransform]) – optional transformation of parameters. Let’s call the parameters initialized in init_model_params() as original parameter space. Sometimes, it’s easier to work in another parameter (e.g. optimizers can perform better in the log space). Then we can use this parameter transformation class to transform between the original parameter space and the new easy-to-work space. Typically, a model only knows how to work in its original space to compute, e.g. energy and forces, so we need to inverse transform parameters back to original space (after an optimizer update its value in the log space). A params_transform instance should implement both a transform and an inverse_transform method to accomplish the above tasks. Note, all the parameters of this (the Model) class (e.g. self.model_params, and self.opt_params) are in the transformed easy-to-work space.

init_model_params()[source]#

Initialize the parameters of the model.

Should return a dictionary of parameters.

Example

model_params = {“sigma”: Parameter([0.5]

“epsilon”: Parameter([0.4])

return model_params

Return type

Dict[str, Parameter]

init_influence_distance()[source]#

Initialize the influence distance (aka cutoff distance) of the model.

This is used to compute the neighbor list of each atom.

Example

return 5.0

Return type

float

init_supported_species()[source]#

Initialize the supported species of the model.

Should return a dict with chemical symbol as key and integer code as value.

Example

return {“C:0, “O”:1}

Return type

Dict[str, int]

get_compute_argument_class()[source]#
get_kim_model_params()[source]#

Inquire the KIM model to get all the parameters.

Return type

Dict[str, Parameter]

Returns

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

create_a_kim_compute_argument()[source]#

Create a compute argument for the KIM model.

set_opt_params(**kwargs)[source]#

Set the parameters that will be optimized.

One or more parameters can be set. Each argument is for one parameter, where the argument name is the parameter name, the value of the argument is the settings(including initial value, fix flag, lower bound, and upper bound).

The value of the argument should be a list of list, where each inner list is for one component of the parameter, which can contain 1, 2, or 3 elements.

See ~kliff.model.model.Model.read_opt_params() for the options of the elements.

Example

instance.set(A=[[‘DEFAULT’], [2.0, 1.0, 3.0]], B=[[1.0, ‘FIX’], [2.0, ‘INF’, 3.0]])

set_one_opt_param(name, settings)[source]#

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]]) – initial value, flag to fix a parameter, lower and upper bounds of a parameter.

Example

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

update_model_params(params)[source]#

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

write_kim_model(path=None)[source]#

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.model_params. path will be created if it does not exist.

Parameters

path (Optional[Path]) – Path to the 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.

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

Echo the model parameters.

Parameters
  • filename (Union[Path, TextIO, None]) – Path to write the model parameter info (e.g. sys.stdout). If None, do not write.

  • params_space (str) – In which space to show the parameters, options are original and transformed.

Return type

str

Returns

model parameter info in a string

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

Echo the optimizing parameter to a file.

get_influence_distance()#

Return influence distance (aka cutoff distance) of the model.

Return type

float

get_model_params()#

Return all parameters of the model.

Return type

Dict[str, Parameter]

get_num_opt_params()#

Number of optimizing parameters.

This is the total number of model parameter components. For example, if the model has two parameters set to be optimized and each have two components, this will be four.

Return type

int

get_opt_param_name_value_and_indices(index)#

Get the name, value, parameter_index, and component_index of optimizing parameter in slot index.

Parameters

index (int) – slot index of the optimizing parameter

Return type

Tuple[str, float, int, int]

get_opt_params()#

Nest all optimizing parameter values (except the fixed ones) to a 1D array.

The obtained values can be provided to the optimizer as the starting parameters.

This is the opposite operation of update_model_params().

Returns

A 1D array of nested optimizing parameter values.

Return type

opt_params

get_opt_params_bounds()#

Get the lower and upper bounds of optimizing parameters.

Return type

List[Tuple[int, int]]

get_supported_species()#

Return supported species of the model, a dict with chemical symbol as key and integer code as value.

Return type

Dict[str, int]

has_opt_params_bounds()#

Whether bounds are set for some parameters.

Return type

bool

load(filename='trained_model.yaml')#

Load a model on disk into memory.

Parameters

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

read_opt_params(filename)#

Read optimizing parameters from a file.

Each parameter is a 1D array, and each component of the parameter array should be listed in a new line. Each line can contain 1, 2, or 3 elements, described in details below:

1st element: float or DEFAULT

Initial guess of the parameter component. If DEFAULT (case insensitive), the value from the calculator is used as the initial guess.

The 2nd and 3rd elements are optional.

If 2 elements are provided:

2nd element: FIX (case insensitive)

If FIX, the corresponding component will not be optimized.

If 3 elements are provided:

2nd element: float or INF (case insensitive)

Lower bound of the parameter. INF indicates that the lower bound is negative infinite, i.e. no lower bound is applied.

3rd element: float or INF (case insensitive)

Upper bound of the parameter. INF indicates that the upper bound is positive infinite, i.e. no upper bound is applied.

Instead of reading fitting parameters from a file, you can also setting them using a dictionary by calling the set_opt_params() or set_one_opt_params() method.

Parameters

filename (Path) – path to file that includes the fitting parameters.

Example

# put the below in a file, say model_params.txt and you can read the fitting # parameters by this_class.read(filename=”model_params.txt”)

A DEFAULT 1.1

B DEFAULT FIX 1.1 FIX

C DEFAULT 0.1 INF 1.0 INF 2.1 2.0 FIX

save(filename='trained_model.yaml')#

Save a model to disk.

Parameters

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

class kliff.models.ModelTorch(descriptor, seed=35)[source]#

Base class for machine learning models.

Typically, a user will not directly use this.

Parameters
forward(x)[source]#
fit(path)[source]#

Fit the model using analytic solution.

Parameters

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

set_save_metadata(prefix, start, frequency=1)[source]#

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.

save(filename)[source]#

Save a model to disk.

Parameters

filename (Path) – Path to store the model.

load(filename, mode='train')[source]#

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.

write_kim_model(path=None)[source]#
property device#
class kliff.models.NeuralNetwork(descriptor, seed=35)[source]#

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)[source]#

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)[source]#
write_kim_model(path=None, driver_name='DUNN__MD_292677547454_000', dropout_ensemble_size=None)[source]#

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.

property device#
fit(path)#

Fit the model using analytic solution.

Parameters

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

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.

save(filename)#

Save a model to disk.

Parameters

filename (Path) – Path to store the model.

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.

class kliff.models.LinearRegression(*args: Any, **kwargs: Any)[source]#

Linear regression model.

forward(x)[source]#
fit(path)[source]#

Fit the model using analytic solution.

set_params(beta)[source]#

Set linear weight and bias.

Parameters

beta (Tensor) – First component is bias and the remaining components is weight.

prepare_data(loader, use_energy=True, use_forces=False)[source]#
property device#
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.

save(filename)#

Save a model to disk.

Parameters

filename (Path) – Path to store the model.

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.

write_kim_model(path=None)#