ichor.core.atoms package

Submodules

ichor.core.atoms.alf module

Atomic Local Frame used for one atom. Atomic local frame consists of central atom index, x-axis atom index, xy-plane atom index. These indices are 0-indexed. The xy-plane atom might not exist if there are only 2 atoms, so default for it is None.

class ALF(origin_idx, x_axis_idx, xy_plane_idx)

Bases: tuple

origin_idx

Alias for field number 0

x_axis_idx

Alias for field number 1

xy_plane_idx

Alias for field number 2

ichor.core.atoms.atom module

class Atom(ty: str, x: float, y: float, z: float, index: int | None = None, parent: ichor.core.atoms.Atoms | None = None, units: AtomicDistance = AtomicDistance.Angstroms)

Bases: VarReprMixin, Coordinates3D

The Atom class is used for ONE atom in ONE timestep.

e.g. If we have 1000 timesteps in the trajectory, with 6 atoms in each timestep, the we will have 6000 Atom instances in total.

C(alf: ALF) → ndarray

Mills, M.J.L., Popelier, P.L.A., 2014. Electrostatic Forces: Formulas for the First Derivatives of a Polarizable, Anisotropic Electrostatic Potential Energy Function Based on Machine Learning. Journal of Chemical Theory and Computation 10, 3840-3856.. doi:10.1021/ct500565g

Eq. 25-30

Parameters:

alf – An atomic local frame (ALF instance) which is then used to calculate the C matrix for a given ALF.

Returns:

A 3x3 rotation matrix (C matrix) which rotates from Global cartesian to local frame where the origin (0,0,0) is the current atom, the x-axis is the x-axis atom, the xy-plane is defined by the xy-plane atom, and the z-axis is orthogonal to the xy-plane.

alf(alf_calculator: Callable[[...], ALF], *args, **kwargs) → ALF

Returns an instance of ALF. This ALF is ONLY for this Atom.

e.g. If we have an Atoms instance for the water monomer, the ALF for the whole water monomer can be written as [[0,1,2], [1,0,2], [2,0,1]], while the ALF for the first atom only is [0,1,2]

[0,1,2] contains the indices for the central atom, x-axis atom, and xy-plane atom. These indices start at 0 to index Python objects correctly.

Parameters:

alf_calculator – function which calculates Atomic Local Frame for given atom.

Returns:

An ALF instance which contains the origin atom index (self.i) as well as the x-axis and optionally xy-plane index. For two-atom systems, there is only an x-axis index.

alf_array(alf_calculator: Callable[[...], ndarray], *args, **kwargs) → ndarray

Returns a list containing the index of the central atom, the x-axis atom, and the xy-plane atom. THere indices are what are used in python lists (as they start at 0).

Parameters:

alf_calculator – function which calculates Atomic Local Frame for given atom.

Returns:

A numpy array containing the central atom index (self.i), as well as the x-axis and xy-plane indices.

angle(atom1: Atom, atom2: Atom) → float

Angle subtending atom1-self-atom2 :param atom1: atom bonded to self :param atom2: other atom bonded to self :return: angle subtending atom1-self-atom2 as float

bonded_atoms(connectivity_calculator: Callable[[...], list]) → list

Returns a list of Atom instances to which this Atom instance is connected

Parameters:

connectivity_calculator – function which calculates connectivity for given atom.

Returns:

A list of Atom instances to which this atom is bonded to

bonded_atoms_i(connectivity_calculator: Callable[[...], list]) → list

Returns a list of Atom indices to which this Atom instance is connected

Parameters:

connectivity_calculator – function which calculates connectivity for given atom.

Returns:

A list of atom indices to which this atom is bonded to (these are 0-indexed)

bonded_atoms_names(connectivity_calculator: Callable[[...], list]) → list

Returns a list of the names of Atom instances to which this Atom instance is connected

Parameters:

connectivity_calculator – function which calculates connectivity for given atom.

Returns:

A list of atom names (str) to which this atom is bonded to

connectivity(connectivity_calculator: Callable[[...], ndarray]) → ndarray

Returns the 1D np.array corresponding to the connectivity of ONE Atom with respect to all other Atom instances that are held in an Atoms instance. For an Atom instance, this is only one row of the full connectivity matrix of the Atoms instance that is self.parent. However, to compute the connectivity in the first place, we need access to the Atoms instance (self.parent).

Parameters:

connectivity_calculator – function which calculates connectivity for given atom.

property coordinates_string: str

Returns the coordinate string representation of the atom

Returns:

coordinate string of atom (x, y, z coordinates)

Return type:

str

dist(other: Atom) → float

Calculated the distance between self and other :param other: atom to calculate the distance to :return: the distance between self and other as a float

property electronegativity: float

