kliff.uq.bootstrap

class kliff.uq.bootstrap.Bootstrap(loss: Loss, seed: int | None = 1717, *args, **kwargs)

Bootstrap sampler class for uncertainty quantification.

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

Parameters:

• loss – Loss function class instance from Loss.

• seed – Random number generator seed.

• args – Additional positional and keyword arguments for instantiating BootstrapEmpiricalModel or BootstrapNeuralNetworkModel.

• kwargs – Additional positional and keyword arguments for instantiating BootstrapEmpiricalModel or BootstrapNeuralNetworkModel.

kliff.uq.bootstrap.bootstrap_cas_generator_empirical(nsamples, orig_cas, ncas=None, rstate=None)

Default class to generate bootstrap compute arguments for empirical, physics-based model.

The compute arguments from all calculators will be combined, then the bootstrap sample configurations will be generated from the combined list. Afterwards, the configurations will be split into their respective calculators.

Parameters:

• nsamples (int) – Number of the bootstrap compute arguments requested.

• orig_cas (List) –

  The original list of compute arguments. The bootstrap compute arguments will be generated from this list. The format of this input is given below:

  orig_cas = [
      [calc0_ca0, calc0_ca1, ...],
      [calc1_ca0, calc1_ca1, ...],
      ...
  ]
  

• ncas (Optional[int]) – Number of compute arguments to have in each sample. If not specified, the function will generate the same number of compute arguments sample as the number of the original compute argument list.

• rstate (Optional[RandomState]) – The state of random number generator.

Return type:

dict

Returns:

A set of bootstrap compute arguments, written in a dictionary format, where the keys index the bootstrap samples compute arguments:

bootstrap_configs = {
    0: [[calc0_cas], [calc1_cas]],
    1: [[calc0_cas], [calc1_cas]]
}

kliff.uq.bootstrap.get_identifiers_from_compute_arguments(compute_arguments)

Retrieve the identifiers from a list of compute arguments.

Parameters:

compute_arguments (List) – A list of ComputeArguments.

Return type:

List[List[str]]

Returns:

A list of compute arguments’ identifiers, which shows the paths to the xyz files.

kliff.uq.bootstrap.default_callback(*args)

Default callback function that does nothing.

class kliff.uq.bootstrap.BootstrapEmpiricalModel(loss, seed=1717)

Bootstrap sampler class for empirical, physics-based potentials.

Parameters:

• loss (Loss) – Loss function class instance from Loss.

• seed (Optional[int]) – Random number generator seed.

generate_bootstrap_compute_arguments(nsamples, bootstrap_cas_generator_fn=None, **kwargs)

Generate bootstrap compute arguments samples.

If this function is called multiple, say, K times, then it will in total generate: math: K imes nsamples bootstrap compute arguments samples. That is, consecutive call of this function will append the generated compute arguments samples.

Parameters:

• nsamples (int) – Number of bootstrap samples to generate.

• bootstrap_cas_generator_fn (Optional[Callable]) – A function to generate bootstrap compute argument samples. The default function combine the compute arguments across all calculators and do sampling with replacement from the combined list. Another possible convention is to do sampling with replacement on the compute arguments list of each calculator separately, in which case a custom function needs to be defined and used. The required argument for the custom generator functions is the requested number of samples.

• kwargs – Additional keyword arguments to bootstrap_cas_generator_fn.

save_bootstrap_compute_arguments(filename)

Export the generated bootstrap compute arguments as a json file.

The json file will contain the identifier of the compute arguments for each sample.

Parameters:

filename (Union[Path, str]) – Where to export the bootstrap compute arguments samples

load_bootstrap_compute_arguments(filename)

Load the bootstrap compute arguments from a json file.

If a list of bootstrap compute arguments samples exists prior to this function call, then the samples read from this file will be appended to the old list.

Parameters:

filename (Union[Path, str]) – Name or path of json file to read.

Return type:

dict

Returns:

Dictionary read from the json file.

run(min_kwargs=None, initial_guess=None, residual_fn_list=None, callback=None)

Iterate over the generated bootstrap compute arguments samples and train the potential using each compute arguments sample.

Parameters:

• min_kwargs (Optional[dict]) – Keyword arguments for minimize().

• initial_guess (Optional[ndarray]) – (ndim,) Initial guess of parameters to use for the minimization. It is recommended to use the same values as used in the training process if such step is done prior to running bootstrap.

• residual_fn_list (Optional[List]) – List of residual function to use in each calculator. Currently, this only affect the case when multiple calculators are used. If there is only a single calculator, don’t worry about this argument.

