inquanto.geometries

class GeometryMolecular(geometry=None, distance_units='angstrom')

Bases: Geometry

Geometry class for handling and manipulating molecular systems.

Various transformations of the system in 3D space are supported. The default units are Angstroms and degrees. Alternatively, one can use Bohrs and radians.

Parameters:

• geometry (Union[str, DataFrame, list, None], default: None) – Geometrical information - can be a list of lists (e.g [['H', [0, 0, 0]], ['H', [0, 0, 1]]]), a zmatrix string, xyz coordinates as a string or pandas.DataFrame.

• distance_units (str, default: "angstrom") – Specification of distance units. Supported units are Angstroms ("angstrom") and Bohrs ("bohr").

add_atom(element, position=None)

Add an atom to the geometry.

Parameters:

• element (str) – Element symbol.

• position (Optional[ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]], default: None) – Cartesian position vector. If omitted, generates a random position with coordinates between +/-1 Angstroms.

Returns:

DataFrame – The updated dataframe object.

align_bond_to_axis(atom_ids, axis)

Align any bond to an axis.

Rotate and translate the geometry to align the bond defined by the elements of the atom_ids list to a co-ordinate axis.

Align

Parameters:

• atom_ids (list) – Two atom indices which define the bond to align to the axis.

• axis (str) – A cartesian co-ordinate axis, options are "X", "Y", "Z", "x",

:param "y": :param "z".:

Returns:

DataFrame – The updated dataframe object.

align_bond_to_vector(atom_ids, vector)

Align any bond to any user-defined vector.

Rotate and translate the geometry to align the bond defined by the elements of the atom_ids list to a vector.

Parameters:

• atom_ids (list[int]) – Indices of the atoms defining the bond to align to a vector.

• vector (ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]) – The vector of length three that we use to align the bond.

Returns:

DataFrame – The updated dataframe object.

align_to_plane(atom_ids, vectors)

Rotate and translate the geometry such that three atoms lie in the plane defined by the vectors provided.

Parameters:

• atom_ids (list[int]) – The indices of three atoms in the geometry that we use to align to the plane.

• vectors (list[ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]]) – An iterable containing three vectors that define the plane.

Returns:

DataFrame – The updated dataframe object.

align_to_xy_plane(atom_ids=None)

Align any three atoms to the \(xy\) plane.

Rotate and translate the geometry such that the plane defined by the three atom indices in atom_ids becomes the \(xy\) plane.

Parameters:

atom_ids (Optional[list[int]], default: None) – The indices of three atoms in the geometry that we align to the \(xy\) plane.

Returns:

DataFrame – The updated dataframe object.

align_to_xz_plane(atom_ids=None)

Align any three atoms to the \(xz\) plane.

Rotate and translate the geometry such that the plane defined by the three atom indices in the atom_ids variable becomes the \(xz\) plane.

Parameters:

atom_ids (Optional[list[int]], default: None) – The indices of three atoms in the geometry that we align to the \(xz\) plane.

Returns:

DataFrame – The updated dataframe object.

align_to_yz_plane(atom_ids=None)

Align any three atoms to the \(yz\) plane.

Rotate and translate the geometry such that the plane defined by the three atom indices in atom_ids becomes the \(yz\) plane.

Parameters:

atom_ids (Optional[list[int]], default: None) – The indices of three atoms in the geometry that we align to the \(yz\) plane.

Returns:

DataFrame – The updated dataframe object.

property atomic_coordinates: ndarray[Any, dtype[_ScalarType_co]]

Get an array of position vectors of each atom in the geometry.

Each row corresponds to one position vector.

Returns:

An array of floats where each row at index \(i\) contains the \(x, y, z\) coordinates of atom \(i\).

bond_angle(atom_ids, units='deg')

Compute the bond angle defined by the three atoms indexed by the elements of atom_ids.

The angle is at the middle atom, or second index in the atom_ids list. For example, to compute the bond angle at the oxygen atom in water, one would pass [index of H1, index of O, index of H2].

Parameters:

• atom_ids (list[int]) – An iterable containing the indices of three atoms to use in calculating the angle.

• units (str, default: "deg") – Units of the reported bond angle, options are "deg" or "rad".

Returns:

float – The bond angle in the specified units.

bond_length(atom_ids)

Compute the inter-nuclear separation between the two atoms indexed by the elements of atom_ids.

Parameters:

atom_ids (list[int]) – An iterable containing the indices of the atoms defining the bond.

Returns:

float – Internuclear separation in the units of the Geometry object.

build_2atom_chain(atom='H', num_pair=4, d_intra=0.75, d_inter=0.75)

Construct xyz geometry for a chain of homonuclear diatomics.

Parameters:

• atom (str, default: "H") – Element symbol.

• num_pair (int, default: 4) – Number of diatomics in the chain.