Returns the electronegativity of the Atom instance

Returns:

The electronegativity of the atom (as defined by the atom type)

Return type:

float

features(feature_calculator: Callable[[...], ndarray], *args, **kwargs) → ndarray

Returns a 1D 3N-6 np.ndarray of the features for the current Atom instance.

Parameters:

  • feature_calculator – A function used to calculate features from the Atom instance

  • args – positional arguments to pass to feature calculator function.

  • kwargs – key word arguments to pass to the feature calculator function. Check the feature calculator to see what required key word arguments the calculator needs to function.

Returns:

The features associated with self.

Note

The current implementation allows us to fairly easily switch between features as we can change the calculator that is being used, as well as pass in new key word arguments to the given calculator.

classmethod from_atom(atom: Atom) → Atom
property i: int

Returns the index of the atom, if used in any arrays/list in Python.

Returns:

the index of the atom (0-indexed)

Return type:

int

property index: int

Returns the integer assigned to the atom, calculated from the trajectory file. Indices start at 1. This number is given to every atom in the trajectory, so atoms of the same type(element) can be distinguished.

property mass: float

Returns the mass of the atom

Returns:

The atomic mass of the atom

Return type:

float

property name: str

Returns the name of the Atom instance, which is later used to distinguish atoms when making GPR models. The number in the name starts at 1 (inclusive). e.g. O1

Returns:

the name of the atom (the type + the index of the atom (the indices start from 1))

Return type:

str

property nuclear_charge: float

Returns the nuclear charge of the atom as a float

Returns:

the nuclear change of the atom

Return type:

float

property parent: ichor.core.atoms.Atoms

Returns the parent instance (an instance of Atoms class) that holds self (an instance of Atom).

Raises:

ValueError – if parent is not defined

Returns:

parent instance of type Atoms

Return type:

ichor.core.atoms.Atoms

property radius

Returns the covalent radius of the given Atom instance.

Returns:

Covalent radius of the Atom instance (as defined by the atom type)

Return type:

float

to_angstroms() → Atom

Convert the coordiantes to Angstroms

to_bohr() → Atom

Convert the coordiantes to Bohr

property valence: int

Returns the valence of the Atom instance

Returns:

the valence of the atom (as defined by the atom type)

Return type:

int

property vdwr

Returns the Van der Waals radius of the given Atom instance.

Returns:

The Van der Waals radius of the atom (as defined by the atom type)

Return type:

float

vec_to(other: Atom) → ndarray

Calculates the vector from self to other :param other: atom to calculate the vector to :return: the vector from self to other as numpy array

property xyz_string: str

Returns the atom type and coordinates for one Atom instance. This is used to write out an xyz file, which expects entries in the form of atom_type x_coordinate, y_coordinate, z_coordinate

Returns:

coordinate string of atom with atom type (atom.type x, y, z)

Return type:

str

ichor.core.atoms.atoms module

class Atoms(atoms: Sequence[Atom] | None = None)

Bases: list

The Atoms class handles ONE timestep in the trajectory. It is mainly used to group together Atom objects that are in the same timestep. However, it is written in a way that any number of Atom instances can be grouped together if the user wants to do so.

e.g. if we have a trajectory of methanol (6 atoms) with 1000 timesteps, we will have 1000 Atoms instances. Each of the Atoms instances will hold 6 instances of the Atom class.

C_matrix_dict(system_alf: List[ALF]) → Dict[str, ndarray]

Returns a dictionary of key (atom name), value (C matrix np array) for every atom

C_matrix_list(system_alf: List[ALF]) → List[ndarray]

Returns a list C matrix np array for every atom

add(atom: Atom)

Add Atom instances for each atom in the timestep to the self._atoms list. Each coordinate line in the trajectory file (for one timestep) is added as a separate Atom instance.

alf(alf_calculator: Callable[[...], ALF], *args, **kwargs) → List[ALF]

Returns the Atomic Local Frame (ALF) for all Atom instances that are held in Atoms e.g. [[0,1,2],[1,0,2], [2,0,1]]

Parameters:

  • args – positional arguments to pass to alf calculator

  • kwargs – key word arguments to pass to alf calculator

alf_dict(alf_calculator: Callable[[...], ALF], *args, **kwargs) → Dict[str, ALF]

Returns a list of lists with the atomic local frame indices for every atom (0-indexed).

Parameters:

  • args – positional arguments to pass to alf calculator

  • kwargs – key word arguments to pass to alf calculator

alf_list(alf_calculator: Callable[[...], ALF], *args, **kwargs) → List[List[int]]

Returns a list of lists with the atomic local frame indices for every atom (0-indexed).

Parameters:

  • args – positional arguments to pass to alf calculator

  • kwargs – key word arguments to pass to alf calculator