• callback (Optional[Callable]) – Called after each iteration. The arguments for this function are the bootstrap instance and and output of minimize(). This function can also be used to break the run, by returning boolean True.

Return type:

ndarray

Returns:

(nsamples, ndim,) Parameter samples from bootstrapping.

Raises:

• BootstrapError – If there is no bootstrap compute areguments generated prior to calling this method.

• ValueError – If the calculators use neither the energy nor forces.

restore_loss()

Restore the loss function: revert back the compute arguments and the parameters to the original state.

kliff.uq.bootstrap.bootstrap_cas_generator_neuralnetwork(nsamples, orig_fingerprints, nfingerprints=None, rstate=None)

Default class to generate bootstrap compute arguments (fingerprints) for neural network model.

When models for separate species are used, we assume that the compute arguments used for those models are the same. This assumption is valid since usually the atomic configurations contain multiple atom species, which are the same as the species used for those models.

Parameters:

• nsamples (int) – Number of the bootstrap compute arguments requested.

• orig_fingerprints (List) –

  The original list of compute arguments(fingerprints). The bootstrap compute arguments will be generated from this list. The format of this input is given below: :

  orig_fingerprints = [ca0, ca1, …]

• nfingerprints (Optional[int]) – Number of compute arguments to have in each sample. If not specified, the function will generate the same number of compute arguments sample as the number of the original compute argument list.

• rstate (Optional[RandomState]) – The state of random number generator

Return type:

dict

Returns:

A set of bootstrap compute arguments(fingerprints), written in a dictionary format, where the keys index the bootstrap samples compute arguments:

bootstrap_configs = {
    0: [ca0, ca1, ...],
    1: [ca0, ca1, ...],
}

kliff.uq.bootstrap.get_identifiers_from_fingerprints(fingerprints)

Retrieve the identifiers of a list of fingerprints.

Parameters:

fingerprints (List) – A list of fingerprints.

Return type:

List[str]

Returns:

A list of fingerprints’ identifiers, which shows the paths to the xyz files.

class kliff.uq.bootstrap.BootstrapNeuralNetworkModel(loss, seed=1717, orig_state_filename='orig_model.pkl')

Bootstrap sampler class for neural network potentials.

Parameters:

• loss (Loss) – Loss function class instance from Loss.

• seed (Optional[int]) – Random number generator seed.

• orig_state_filename (Union[str, Path, None]) – Name of the file in which the initial state of the model prior to bootstrapping will be stored. This is to use at the end of the bootstrap run to reset the model to the initial state.

generate_bootstrap_compute_arguments(nsamples, bootstrap_cas_generator_fn=None, **kwargs)

Generate bootstrap compute arguments samples.

If this function is called multiple, say, K times, then it will in total generate: math: K imes nsamples bootstrap compute arguments samples. That is, consecutive call of this function will append the generated compute arguments samples.

Parameters:

• nsamples (int) – Number of bootstrap samples to generate.

• bootstrap_cas_generator_fn (Optional[Callable]) – A function to generate bootstrap compute argument samples. The default function combine the compute arguments across all calculators and do sampling with replacement from the combined list. Another possible convention is to do sampling with replacement on the compute arguments list of each calculator separately, in which case a custom function needs to be defined and used.

• kwargs – Additional keyword arguments to bootstrap_cas_generator_fn.

save_bootstrap_compute_arguments(filename)

Export the generated bootstrap compute arguments as a json file.

The json file will contain the identifier of the compute arguments for each sample.

Parameters:

filename (Union[Path, str]) – Where to export the bootstrap compute arguments samples

load_bootstrap_compute_arguments(filename)

Load the bootstrap compute arguments from a json file.

If a list of bootstrap compute arguments samples exists prior to this function call, then the samples read from this file will be appended to the old list.

Parameters:

filename (Union[Path, str]) – Name or path of json file to read.

Return type:

dict

Returns:

Dictionary read from the json file.

run(min_kwargs=None, callback=None)

Iterate over the generated bootstrap compute arguments samples and train the potential using each compute arguments sample.

Parameters:

• min_kwargs (Optional[dict]) – Keyword arguments for minimize().

• callback (Optional[Callable]) – Called after each iteration. The arguments for this function are the bootstrap instance and and output of minimize(). This function can also be used to break the run, by returning boolean True.

Return type:

ndarray

Returns:

(nsamples, ndim,) Parameter samples from bootstrapping.

Raises:

BootstrapError – If there is no bootstrap compute areguments generated prior to calling this method.

restore_loss()

Restore the loss function: revert back the compute arguments and the parameters to the original state.

exception kliff.uq.bootstrap.BootstrapError(msg)