ConfigurationSet

class mlptrain.configurations.configuration_set.ConfigurationSet(*args: Configuration | str, allow_duplicates: bool = False)

Bases: list

A set of configurations

__add__(other: Configuration | ConfigurationSet) → ConfigurationSet

Add another configuration or set of configurations onto this one

__init__(*args: Configuration | str, allow_duplicates: bool = False)

Construct a configuration set from Configurations, or a saved file. This is a set, thus no duplicates configurations are present.

Parameters:

• args (Configuration, str) – Either strings of existing files (e.g. data.npz) or individual configurations.

• allow_duplicates (bool) – Should duplicate configurations be supported? For a training configuration set this should be false

append(value: Configuration | None) → None

Append an item onto these set of configurations. None will not be appended

Parameters:

value (Configuration) – Structure in a form of Configuration

property bias_energies: List[float | None]

Bias energies from ASE and PLUMED biases

compare(*args: MLPotential | str) → None

Compare methods e.g. a MLP to a ground truth reference method over these set of configurations. Will generate plots of total energies over these configurations and save a text file with ∆s

Parameters:

*args (mlptrain.potentials.MLPotential) – Strings defining the method or MLPs

classmethod from_orca_files(file_paths: list[str], *, load_energies: bool = True, load_forces: bool = True) → ConfigurationSet

Create ConfigurationSet from existing ORCA calculation output files.

file_paths: (list[str]) List of orca output file paths.

load_energies: (bool) If True, load energies from the files.

load_forces: (bool) If True, load forces from the files.

classmethod from_xyz(filename: str, *, charge: int, mult: int, box: Box | None = None, load_energies: bool = False, load_forces: bool = False) → ConfigurationSet

property has_a_none_energy: bool

Does this set of configurations have a true energy that is undefined (i.e. thus is set to None)?

Return type:

(bool)

property inherited_bias_energies: List[float | None]

If active learning is performed using inheritable metadynamics bias, at any given active learning iteration this property is equal to the value of metadynamics bias inherited from the previous active learning iteration

load(filename: str) → None

Load energies and forces from a saved numpy compressed array (.npz).

Parameters:

filename (str) – File name with .npz

Raises:

(ValueError) – If an unsupported file extension is present

load_xyz(filename: str, charge: int, mult: int, box: Box | None = None, load_energies: bool = False, load_forces: bool = False) → None

Load configurations from a .xyz file with optional box, energies and forces if specified. Note: this currently assumes that all configurations have the same charge and multiplicity.

Parameters:

• filename (str) – name of the input .xyz file

• charge (int) – total charge on all configurations in the set

• mult (int) – total spin multiplicity on all configurations in the set

• box (Box) – optionally specify a Box or None, if the configurations are in vacuum (or if ‘Lattice’ is specified in extended .xyz)

• load_energies (bool) – whether to load ‘true’ configurational energies or not

• load_forces (bool) – whether to load ‘true’ forces from atom lines or not

property lowest_biased_energy: Configuration

Determine the configuration with the lowest biased energy (true energy + bias energy) in this set. If not evaluated then returns the first configuration

Return type:

(mlptrain.Configuration)

property lowest_energy: Configuration

Determine the lowest energy configuration in this set based on the true energies. If not evaluated then returns the first configuration

Return type:

(mlptrain.Configuration)

property lowest_inherited_biased_energy: Configuration

Determine the configuration with the lowest inherited biased energy (true energy + inherited bias energy) in this set. If not evaluated then returns the first configuration

Return type:

(mlptrain.Configuration)

property plumed_coordinates: ndarray | None

PLUMED collective variable values in this set

Returns:

PLUMED collective variable matrix (n, n_cvs),

where n is len(self)

Return type:

(np.ndarray)

property predicted_energies: List[float | None]

Predicted energies using a MLP

property predicted_forces: ndarray | None

Predicted force tensor. shape = (N, n_atoms, 3)

Returns:

(np.ndarray | None)

remove_above_e(energy: float) → None

Remove all configuration above a particular relative energy

Parameters:

energy (float) – Relative energy (eV) above which to discard configurations

remove_none_energy() → None

Remove configurations in this set with no true energy

save(filename: str) → None

Save all the parameters for this configuration. Overrides any current data in that file

Parameters:

filename (str) – Filename with .xyz or .npz, if extension is not provided, it will be saved as .npz

save_xyz(filename: str, true: bool = False, predicted: bool = False) → None

Save these configurations to a file

Parameters:

• filename (str) – File in with .xyz

• true (bool) – Save ‘true’ energies and forces, if they exist

• predicted (bool) – Save the MLP predicted energies and forces, if they exist.

single_point(method: str, n_cores_pp: int = 0) → None

Evaluate energies and forces on all configuration in this set

Parameters:

• method (str) – Electronic structure method used for calculations

• n_cores_pp (int) – Number of CPU per computation, if int=0, n_cores will be assigned automatically as follows: if the number of structures is larger than number of CPUs available, computations will be submitted on 1 CPU until all available CPUs are occupied. If number of CPUs is larger than number of structures, CPUs per process will be assigned as number of CPUs devided by the number of structures, rounded down to the nearest integer.

t_min(from_idx: int) → float

Determine the minimum time for a slice (portion) of these configurations, if a time is not specified for a frame then assume it was generated at ‘zero’ time

Parameters:

from_idx (int) – Index from which to consider the minimum time

Returns:

Time in fs

Return type:

(float)

property true_energies: List[float | None]

True calculated energies

property true_forces: ndarray | None

(n_atoms, 3)

Returns:

(np.ndarray | None)

Type:

List of true config forces. List of np.ndarray with shape