• d_intra (float, default: 0.75) – Bond length in each diatomic unit of the chain.

• d_inter (float, default: 0.75) – Inter-molecular separation.

Return type:

None

build_alternating_ring(element_a, a, bb, b, n)

Builds a ring geometry of atoms as -A–B–A–B-…

Parameters:

• element_a (str) – Atomic symbol of element A.

• a (float) – Distance between A and B in the AB pairs.

• bb (str) – Atomic symbol of element B.

• b (float) – B to A distance between AB pairs.

• n (int) – Number of A–B atom pairs in the ring.

Return type:

None

build_rectangle(element, dx, nx, dy=0, ny=1)

Builds a rectangular grid geometry of atoms.

Parameters:

• element (str) – Atomic symbol.

• dx (float) – Distance between the atoms in \(x\) direction.

• nx (int) – Number of atoms in the \(x\) direction.

• dy (float, default: 0) – Distance between the atoms in \(y\) direction.

• ny (int, default: 1) – Number of atoms in the \(y\) direction.

Return type:

None

build_ring(element, d, n)

Builds a ring geometry of atoms.

Parameters:

• element (str) – Atomic symbol of the element.

• d (float) – Distance between the atoms in the ring.

• n (int) – Number of atoms in the ring.

Return type:

None

compute_distance_matrix()

Compute a distance matrix.

Each \(i\), \(j\) th element is the internuclear separation between atom \(i\) and \(j\).

Returns:

ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]] – The distance matrix.

property dataframe: DataFrame

Return the geometry in a pandas.DataFrame object.

Each row corresponds to an atom in the geometry and each column holds the atomic symbol of an element and their \(x, y, z\) coordinates.

Returns:

An pandas.DataFrame containing a geometry.

delete_atom(atom_index)

Delete an atom from the geometry.

Parameters:

atom_index (Union[int, list]) – Index of the atom to delete.

Returns:

DataFrame – The updated dataframe object.

df_to_xyz()

Returns the xyz geometry based on the dataframe attribute.

Returns:

list[tuple[str, tuple[float, float, float]]] – The xyz geometry.

dihedral_angle(atom_ids, units='deg')

Compute the dihedral angle defined by the four atoms specified in atom_ids.

Parameters:

• atom_ids (list[int]) – The four atom indices.

• units (str, default: "deg") – The units the angle is reported in, options are "deg" or "rad".

Returns:

float – The dihedral angle defined by the four atoms indexed in atom_ids, given in the units specified.

property elements: list[str]

Return a list of the chemical symbols present in the geometry.

static from_xyz_string(xyz_string, distance_units='angstrom')

Create a Geometry object from a string.

Parameters:

• xyz_string (str) – A string in which each new line contains the element symbol and \(x, y,\) and \(z\) positions separated by a space.

• distance_units (str, default: "angstrom") – The geometrical units of the system, can be "angstrom" or "bohr".

Returns:

Geometry – A Geometry object containing the geometry provided in the xyz_string argument.

load_csv(fn)

Load a csv file into the dataframe attribute.

Parameters:

fn (str) – The input filename.

Return type:

None

load_json(fn)

Load a json file into the dataframe attribute of the Geometry object.

Parameters:

fn (str) – The input filename.

Return type:

None

classmethod load_xyz(filename, distance_units='angstrom')

Load geometry from an xyz file.

Currently, only the xyz file format is supported.

Parameters:

• filename (str) – Filename of the xyz file.

• distance_units (str, default: "angstrom") – Distance units the geometry is expressed in. Supported units are Angstrom ("angstrom") and Bohrs ("bohr").

Returns:

Geometry – The loaded geometry.

load_zmatrix(filename, distance_units='angstrom')

Load a z-matrix from file into the zmatrix attribute.

Parameters:

• filename (str) – Filename.

• distance_units (str, default: "angstrom") – Distance units; supported units are Angstrom ("angstrom") and Bohrs ("bohr").

Return type:

None

modify_bond_angle(atom_ids, theta, units='deg')

Change the bond angle at the atom with the index that matches the second element of atom_ids.

The atom indexed by the third element of atom_ids has its position updated.

Parameters:

• atom_ids (list[int]) – The indices of three atoms.

• theta (float) – New bond angle.

• units (str, default: "deg") – Units of the bond angle, options are "deg" or "rad".

Returns:

DataFrame – The updated dataframe object.

modify_bond_angle_by_group(atom_ids, theta, group, units='deg')

Modify the bond angle between two groups of atoms.

Modify the bond angle at the second element of atom_ids, moving the third element of atom_ids and the subgroup it belongs to by the same angle. Elements 1 and 2 of atom_ids must belong to a different subgroup to the final element. The structure within each subgroup is preserved.

Parameters:

• atom_ids (list[int]) – The indices of three atoms.

• theta (float) – New bond angle.

• group (str) – Grouping scheme name.

• units (str, default: "deg") – Units of the angle, "deg" or "rad".

Returns:

DataFrame – The updated dataframe object.

modify_bond_length(atom_ids, new_bond_length)

Change the internuclear separation between two atoms.

The first atom in atom_ids is fixed, the second atom is moved.

Parameters:

• atom_ids (list[int]) – The indices of two atoms.

• new_bond_length (float) – The new bond length.

Returns:

DataFrame – The updated dataframe object.

modify_bond_length_by_group(atom_ids, bond_length, group)

Modify the bond length connecting two groups of atoms.

Modify the bond length connecting two atoms in different subgroups. Each subgroup’s internal structure is preserved. The two atoms specified in atom_ids must belong to different subgroups as defined by the group argument. The subgroup translated is the one containing the second atom indexed in atom_ids.

Parameters:

• atom_ids (list[int]) – Atom indices.

• bond_length (float) – New bond length.

• group (str) – Group name.

Returns:

DataFrame – The updated dataframe attribute.

modify_dihedral_angle(atom_ids, theta, units='deg')

Modify a dihedral angle.

Change the dihedral angle defined by the four atoms indexed by the elements of atom_ids. The atom indexed by the last element has its position updated.

Parameters:

• atom_ids (list[int]) – The indices of the four atoms.

• theta (float) – The dihedral angle.

• units (str, default: "deg") – Units of the dihedral angle, supported units are "rad" or "deg".

Returns:

DataFrame – The modified dataframe object.

modify_dihedral_angle_by_group(atom_ids, theta, group, units='deg')

Modify a dihedral angle between two groups of atoms.

Modify the dihedral angle defined by atoms indexed in atom_ids. The structure within each group is retained. The 3rd and 4th elements of atom_ids must belong to the same label, and be different to the label defined by atoms indexed by the 1st and 2nd elements.

Parameters:

• atom_ids (list[int]) – The indices of four atoms.

• theta (float) – The dihedral angle.

• group (str) – Grouping label.

• units (str, default: "deg") – Units of the dihedral angle; supported units are "rad" or "deg".

Returns:

DataFrame – The updated dataframe object.

randomize_xyz(sigma=0.05, seed=0, freeze_atoms=None)

Add random numbers to the xyz geometry.

The random numbers are sampled from Gaussian distributions centred at each atomic position.

Parameters:

• sigma (float, default: 0.05) – Sigma for the Gaussian distribution.

• seed (int, default: 0) – Random seed.

• freeze_atoms (Optional[list], default: None) – The of indices of atoms to freeze.

Returns:

DataFrame – The updated dataframe object.

rescale_position_vectors(factor)

Multiply the atomic position vectors by a constant factor.

Parameters:

factor (float) – Conversion factor to new coordinate frame.

Returns:

DataFrame – The updated dataframe object.

rotate_around_axis(theta, axis, units='deg')

Rotate the geometry around one of the coordinate axes.

Parameters:

• theta (float) – The angle through which to rotate.

• axis (str) – the coordinate axis to rotate around (upper or lower case).

• units (str, default: "deg") – units of the angle specified, options are "deg" or :code:``”rad”`.

Returns:

DataFrame – The updated dataframe object.

rotate_around_vector(vector, theta, units='deg')

Rotate the geometry around a vector defined by input theta.

Parameters:

• vector (ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]) – The vector around which to rotate.

• theta (float) – The angle to rotate through.

• units (str, default: "deg") – The units of the angle, options are "deg" or "rad".

Returns:

DataFrame – The updated dataframe object.

save_csv(fn)

Write the current dataframe object of the Geometry object to a csv file.

Parameters:

fn (str) – The output filename.

Return type:

None

save_json(fn)

Write the current self.df property of the Geometry object to a json file.

Parameters:

fn (str) – The output filename.

Return type:

None

save_xyz(filename)

Save geometry to an xyz file.

Currently, only the file format xyz is supported.

Parameters:

filename (str) – Name of the output file containing the geometry.

Return type:

None

save_zmatrix(filename)

Write the zmatrix attribute to file with name filename.

Parameters:

filename (str) – Output filename.

Return type:

None

scan_bond_angle(atom_ids, bond_angles, units='deg')

Construct many Geometry objects corresponding to a scan of a bond angle.

Create a list of Geometry objects that correspond to a scan of the potential energy surface by bond angle. The modification of the angle moves only one atom - the atom corresponding to the third element of the atom_ids argument by index.

Parameters:

• atom_ids (list[int]) – The indices of the atoms between which the bond angle is changed.

• bond_angles (list[float]) – A list of bond angles.

• units (str, default: "deg")

Returns:

list[Geometry] – The Geometry objects corresponding the bond lengths specified in the input.

scan_bond_angle_by_group(atom_ids, bond_angles, group, units='deg')

Scan a bond angle between two different groups while retaining the geometry of each group.

Parameters:

• atom_ids (list[int]) – The indices of three atoms.

• bond_angles (list[float]) – Bond angles to create Geometry objects for.

• group (str) – Group heading.

• units (str, default: "deg") – Units of the angles defined in :code:bond_angles` in "deg" or "rad".