append(atom: Atom)

Appends an Atom instance to self.

property atom_names: List[str]

Returns the atom names as a list ([‘O1’, ‘H2’…]).

centre(centre_atom: int | str | List[Atom | str | int] | None = None)

Centers the geometry on some atom. But this is still in GLOBAL Cartesian coordinates.

property centroid: ndarray

Returns the centroid of the system (the mean of the x,y,z coordinates of the atoms).

connectivity(connectivity_calculator: Callable[[...], ndarray]) → ndarray

Return the connectivity matrix (n_atoms x n_atoms) for the given Atoms instance.

Parameters:

connectivity_calculator (Callable[..., np.ndarray]) – connectivity calculator function that calculates connectivity

Returns:

np.ndarray of shape n_atoms x n_atoms

Return type:

np.ndarray

property coordinates: ndarray

Returns an array that contains the coordinates for each Atom instance held in the Atoms instance.

copy() → Atoms

Creates a new atoms instance (different object) from the current Atoms instance.

features(feature_calculator: Callable[[...], ndarray], *args, is_atomic=True, **kwargs) → ndarray

Returns the features for this Atoms instance, corresponding to the features of each Atom instance held in this Atoms isinstance Features are calculated in the Atom class and concatenated to a 2d array here.

The array shape is n_atoms x n_features (3*n_atoms - 6)

Parameters:

  • is_atomic – whether the feature calculator calculates features for individual atoms or for the whole geometry.

  • args – positional arguments to pass to feature calculator

  • kwargs – key word arguments to pass to feature calculator

Returns:

type: np.ndarray of shape n_atoms x n_features (3N-6)

Return the feature matrix of this Atoms instance

features_dict(feature_calculator: Callable[[...], ndarray], *args, is_atomic=True, **kwargs) → dict

Returns the features in a dictionary for this Atoms instance, corresponding to the features of each Atom instance held in this Atoms isinstance Features are calculated in the Atom class and concatenated to a 2d array here.

Parameters:

  • is_atomic – whether the feature calculator calculates features for per atom or for the whole geometry

  • args – positional arguments to pass to feature calculator

  • kwargs – key word arguments to pass to feature calculator

e.g. {“C1”: np.array, “H2”: np.array}

property hash

Returns a hash for the system which is just the atom names joined by a comma.

kabsch(other: Atoms) → ndarray
property masses: List[float]

Returns a list of the masses of the Atom instances held in the Atoms instance.

property names: List[str]

Return a list of atom names that are held in the instance of Atoms.

property natoms: int

Returns the number of atoms in a timestep. Since each timestep has the same number of atoms. This means the number of atoms in the system is returned.

property nuclear_charge_sum: int

Returns the sum of nuclear charges of Atoms instance

rmsd(other: Atoms)
rotate(R: ndarray)

Perform a rotation in 3D space with a matrix R. This rotates all atoms in the system the same amount. This method also changes the coordinates of the Atom instances held in the Atoms instance.

to_angstroms() → Atoms

Convert the x, y, z coordinates of all Atom instances held in an Atoms instance to angstroms

to_bohr() → Atoms

Convert the x, y, z coordinates of all Atom instances held in an Atoms instance to bohr

translate(v: ndarray)

Translates a system in 3D space.

Parameters:

v – numpy array of shape (3,) which is added to the coordinates of each atom.

property types: List[str]

Returns the atom elements for atoms, removes duplicates

property types_extended: list

Returns the atom elements for all atoms, includes duplicates.

property xyz_string

Returns a string containing all atoms and their coordinates stored in the Atoms instance

ichor.core.atoms.atoms_not_found_exception module

exception AtomNotFound

Bases: Exception

exception AtomsNotFoundError

Bases: Exception

ichor.core.atoms.list_of_atoms module

class ListOfAtoms(*args, **kwargs)

Bases: list, ABC

Used to focus only on how one atom moves in a trajectory, so the user can do something like trajectory[‘C1’] where trajectory is an instance of class Trajectory. This way the user can also do trajectory[‘C1’].features, trajectory[‘C1’].coordinates, etc.

abstract alf() → ALF

Returns the atomic local frame for the first timestep.

abstract property atom_names

Return the atom names from the first timestep. Assumes that all timesteps have the same number of atoms/atom names.

center_geometries_on_atom_and_write_xyz(central_atom_name: str, system_alf: Dict[str, ALF], fname: str | Path | None = None)

Centers all geometries (from a Trajectory of PointsDirectory instance) onto a central atom and then writes out a new xyz file with all geometries centered on that atom. This is essentially what the ALFVisualizier application (ALFi) does. The features for the central atom are calculated, after which they are converted back into xyz coordinates. Thus all geometries are now centered on the given central atom).

