kliff.legacy.loss

kliff.legacy.loss.energy_forces_residual(identifier, natoms, weight, prediction, reference, data)

A residual function using both energy and forces.

The residual is computed as

weight.config_weight * wi * (prediction - reference)

where wi can be weight.energy_weight or weight.forces_weight, depending on the property.

Parameters:

• identifier (str) – (unique) identifier of the configuration for which to compute the residual. This is useful when you want to weigh some configuration differently.

• natoms (int) – number of atoms in the configuration

• weight (Weight) – an instance that computes the weight of the configuration in the loss function.

• prediction (array) – prediction computed by calculator, 1D array

• reference (array) – references data for the prediction, 1D array

• data (Dict[str, Any]) – additional data for calculating the residual. Supported key value pairs are: - normalize_by_atoms: bool (default: True) If normalize_by_atoms is True, the residual is divided by the number of atoms in the configuration.

Returns:

1D array of the residual

Note

The length of prediction and reference (call it S) are the same, and it depends on use_energy and use_forces in Calculator. Assume the configuration contains of N atoms.

1. If use_energy == True and use_forces == False, then S = 1. prediction[0] is the potential energy computed by the calculator, and reference[0] is the reference energy.

2. If use_energy == False and use_forces == True, then S = 3N. prediction[3*i+0], prediction[3*i+1], and prediction[3*i+2] are the x, y, and z component of the forces on atom i in the configuration, respectively. Correspondingly, reference is the 3N concatenated reference forces.

3. If use_energy == True and use_forces == True, then S = 3N + 1. prediction[0] is the potential energy computed by the calculator, and reference[0] is the reference energy. prediction[3*i+1], prediction[3*i+2], and prediction[3*i+3] are the x, y, and z component of the forces on atom i in the configuration, respectively. Correspondingly, reference is the 3N concatenated reference forces.

kliff.legacy.loss.energy_residual(identifier, natoms, weight, prediction, reference, data)

A residual function using just the energy.

See the documentation of energy_forces_residual() for the meaning of the arguments.

kliff.legacy.loss.forces_residual(identifier, natoms, weight, prediction, reference, data)

A residual function using just the forces.

See the documentation of energy_forces_residual() for the meaning of the arguments.

class kliff.legacy.loss.Loss(calculator, nprocs: int = 1, residual_fn: Callable | None = None, residual_data: Dict[str, Any] | None = None, log_per_atom_pred: bool | None = False, log_per_atom_pred_path: str | None = None)

Loss function class to optimize the potential parameters.

This is a wrapper over LossPhysicsMotivatedModel and LossNeuralNetworkModel to provide a united interface. You can use the two classes directly.

Parameters:

• calculator – Calculator to compute prediction from atomic configuration using a potential model.

• nprocs – Number of processes to use..

• residual_fn – function to compute residual, e.g. energy_forces_residual(), energy_residual(), and forces_residual(). See the documentation of energy_forces_residual() for the signature of the function. Default to energy_forces_residual().

• residual_data –

  data passed to residual_fn; can be used to fine tune the residual function. Default to {

  ”normalize_by_natoms”: True,

  } See the documentation of energy_forces_residual() for more.

• log_per_atom_pred – whether to log the prediction per atom.

• log_per_atom_pred_path – path to save the per atom prediction. If not None, the per atom prediction will be saved to this path. The file name is <log_per_atom_pred_path>/per_atom_pred_database.lmdb.

class kliff.legacy.loss.LossPhysicsMotivatedModel(calculator, nprocs=1, residual_fn=None, residual_data=None)

Loss function class to optimize the physics-based potential parameters.

Parameters:

• calculator (Calculator) – Calculator to compute prediction from atomic configuration using a potential model.

• nprocs (int) – Number of processes to use..

• residual_fn (Optional[Callable]) – function to compute residual, e.g. energy_forces_residual(), energy_residual(), and forces_residual(). See the documentation of energy_forces_residual() for the signature of the function. Default to energy_forces_residual().

• residual_data (Optional[Dict[str, Any]]) –

  data passed to residual_fn; can be used to fine tune the residual function. Default to {

  ”normalize_by_natoms”: True,

  } See the documentation of energy_forces_residual() for more.

scipy_minimize_methods = ['Nelder-Mead', 'Powell', 'CG', 'BFGS', 'Newton-CG', 'L-BFGS-B', 'TNC', 'COBYLA', 'SLSQP', 'trust-constr', 'dogleg', 'trust-ncg', 'trust-exact', 'trust-krylov']

scipy_minimize_methods_not_supported_args = ['bounds']

scipy_least_squares_methods = ['trf', 'dogbox', 'lm', 'geodesiclm']

scipy_least_squares_methods_not_supported_args = ['bounds']

minimize(method='L-BFGS-B', **kwargs)

Minimize the loss.

Parameters:

• method (str) – minimization methods as specified at: https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.least_squares.html

• kwargs – extra keyword arguments that can be used by the scipy optimizer

class kliff.legacy.loss.LossNeuralNetworkModel(calculator, nprocs=1, residual_fn=None, residual_data=None, log_per_atom_pred=False, log_per_atom_pred_path=None)

Loss function class to optimize the ML potential parameters.

This is a wrapper over LossPhysicsMotivatedModel and LossNeuralNetworkModel to provide a united interface. You can use the two classes directly.

Parameters:

• calculator – Calculator to compute prediction from atomic configuration using a potential model.

• nprocs (int) – Number of processes to use..

• residual_fn (Optional[Callable]) – function to compute residual, e.g. energy_forces_residual(), energy_residual(), and forces_residual(). See the documentation of energy_forces_residual() for the signature of the function. Default to energy_forces_residual().

• residual_data (Optional[Dict[str, Any]]) –

  data passed to residual_fn; can be used to fine tune the residual function. Default to {

  ”normalize_by_natoms”: True,

  } See the documentation of energy_forces_residual() for more.

• log_per_atom_pred (bool) – whether to log the prediction per atom (only forces supported currently.)

• log_per_atom_pred_path (Optional[str]) – path to save the per atom prediction. If not None, the per atom prediction will be saved to this path. The file name is <log_per_atom_pred_path>/per_atom_pred_database.lmdb. You can control the LMDB memory mapping by setting the environment variable KLIFF_LMDB_MAP_SIZE.

torch_minimize_methods = ['Adadelta', 'Adagrad', 'Adam', 'SparseAdam', 'Adamax', 'ASGD', 'LBFGS', 'RMSprop', 'Rprop', 'SGD']

minimize(method='Adam', batch_size=100, num_epochs=1000, start_epoch=0, **kwargs)

Minimize the loss.

Parameters:

• method (str) – PyTorch optimization methods, and available ones are: [Adadelta, Adagrad, Adam, SparseAdam, Adamax, ASGD, LBFGS, RMSprop, Rprop, SGD] See also: https://pytorch.org/docs/stable/optim.html

• batch_size (int) – Number of configurations used in each minimization step.

• num_epochs (int) – Number of epochs to carry out the minimization.

• start_epoch (int) – The starting epoch number. This is typically 0, but if continuing a training, it is useful to set this to the last epoch number of the previous training.

• kwargs – Extra keyword arguments that can be used by the PyTorch optimizer.

save_optimizer_state(path='optimizer_state.pkl')

Save the state dict of optimizer to disk.

load_optimizer_state(path='optimizer_state.pkl')

Load the state dict of optimizer from file.

exception kliff.legacy.loss.LossError(msg)