Returns:

list – A list of geometries corresponding to the description and bond_angles passed in.

scan_bond_length(atom_ids, bond_lengths)

Construct many Geometry objects corresponding to a scan of bond lengths.

Create Geometry objects corresponding to a scan of the potential energy surface by bond length. The bond stretching moves only one atom - the atom corresponding to the second element of the atom_ids argument by index.

Parameters:

• atom_ids (list[int]) – The atoms between which the bond is stretched.

• bond_lengths (list[float]) – A list of bond lengths.

Returns:

list[Geometry] – The Geometry objects corresponding the bond lengths specified in the input.

scan_bond_length_by_group(atom_ids, bond_lengths, group)

Scan a bond length between two different subgroups while retaining the geometry of each subgroup.

Parameters:

• atom_ids (list[int]) – The indices of three atoms.

• bond_lengths (list[float]) – Bond lengths to create Geometry objects for.

• group (str) – Group heading.

Returns:

list[Geometry] – The geometries corresponding to the description and bond_lengths passed in.

scan_dihedral_angle(atom_ids, dihedral_angles, units='deg')

Construct many Geometry objects corresponding to a scan of dihedral angles.

Create Geometry objects corresponding to a scan of the potential energy surface by dihedral angle. The modification of the angle moves only one atom - the atom corresponding to the fourth element of the atom_ids argument by index.

Parameters:

• atom_ids (list[int]) – The four atoms between which the dihedral is changed.

• dihedral_angles (list[float]) – The dihedral angles.

• units (str, default: "deg")

Returns:

list[Geometry] – A list of Geometry objects corresponding the bond lengths specified in the input.

scan_dihedral_angle_by_group(atom_ids, dihedral_angles, group, units='deg')

Scan a dihedral angle between atoms in different groups while retaining the geometry of each group.

Parameters:

• atom_ids (list[int]) – Atom indices.

• dihedral_angles (list[float]) – Dihedral angles to create Geometry objects for.

• group (str) – Group heading.

• units (str, default: "deg") – Units of the angles defined in dihedral_angles.

Returns:

list – A list of geometries corresponding to the description and dihedral angles passed in.

set_groups(target, source, mapping=None)

Set group information for the atoms in the system.

Target specifies the heading of the new column created in the underlying dataframe attribute of the geometry. The source argument can be either a dict, where the keys are the labels of the group and the values are the atom indices corresponding to the label, or a string. If source is a dict, the mapping argument does nothing. If source is a string, it must be an existing column heading in dataframe. In which case, the mapping argument must be provided as a callable function which modifies the existing entries in the source column and inserts them into the new target column.

Parameters:

• target (str) – Column in the table that refer to this grouping.

• source (str) – Another column or a dictionary defining the groups.

• mapping (Optional[Callable], default: None) – Optional mapping to transform group names.

Return type:

None

set_subgroups(target, pattern, subgroup)

Set subgroups on the target grouping via regular expression pattern.

Parameters:

• target (str) – Target column in the table, a table that has a grouping in it.

• pattern (str) – Regex pattern to match.

• subgroup (str) – Adding subgroups to the matching groups.

Return type:

None

to_angstrom()

Convert the geometry in the dataframe attribute from Bohrs to Angstroms.

Returns:

DataFrame – The updated dataframe object.

to_bohr()

Convert the geometry in the dataframe attribute from Angstroms to Bohrs.

Returns:

DataFrame – The updated dataframe object.

to_zmatrix()

Map the geometry held in the dataframe attribute to a z-matrix.

Atoms are taken in order, and z-matrix sequences are defined backwards through the geometry. For example, the first dihedral is defined by the 4th, 3rd, 2nd and 1st atoms in the geometry.

Returns:

str – The updated zmatrix attribute.

translate_by_vector(v)

Translate all atoms in the geometry by a vector, v.

Parameters:

v (ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]) – Vector defining the translation.

Returns:

DataFrame – The updated dataframe object.

property xyz: list[tuple[str, tuple[float, float, float]]]

Return the geometry in xyz format.

Returns:

The geometry as a list of lists of atom symbols and positions

xyz_to_df(xyz)

Convert the xyz geometry to a pandas.DataFrame.

Parameters:

xyz (list[Any]) – An xyz geometry as a list of lists containing the element as a string and the position as a list of floats.