Parameters:

  • feature_calculator – Function which calculates features

  • central_atom_name – the name of the central atom to center all geometries on. Eg. ‘O1’

  • fname – Optional file name in which to save the rotated geometries.

  • args – Positional arguments to pass to calculator function

  • kwargs – Key word arguments to pass to calculator function

abstract connectivity() → ndarray

Returns the connectivity matrix of the first timestep.

abstract property coordinates: ndarray

Abstract method for coordinates.

Returns:

the xyz coordinates of all atoms for all timesteps. Shape n_timesteps x n_atoms x 3

features(feature_calculator: Callable[[...], ndarray], *args, is_atomic=True, **kwargs) → ndarray

Return the ndarray of features. This is assumed to be either 2D or 3D array. If the dimensionality of the feature array is 3, the array is transposed to transform a (ntimestep, natom, nfeature) array into a (natom, ntimestep, nfeature) array so that all features for a single atom are easier to group.

Parameters:

  • feature_calculator – The calculator function which calculates features

  • is_atomic – Whether the calculator calculates features for individual atoms or the whole geometry

  • args – Positional arguments to pass to feature calculator function

  • kwargs – Key word arguments to pass to feature calculator function

Returns:

If the features for the whole trajectory are returned, the array has shape n_atoms x n_timesteps x n_features If the trajectory instance is indexed by str, the array has shape n_timesteps x n_features. If the trajectory instance is indexed by int, the array has shape n_atoms x n_features. If the trajectory instance is indexed by slice, the array has shape n_atoms x`slice` x n_features. If a non-atomic calculator is passed, a n_timesteps x features (features could be vector, matrix, etc) is returned.

features_to_csv(feature_calculator: Callable[[...], ndarray], *args, fname: str | Path | None = None, atom_names: List[str] | None = None, **kwargs)

Writes csv files containing features for every atom in the system. Optionally a list can be passed in to get csv files for only a subset of atoms.

Parameters:

  • feature_calculator – Calculator function to be used to calculate features

  • fname – A string to be appended to the default csv file names. A .csv file is written out for every atom with default name atom_name_features.csv If an fname is given, the name becomes fname_atom_name_features.csv

  • atom_names – A list of atom names for which to write csv files. If None, then write out the features for every atom in the system.

  • args – positional arguments to pass to calculator function

  • kwargs – key word arguments to be passed to the feature calculator function

features_to_excel(feature_calculator: ALF | Callable, *args, fname: str | Path = PosixPath('features_to_excel.xlsx'), atom_names: List[str] | None = None, **kwargs)

Writes out one excel file which contains a sheet with features for every atom in the system. Optionally a list of atom names can be passed in to only make sheets for certain atoms

Parameters:

  • atom_names – A list of atom names for which to calculate features and write in excel spreadsheet

  • args – positional arguments to pass to calculator function

  • kwargs – key word arguments to be passed to the feature calculator function

  • fname – File name to save features to

get_headings()

Helper function which makes the column headings for csv or excel files in which features are going to be saved.

abstract property natoms

Abstract method for natoms.

Returns:

Returns the number of atoms in the first timestep. Each timestep should have the same number of atoms.

abstract property types: List[str]

Returns the atom elements for atoms, assumes each timesteps has the same atoms. Removes duplicates.

abstract property types_extended: List[str]

Returns the atom elements for atoms, assumes each timesteps has the same atoms. Does not remove duplicates

ichor.core.atoms.list_of_atoms_atom_view module

class AtomView(parent, atom)

Bases: ListOfAtoms

Class used to index a ListOfAtoms instance by an atom name (eg. C1, H2, etc.). This allows a user to get information (such as coordinates or features) for one atom.

Parameters:

  • parent – An instance of a class that subclasses from ListOfAtoms

  • atom – A string representing the name of an atom, e.g. C1, H2, etc.

C(alf: ALF | List[int])

Returns the C matrix for every Atom instance in the ListOfAtomsAtomView.

Thus, the shape is n_timesteps x 3 x 3

alf(alf_calculator: Callable, *args, **kwargs)

Returns the alf calculated from the first Atom object inside the ListOfAtomsAtomView object

property atom_name

Returns the name of the atom, e.g. ‘C1’, ‘H2’, etc.

property atom_names

Returns a list containing the name of the atom (so contains 1 element)

connectivity(connectivity_calculator: Callable)

Returns the alf calculated from the first Atom object inside the ListOfAtomsAtomView object

features(feature_calculator: Callable, *args, **kwargs) → ndarray

Return the ndarray of features for only one atom, given an alf for that atom. This is assumed to a 2D array of features for only one atom.

Parameters:

alf – A list of integers or a numpy array corresponding to the alf of one atom The atom which the atom view is for.

Returns:

The array has shape n_timesteps x n_features.

