matscipy.calculators.committee.committee

Classes

`Committee`([members])	Instances of this class represent a committee of models.
`CommitteeMember`(calculator[, training_data])	Lightweight class defining a member (i.e. a sub-model) of a committee model.
`CommitteeUncertainty`(committee[, atoms])	Calculator for a committee of machine learned interatomic potentials (MLIP).

class matscipy.calculators.committee.committee.CommitteeUncertainty(committee, atoms=None)

Bases: Calculator

Calculator for a committee of machine learned interatomic potentials (MLIP).

The class assumes individual members of the committee already exist (i.e. their training is performed externally). Instances of this class are initialized with these committee members and results (energy, forces) are calculated as average over these members. In addition to these values, also the uncertainty (standard deviation) is calculated.

The idea for this Calculator class is based on the following publication: Musil et al., J. Chem. Theory Comput. 15, 906−915 (2019) https://pubs.acs.org/doi/full/10.1021/acs.jctc.8b00959

Attributes:

directory
label
name

Methods

`band_structure`()	Create band-structure object for plotting.
`calculate`([atoms, properties, system_changes])	Calculates committee (mean) values and variances.
`calculate_numerical_forces`(atoms[, d])	Calculate numerical forces using finite difference.
`calculate_numerical_stress`(atoms[, d, voigt])	Calculate numerical stress using finite difference.
`calculate_properties`(atoms, properties)	This method is experimental; currently for internal use.
`check_state`(atoms[, tol])	Check for any system changes since last calculation.
`get_magnetic_moments`([atoms])	Calculate magnetic moments projected onto atoms.
`get_property`(name[, atoms, allow_calculation])	Get the named property.
`get_stresses`([atoms])	the calculator should return intensive stresses, i.e., such that stresses.sum(axis=0) == stress
`read`(label)	Read atoms, parameters and calculated properties from output file.
`reset`()	Clear all information from old calculation.
`set`(**kwargs)	Set parameters like set(key1=value1, key2=value2, ...).
`set_label`(label)	Set label and convert label to directory and prefix.

calculation_required
export_properties
get_atoms
get_charges
get_default_parameters
get_dipole_moment
get_forces
get_magnetic_moment
get_potential_energies
get_potential_energy
get_stress
read_atoms
todict

__init__(committee, atoms=None)

Basic calculator implementation.

restart: str: Prefix for restart file. May contain a directory. Default is None: don’t restart.
ignore_bad_restart_file: bool: Deprecated, please do not use. Passing more than one positional argument to Calculator() is deprecated and will stop working in the future. Ignore broken or missing restart file. By default, it is an error if the restart file is missing or broken.
directory: str or PurePath: Working directory in which to read and write files and perform calculations.
label: str: Name used for all files. Not supported by all calculators. May contain a directory, but please use the directory parameter for that instead.
atoms: Atoms object: Optional Atoms object to which the calculator will be attached. When restarting, atoms will get its positions and unit-cell updated from file.

implemented_properties: List[str] = []: Properties calculator can handle (energy, forces, …)

calculate(atoms=None, properties=['energy', 'forces', 'stress'], system_changes=['positions', 'numbers', 'cell', 'pbc', 'initial_charges', 'initial_magmoms']): Calculates committee (mean) values and variances.

band_structure(): Create band-structure object for plotting.

calculate_numerical_forces(atoms, d=0.001)

Calculate numerical forces using finite difference.

All atoms will be displaced by +d and -d in all directions.

calculate_numerical_stress(atoms, d=1e-06, voigt=True): Calculate numerical stress using finite difference.

calculate_properties(atoms, properties): This method is experimental; currently for internal use.

calculation_required(atoms, properties)

check_state(atoms, tol=1e-15): Check for any system changes since last calculation.

default_parameters: Dict[str, Any] = {}: Default parameters

property directory: str

discard_results_on_any_change = False: Whether we purge the results following any change in the set() method.

export_properties()

get_atoms()

get_charges(atoms=None)

get_default_parameters()

get_dipole_moment(atoms=None)

get_forces(atoms=None)

get_magnetic_moment(atoms=None)

get_magnetic_moments(atoms=None): Calculate magnetic moments projected onto atoms.

get_potential_energies(atoms=None)

get_potential_energy(atoms=None, force_consistent=False)

get_property(name, atoms=None, allow_calculation=True): Get the named property.

get_stress(atoms=None)

get_stresses(atoms=None): the calculator should return intensive stresses, i.e., such that stresses.sum(axis=0) == stress

ignored_changes: Set[str] = {}: Properties of Atoms which we ignore for the purposes of cache

property label

property name: str

read(label)

Read atoms, parameters and calculated properties from output file.

Read result from self.label file. Raise ReadError if the file is not there. If the file is corrupted or contains an error message from the calculation, a ReadError should also be raised. In case of succes, these attributes must set:

atoms: Atoms object: The state of the atoms from last calculation.
parameters: Parameters object: The parameter dictionary.
results: dict: Calculated properties like energy and forces.

The FileIOCalculator.read() method will typically read atoms and parameters and get the results dict by calling the read_results() method.

classmethod read_atoms(restart, **kwargs)

reset(): Clear all information from old calculation.

set(**kwargs)

Set parameters like set(key1=value1, key2=value2, …).

A dictionary containing the parameters that have been changed is returned.

Subclasses must implement a set() method that will look at the chaneged parameters and decide if a call to reset() is needed. If the changed parameters are harmless, like a change in verbosity, then there is no need to call reset().

The special keyword ‘parameters’ can be used to read parameters from a file.

set_label(label)

Set label and convert label to directory and prefix.

Examples:

label=’abc’: (directory=’.’, prefix=’abc’)
label=’dir1/abc’: (directory=’dir1’, prefix=’abc’)
label=None: (directory=’.’, prefix=None)

todict(skip_default=True)

class matscipy.calculators.committee.committee.Committee(members=None)

Bases: object

Instances of this class represent a committee of models.

It’s use is to store the ```CommitteeMember```s representing the committee model and to calibrate the obtained uncertainties (required when sub-sampling is used to create the training data of the committee members).

Attributes:

alphas: (Linear) scaling factors for committee uncertainties.
atoms: Combined Atoms/samples in the committee.
calibrated_for: Set of properties the committee has been calibrated for.
id_counter: Counter-object for identifier appearances in the committee.
id_to_atoms: Dictionary to translate identifiers to Atoms-objects.
ids: Identifiers of atoms/samples in the committee.
members: List with committee members.
number: Number of committee members.
validation_set: List of Atoms-objects.

Methods

`add_member`(member)	Extend committee by new `member` (i.e. `CommitteeMember`-instance).
`calibrate`(prop, key, location[, system_changes])	Obtain parameters to properly scale committee uncertainties and make them available as an attribute (`alphas`) with another associated attribute (`calibrated_for`) providing information about the property for which the uncertainty will be scaled by it.
`is_calibrated_for`(prop)	Check whether committee has been calibrated for `prop`.
`scale_uncertainty`(value, prop)	Scale uncertainty `value` obtained with the committee according to the calibration for the corresponding property (`prop`).
`set_internal_validation_set`(appearance_threshold)	Define a validation set based on the Atoms-objects of sub-sampled committee training sets.

__init__(members=None)

property members: List with committee members.

property number: Number of committee members.

property atoms: Combined Atoms/samples in the committee.

property ids: Identifiers of atoms/samples in the committee.

property id_to_atoms: Dictionary to translate identifiers to Atoms-objects.

property id_counter: Counter-object for identifier appearances in the committee.

property alphas: (Linear) scaling factors for committee uncertainties.

property calibrated_for: Set of properties the committee has been calibrated for.

property validation_set: List of Atoms-objects.

add_member(member): Extend committee by new `member` (i.e. `CommitteeMember`-instance).

set_internal_validation_set(appearance_threshold): Define a validation set based on the Atoms-objects of sub-sampled committee training sets.

calibrate(prop, key, location, system_changes=['positions', 'numbers', 'cell', 'pbc', 'initial_charges', 'initial_magmoms']): Obtain parameters to properly scale committee uncertainties and make them available as an attribute (`alphas`) with another associated attribute (`calibrated_for`) providing information about the property for which the uncertainty will be scaled by it.

is_calibrated_for(prop): Check whether committee has been calibrated for `prop`.

scale_uncertainty(value, prop): Scale uncertainty `value` obtained with the committee according to the calibration for the corresponding property (`prop`).

class matscipy.calculators.committee.committee.CommitteeMember(calculator, training_data=None)

Bases: object

Lightweight class defining a member (i.e. a sub-model) of a committee model.

Attributes:

atoms: Atoms/samples in the committee member.
calculator: Model of the committee member.
filename: Path to the atoms/samples in the committee member.
ids: Identifiers of atoms/samples in the committee member.

Methods

`is_sample_in_atoms`(sample)	Check if passed Atoms-object is part of this committee member (by comparing identifiers).
`set_training_data`(training_data)	Read in and store the training data of this committee members from the passed `filename`.

__init__(calculator, training_data=None)

property calculator: Model of the committee member.

property filename: Path to the atoms/samples in the committee member.

property atoms: Atoms/samples in the committee member.

property ids: Identifiers of atoms/samples in the committee member.

set_training_data(training_data): Read in and store the training data of this committee members from the passed `filename`.

is_sample_in_atoms(sample): Check if passed Atoms-object is part of this committee member (by comparing identifiers).