Returns:

DataFrame – The dataframe corresponding to the xyz argument.

property zmatrix: str

Return the geometry in z-matrix format.

Returns:

The geometry as a z-matrix string.

zmatrix_to_df()

Convert the zmatrix attribute to a pandas.DataFrame.

Returns:

DataFrame – The updated dataframe object geometry.

class GeometryPeriodic(geometry=None, unit_cell=None, distance_units='angstrom')

Bases: Geometry

Geometry class for handling periodic systems.

Various transformations and extensions of the system in 3D space are supported. The default units are Angstroms and degrees. Alternatively, one can use bohrs and radians.

Parameters:

• geometry (Union[str, DataFrame, list, None], default: None) – Geometrical information - can be a list of lists (e.g [['H', [0, 0, 0]], ['H', [0, 0, 1]]]), xyz coordinates as a string or pandas.DataFrame.

• unit_cell (Optional[ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]], default: None) – The unit cell as a 3x3 array with each row being one cell vector.

• distance_units (str) – Specification of distance units. Supported units are Angstrom ("angstrom") and Bohrs ("bohr").

add_atom(element, position=None)

Add an atom to the geometry.

Parameters:

• element (str) – Element symbol.

• position (Optional[ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]], default: None) – Cartesian position vector. If omitted, generates a random position with coordinates between +/-1 Angstroms.

Returns:

DataFrame – The updated dataframe object.

align_bond_to_axis(atom_ids, axis)

Align any bond to an axis.

Rotate and translate the geometry to align the bond defined by the elements of the atom_ids list to a co-ordinate axis.

Align

Parameters:

• atom_ids (list) – Two atom indices which define the bond to align to the axis.

• axis (str) – A cartesian co-ordinate axis, options are "X", "Y", "Z", "x",

:param "y": :param "z".:

Returns:

DataFrame – The updated dataframe object.

align_bond_to_vector(atom_ids, vector)

Align any bond to any user-defined vector.

Rotate and translate the geometry to align the bond defined by the elements of the atom_ids list to a vector.

Parameters:

• atom_ids (list[int]) – Indices of the atoms defining the bond to align to a vector.

• vector (ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]) – The vector of length three that we use to align the bond.

Returns:

DataFrame – The updated dataframe object.

align_to_plane(atom_ids, vectors)

Rotate and translate the geometry such that three atoms lie in the plane defined by the vectors provided.

Parameters:

• atom_ids (list[int]) – The indices of three atoms in the geometry that we use to align to the plane.

• vectors (list[ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]]) – An iterable containing three vectors that define the plane.

Returns:

DataFrame – The updated dataframe object.

align_to_xy_plane(atom_ids=None)

Align any three atoms to the \(xy\) plane.

Rotate and translate the geometry such that the plane defined by the three atom indices in atom_ids becomes the \(xy\) plane.

Parameters:

atom_ids (Optional[list[int]], default: None) – The indices of three atoms in the geometry that we align to the \(xy\) plane.

Returns:

DataFrame – The updated dataframe object.

align_to_xz_plane(atom_ids=None)

Align any three atoms to the \(xz\) plane.

Rotate and translate the geometry such that the plane defined by the three atom indices in the atom_ids variable becomes the \(xz\) plane.

Parameters:

atom_ids (Optional[list[int]], default: None) – The indices of three atoms in the geometry that we align to the \(xz\) plane.

Returns:

DataFrame – The updated dataframe object.

align_to_yz_plane(atom_ids=None)

Align any three atoms to the \(yz\) plane.

Rotate and translate the geometry such that the plane defined by the three atom indices in atom_ids becomes the \(yz\) plane.

Parameters:

atom_ids (Optional[list[int]], default: None) – The indices of three atoms in the geometry that we align to the \(yz\) plane.

Returns:

DataFrame – The updated dataframe object.

property atomic_coordinates: ndarray[Any, dtype[_ScalarType_co]]

Get an array of position vectors of each atom in the geometry.

Each row corresponds to one position vector.

Returns:

An array of floats where each row at index \(i\) contains the \(x, y, z\) coordinates of atom \(i\).

bond_angle(atom_ids, units='deg')

Compute the bond angle defined by the three atoms indexed by the elements of atom_ids.

The angle is at the middle atom, or second index in the atom_ids list. For example, to compute the bond angle at the oxygen atom in water, one would pass [index of H1, index of O, index of H2].

Parameters:

• atom_ids (list[int]) – An iterable containing the indices of three atoms to use in calculating the angle.

• units (str, default: "deg") – Units of the reported bond angle, options are "deg" or "rad".

Returns:

float – The bond angle in the specified units.

bond_length(atom_ids)

Compute the inter-nuclear separation between the two atoms indexed by the elements of atom_ids.

Parameters:

atom_ids (list[int]) – An iterable containing the indices of the atoms defining the bond.

Returns:

float – Internuclear separation in the units of the Geometry object.

build_2atom_chain(atom='H', num_pair=4, d_intra=0.75, d_inter=0.75)

Construct xyz geometry for a chain of homonuclear diatomics.

Parameters:

• atom (str, default: "H") – Element symbol.

• num_pair (int, default: 4) – Number of diatomics in the chain.

• d_intra (float, default: 0.75) – Bond length in each diatomic unit of the chain.

• d_inter (float, default: 0.75) – Inter-molecular separation.

Return type:

None

build_alternating_ring(element_a, a, bb, b, n)

Builds a ring geometry of atoms as -A–B–A–B-…

Parameters:

• element_a (str) – Atomic symbol of element A.

• a (float) – Distance between A and B in the AB pairs.

• bb (str) – Atomic symbol of element B.

• b (float) – B to A distance between AB pairs.

• n (int) – Number of A–B atom pairs in the ring.

Return type:

None

build_rectangle(element, dx, nx, dy=0, ny=1)

Builds a rectangular grid geometry of atoms.

Parameters:

• element (str) – Atomic symbol.

• dx (float) – Distance between the atoms in \(x\) direction.

• nx (int) – Number of atoms in the \(x\) direction.

• dy (float, default: 0) – Distance between the atoms in \(y\) direction.

• ny (int, default: 1) – Number of atoms in the \(y\) direction.

Return type:

None

build_ring(element, d, n)

Builds a ring geometry of atoms.

Parameters:

• element (str) – Atomic symbol of the element.

• d (float) – Distance between the atoms in the ring.

• n (int) – Number of atoms in the ring.

Return type:

None

build_supercell(dimensions)

Construct a supercell.

Repeat the unit cell geometry in each direction according to the elements of the provided dimensions list.

Parameters:

dimensions (list[int]) – Number of times to repeat the unit cell in each direction.

Returns:

DataFrame – The updated dataframe object.

compute_distance_matrix()

Compute a distance matrix.

Each \(i\), \(j\) th element is the internuclear separation between atom \(i\) and \(j\).

Returns:

ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]] – The distance matrix.

property dataframe: DataFrame

Return the geometry in a pandas.DataFrame object.

Each row corresponds to an atom in the geometry and each column holds the atomic symbol of an element and their \(x, y, z\) coordinates.

Returns:

An pandas.DataFrame containing a geometry.

delete_atom(atom_index)

Delete an atom from the geometry.

Parameters:

atom_index (Union[int, list]) – Index of the atom to delete.

Returns:

DataFrame – The updated dataframe object.

df_to_xyz()

Returns the xyz geometry based on the dataframe attribute.

Returns:

list[tuple[str, tuple[float, float, float]]] – The xyz geometry.

dihedral_angle(atom_ids, units='deg')

Compute the dihedral angle defined by the four atoms specified in atom_ids.

Parameters:

• atom_ids (list[int]) – The four atom indices.

• units (str, default: "deg") – The units the angle is reported in, options are "deg" or "rad".

Returns:

float – The dihedral angle defined by the four atoms indexed in atom_ids, given in the units specified.

property elements: list[str]

Return a list of the chemical symbols present in the geometry.

static from_xyz_string(xyz_string, distance_units='angstrom')

Create a Geometry object from a string.

Parameters:

• xyz_string (str) – A string in which each new line contains the element symbol and \(x, y,\) and \(z\) positions separated by a space.

• distance_units (str, default: "angstrom") – The geometrical units of the system, can be "angstrom" or "bohr".

Returns:

Geometry – A Geometry object containing the geometry provided in the xyz_string argument.

load_csv(fn)

Load a csv file into the dataframe attribute.

Parameters:

fn (str) – The input filename.

Return type:

None

load_json(fn)

Load a json file into the dataframe attribute of the Geometry object.

Parameters:

fn (str) – The input filename.

Return type:

None

classmethod load_xyz(filename, distance_units='angstrom')

Load geometry from an xyz file.

Currently, only the xyz file format is supported.

Parameters:

• filename (str) – Filename of the xyz file.

• distance_units (str, default: "angstrom") – Distance units the geometry is expressed in. Supported units are Angstrom ("angstrom") and Bohrs ("bohr").

Returns:

Geometry – The loaded geometry.

modify_bond_angle(atom_ids, theta, units='deg')

Change the bond angle at the atom with the index that matches the second element of atom_ids.

The atom indexed by the third element of atom_ids has its position updated.

Parameters:

• atom_ids (list[int]) – The indices of three atoms.

• theta (float) – New bond angle.

• units (str, default: "deg") – Units of the bond angle, options are "deg" or "rad".

Returns:

DataFrame – The updated dataframe object.