property natoms

Returns the name of the atom, e.g. ‘C1’, ‘H2’, etc.

property type

Returns the types of atoms in the atom view. Since only one atom type is present, it returns a list with one element

Module contents

Handles a group of atoms (mostly used to group together atoms in the same chemical system). Each Atoms instance could contain multiple Atom instances.

class ALF(origin_idx, x_axis_idx, xy_plane_idx)

Bases: tuple

origin_idx

Alias for field number 0

x_axis_idx

Alias for field number 1

xy_plane_idx

Alias for field number 2

class Atom(ty: str, x: float, y: float, z: float, index: int | None = None, parent: ichor.core.atoms.Atoms | None = None, units: AtomicDistance = AtomicDistance.Angstroms)

Bases: VarReprMixin, Coordinates3D

The Atom class is used for ONE atom in ONE timestep.

e.g. If we have 1000 timesteps in the trajectory, with 6 atoms in each timestep, the we will have 6000 Atom instances in total.

C(alf: ALF) → ndarray

Mills, M.J.L., Popelier, P.L.A., 2014. Electrostatic Forces: Formulas for the First Derivatives of a Polarizable, Anisotropic Electrostatic Potential Energy Function Based on Machine Learning. Journal of Chemical Theory and Computation 10, 3840-3856.. doi:10.1021/ct500565g

Eq. 25-30

Parameters:

alf – An atomic local frame (ALF instance) which is then used to calculate the C matrix for a given ALF.

Returns:

A 3x3 rotation matrix (C matrix) which rotates from Global cartesian to local frame where the origin (0,0,0) is the current atom, the x-axis is the x-axis atom, the xy-plane is defined by the xy-plane atom, and the z-axis is orthogonal to the xy-plane.

alf(alf_calculator: Callable[[...], ALF], *args, **kwargs) → ALF

Returns an instance of ALF. This ALF is ONLY for this Atom.

e.g. If we have an Atoms instance for the water monomer, the ALF for the whole water monomer can be written as [[0,1,2], [1,0,2], [2,0,1]], while the ALF for the first atom only is [0,1,2]

[0,1,2] contains the indices for the central atom, x-axis atom, and xy-plane atom. These indices start at 0 to index Python objects correctly.

Parameters:

alf_calculator – function which calculates Atomic Local Frame for given atom.

Returns:

An ALF instance which contains the origin atom index (self.i) as well as the x-axis and optionally xy-plane index. For two-atom systems, there is only an x-axis index.

alf_array(alf_calculator: Callable[[...], ndarray], *args, **kwargs) → ndarray

Returns a list containing the index of the central atom, the x-axis atom, and the xy-plane atom. THere indices are what are used in python lists (as they start at 0).

Parameters:

alf_calculator – function which calculates Atomic Local Frame for given atom.

Returns:

A numpy array containing the central atom index (self.i), as well as the x-axis and xy-plane indices.

angle(atom1: Atom, atom2: Atom) → float

Angle subtending atom1-self-atom2 :param atom1: atom bonded to self :param atom2: other atom bonded to self :return: angle subtending atom1-self-atom2 as float

bonded_atoms(connectivity_calculator: Callable[[...], list]) → list

Returns a list of Atom instances to which this Atom instance is connected

Parameters:

connectivity_calculator – function which calculates connectivity for given atom.

Returns:

A list of Atom instances to which this atom is bonded to

bonded_atoms_i(connectivity_calculator: Callable[[...], list]) → list

Returns a list of Atom indices to which this Atom instance is connected

Parameters:

connectivity_calculator – function which calculates connectivity for given atom.

Returns:

A list of atom indices to which this atom is bonded to (these are 0-indexed)

bonded_atoms_names(connectivity_calculator: Callable[[...], list]) → list

Returns a list of the names of Atom instances to which this Atom instance is connected

Parameters:

connectivity_calculator – function which calculates connectivity for given atom.

Returns:

A list of atom names (str) to which this atom is bonded to

connectivity(connectivity_calculator: Callable[[...], ndarray]) → ndarray

Returns the 1D np.array corresponding to the connectivity of ONE Atom with respect to all other Atom instances that are held in an Atoms instance. For an Atom instance, this is only one row of the full connectivity matrix of the Atoms instance that is self.parent. However, to compute the connectivity in the first place, we need access to the Atoms instance (self.parent).

Parameters:

connectivity_calculator – function which calculates connectivity for given atom.

property coordinates_string: str

Returns the coordinate string representation of the atom

Returns:

coordinate string of atom (x, y, z coordinates)

Return type:

str

dist(other: Atom) → float

Calculated the distance between self and other :param other: atom to calculate the distance to :return: the distance between self and other as a float

property electronegativity: float

