kliff.legacy.calculators

class kliff.legacy.calculators.Calculator(model)

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)

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()

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

Return type:

List[Any]

compute(compute_arguments)

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)

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)

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)

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: []

get_prediction(compute_arguments)

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)

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()

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()

Return the number of optimizing parameters.

Return type:

int

opt_params_has_bounds()

Return a bool to indicate whether there are parameters whose bounds are provided.

get_opt_params_bounds()

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)

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.legacy.calculators.CalculatorTorch(model, gpu=None)

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)

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_fingerprints()

Return a list of fingerprints of the configurations.

Return type:

List[dict]

get_compute_arguments(batch_size=1)

Return the dataloader with batch size set to batch_size.

set_fingerprints(fingerprints)

Update the fingerprints of the calculator. The fingerprints input argument should be in the same format as the output of meth:~kliff.legacy.descriptors.descriptor.load_fingerprints, which is a list of dictionaries.

Parameters:

fingerprints (List[dict]) – A list of fingerprints.

fit()

compute(batch)

property model

Get the underlying torch model

save_model(epoch, force_save=False)

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)

get_forces(batch)

get_stress(batch)

get_size_opt_params()

Return the size of the parameters.

Returns:

Each element in the list gives the shape of each type of parameter

tensors, containing, e.g., weights and biases, for each layer.

nelements: Number of elements of each parameter tensor. nparams: Total number of parameters

Return type:

sizes

get_num_opt_params()

Return the total number of parameters.

Return type:

int

get_opt_params(flat=True)

Retrieve the parameters, i.e., weights and biases.

Parameters:

flat (bool) – A flag to return a flat, 1D array.

Return type:

Union[List, array]

Returns:

Parameters, i.e., weights and biases. If flat=True, a 1D np.ndarray will be returned. Otherwise, nested lists will be returned, where each list contain the weights and biases for each layer.

update_model_params(parameters)

Update the model parameters from a 1D array.

Parameters:

parameters (array) – New parameter values to set. It needs to be a 1D array.