modify_bond_angle_by_group(atom_ids, theta, group, units='deg')

Modify the bond angle between two groups of atoms.

Modify the bond angle at the second element of atom_ids, moving the third element of atom_ids and the subgroup it belongs to by the same angle. Elements 1 and 2 of atom_ids must belong to a different subgroup to the final element. The structure within each subgroup is preserved.

Parameters:

• atom_ids (list[int]) – The indices of three atoms.

• theta (float) – New bond angle.

• group (str) – Grouping scheme name.

• units (str, default: "deg") – Units of the angle, "deg" or "rad".

Returns:

DataFrame – The updated dataframe object.

modify_bond_length(atom_ids, new_bond_length)

Change the internuclear separation between two atoms.

The first atom in atom_ids is fixed, the second atom is moved.

Parameters:

• atom_ids (list[int]) – The indices of two atoms.

• new_bond_length (float) – The new bond length.

Returns:

DataFrame – The updated dataframe object.

modify_bond_length_by_group(atom_ids, bond_length, group)

Modify the bond length connecting two groups of atoms.

Modify the bond length connecting two atoms in different subgroups. Each subgroup’s internal structure is preserved. The two atoms specified in atom_ids must belong to different subgroups as defined by the group argument. The subgroup translated is the one containing the second atom indexed in atom_ids.

Parameters:

• atom_ids (list[int]) – Atom indices.

• bond_length (float) – New bond length.

• group (str) – Group name.

Returns:

DataFrame – The updated dataframe attribute.

modify_dihedral_angle(atom_ids, theta, units='deg')

Modify a dihedral angle.

Change the dihedral angle defined by the four atoms indexed by the elements of atom_ids. The atom indexed by the last element has its position updated.

Parameters:

• atom_ids (list[int]) – The indices of the four atoms.

• theta (float) – The dihedral angle.

• units (str, default: "deg") – Units of the dihedral angle, supported units are "rad" or "deg".

Returns:

DataFrame – The modified dataframe object.

modify_dihedral_angle_by_group(atom_ids, theta, group, units='deg')

Modify a dihedral angle between two groups of atoms.

Modify the dihedral angle defined by atoms indexed in atom_ids. The structure within each group is retained. The 3rd and 4th elements of atom_ids must belong to the same label, and be different to the label defined by atoms indexed by the 1st and 2nd elements.

Parameters:

• atom_ids (list[int]) – The indices of four atoms.

• theta (float) – The dihedral angle.

• group (str) – Grouping label.

• units (str, default: "deg") – Units of the dihedral angle; supported units are "rad" or "deg".

Returns:

DataFrame – The updated dataframe object.

randomize_xyz(sigma=0.05, seed=0, freeze_atoms=None)

Add random numbers to the xyz geometry.

The random numbers are sampled from Gaussian distributions centred at each atomic position.

Parameters:

• sigma (float, default: 0.05) – Sigma for the Gaussian distribution.

• seed (int, default: 0) – Random seed.

• freeze_atoms (Optional[list], default: None) – The of indices of atoms to freeze.

Returns:

DataFrame – The updated dataframe object.

rescale_position_vectors(factor)

Multiply the atomic position vectors by a constant factor.

Parameters:

factor (float) – Conversion factor to new coordinate frame.

Returns:

DataFrame – The updated dataframe object.

rotate_around_axis(theta, axis, units='deg')

Rotate the geometry around one of the coordinate axes.

Parameters:

• theta (float) – The angle through which to rotate.

• axis (str) – the coordinate axis to rotate around (upper or lower case).

• units (str, default: "deg") – units of the angle specified, options are "deg" or :code:``”rad”`.

Returns:

DataFrame – The updated dataframe object.

rotate_around_vector(vector, theta, units='deg')

Rotate the geometry around a vector defined by input theta.

Parameters:

• vector (ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]) – The vector around which to rotate.

• theta (float) – The angle to rotate through.

• units (str, default: "deg") – The units of the angle, options are "deg" or "rad".

Returns:

DataFrame – The updated dataframe object.

save_csv(fn)

Write the current dataframe object of the Geometry object to a csv file.

Parameters:

fn (str) – The output filename.

Return type:

None

save_json(fn)

Write the current self.df property of the Geometry object to a json file.

Parameters:

fn (str) – The output filename.

Return type:

None

save_xyz(filename)

Save geometry to an xyz file.

Currently, only the file format xyz is supported.

Parameters:

filename (str) – Name of the output file containing the geometry.

Return type:

None

scan_bond_angle(atom_ids, bond_angles, units='deg')

Construct many Geometry objects corresponding to a scan of a bond angle.

Create a list of Geometry objects that correspond to a scan of the potential energy surface by bond angle. The modification of the angle moves only one atom - the atom corresponding to the third element of the atom_ids argument by index.

Parameters:

• atom_ids (list[int]) – The indices of the atoms between which the bond angle is changed.

• bond_angles (list[float]) – A list of bond angles.

• units (str, default: "deg")

Returns:

list[Geometry] – The Geometry objects corresponding the bond lengths specified in the input.

scan_bond_angle_by_group(atom_ids, bond_angles, group, units='deg')

Scan a bond angle between two different groups while retaining the geometry of each group.

Parameters:

• atom_ids (list[int]) – The indices of three atoms.

• bond_angles (list[float]) – Bond angles to create Geometry objects for.

• group (str) – Group heading.

• units (str, default: "deg") – Units of the angles defined in :code:bond_angles` in "deg" or "rad".