Returns the electronegativity of the Atom instance

Returns:

The electronegativity of the atom (as defined by the atom type)

Return type:

float

features(feature_calculator: Callable[[...], ndarray], *args, **kwargs) → ndarray

Returns a 1D 3N-6 np.ndarray of the features for the current Atom instance.

Parameters:

  • feature_calculator – A function used to calculate features from the Atom instance

  • args – positional arguments to pass to feature calculator function.

  • kwargs – key word arguments to pass to the feature calculator function. Check the feature calculator to see what required key word arguments the calculator needs to function.

Returns:

The features associated with self.

Note

The current implementation allows us to fairly easily switch between features as we can change the calculator that is being used, as well as pass in new key word arguments to the given calculator.

classmethod from_atom(atom: Atom) → Atom
property i: int

Returns the index of the atom, if used in any arrays/list in Python.

Returns:

the index of the atom (0-indexed)

Return type:

int

property index: int

Returns the integer assigned to the atom, calculated from the trajectory file. Indices start at 1. This number is given to every atom in the trajectory, so atoms of the same type(element) can be distinguished.

property mass: float

Returns the mass of the atom

Returns:

The atomic mass of the atom

Return type:

float

property name: str

Returns the name of the Atom instance, which is later used to distinguish atoms when making GPR models. The number in the name starts at 1 (inclusive). e.g. O1

Returns:

the name of the atom (the type + the index of the atom (the indices start from 1))

Return type:

str

property nuclear_charge: float

Returns the nuclear charge of the atom as a float

Returns:

the nuclear change of the atom

Return type:

float

property parent: ichor.core.atoms.Atoms

Returns the parent instance (an instance of Atoms class) that holds self (an instance of Atom).

Raises:

ValueError – if parent is not defined

Returns:

parent instance of type Atoms

Return type:

ichor.core.atoms.Atoms

property radius

Returns the covalent radius of the given Atom instance.

Returns:

Covalent radius of the Atom instance (as defined by the atom type)

Return type:

float

to_angstroms() → Atom

Convert the coordiantes to Angstroms

to_bohr() → Atom

Convert the coordiantes to Bohr

property valence: int

Returns the valence of the Atom instance

Returns:

the valence of the atom (as defined by the atom type)

Return type:

int

property vdwr

Returns the Van der Waals radius of the given Atom instance.

Returns:

The Van der Waals radius of the atom (as defined by the atom type)

Return type:

float

vec_to(other: Atom) → ndarray

Calculates the vector from self to other :param other: atom to calculate the vector to :return: the vector from self to other as numpy array

property xyz_string: str

Returns the atom type and coordinates for one Atom instance. This is used to write out an xyz file, which expects entries in the form of atom_type x_coordinate, y_coordinate, z_coordinate

Returns:

coordinate string of atom with atom type (atom.type x, y, z)

Return type:

str

exception AtomNotFound

Bases: Exception

class AtomView(parent, atom)

Bases: ListOfAtoms

Class used to index a ListOfAtoms instance by an atom name (eg. C1, H2, etc.). This allows a user to get information (such as coordinates or features) for one atom.

Parameters:

  • parent – An instance of a class that subclasses from ListOfAtoms

  • atom – A string representing the name of an atom, e.g. C1, H2, etc.

C(alf: ALF | List[int])

Returns the C matrix for every Atom instance in the ListOfAtomsAtomView.

Thus, the shape is n_timesteps x 3 x 3

alf(alf_calculator: Callable, *args, **kwargs)

Returns the alf calculated from the first Atom object inside the ListOfAtomsAtomView object

property atom_name

Returns the name of the atom, e.g. ‘C1’, ‘H2’, etc.

property atom_names

Returns a list containing the name of the atom (so contains 1 element)

connectivity(connectivity_calculator: Callable)

Returns the alf calculated from the first Atom object inside the ListOfAtomsAtomView object

features(feature_calculator: Callable, *args, **kwargs) → ndarray

Return the ndarray of features for only one atom, given an alf for that atom. This is assumed to a 2D array of features for only one atom.

Parameters:

alf – A list of integers or a numpy array corresponding to the alf of one atom The atom which the atom view is for.

Returns:

The array has shape n_timesteps x n_features.

property natoms

Returns the name of the atom, e.g. ‘C1’, ‘H2’, etc.

property type

Returns the types of atoms in the atom view. Since only one atom type is present, it returns a list with one element

class Atoms(atoms: Sequence[Atom] | None = None)

Bases: list

The Atoms class handles ONE timestep in the trajectory. It is mainly used to group together Atom objects that are in the same timestep. However, it is written in a way that any number of Atom instances can be grouped together if the user wants to do so.

