kliff.calculators#

class kliff.calculators.Calculator(model)[source]#

Calculator to compute properties (e.g. energy and forces) using a potential model for each configuration in the dataset.

The properties, together with the corresponding reference data stored in the configurations, are provided to Loss to construct a loss function for the optimizer.

In the reverse direction, a calculator grabs the new parameters from the optimizer and update the model with the new parameters.

Parameters: model (Model) – An instance of Model.

create(configs, use_energy=True, use_forces=True, use_stress=False)[source]#

Create compute arguments for a collection of configurations.

By compute arguments, we mean the information needed by a model to carry on a calculation, such as the coordinates, species, cutoff distance, neighbor list, etc. Each configuration has its own compute arguments, and this function creates the compute arguments for all the configurations in configs.

Parameters

configs (List[Configuration]) – atomic configurations. instances.
use_energy (Union[List[bool], bool]) – Whether to require the calculator to compute energy. If a list of bool is provided, each component is for one configuration in configs. If a bool is provided, it is applied to all configurations.
use_forces (Union[List[bool], bool]) – Whether to require the calculator to compute forces. If a list of bool is provided, each component is for one configuration in configs. If a bool is provided, it is applied to all configurations.
use_stress (Union[List[bool], bool]) – Whether to require the calculator to compute stress. If a list of bool is provided, each component is for one configuration in configs. If a bool is provided, it is applied to all configurations.

get_compute_arguments()[source]#

Return a list of compute arguments, each associated with a configuration.

Return type: List[Any]

compute(compute_arguments)[source]#

Compute the properties given the compute arguments associated with a configuration.

Parameters

compute_arguments – A compute arguments instance for a configuration.

Return type

Dict[str, Any]

Returns

A dictionary of properties, with keys of energy, forces and stress,: values of float or np.array.

get_energy(compute_arguments)[source]#

Get the energy of a configuration.

Parameters: compute_arguments – A compute arguments instance for a configuration.
Return type: float
Returns: The energy of the configuration associated with the compute arguments.

get_forces(compute_arguments)[source]#

Get the forces of a configuration.

Parameters

compute_arguments – A compute arguments instance for a configuration.

Return type

array

Returns

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

get_stress(compute_arguments)[source]#

Get the stress of a configuration.

Parameters: compute_arguments – A compute arguments instance for a configuration.
Return type: array
Returns: Virial stress of the configuration associated with the compute arguments, 1D array with 6 component. The returned stress is in Voigt notation, i.e. this function returns: [ $\sigma_{xx}, \sigma_{yy}, \sigma_{zz}, \sigma_{yz}, \sigma_{xy}, \sigma_{xz}$ ]

get_prediction(compute_arguments)[source]#

Get the prediction of all properties that are requested to compute.

The energy, forces, and stress are each flattened to a 1D array, and then concatenated (in the order of energy, forces, and stress) to form the prediction. Depending on the values of use_energy, use_forces, and use_stress that are provided in create(), one or more of energy, forces and stress may not be included in the prediction.

Parameters

compute_arguments – A compute arguments instance for a configuration.

Returns

If use_energy, use_forces, and use_stress are all True, the size of prediction is 1+3N+6, with the 1st component the energy, the 2nd to 1+3N components the flattened forces on N atoms, and the remaining 6 components the Voigt stress.
If one or more of use_energy, use_forces, and use_stress is False, its corresponding value is removed from prediction, and the size of prediction shrinks accordingly. For example, if both use_energy and use_stress are True but use_forces is False, then the size of prediction is 1+6, with the 1st component the energy, and the 2nd to 7th components the Voigt stress.

Return type

1D array of predictions. For a configuration of N atoms

get_reference(compute_arguments)[source]#

Get the reference data of all properties that are requested to compute.

Same as get_prediction(), the energy, forces, and stress are each flattened to a 1D array, and then concatenated (in the order of energy, forces, and stress) to form the reference. Depending on the values of use_energy, use_forces, and use_stress that are provided in create(), one or more of energy, forces and stress may not be included in the reference.

