Configuration

class mlptrain.configurations.configuration.Configuration(atoms: Atoms | List[Atom] | None = None, charge: int = 0, mult: int = 1, box: Box | None = None)

Bases: AtomCollection

Configuration of atoms

__eq__(other) → bool: Another configuration is identical to this one

__init__(atoms: Atoms | List[Atom] | None = None, charge: int = 0, mult: int = 1, box: Box | None = None)

Set of atoms perhaps in a periodic box with an overall charge and spin multiplicity.

May contain a list with the indices of each first atom of a molecule, if there are several. When adding several different molecules to a configuration, one can add the starting index of each molecule to this list. e.g. a list of three waters would be [0, 3, 6]. This list gets updated when the solvate function is called.

Parameters:

mult
box – Optional box, if None
mol_dict – Dict[int] = None

property ase_atoms: Atoms: ASE atoms for this configuration, absent of energy and force properties.

copy() → Configuration

classmethod from_orca_file(file_path: str, *, load_energy: bool = True, load_forces: bool = True) → Configuration

Return Configuration from existing ORCA calculation output files.

file_path: (str) Path to orca output file.

load_energy: (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 = 0, mult: int = 1) → Configuration

Create a Configuration from an xyz file and automatically load mol_dict if available.

Parameters:

filename – Path to xyz file
charge – Overall charge
mult – Spin multiplicity

Returns:

New configuration with mol_dict loaded if available

Return type:

Configuration

k_d_tree_insertion(solvent_molecule: Molecule, box_size: float, contact_threshold: float, n_solvent: int, random_seed: int) → ndarray

Insert solvent molecules into the box using a k-d tree to check for collisions. Implemented according to the algorithm described in the paper:

“https://chemrxiv.org/engage/chemrxiv/article-details/678621ccfa469535b9ea8786”

This implementation includes periodic boundary condition handling by creating periodic images of atoms near box boundaries.

Arguments:

solvent_molecule: autode.Molecule: The molecule representing the solvent to be inserted.
box_size: float: The size of the box in Å. A cubic box is assumed, and boxes where the three box vectors are not equal are not supported.
contact_threshold: float: The distance in Å below which two atoms are considered to be in contact.
n_solvent: int: The number of solvent molecules to be inserted.

load_from_xyz(filename: str) → None

Load atoms from an xyz file into this configuration, replacing existing atoms.

Parameters:: filename – Path to xyz file

load_mol_dict(filename: str) → bool

Load mol_dict from a hidden .mol_dict.txt file if it exists and assign to self.

Parameters:: filename – The xyz filename to check for an associated mol_dict file
Returns:: True if mol_dict was loaded, False if file doesn’t exist
Return type:: bool

save_mol_dict(filename: str) → None

Save the mol_dict to a hidden .mol_dict.txt file alongside the xyz file.

Parameters:: filename – The xyz filename (mol_dict will be saved as .filename.mol_dict.txt)

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

Print this configuration as an extended xyz file where the first 4 columns are the atom symbol, x, y, z and, if this configuration contains forces then add the x, y, z components of the force on as columns 4-7.

Parameters:

true – Save the true energy and forces
predicted – Save the predicted energy and forces

single_point(method: str | MLPotential, n_cores: int = 1) → None: Run a single point energy and gradient (force) evaluation using either a reference method defined by a string (e.g. ‘orca’) or a machine learned potential (with a .predict) method.

solvate(box_size: float | None = None, buffer_distance: float = 10.0, solvent_name: str | None = None, solvent_density: float | None = None, solvent_molecule: Molecule | None = None, contact_threshold: float = 1.8, random_seed: int = 42) → None

Solvate the configuration of a solute using solvent molecules. Currently solvent mixtures are not supported. The box size can be specified manually in Å or it can be calculated automatically by adding a buffer distance (in Å) to the maximum distance between any two atoms in the solute.

The solvent can be specified either by name, if it is already contained in the solvent database. With this option, the solvent will be optimised by XTB and the density will be extracted from the database.

Another option is to providing an autode Molecule object of a pre-optimised solvent molecule of your choosing, in which case the density of the solvent (in g/cm^3) must also be provided. This can also serve to provide non-standard solvents and densities.

The contact threshold is the distance in Å below which two atoms are considered to be in contact, when placing the solvents in the box.

Arguments:

box_size: float = None: The size of the box in Å. If None, the box size will be calculated automatically. This is done by calculating the maximum distance between any two atoms in the solute and adding a buffer distance, which is specified by the buffer_distance argument.
buffer_distance: float = 10: The distance in Å to be added to the maximum distance between any two atoms in the solute, to calculate the box size. This argument is only used if the box_size is not provided.
solvent_name: str = None: The name of the solvent contained in the solvent database.
solvent_molecule: autode.Molecule = None: The autode Molecule object representing the solvent, if provided explicitly by the user.
solvent_density: float = None: The density, in g/cm^3 which must be provided along with the solvent molecule.
contact_threshold: float = 1.8: The distance in Å below which two atoms are considered to be in contact.
random_seed: int = 42: The seed number used to generate random vectors for the rotation and translation of the solvent molecules. This is to avoid the same solvent molecule being inserted multiple times in the same orientation.

update_attr_from(configuration: Configuration) → None: Update system attributes from a configuration

validate_mol_dict() → bool

Validate that the mol_dict indices are consistent with the current atoms.

Returns:: True if mol_dict is valid, False otherwise
Return type:: bool

mlptrain.configurations.configuration.optimise_solvent(solvent: Molecule) → Molecule: Optimise a solvent molecule with XTB