e.g. if we have a trajectory of methanol (6 atoms) with 1000 timesteps, we will have 1000 Atoms instances. Each of the Atoms instances will hold 6 instances of the Atom class.

C_matrix_dict(system_alf: List[ALF]) → Dict[str, ndarray]

Returns a dictionary of key (atom name), value (C matrix np array) for every atom

C_matrix_list(system_alf: List[ALF]) → List[ndarray]

Returns a list C matrix np array for every atom

add(atom: Atom)

Add Atom instances for each atom in the timestep to the self._atoms list. Each coordinate line in the trajectory file (for one timestep) is added as a separate Atom instance.

alf(alf_calculator: Callable[[...], ALF], *args, **kwargs) → List[ALF]

Returns the Atomic Local Frame (ALF) for all Atom instances that are held in Atoms e.g. [[0,1,2],[1,0,2], [2,0,1]]

Parameters:

  • args – positional arguments to pass to alf calculator

  • kwargs – key word arguments to pass to alf calculator

alf_dict(alf_calculator: Callable[[...], ALF], *args, **kwargs) → Dict[str, ALF]

Returns a list of lists with the atomic local frame indices for every atom (0-indexed).

Parameters:

  • args – positional arguments to pass to alf calculator

  • kwargs – key word arguments to pass to alf calculator

alf_list(alf_calculator: Callable[[...], ALF], *args, **kwargs) → List[List[int]]

Returns a list of lists with the atomic local frame indices for every atom (0-indexed).

Parameters:

  • args – positional arguments to pass to alf calculator

  • kwargs – key word arguments to pass to alf calculator

append(atom: Atom)

Appends an Atom instance to self.

property atom_names: List[str]

Returns the atom names as a list ([‘O1’, ‘H2’…]).

centre(centre_atom: int | str | List[Atom | str | int] | None = None)

Centers the geometry on some atom. But this is still in GLOBAL Cartesian coordinates.

property centroid: ndarray

Returns the centroid of the system (the mean of the x,y,z coordinates of the atoms).

connectivity(connectivity_calculator: Callable[[...], ndarray]) → ndarray

Return the connectivity matrix (n_atoms x n_atoms) for the given Atoms instance.

Parameters:

connectivity_calculator (Callable[..., np.ndarray]) – connectivity calculator function that calculates connectivity

Returns:

np.ndarray of shape n_atoms x n_atoms

Return type:

np.ndarray

property coordinates: ndarray

Returns an array that contains the coordinates for each Atom instance held in the Atoms instance.

copy() → Atoms

Creates a new atoms instance (different object) from the current Atoms instance.

features(feature_calculator: Callable[[...], ndarray], *args, is_atomic=True, **kwargs) → ndarray

Returns the features for this Atoms instance, corresponding to the features of each Atom instance held in this Atoms isinstance Features are calculated in the Atom class and concatenated to a 2d array here.

The array shape is n_atoms x n_features (3*n_atoms - 6)

Parameters:

  • is_atomic – whether the feature calculator calculates features for individual atoms or for the whole geometry.

  • args – positional arguments to pass to feature calculator

  • kwargs – key word arguments to pass to feature calculator

Returns:

type: np.ndarray of shape n_atoms x n_features (3N-6)

Return the feature matrix of this Atoms instance

features_dict(feature_calculator: Callable[[...], ndarray], *args, is_atomic=True, **kwargs) → dict

Returns the features in a dictionary for this Atoms instance, corresponding to the features of each Atom instance held in this Atoms isinstance Features are calculated in the Atom class and concatenated to a 2d array here.

Parameters:

  • is_atomic – whether the feature calculator calculates features for per atom or for the whole geometry

  • args – positional arguments to pass to feature calculator

  • kwargs – key word arguments to pass to feature calculator

e.g. {“C1”: np.array, “H2”: np.array}

property hash

Returns a hash for the system which is just the atom names joined by a comma.

kabsch(other: Atoms) → ndarray
property masses: List[float]

Returns a list of the masses of the Atom instances held in the Atoms instance.

property names: List[str]

Return a list of atom names that are held in the instance of Atoms.

property natoms: int

Returns the number of atoms in a timestep. Since each timestep has the same number of atoms. This means the number of atoms in the system is returned.

property nuclear_charge_sum: int

Returns the sum of nuclear charges of Atoms instance

rmsd(other: Atoms)
rotate(R: ndarray)

Perform a rotation in 3D space with a matrix R. This rotates all atoms in the system the same amount. This method also changes the coordinates of the Atom instances held in the Atoms instance.

to_angstroms() → Atoms

Convert the x, y, z coordinates of all Atom instances held in an Atoms instance to angstroms

to_bohr() → Atoms

Convert the x, y, z coordinates of all Atom instances held in an Atoms instance to bohr

translate(v: ndarray)

Translates a system in 3D space.