Parameters

compute_arguments – A compute arguments instance for a configuration.

Returns

If use_energy, use_forces, and use_stress are all True, the size of reference is 1+3N+6, with the 1st component the energy, the 2nd to 1+3N components the flattened forces on N atoms, and the remaining 6 components the Voigt stress.
If one or more of use_energy, use_forces, and use_stress is False, its corresponding value is removed from reference, and the size of reference shrinks accordingly. For example, if both use_energy and use_stress are True but use_forces is False, then the size of reference is 1+6, with the 1st component the energy, and the 2nd to 7th components the Voigt stress.

Return type

1D array of reference values. For a configuration of N atoms

get_opt_params()[source]#

Return a list of optimizing parameters.

The optimizing parameters is a list consisting of the values of the model parameters that is set to fit via kliff.models.Model.set_opt_params() or kliff.models.Model.set_one_opt_param(). The returned value is typically passed to an optimizer as the initial values to carry out the optimization.

Return type: array

get_num_opt_params()[source]#

Return the number of optimizing parameters.

Return type: int

has_opt_params_bounds()[source]#: Return a bool to indicate whether there are parameters whose bounds are provided.

get_opt_params_bounds()[source]#

Return the lower and upper bounds for the optimizing parameters.

The returned value is a list of (lower, upper) tuples. Each tuple contains the lower and upper bounds for the corresponding parameter obtained from get_opt_params(). None for lower or upper means that no bound should be applied.

update_model_params(opt_params)[source]#

Update model parameters from a list of opt_params.

This is the reverse of get_opt_params().

Parameters: opt_params (List[float]) – Optimizing parameters.

class kliff.calculators.CalculatorTorch(model, gpu=None)[source]#

A calculator for torch based models.

Parameters

model (ModelTorch) – torch models, e.g. NeuralNetwork.
gpu (Union[bool, int, None]) – whether to use gpu for training. If int (e.g. 0), will trained on this gpu device. If True will always train on gpu 0.

implemented_property = ['energy', 'forces', 'stress']#

create(configs, use_energy=True, use_forces=True, use_stress=False, fingerprints_filename='fingerprints.pkl', fingerprints_mean_stdev_filename=None, reuse=False, use_welford_method=False, nprocs=1)[source]#

Process configs to generate fingerprints.

Parameters

configs (List[Configuration]) – atomic configurations
use_energy (bool) – Whether to require the calculator to compute energy.
use_forces (bool) – Whether to require the calculator to compute forces.
use_stress (bool) – Whether to require the calculator to compute stress.
fingerprints_filename (Union[Path, str]) – Path to save the generated fingerprints. If reuse=True, Will not generate the fingerprints, but directly use the one provided via this file.
fingerprints_mean_stdev_filename (Union[str, Path, None]) – Path to save the mean and standard deviation of the fingerprints. If reuse=True, Will not generate new fingerprints mean and stdev, but directly use the one provided via this file. If normalize is not required by a descriptor, this is ignored.
reuse (bool) – Whether to reuse provided fingerprints.
use_welford_method (bool) – Whether to compute mean and standard deviation using the Welford method, which is memory efficient. See https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance
nprocs (int) – Number of processes used to generate the fingerprints. If 1, run in serial mode, otherwise nprocs processes will be forked via multiprocessing to do the work.

get_compute_arguments(batch_size=1)[source]#: Return the dataloader with batch size set to batch_size.

fit()[source]#

compute(batch)[source]#

property model#: Get the underlying torch model

save_model(epoch, force_save=False)[source]#

Save the model to disk.

When to save a model is dependent on epoch and a model’s metadata for save.

Parameters

epoch (int) – current optimization epoch.
force_save (bool) – save the model, ignoring epoch and save metadata.

get_energy(batch)[source]#

get_forces(batch)[source]#

get_stress(batch)[source]#