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]
- 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 componentv (
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 componentv (
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 componentv (
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
- 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 parametersettings (
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]]
- 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 configurationssupported_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 neighborscompute_energy (
bool) – whether to compute energycompute_forces (
bool) – whether to compute forcescompute_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_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
- 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_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]
- 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 parametersettings (
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]]
- 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}
- 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_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 parametersettings (
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_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.
- 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 parametersettings (
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_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
descriptor (
Descriptor) – atomic environment descriptor for computing configuration fingerprints. SeeSymmetryFunction()andBispectrum().seed (
int) – random seed.
- write_kim_model(path=None)[source]#
Write the model out as a KIM-API compatible one.
- Parameters
path (
Optional[Path]) – path to write the model
- fit(path)[source]#
Fit the model using analytic solution.
- Parameters
path (
Path) – path to the fingerprints generated by the descriptor.
- load(filename, mode='train')[source]#
Load a save model.
- Parameters
filename (
Path) – Path where the model is stored, e.g. kliff_model.pklmode (
str) – Purpose of the loaded model. Should be either train or eval.
- 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.
- property descriptor#
- property device#
- property dtype#
- property save_prefix#
- property save_start#
- property save_frequency#
- 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.nnlayers 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]#
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)[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 descriptor#
- property device#
- property dtype#
- 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.pklmode (
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.
- property save_frequency#
- property save_prefix#
- property save_start#
- 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]#
- Parameters
x (
Tensor) – Descriptors of shape (N, M), where N is the number of descriptors and M is the descriptor size.
- property descriptor#
- property device#
- property dtype#
- load(filename, mode='train')#
Load a save model.
- Parameters
filename (
Path) – Path where the model is stored, e.g. kliff_model.pklmode (
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.
- property save_frequency#
- property save_prefix#
- property save_start#
- 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)#
Write the model out as a KIM-API compatible one.
- Parameters
path (
Optional[Path]) – path to write the model