Parameters:

v – numpy array of shape (3,) which is added to the coordinates of each atom.

property types: List[str]

Returns the atom elements for atoms, removes duplicates

property types_extended: list

Returns the atom elements for all atoms, includes duplicates.

property xyz_string

Returns a string containing all atoms and their coordinates stored in the Atoms instance

exception AtomsNotFoundError

Bases: Exception

class ListOfAtoms(*args, **kwargs)

Bases: list, ABC

Used to focus only on how one atom moves in a trajectory, so the user can do something like trajectory[‘C1’] where trajectory is an instance of class Trajectory. This way the user can also do trajectory[‘C1’].features, trajectory[‘C1’].coordinates, etc.

abstract alf() → ALF

Returns the atomic local frame for the first timestep.

abstract property atom_names

Return the atom names from the first timestep. Assumes that all timesteps have the same number of atoms/atom names.

center_geometries_on_atom_and_write_xyz(central_atom_name: str, system_alf: Dict[str, ALF], fname: str | Path | None = None)

Centers all geometries (from a Trajectory of PointsDirectory instance) onto a central atom and then writes out a new xyz file with all geometries centered on that atom. This is essentially what the ALFVisualizier application (ALFi) does. The features for the central atom are calculated, after which they are converted back into xyz coordinates. Thus all geometries are now centered on the given central atom).

Parameters:

  • feature_calculator – Function which calculates features

  • central_atom_name – the name of the central atom to center all geometries on. Eg. ‘O1’

  • fname – Optional file name in which to save the rotated geometries.

  • args – Positional arguments to pass to calculator function

  • kwargs – Key word arguments to pass to calculator function

abstract connectivity() → ndarray

Returns the connectivity matrix of the first timestep.

abstract property coordinates: ndarray

Abstract method for coordinates.

Returns:

the xyz coordinates of all atoms for all timesteps. Shape n_timesteps x n_atoms x 3

features(feature_calculator: Callable[[...], ndarray], *args, is_atomic=True, **kwargs) → ndarray

Return the ndarray of features. This is assumed to be either 2D or 3D array. If the dimensionality of the feature array is 3, the array is transposed to transform a (ntimestep, natom, nfeature) array into a (natom, ntimestep, nfeature) array so that all features for a single atom are easier to group.

Parameters:

  • feature_calculator – The calculator function which calculates features

  • is_atomic – Whether the calculator calculates features for individual atoms or the whole geometry

  • args – Positional arguments to pass to feature calculator function

  • kwargs – Key word arguments to pass to feature calculator function

Returns:

If the features for the whole trajectory are returned, the array has shape n_atoms x n_timesteps x n_features If the trajectory instance is indexed by str, the array has shape n_timesteps x n_features. If the trajectory instance is indexed by int, the array has shape n_atoms x n_features. If the trajectory instance is indexed by slice, the array has shape n_atoms x`slice` x n_features. If a non-atomic calculator is passed, a n_timesteps x features (features could be vector, matrix, etc) is returned.

features_to_csv(feature_calculator: Callable[[...], ndarray], *args, fname: str | Path | None = None, atom_names: List[str] | None = None, **kwargs)

Writes csv files containing features for every atom in the system. Optionally a list can be passed in to get csv files for only a subset of atoms.

Parameters:

  • feature_calculator – Calculator function to be used to calculate features

  • fname – A string to be appended to the default csv file names. A .csv file is written out for every atom with default name atom_name_features.csv If an fname is given, the name becomes fname_atom_name_features.csv

  • atom_names – A list of atom names for which to write csv files. If None, then write out the features for every atom in the system.

  • args – positional arguments to pass to calculator function

  • kwargs – key word arguments to be passed to the feature calculator function

features_to_excel(feature_calculator: ALF | Callable, *args, fname: str | Path = PosixPath('features_to_excel.xlsx'), atom_names: List[str] | None = None, **kwargs)

Writes out one excel file which contains a sheet with features for every atom in the system. Optionally a list of atom names can be passed in to only make sheets for certain atoms

Parameters:

  • atom_names – A list of atom names for which to calculate features and write in excel spreadsheet

  • args – positional arguments to pass to calculator function

  • kwargs – key word arguments to be passed to the feature calculator function

  • fname – File name to save features to

get_headings()

Helper function which makes the column headings for csv or excel files in which features are going to be saved.

abstract property natoms

Abstract method for natoms.

Returns:

Returns the number of atoms in the first timestep. Each timestep should have the same number of atoms.

abstract property types: List[str]

Returns the atom elements for atoms, assumes each timesteps has the same atoms. Removes duplicates.

abstract property types_extended: List[str]

Returns the atom elements for atoms, assumes each timesteps has the same atoms. Does not remove duplicates