Returns:

list – A list of geometries corresponding to the description and bond_angles passed in.

scan_bond_length(atom_ids, bond_lengths)

Construct many Geometry objects corresponding to a scan of bond lengths.

Create Geometry objects corresponding to a scan of the potential energy surface by bond length. The bond stretching moves only one atom - the atom corresponding to the second element of the atom_ids argument by index.

Parameters:

• atom_ids (list[int]) – The atoms between which the bond is stretched.

• bond_lengths (list[float]) – A list of bond lengths.

Returns:

list[Geometry] – The Geometry objects corresponding the bond lengths specified in the input.

scan_bond_length_by_group(atom_ids, bond_lengths, group)

Scan a bond length between two different subgroups while retaining the geometry of each subgroup.

Parameters:

• atom_ids (list[int]) – The indices of three atoms.

• bond_lengths (list[float]) – Bond lengths to create Geometry objects for.

• group (str) – Group heading.

Returns:

list[Geometry] – The geometries corresponding to the description and bond_lengths passed in.

scan_dihedral_angle(atom_ids, dihedral_angles, units='deg')

Construct many Geometry objects corresponding to a scan of dihedral angles.

Create Geometry objects corresponding to a scan of the potential energy surface by dihedral angle. The modification of the angle moves only one atom - the atom corresponding to the fourth element of the atom_ids argument by index.

Parameters:

• atom_ids (list[int]) – The four atoms between which the dihedral is changed.

• dihedral_angles (list[float]) – The dihedral angles.

• units (str, default: "deg")

Returns:

list[Geometry] – A list of Geometry objects corresponding the bond lengths specified in the input.

scan_dihedral_angle_by_group(atom_ids, dihedral_angles, group, units='deg')

Scan a dihedral angle between atoms in different groups while retaining the geometry of each group.

Parameters:

• atom_ids (list[int]) – Atom indices.

• dihedral_angles (list[float]) – Dihedral angles to create Geometry objects for.

• group (str) – Group heading.

• units (str, default: "deg") – Units of the angles defined in dihedral_angles.

Returns:

list – A list of geometries corresponding to the description and dihedral angles passed in.

set_groups(target, source, mapping=None)

Set group information for the atoms in the system.

Target specifies the heading of the new column created in the underlying dataframe attribute of the geometry. The source argument can be either a dict, where the keys are the labels of the group and the values are the atom indices corresponding to the label, or a string. If source is a dict, the mapping argument does nothing. If source is a string, it must be an existing column heading in dataframe. In which case, the mapping argument must be provided as a callable function which modifies the existing entries in the source column and inserts them into the new target column.

Parameters:

• target (str) – Column in the table that refer to this grouping.

• source (str) – Another column or a dictionary defining the groups.

• mapping (Optional[Callable], default: None) – Optional mapping to transform group names.

Return type:

None

set_subgroups(target, pattern, subgroup)

Set subgroups on the target grouping via regular expression pattern.

Parameters:

• target (str) – Target column in the table, a table that has a grouping in it.

• pattern (str) – Regex pattern to match.

• subgroup (str) – Adding subgroups to the matching groups.

Return type:

None

to_angstrom()

Convert the geometry in the dataframe attribute from Bohrs to Angstroms.

Returns:

DataFrame – The updated dataframe object.

to_bohr()

Convert the geometry in the dataframe attribute from Angstroms to Bohrs.

Returns:

DataFrame – The updated dataframe object.

translate_by_vector(v)

Translate all atoms in the geometry by a vector, v.

Parameters:

v (ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]) – Vector defining the translation.

Returns:

DataFrame – The updated dataframe object.

property xyz: list[tuple[str, tuple[float, float, float]]]

Return the geometry in xyz format.

Returns:

The geometry as a list of lists of atom symbols and positions

xyz_to_df(xyz)

Convert the xyz geometry to a pandas.DataFrame.

Parameters:

xyz (list[Any]) – An xyz geometry as a list of lists containing the element as a string and the position as a list of floats.

Returns:

DataFrame – The dataframe corresponding to the xyz argument.