The structural package#

The structural package contains modules for dealing with molecular structures - it is the functional core that performs the real action behind most of the methods that are available in the Molecule class’s methods. This includes operations such as computing angles, rotating around bonds, and assembling molecules together.

The structural package is divided into several submodules, each of which is described below.

Basic structural operations#

The base module contains the basic structural operations that are used by the other modules.

Basic structural operations

Basic structure related functions

buildamol.structural.base.adjust_bond_length(bond, new_length: float)[source]#

Adjust the bond length of a bond.

Parameters:

bond (buildamol.Bond) – The bond to adjust
new_length (float) – The new bond length

Returns:

adjusted_bond – The adjusted bond

Return type:

Bio.PDB.Bond

buildamol.structural.base.adjust_distance(coord1, coord2, new_length: float)[source]#

Adjust the distance between two points.

Parameters:

coord1 (array-like) – The first point
coord2 (array-like) – The second point
new_length (float) – The new distance

Returns:

new_coord2 – The new coordinates of the second point

Return type:

array-like

buildamol.structural.base.angle_between(coords1, coords2, coords3)[source]#

Compute the angle between three atoms.

Parameters:

coords1 (numpy.ndarray) – The coordinates of the first atom
coords2 (numpy.ndarray) – The coordinates of the second atom
coords3 (numpy.ndarray) – The coordinates of the third atom

Returns:

angle – The angle between the three atoms in degrees

Return type:

float

buildamol.structural.base.atom_make_full_id(self)[source]#: A self-adjusting full_id for an Biopython Atom

buildamol.structural.base.bond_angle(bond1, bond2)[source]#

Compute the angle between two bonds.

Parameters:

bond1 (Bio.PDB.Bond) – The first bond
bond2 (Bio.PDB.Bond) – The second bond

Returns:

angle – The angle between the two bonds in degrees

Return type:

float

buildamol.structural.base.bond_vector(bond)[source]#

Compute the vector between two atoms in a bond.

Parameters:: bond (Bio.PDB.Bond) – The bond
Returns:: vector – The vector between the two atoms in the bond
Return type:: numpy.ndarray

buildamol.structural.base.center_of_geometry(coords)[source]#

Compute the center of geometry of a molecule.

Parameters:: coords (array-like) – The coordinates of the atoms as an nx3 array
Returns:: cog – The center of geometry
Return type:: array-like

buildamol.structural.base.center_of_gravity(masses, coords)[source]#

Compute the center of gravity of a molecule.

Parameters:

masses (array-like) – The masses of the atoms as an nx1 vector
coords (array-like) – The coordinates of the atoms as an nx3 array

Returns:

cog – The center of gravity

Return type:

array-like

buildamol.structural.base.center_of_mass(masses, coords)#

Compute the center of gravity of a molecule.

Parameters:

masses (array-like) – The masses of the atoms as an nx1 vector
coords (array-like) – The coordinates of the atoms as an nx3 array

Returns:

cog – The center of gravity

Return type:

array-like

buildamol.structural.base.chain_make_full_id(self)[source]#: A self-adjusting full_id for an Biopython Chain

buildamol.structural.base.compute_angle(atom1, atom2, atom3)[source]#

Compute the angle between three atoms.

Parameters:

atom1 (Bio.PDB.Atom) – The first atom
atom2 (Bio.PDB.Atom) – The second atom
atom3 (Bio.PDB.Atom) – The third atom

Returns:

angle – The angle between the three atoms in degrees

Return type:

float

buildamol.structural.base.compute_dihedral(atom1, atom2, atom3, atom4)[source]#

Compute the dihedral angle between four atoms.

Parameters:

atom1 (Bio.PDB.Atom) – The first atom
atom2 (Bio.PDB.Atom) – The second atom
atom3 (Bio.PDB.Atom) – The third atom
atom4 (Bio.PDB.Atom) – The fourth atom

Returns:

dihedral – The dihedral angle between the four atoms in degrees

Return type:

float

buildamol.structural.base.compute_distance(atom1, atom2)[source]#

Compute the distance between two atoms.

Parameters:

atom1 (Bio.PDB.Atom) – The first atom
atom2 (Bio.PDB.Atom) – The second atom

Returns:

distance – The distance between the two atoms

Return type:

float

buildamol.structural.base.compute_torsional(atom1, atom2, atom3, atom4)#

Compute the dihedral angle between four atoms.

Parameters:

atom1 (Bio.PDB.Atom) – The first atom
atom2 (Bio.PDB.Atom) – The second atom
atom3 (Bio.PDB.Atom) – The third atom
atom4 (Bio.PDB.Atom) – The fourth atom

Returns:

dihedral – The dihedral angle between the four atoms in degrees

Return type:

float

buildamol.structural.base.dihedral_between(coords1, coords2, coords3, coords4)[source]#

Compute the dihedral angle between four points

Parameters:

coords1 (numpy.ndarray) – The coordinates of the first atom
coords2 (numpy.ndarray) – The coordinates of the second atom
coords3 (numpy.ndarray) – The coordinates of the third atom
coords4 (numpy.ndarray) – The coordinates of the fourth atom

Returns:

dihedral – The dihedral angle between the four atoms in degrees

Return type:

float

buildamol.structural.base.distance_between(coord1, coord2)[source]#

Compute the distance between two 3d coordinates.

Parameters:

coord1 (numpy.ndarray) – The first coordinate
coord2 (numpy.ndarray) – The second coordinate

Returns:

distance – The euclidean distance between the two coordinates

Return type:

float

buildamol.structural.base.flip_coords(coords: ndarray, plane_vector: ndarray)[source]#

Flip a set of coordinates around an axis.

Parameters:

coords (array-like) – The coordinates to flip
plane_vector (array-like) – The vector describing the plane to flip around

Returns:

flipped_coords – The flipped coordinates

Return type:

array-like

buildamol.structural.base.flip_molecule(mol, plane_vector: ndarray, center: ndarray = None)[source]#

Flip a molecule around an axis.

Parameters:

mol (Molecule) – The molecule to flip
plane_vector (array-like) – The vector describing the plane to flip around

Returns:

flipped_molecule – The flipped molecule

Return type:

Bio.PDB.Structure

buildamol.structural.base.length_along_axis(coords, axis) → float[source]#

Compute the length of a set of coordinates along an axis.

Parameters:

coords (array-like) – The coordinates of the atoms
axis (array-like) – The axis to compute the length along

Returns:

length – The length of the coordinates along the axis

Return type:

float

buildamol.structural.base.make_empty_structure(id: str = 'empty')[source]#

Make an empty PDB structure with a single model and chain.

Returns:: structure – The empty structure
Return type:: Bio.PDB.Structure

buildamol.structural.base.model_make_full_id(self)[source]#: A self-adjusting full_id for an Biopython Model

buildamol.structural.base.norm_vector(atom1, atom2)[source]#

Compute the normalized vector between two atoms.

Parameters:

atom1 (Bio.PDB.Atom) – The first atom
atom2 (Bio.PDB.Atom) – The second atom

Returns:

vector – The normalized vector between the two atoms

Return type:

numpy.ndarray

buildamol.structural.base.origin = array([0., 0., 0.])#: The origin of the 3D coordinate system

buildamol.structural.base.plane_of_points(points) → ndarray[source]#

Compute the plane vector that best describes the plane defined by a set of points

Parameters:: points (array-like) – The points that define the plane
Returns:: plane – The plane vector
Return type:: np.ndarray

buildamol.structural.base.plane_vector(vec1, vec2)[source]#

Compute the vector of the plane of two vectors.

Parameters:

vec1 (numpy.ndarray) – The first vector
vec2 (numpy.ndarray) – The second vector

Returns:

vector – The norm-vector of the plane of the two vectors

Return type:

numpy.ndarray

buildamol.structural.base.principal_axis(coords: ndarray) → ndarray[source]#

Compute the principle axis of a set of coordinates The principle axis is the eigenvector of the covariance matrix with the largest eigenvalue

Parameters:: coords (array-like) – The coordinates of the atoms
Returns:: axis – The principle axis
Return type:: np.ndarray

buildamol.structural.base.rename_residue(residue: Residue, new_name: str)[source]#

Rename a biopython residue object. This happens in-place.

Parameters:

residue (Bio.PDB.Residue.Residue) – The residue to rename.
new_name (str) – The new name of the residue.

Returns:

residue – The renamed residue.

Return type:

Bio.PDB.Residue.Residue

buildamol.structural.base.residue_make_full_id(self)[source]#: A self-adjusting full_id for an Biopython Residue

buildamol.structural.base.rotate_coords(coords: ndarray, angle: float, axis: ndarray)[source]#

Rotate a set of coordinates around an axis by a given angle.

Parameters:

coords (array-like) – The coordinates to rotate
angle (float) – The angle to rotate by (in radians)
axis (array-like) – The axis to rotate around

Returns:

rotated_coords – The rotated coordinates

Return type:

array-like

buildamol.structural.base.rotate_molecule(molecule, angle: float, axis: ndarray, center: ndarray = None)[source]#

Rotate a molecule around an axis by a given angle.

Parameters:

molecule (Bio.PDB.Structure) – The molecule to rotate
axis (array-like) – The axis to rotate around
angle (float) – The angle to rotate by (in radians)

Returns:

rotated_molecule – The rotated molecule

Return type:

Bio.PDB.Structure

buildamol.structural.base.set_full_id(self, value)[source]#

buildamol.structural.base.superimpose_points(coords: ndarray, points1: tuple, points2: tuple)[source]#

Superimpose two structures by aligning two sets of points. This will place the first point of points1 on the first point of points2 and so on, while transforming the rest of the points accordingly.

Parameters:

coords (array-like) – The coordinates of the atoms to move and align. The coordinates of the participants of Bond1 must be part of the coordinates.
points1 (tuple) – The first set of points. This must be a tuple of two or three coordinates (numpy.ndarray) which are part of the coords.
points2 (tuple) – The second bond. This must be a tuple of two or three coordinates (numpy.ndarray), depending on how many were provided as points1 (the same number of points).

Returns:

new_coords – The new coordinates of the atoms

Return type:

array-like

buildamol.structural.base.vector_between(atom1, atom2)[source]#

Compute the vector between two atoms.

Parameters:

atom1 (Bio.PDB.Atom) – The first atom
atom2 (Bio.PDB.Atom) – The second atom

Returns:

vector – The vector between the two atoms

Return type:

numpy.ndarray

buildamol.structural.base.x_axis = array([1., 0., 0.])#: Unit vector along the x-axis

buildamol.structural.base.xy_plane = array([0., 0., 1.])#: Unit vector normal to the xy-plane

buildamol.structural.base.xz_plane = array([0., 1., 0.])#: Unit vector normal to the xz-plane

buildamol.structural.base.y_axis = array([0., 1., 0.])#: Unit vector along the y-axis

buildamol.structural.base.yz_plane = array([1., 0., 0.])#: Unit vector normal to the yz-plane

buildamol.structural.base.z_axis = array([0., 0., 1.])#: Unit vector along the z-axis

Inferring Structural Properties#

The infer module contains methods for inferring structural properties from a molecule’s atoms and connectivity. Among these are connections, or atom labels.

Inferential structural operations

Functions to infer structural data such as missing atom coordinates, bond connectivity, or atom labels.

class buildamol.structural.infer.AutoLabel(atom_graph)[source]#

Bases: object

A automatic atom labeller

Parameters:: atom_graph (nx.Graph) – The molecule’s atom graph

autolabel()[source]#

Generate labels for the atoms in the molecule

Returns:: A dataframe with the atom objects and their new labels.
Return type:: pd.DataFrame

property carbons#: All carbon atoms in the molecule.

static hydrogen_neighbors(atom)[source]#

Generate automated labels for an atom’s possible hydrogen neighbors.

Parameters:: atom (Atom) – The atom
Returns:: A list of possible hydrogen labels
Return type:: list

Examples

>>> from buildamol import Atom
>>> a = Atom(id="C1")
>>> AutoLabel.hydrogen_neighbors(a)
['H1', 'H11', 'H12', 'H13', 'H14']
>>> a = Atom(id="OXT")
>>> AutoLabel.hydrogen_neighbors(a)
['HOXT', 'HOXT1', 'HOXT2']

class buildamol.structural.infer.Hydrogenator[source]#

Bases: object

A class to automatically add hydrogen atoms to organic molecules.

Note

This is designed specifically to infer hydrogens for organic molecules. So it can infer hydrogen coordinates for CHNOPS atoms, but may not work reliably for non organic molecules.

add_hydrogens(atom, _molecule=None)[source]#: Add hydrogens to one particular atom.

infer_hydrogens(molecule: Molecule, bond_length: float = 1) → Molecule[source]#

Add hydrogen atoms to a molecule.

Parameters:

molecule (buildamol.core.Molecule) – The molecule to add hydrogen atoms to.
bond_length (float) – The bond length to use for the hydrogen atoms.

Returns:

The molecule with hydrogen atoms added.

Return type:

Molecule

linear = <buildamol.structural.geometry.Linear object>#

tetrahedral = <buildamol.structural.geometry.Tetrahedral object>#

trigonal_planar = <buildamol.structural.geometry.TrigonalPlanar object>#

buildamol.structural.infer.acceptable_surplus_charge = 5#

The maximum allowed positive charge that can be left on an atom if no hydrogens can be further removed to balance the charge.

This is used in change_element to prevent the creation of unrealistically charged atoms and thereby unlikely structures.

buildamol.structural.infer.adjust_protonation(molecule, atom, new_charge)[source]#

Adjust the protonation state of an atom in a molecule.

Parameters:

molecule (Molecule) – The molecule to adjust the protonation state in.
atom (Atom) – The atom to adjust the protonation state of.
new_charge (int) – The new charge of the atom.

buildamol.structural.infer.adjust_to_ph(molecule, ph: float | int | tuple, inplace: bool = True, **kwargs)[source]#

Adjust the protonation state of a molecule to suit a specific pH range

Note

This requires that rdkit and molscrub packages are installed!

Parameters:

molecule (Molecule) – The molecule to adjust the protonation state in.
ph (Union(float, int, tuple)) – The pH value or range of pH values to adjust the protonation state to. If a single value is provided, the molecule will be adjusted to that pH. If a tuple is provided, the molecule will be adjusted to the pH range (low, high)
inplace (bool) – Whether to adjust the molecule inplace or return a new molecule.
**kwargs – Any keyword arguments to pass to the molscrub.Scrub class.

Returns:

The molecule with the adjusted protonation state

Return type:

Molecule

buildamol.structural.infer.apply_reference_bonds(structure, _compounds=None)[source]#

Apply bonds according to loaded reference compounds. This will compute a list of tuples with bonded atoms from the same residue. It will not infer residue-residue connections! It is possible to provide a single atom as input structure, in which case all bonds that involve said atom are returned.

Parameters:

structure – The structure to apply the bonds to. This can be any of the following objects which hosts Atoms: - buildamol.Structure - buildamol.Model - buildamol.Chain - buildamol.Residue
_compounds (PDBECompounds) – The reference compounds to use for bond inference. If not provided, the default compounds are used.

Returns:

bonds – A list of tuples of Atoms that are bonded.

Return type:

list

buildamol.structural.infer.atomic_number(element: str)[source]#

Get the atomic number of an element.

Parameters:: element (str) – The element symbol.
Returns:: The atomic number of the element.
Return type:: int

buildamol.structural.infer.atoms_in_area(structure, center, radius)[source]#

Get all atoms in a given area around a center point.

Parameters:

structure (Structure) – The structure to search for atoms.
center (np.ndarray) – The center point of the area to search.
radius (float) – The radius of the area to search.

Yields:

Atom – The atoms in the area.

buildamol.structural.infer.autolabel(molecule)[source]#

Automatically relabel atoms in a structure to match the CHARMM naming scheme. Note, this function is not guaranteed to produce the correct labels in all cases, validation of the labels is recommended.

Parameters:: molecule (buildamol.core.Molecule) – The molecule that holds the atoms to be relabeled. This molecule needs to have bonds assigned or computed.

buildamol.structural.infer.autolabel_atoms(bonds, to_label)[source]#

Automatically relabel a list of atoms to match the CHARMM naming scheme. Note, this function is not guaranteed to produce the correct labels in all cases, validation of the labels is recommended.

Parameters:

bonds (list) – A list of Bond objects that define the connectivity of atoms relevant for the labelling.
to_label (list) – A list of Atom objects to relabel. This must be a subset of the atoms present in the bonds.

Returns:

A dictionary mapping the original Atom objects to their new labels.

Return type:

dict

buildamol.structural.infer.change_bond_order(molecule, atom1, atom2, order)[source]#

Change the bond order between two atoms. This will also adjust the protonation state and add or remove hydrogens if necessary. This function will not, however, adjust the overall geometry of the molecule. It can currently only adjust the local geometry of the atoms involved and their hydrogen partners.

Parameters:

molecule (Molecule) – The molecule to change the bond order in.
atom1 (Atom) – The first atom of the bond.
atom2 (Atom) – The second atom of the bond.
order (int) – The new bond order. This can be either 1, 2, or 3.

buildamol.structural.infer.change_element(atom, new_element: str, _molecule)[source]#: Change the element of an atom and update its connectivity accordingly. This will remove hydrogen atoms if the new element has a lower connectivity, or add them.

buildamol.structural.infer.compute_atom1_from_others(coords2, coords3, coords4, ic)[source]#

Compute the coordinates of the first atom from internal coordinates and the coordinates of the other three.

Parameters:

*coords (array-like) – The coordinates of the other three atoms
ic (InternalCoordinates) – The internal coordinates

Returns:

coords1 – The coordinates of the first atom

Return type:

array-like

buildamol.structural.infer.compute_atom4_from_others(coords1, coords2, coords3, ic)[source]#

Compute the coordinates of the fourth atom from internal coordinates and the coordinates of the other three.

Parameters:

*coords (array-like) – The coordinates of the other three atoms
ic (InternalCoordinates) – The internal coordinates

Returns:

coords4 – The coordinates of the fourth atom

Return type:

array-like

buildamol.structural.infer.compute_internal_coordinates(bonds: list)[source]#

Compute internal coordinates for a structure.

Parameters:: bonds (list) – A list of tuples of atoms that are bonded. The atoms must be Bio.PDB.Atom objects with coordinates.
Returns:: A list of InternalCoordinates
Return type:: list

buildamol.structural.infer.compute_outlier_atoms(residue, f: float = 1.5)[source]#

Compute which atoms of a residue are especially far away from the residues center of mass. This function compute the distances between the center of mass of the residue and its atoms and returns all atoms are further than f * p75 away from the center of mass, where p75 is the 75th percentile of the distances.

Parameters:

residue (Bio.PDB.Residue.Residue) – The residue to compute the outlier atoms for.
f (float) – The factor to multiply the 75th percentile with.

Returns:

outlier_atoms – A list of atoms that are considered outliers.

Return type:

list

buildamol.structural.infer.compute_residue_radius(residue)[source]#

Compute the radius of a residue by computing the distance between its center of mass and the furthest atom.

Parameters:: residue (Bio.PDB.Residue.Residue) – The residue to compute the radius for.
Returns:: radius – The radius of the residue.
Return type:: float

buildamol.structural.infer.find_axial_hydrogens(molecule)[source]#

Find the axial hydrogen atoms in a molecule.

Parameters:: molecule (Molecule) – The molecule to search in
Returns:: The axial hydrogen atoms.
Return type:: list

buildamol.structural.infer.find_axial_substituents(molecule)[source]#

Find all atoms in a molecule that are axial to some ring within the molecule.

Parameters:: molecule (Molecule) – The molecule to search in
Returns:: A list of atoms that are axial to some ring.
Return type:: list

buildamol.structural.infer.find_clashes(molecule, min_dist: float = 1.0, ignore_hydrogens: bool = False)[source]#

Find all clashing atoms in a molecule.

Parameters:

molecule (Molecule) – The molecule to check for clashes.
min_dist (float) – The minimal allowed distance between atoms (in Angstrom).
ignore_hydrogens (bool) – If set to True, hydrogen atoms are ignored.

Yields:

tuple – A tuple of clashing atoms.

buildamol.structural.infer.find_clashes_between(mol_a, mol_b, min_dist: float = 1.0, ignore_hydrogens: bool = False, coarse_precheck: bool = True)[source]#

Find all clashing atoms between two sets of atoms.

Parameters:

mol_a (Molecule) – Two molecules to check for clashes.
mol_b (Molecule) – Two molecules to check for clashes.
min_dist (float) – The minimal allowed distance between atoms (in Angstrom).
ignore_hydrogens (bool) – If set to True, hydrogen atoms are ignored.
coarse_precheck (bool) – If set to True, a coarse-grain precheck is performed on residue-level before checking for clashes on atom-level. This will speed up the process for large molecules but may miss clashes if individual residues are particularly large (e.g. lipids with long tails).

Yields:

tuple – A tuple of clashing atoms.

buildamol.structural.infer.find_equatorial_hydrogens(molecule)[source]#

Find the equatorial hydrogen atoms in a molecule.

Parameters:: molecule (Molecule) – The molecule to search in
Returns:: The equatorial hydrogen atoms.
Return type:: list

buildamol.structural.infer.find_equatorial_substituents(molecule)[source]#

Find all atoms in a molecule that are equatorial to some ring within the molecule.

Parameters:: molecule (Molecule) – The molecule to search in
Returns:: A list of atoms that are equatorial to some ring.
Return type:: list

buildamol.structural.infer.get_axial_hydrogen_neighbor(molecule, atom)[source]#

Get the axial hydrogen atom of a given atom.

Parameters:

molecule (Molecule) – The molecule to search in
atom (Atom) – The atom to search for

Returns:

The axial hydrogen atom (if present, or None if not present)

Return type:

Atom

buildamol.structural.infer.get_axial_neighbor(molecule, atom)[source]#

Get the axial atom of a given atom.

Parameters:

molecule (Molecule) – The molecule to search in
atom (Atom) – The atom to search for

Returns:

The axial atom (if present, or None if not present)

Return type:

Atom

buildamol.structural.infer.get_equatorial_hydrogen_neighbor(molecule, atom)[source]#

Get the equatorial hydrogen atom of a given atom.

Parameters:

molecule (Molecule) – The molecule to search in
atom (Atom) – The atom to search for

Returns:

The equatorial hydrogen atom (if present, or None if not present)

Return type:

Atom

buildamol.structural.infer.get_equatorial_neighbor(molecule, atom)[source]#

Get the equatorial atom of a given atom.

Parameters:

molecule (Molecule) – The molecule to search in
atom (Atom) – The atom to search for

Returns:

The equatorial atom (if present, or None if not present)

Return type:

Atom

buildamol.structural.infer.get_left_hydrogen_neighbor(molecule, atom)[source]#

Get the “left-protruding” hydrogen neighbor of an atom that has two hydrogen neighbors.

Parameters:

molecule (Molecule) – The molecule to search in
atom (Atom) – The atom to search for

Returns:

The left hydrogen atom. If the nomenclature does not apply to the atom (e.g. because it is completely symmetrical on both sides) any of the two hydrogen atoms is returned. If the atom does not have two hydrogen neighbors, None may be returned if the only hydrogen neighbor is not in the correct orientation, otherwise the hydrogen neighbor is returned.

Return type:

Atom

Example

In a molecule: ```

H_B |

CH3 – C – CH2 – OH

H_A

``` We want to get the left and right hydrogens of the central C atom (labeled only C). Using part of the logic behind R/S nomenclature for chiral centers, we prioritize the non-H neighbors and then rotate the molecule such that the highest order non-H neighbor points toward the user and the other non-H neighbor points away. The left and right hydrogens are then determined based on their orientation in this view.

In this case, the left hydrogen is H_A and the right hydrogen is H_B.

buildamol.structural.infer.get_right_hydrogen_neighbor(molecule, atom)[source]#

Get the “right-protruding” hydrogen neighbor of an atom that has two hydrogen neighbors.

Parameters:

molecule (Molecule) – The molecule to search in
atom (Atom) – The atom to search for

Returns:

The right hydrogen atom. If the nomenclature does not apply to the atom (e.g. because it is completely symmetrical on both sides) any of the two hydrogen atoms is returned. If the atom does not have two hydrogen neighbors, None may be returned if the only hydrogen neighbor is not in the correct orientation, otherwise the hydrogen neighbor is returned.

Return type:

Atom

Example

In a molecule: ```

H_B |

CH3 – C – CH2 – OH

H_A

``` We want to get the left and right hydrogens of the central C atom (labeled only C). Using part of the logic behind R/S nomenclature for chiral centers, we prioritize the non-H neighbors and then rotate the molecule such that the highest order non-H neighbor points toward the user and the other non-H neighbor points away. The left and right hydrogens are then determined based on their orientation in this view.

In this case, the left hydrogen is H_A and the right hydrogen is H_B.

buildamol.structural.infer.has_free_valence(atom, bonds, needed: int = 1)[source]#

Check if an atom has free valence.

Parameters:

atom (Atom) – The atom to check for free valence.
bonds (list) – A list of Bond objects that connect the atom to other atoms.
needed (int) – The number of free valences needed.

Returns:

True if the atom has free valence, False otherwise.

Return type:

bool

buildamol.structural.infer.infer_bond_orders(molecule)[source]#

Infer the bond orders using the registered higher order functional groups (i.e. functional groups with bonds of order > 1).

Parameters:: molecule (Molecule) – The molecule to infer the bond orders for.

buildamol.structural.infer.infer_bonds(structure, bond_length: float = None, restrict_residues: bool = True)[source]#

Generate a connectivity graph by inferring bonds from the distance between atoms.

Parameters:

structure (Bio.PDB.Structure.Structure) – The structure to infer the bonds from. This can be any of the following objects which host Residues: - Bio.PDB.Structure - Bio.PDB.Model - Bio.PDB.Chain - Bio.PDB.Residue
bond_length (float or tuple) – The maximum distance between two atoms to be considered a bond. If a tuple is provided, it specifies the minimal and maximal distances between atoms.
restrict_residues (bool) – If set to True, only bonds between atoms of the same residue will be considered.

Returns:

bonds – The connectivity graph of the molecule, storing tuples of Bio.PDB.Atom objects.

Return type:

list

buildamol.structural.infer.infer_residue_connections(structure, bond_length: float = None, triplet: bool = False)[source]#

Infer the connectivity graph of residues from the distances between atoms of residue pairs. This will establish only bonds between close-by atoms from non-identical residues.

Parameters:

structure (Bio.PDB.Structure.Structure) – The structure to infer the bonds from. This can be any of the following objects which host at least two Residues: - Bio.PDB.Structure - Bio.PDB.Model - Bio.PDB.Chain
bond_length (float) – The maximum distance between two atoms to be considered a bond.
triplet (bool) – If True, bonds between atoms of the same residue are also added, if one of the atoms is considered bonded to another residue. Like this residue connections are described not by a single bond with a pair of atoms, but two bonds with a triplet of atoms.

Returns:

bonds – A list of tuples of Atoms from different Residues that are bonded.

Return type:

list

buildamol.structural.infer.infer_surface_residues(structure, cutoff: int = 75, fraction: float = None)[source]#

Infer residues that are likely to be on the surface of the structure using the Solvent accessible surface area (SASA) of the structure.

Parameters:

structure (Bio.PDB.Structure.Structure) – The structure to infer the surface residues from.
n_points (int) – The number of points to sample on the surface of the structure.
cutoff (int) – The cutoff to use for classifying residues as surface residues.
fraction (float) – The fraction of residues to classify as surface residues. In this case, the cutoff is adjusted to match the fraction of residues.

Returns:

surface_residues – A list of residues that are likely to be on the surface of the structure.

Return type:

list

buildamol.structural.infer.relabel_hydrogens(molecule)[source]#

Relabel hydrogen atoms in a structure to match the CHARMM naming scheme.

Parameters:: molecule (buildamol.structural.base.Molecule) – The molecule that holds the atoms to be relabeled. This molecule needs to have bonds assigned or computed.

buildamol.structural.infer.sample_atoms_around_reference(reference_coord: ndarray, candidates: ndarray, num_samples: int, max_radius: float = 10.0)[source]#

Sample atoms around a reference coordinate. Such that they are spacially evenly distributed around the central reference coordinates.

Parameters:

reference_coord (np.ndarray) – The reference coordinate to sample around.
candidates (np.ndarray) – The atoms to sample from. This must be an array of Atom objects.
num_samples (int) – The number of samples to generate.
max_radius (float) – The maximum radius to sample for.

Returns:

samples – The sampled atoms.

Return type:

np.ndarray

buildamol.structural.infer.split_into_contiguous_residues(molecule, target_residues: list = None)[source]#

In case a molecule contains residues that include multiple contiguous atom groups, split these into multiple residues. Note that the residues that are split will be removed from the molecule!

Parameters:

molecule (Molecule) – The molecule to split into contiguous residues.
target_residues (list) – A list of residues to split. If None, all residues will be split.

buildamol.structural.infer.vet_structure(molecule, clash_range: tuple = (0.6, 2.7), angle_range: tuple = (90, 180)) → bool[source]#

Check for basic structure integrity. This will return False if there are clashes within the structure, or invalid angles.

Parameters:

molecule (Molecule) – A BuildAMol Molecule
clash_range (tuple) – The minimal and maximal allowed distances between bonded atoms (in Angstrom). The lower limit is also used for non-bonded atoms.
angle_range (tuple) – The minimal and maximal allowed angle between a triplet of adjacent bonded atoms (in degrees).

Returns:

True if the structure is free from any obstacles, False otherwise.

Return type:

bool

Reactivities#

The reactivity module contains methods for defining reactivities of atom groups (i.e. functional groups) in a molecule in order to guide connectivity between fragments. These reactivities can be used in conjunction with the Reaction class to define how molecules should react with each other. They are the successors of the older FunctionalGroup classes.

Reactivities

class buildamol.structural.reactivity.Aldehyde(*args, **kwargs)[source]#

Bases: Reactivity

Predefined reactivity pattern for aldehyde groups Can act as electrophile.

electrophile_linker(mol: Molecule)[source]#

nucleophile_linker(mol)[source]#

class buildamol.structural.reactivity.AlkylHalide(*args, **kwargs)[source]#

Bases: Reactivity

Predefined reactivity pattern for alkyl halides (F, Cl, Br, I) Can act as electrophile.

electrophile_deleter(atom: Atom, mol: Molecule)[source]#

electrophile_linker(mol: Molecule)[source]#

nucleophile_linker(mol: Molecule)[source]#

class buildamol.structural.reactivity.Amide(*args, **kwargs)[source]#

Bases: Reactivity

Predefined reactivity pattern for amide groups Can act as both nucleophile and electrophile.

electrophile_deleter(atom: Atom, mol: Molecule)[source]#

electrophile_linker(mol: Molecule)[source]#

nucleophile_linker(mol: Molecule)[source]#

class buildamol.structural.reactivity.Amine(*args, **kwargs)[source]#

Bases: Reactivity

Predefined reactivity pattern for amine groups Can act as both nucleophile and electrophile.

electrophile_deleter(atom: Atom, mol: Molecule)[source]#

electrophile_linker(mol: Molecule)[source]#

nucleophile_linker(mol: Molecule)[source]#

class buildamol.structural.reactivity.Carboxyl(*args, **kwargs)[source]#

Bases: Reactivity

Predefined reactivity pattern for carboxylic acids Can act as both nucleophile and electrophile.

electrophile_deleter(atom: Atom, mol: Molecule)[source]#

electrophile_linker(mol: Molecule)[source]#

nucleophile_linker(mol: Molecule)[source]#

class buildamol.structural.reactivity.Ester(*args, **kwargs)[source]#

Bases: Carboxyl

Predefined reactivity pattern for ester groups Can act as electrophile.

nucleophile_linker(mol)[source]#

class buildamol.structural.reactivity.Hydroxyl(*args, **kwargs)[source]#

Bases: Reactivity

Predefined reactivity pattern for hydroxyl groups Can act as both nucleophile and electrophile.

electrophile_deleter(atom: Atom, mol: Molecule)[source]#

electrophile_linker(mol: Molecule)[source]#

nucleophile_linker(mol: Molecule)[source]#

class buildamol.structural.reactivity.Ketone(*args, **kwargs)[source]#

Bases: Reactivity

Predefined reactivity pattern for ketone groups Can act as electrophile. The deleter function will remove the smaller of the two alkyl substituents or the one with more heteroatoms close-by.

electrophile_deleter(atom: Atom, mol: Molecule)[source]#

electrophile_linker(mol: Molecule)[source]#

nucleophile_linker(mol)[source]#

class buildamol.structural.reactivity.Phosphate(*args, **kwargs)[source]#

Bases: Reactivity

Predefined reactivity pattern for phosphate groups Can act as both nucleophile and electrophile.

electrophile_deleter(atom: Atom, mol: Molecule)[source]#

electrophile_linker(mol: Molecule)[source]#

nucleophile_linker(mol: Molecule)[source]#

exception buildamol.structural.reactivity.ReactionError[source]#: Bases: Exception

class buildamol.structural.reactivity.Reactivity(*args, **kwargs)[source]#

Bases: object

Define a reactivity pattern for a molecule or functional group by specifying functions that identify nucleophilic and electrophilic atoms, as well as optional functions to determine which atoms to delete during the reaction. The class also allows for steric constraints to be applied when selecting reactive sites.

Parameters:

nucleophile_linker (callable, optional) – A function that takes a Molecule and returns an Atom object representing the nucleophilic site (i.e. the atom in the source molecule that will form a bond with the target molecule).
electrophile_linker (callable, optional) – A function that takes a Molecule and returns a single or list of multiple Atom objects representing the electrophilic sites (i.e. the atoms in the target molecule that can form a bond with the source molecule).
nucleophile_deleter (callable, optional) – A function that takes an Atom and its parent Molecule (in that order) and returns an Atom or list thereof representing the atoms to be deleted from the source molecule when the nucleophilic atom forms a bond. If not provided, the default behavior is to delete a hydrogen atom bonded to the nucleophilic atom.
electrophile_deleter (callable, optional) – A function that takes an Atom and its parent Molecule (in that order) and returns an Atom or list thereof representing the atoms to be deleted from the target molecule when the electrophilic atom forms a bond. If not provided, the default behavior is to delete a hydrogen atom bonded to the electrophilic atom.

as_electrophile(serves_target: bool)[source]#

Get the electrophilic linker and deleter functions.

Parameters:: serves_target (bool) – If True, the linker function will return all identified nucleophilic sites. If False, it will return only the most accessible site based on steric constraints.

as_nucleophile(serves_target: bool)[source]#

Get the nucleophilic linker and deleter functions.

Parameters:: serves_target (bool) – If True, the linker function will return all identified nucleophilic sites. If False, it will return only the most accessible site based on steric constraints.

find_atoms(mol: Molecule, role: str, serves_target: bool)[source]#

Find reactive atoms in the given molecule based on the specified reactivity pattern.

Parameters:

mol (Molecule) – The molecule in which to find reactive atoms.
serves_target (bool) – If True, the linker function will return all identified nucleophilic sites. If False, it will return only the most accessible site based on steric constraints.
role (str, optional) – Specify whether to find ‘nucleophile’ or ‘electrophile’ atoms.

Returns:

linkers (list of Atom or Atom) – The identified reactive atoms based on the specified role and steric constraints.
deleters (list of Atom or Atom) – The atoms to be deleted during the reaction based on the specified role.

find_electrophilic_atoms(mol: Molecule, serves_target: bool)[source]#

Find electrophilic atoms in the given molecule based on the specified reactivity pattern.

Parameters:

mol (core.Molecule) – The molecule in which to find electrophilic atoms.
serves_target (bool) – If True, the linker function will return all identified nucleophilic sites. If False, it will return only the most accessible site based on steric constraints.

Returns:

linkers (list of base_classes.Atom or base_classes.Atom) – The identified electrophilic atoms based on steric constraints.
deleters (list of base_classes.Atom or base_classes.Atom) – The atoms to be deleted during the reaction.

find_nucleophilic_atoms(mol: Molecule, serves_target: bool)[source]#

Find nucleophilic atoms in the given molecule based on the specified reactivity pattern.

Parameters:

mol (core.Molecule) – The molecule in which to find nucleophilic atoms.
serves_target (bool) – If True, the linker function will return all identified nucleophilic sites. If False, it will return only the most accessible site based on steric constraints.

Returns:

linkers (list of base_classes.Atom or base_classes.Atom) – The identified nucleophilic atoms based on steric constraints.
deleters (list of base_classes.Atom or base_classes.Atom) – The atoms to be deleted during the reaction.

set_reactivity(nucleophile_linker: callable = None, electrophile_linker: callable = None, nucleophile_deleter: callable = None, electrophile_deleter: callable = None)[source]#

Set or update the reactivity functions for the nucleophile and electrophile. This is an in-place operation. Use with_reactivity to create a new instance with modified reactivity.

Parameters:

nucleophile_linker (callable, optional) – A function that takes a Molecule and returns an Atom object representing the nucleophilic site (i.e. the atom in the source molecule that will form a bond with the target molecule).
electrophile_linker (callable, optional) – A function that takes a Molecule and returns a single or list of multiple Atom objects representing the electrophilic sites (i.e. the atoms in the target molecule that can form a bond with the source molecule).
nucleophile_deleter (callable, optional) – A function that takes an Atom and its parent Molecule (in that order) and returns an Atom or list thereof representing the atoms to be deleted from the source molecule when the nucleophilic atom forms a bond. If not provided, the default behavior is to delete a hydrogen atom bonded to the nucleophilic atom.
electrophile_deleter (callable, optional) – A function that takes an Atom and its parent Molecule (in that order) and returns an Atom or list thereof representing the atoms to be deleted from the target molecule when the electrophilic atom forms a bond. If not provided, the default behavior is to delete a hydrogen atom bonded to the electrophilic atom.

set_steric_constraints(distance: float = 4.0, max_neighbors: int = None, n_target_sites: int = 'all', func: callable = None)[source]#

Specify steric constraints to be applied when selecting reactive sites. Note that these are shared between the nucleophile and electrophile. If different constraints are needed, directly specify them in the linker/deleter functions.

Parameters:

distance (float, optional) – The distance (in angstroms) within which to count neighboring atoms for steric hindrance. Default is 4.0 Å.
max_neighbors (int, optional) – The maximum number of neighboring atoms allowed within the specified distance for a site to be considered accessible. If None, no limit is applied. Default is None.
n_target_sites (int or "all", optional) – The number of the most accessible sites to return after applying steric constraints. If “all”, all sites that meet the steric criteria are returned. Default is “all”.
func (callable, optional) – A custom function that takes a Molecule and a list of Atom objects (in that order) and returns a filtered list of Atom objects based on custom steric criteria. If provided, this function is applied before the default steric constraints. But it will not override the default steric constraints, which will still be applied after this function.

with_reactivity(nucleophile_linker: callable = None, electrophile_linker: callable = None, nucleophile_deleter: callable = None, electrophile_deleter: callable = None)[source]#

Create a new instance of the class with modified reactivity functions. This does not modify the original instance.

Parameters:

nucleophile_linker (callable, optional) – A function that takes a Molecule and returns an Atom object representing the nucleophilic site (i.e. the atom in the source molecule that will form a bond with the target molecule).
electrophile_linker (callable, optional) – A function that takes a Molecule and returns a single or list of multiple Atom objects representing the electrophilic sites (i.e. the atoms in the target molecule that can form a bond with the source molecule).
nucleophile_deleter (callable, optional) – A function that takes an Atom and its parent Molecule (in that order) and returns an Atom or list thereof representing the atoms to be deleted from the source molecule when the nucleophilic atom forms a bond. If not provided, the default behavior is to delete a hydrogen atom bonded to the nucleophilic atom.
electrophile_deleter (callable, optional) – A function that takes an Atom and its parent Molecule (in that order) and returns an Atom or list thereof representing the atoms to be deleted from the target molecule when the electrophilic atom forms a bond. If not provided, the default behavior is to delete a hydrogen atom bonded to the electrophilic atom.

class buildamol.structural.reactivity.Thiol(*args, **kwargs)[source]#

Bases: Reactivity

Predefined reactivity pattern for thiol groups Can act as both nucleophile and electrophile.

electrophile_deleter(atom: Atom, mol: Molecule)[source]#

electrophile_linker(mol: Molecule)[source]#

nucleophile_linker(mol: Molecule)[source]#

Molecular Geometries#

The geometry module contains methods to place atoms in a molecule in a specific geometry. Defined are the basic geometries: linear, trigonal planar, tetrahedral, trigonal bipyramidal, and octahedral.

Molecular Geometries

Geometric units for elemental molecular geometry

class buildamol.structural.geometry.Geometry[source]#

Bases: object

The base class for geometries

angle = -1#

apply(atoms: list, bonds: list = None, **kwargs)[source]#

Automatically apply coordinate generation to a list of atom objects

Parameters:

atoms (list) – The list of atoms to apply the geometry to. Note that there must not be more atoms than the geometry can generate coordinates for. Note that in each case the central atom must be the first atom in the list. Other atoms (planar or axial, where applicable) must come after. Be sure to pass a ‘direction’ argument to specify the inference direction if the points are ambiguous.
bonds (list) – A list of tuples of the same atoms as in ‘atoms’ that are bonded. This can be used to adjust the bond lengths after the geometry is applied.
**kwargs – Additional keyword arguments to pass to the coordinate generation function.

Returns:

The list of atoms with the new coordinates applied.

Return type:

list

fill_hydrogens(*atoms, make_bonds: bool = True, **kwargs)[source]#

Fill the geometry with hydrogen atoms where empty coordinates are found

Parameters:

atoms (list) – The list of atoms to apply the geometry to. Note that there must not be more atoms than the geometry can generate coordinates for. Note that in each case the central atom must be the first atom in the list. Other atoms (planar or axial, where applicable) must come after. Be sure to pass a ‘direction’ argument to specify the inference direction if the points are ambiguous.
make_bonds (bool) – If True, bond objects will also be returned connecting the central atom to the other atoms (provided or newly made).
**kwargs – Additional keyword arguments to pass to the coordinate generation function.

Returns:

atoms (list) – The list of atoms with the new coordinates applied and hydrogens added where necessary.
bonds (list) – A list of Bonds of the same atoms as in ‘atoms’ that are bonded. Or None if ‘make_bonds’ is False.

make_and_apply(atoms_to_make_from: list, atoms_to_apply_to: list, **kwargs)[source]#

Automatically make and apply the geometry to a list of atom objects

Parameters:

atoms_to_make_from (list) – The list of atoms to make the geometry from. Note that there must not be more atoms than the geometry can generate coordinates for. Note that in each case the central atom must be the first atom in the list. Other atoms (planar or axial, where applicable) must come after. Be sure to pass a ‘direction’ argument to specify the inference direction if the points are ambiguous.
atoms_to_apply_to (list) – The list of atoms to apply the geometry to. Note that there must not be more atoms than the geometry can generate coordinates for. Note that in each case the central atom must be the first atom in the list. Other atoms (planar or axial, where applicable) must come after.
**kwargs – Additional keyword arguments to pass to the coordinate generation function.

make_coords(**kwargs)[source]#: Make the coordinates of the geometry

max_points = -1#

size = -1#

class buildamol.structural.geometry.Linear(bond_length=1.2)[source]#

Bases: Geometry

Linear geometry for Sp1 hybridized atoms (or atoms with 2 substituents)

angle = 3.141592653589793#

make_coords(*coords, length: float = None, **kwargs)[source]#

Make the coordinates of a line

Parameters:

coords (array-like) – The coordinates of the atoms that define the line The first atom is the center of the line and the other 2 atoms follow.
float (float) – The bond length to use for the line. By default the bond length is either the default value or the distance between center and first other point (unless specified using this argument).

Returns:

The coordinates of the line with center at the 0th index and the other 2 atoms following. Provided points always precede the ones that were generated.

Return type:

array-like

make_coords_from_one(center, length: float = None)[source]#

Get the coordinates of a line

Parameters:

center (Atom or array-like) – The center of the line
float (float) – The bond length to use for the line. If not provided the default bond length is used.

Returns:

The coordinates of the line with center at the 0th index and the other 2 atoms following.

Return type:

array-like

make_coords_from_two(center, other, length: float = None)[source]#

Get the coordinates of a line

Parameters:

center (Atom or array-like) – The center of the line
other (Atom or array-like) – The other atom to define one axis of the line
float (float) – The bond length to use for the line. If not provided the distance between center and other is used.

Returns:

The coordinates of the line with center at the 0th index and other the 1st index, and the remaining atom following. Provided points always precede the ones that were generated. E.g. other will be at index 1.

Return type:

array-like

max_points = 2#

size = 3#

class buildamol.structural.geometry.Octahedral(bond_length=1.2)[source]#

Bases: Geometry

Octahedral geometry for Sp3d2 hybridized atoms (or atoms with 6 substituents)

angle = 1.5707963267948966#

make_coords(*coords, length: float = None, direction: str = None)[source]#

Make the coordinates of a trigonal bipyramidal

Parameters:

coords (array-like) – The coordinates of the atoms that define the trigonal bipyramidal The first atom is the center of the trigonal bipyramidal and two more atoms may follow.
float (float) – The bond length to use for the trigonal bipyramidal. By default the bond length is either the default value or the distance between center and first other point (unless specified using this argument).
direction (str) – If the points are ambiguous with respect to the axial and planar atoms, the direction can be specified. This can be either “axial”, “planar”, or “mixed”.

Returns:

The coordinates of the trigonal bipyramidal with center at the 0th index and the other 6 atoms following, where first come the planar ones, then the axial ones. Points that were provided always precede the ones that were generated.

Return type:

array-like

make_coords_from_one(center, length: float = None)[source]#

Get the coordinates of a trigonal bipyramidal

Parameters:

center (Atom or array-like) – The center of the trigonal bipyramidal
float (float) – The bond length to use for the trigonal bipyramidal. If not provided the default bond length is used.

Returns:

The coordinates of the trigonal bipyramidal with center at the 0th index and the other 5 atoms following, where first come the planar ones, then the axial ones.

Return type:

array-like

make_coords_from_three_mixed(center, other1, other2, length: float = None)[source]#

Make the coordinates of a trigonal bipyramidal given mixed nodes

Parameters:

center (Atom or array-like) – The center of the trigonal bipyramidal
other1 (Atom or array-like) – The first node (planar)
other2 (Atom or array-like) – The second node (axial)
float (float) – The bond length to use for the trigonal bipyramidal. If not provided the distance between other1 and other2 is used.

Returns:

The coordinates of the trigonal bipyramidal with center at the 0th index and the other 5 atoms following, where first come the planar ones, then the axial ones. Provided points always precede the ones that were generated. E.g. other1 will be at index 1 and other2 will be at index 2.

Return type:

array-like

make_coords_from_three_planar(center, other1, other2, length: float = None)[source]#

Make the coordinates of a trigonal bipyramidal given the planar nodes

Parameters:

other1 (Atom or array-like) – The first planar node
other2 (Atom or array-like) – The second planar node
float (float) – The bond length to use for the trigonal bipyramidal. If not provided the distance between other1 and other2 is used.

Returns:

The coordinates of the trigonal bipyramidal with center at the 0th index and the other 5 atoms following, where first come the planar ones, then the axial ones. Provided points always precede the ones that were generated. E.g. other1 and other2 will be at the 1st and 2nd index.

Return type:

array-like

make_coords_from_two_axial(center, other, length: float = None)[source]#

Make the coordinates of a trigonal bipyramidal given the central node and an axial node (node that is in the linear axis with the central node)

Parameters:

center (Atom or array-like) – The center of the trigonal bipyramidal
other (Atom or array-like) – The axial node
float (float) – The bond length to use for the trigonal bipyramidal. If not provided the distance between center and other is used.

Returns:

The coordinates of the trigonal bipyramidal with center at the 0th index and the other 6 atoms following, where first come the planar ones, then the axial ones. Provided points always precede the ones that were generated. E.g. center and other will be at the 0th and 1st index.

Return type:

array-like

make_coords_from_two_planar(center, other, length: float = None)[source]#

Make the coordinates of a trigonal bipyramidal given the central node and a planar node (node that is in the plane with the central node)

Parameters:

center (Atom or array-like) – The center of the trigonal bipyramidal
other (Atom or array-like) – The planar node
float (float) – The bond length to use for the trigonal bipyramidal. If not provided the distance between center and other is used.

Returns:

The coordinates of the trigonal bipyramidal with center at the 0th index and the other 5 atoms following, where first come the planar ones, then the axial ones. Provided points always precede the ones that were generated. E.g. other will be at the 1st index.

Return type:

array-like

max_points = 3#

size = 7#

class buildamol.structural.geometry.SquarePlanar(bond_length=1.2)[source]#

Bases: Geometry

Square Planar geometry (or partial octahedral without axial atoms) (has 4 substituents)

angle = 1.5707963267948966#

make_coords(*coords, length: float = None, **kwargs)[source]#

Make the coordinates of a square planar

Parameters:

coords (array-like) – The coordinates of the atoms that define the square planar The first atom is the center of the square planar and two more atoms may follow.
float (float) – The bond length to use for the square planar. By default the bond length is either the default value or the distance between center and first other point (unless specified using this argument).

Returns:

The coordinates of the square planar with center at the 0th index and the other 4 atoms following. Provided points always precede the ones that were generated.

Return type:

array-like

make_coords_from_one(center, length: float = None)[source]#

Get the coordinates of a square planar

Parameters:

center (Atom or array-like) – The center of the square planar
float (float) – The bond length to use for the square planar. If not provided the default bond length is used.

Returns:

The coordinates of the square planar with center at the 0th index and the other 5 atoms following, where first come the planar ones, then the axial ones.

Return type:

array-like

make_coords_from_three(center, other1, other2, length: float = None)[source]#

Make the coordinates of a square planar given the two other nodes

Parameters:

other1 (Atom or array-like) – The first planar node
other2 (Atom or array-like) – The second planar node
float (float) – The bond length to use for the square planar. If not provided the distance between other1 and other2 is used.

Returns:

The coordinates of the square planar with center at the 0th index and the other 4 atoms following. Provided points always precede the ones that were generated. E.g. other1 and other2 will be at the 1st and 2nd index.

Return type:

array-like

make_coords_from_two(center, other, length: float = None)[source]#

Make the coordinates of a square planar given the central node and another node

Parameters:

center (Atom or array-like) – The center of the square planar
other (Atom or array-like) – The planar node
float (float) – The bond length to use for the square planar. If not provided the distance between center and other is used.

Returns:

The coordinates of the square planar with center at the 0th index and the other 4 atoms following. Provided points always precede the ones that were generated. E.g. other will be at the 1st index.

Return type:

array-like

max_points = 3#

size = 5#

class buildamol.structural.geometry.Tetrahedral(bond_length=1.2)[source]#

Bases: Geometry

Tetrahedral geometry for Sp3 hybridized atoms (or atoms with 4 substituents)

angle = np.float64(2.0943951023931953)#

dihedral = np.float64(1.911135530933791)#

make_coords(*coords, length: float = None, **kwargs)[source]#

Make the coordinates of a tetrahedron

Parameters:

coords (array-like) – The coordinates of the atoms that define the tetrahedron The first atom is the center of the tetrahedron and the other 4 atoms follow.
float (float) – The bond length to use for the tetrahedron. By default the bond length is either the default value or the distance between center and first other point (unless specified using this argument).

Returns:

The coordinates of the tetrahedron with center at the 0th index and the other 4 atoms following. Provided points always precede the ones that were generated.

Return type:

array-like

make_coords_from_one(center, length: float = None)[source]#

Get the coordinates of a tetrahedron

Parameters:

center (Atom or array-like) – The center of the tetrahedron
float (float) – The bond length to use for the tetrahedron. If not provided the default bond length is used.

Returns:

The coordinates of the tetrahedron with center at the 0th index and the other 4 atoms following.

Return type:

array-like

make_coords_from_three(center, other1, other2, length: float = None)[source]#

Get the coordinates of a tetrahedron

Parameters:

center (Atom or array-like) – The center of the tetrahedron
other1 (Atom or array-like) – The first atom to define one axis of the tetrahedron
other2 (Atom or array-like) – The second atom to define one axis of the tetrahedron
float (float) – The bond length to use for the tetrahedron. If not provided the distance between center and other1 is used.

Returns:

The coordinates of the tetrahedron with center at the 0th index and the other 4 atoms following. Provided points always precede the ones that were generated. E.g. other1 will be at index 1 and other2 at index 2.

Return type:

array-like

make_coords_from_two(center, other, length: float = None)[source]#

Get the coordinates of a tetrahedron

Parameters:

center (Atom or array-like) – The center of the tetrahedron
other (Atom or array-like) – The other atom to define one axis of the tetrahedron
float (float) – The bond length to use for the tetrahedron. If not provided the distance between center and other is used.

Returns:

The coordinates of the tetrahedron with center at the 0th index and other the 1st index, and remaing 3 atoms following. Provided points always precede the ones that were generated. E.g. other will be at index 1.

Return type:

array-like

max_points = 3#

size = 5#

class buildamol.structural.geometry.TrigonalBipyramidal(bond_length=1.2)[source]#

Bases: Geometry

Trigonal Bipyramidal geometry for Sp3d hybridized atoms (or atoms with 5 substituents)

angle = np.float64(2.0943951023931953)#

make_coords(*coords, length: float = None, direction: str = None)[source]#

Make the coordinates of a trigonal bipyramidal

Parameters:

coords (array-like) – The coordinates of the atoms that define the trigonal bipyramidal The first atom is the center of the trigonal bipyramidal and two more atoms may follow.
float (float) – The bond length to use for the trigonal bipyramidal. By default the bond length is either the default value or the distance between center and first other point (unless specified using this argument).
direction (str) – If the points are ambiguous with respect to the axial and planar atoms, the direction can be specified. This can be either “axial”, “planar”, or “mixed”.

Returns:

The coordinates of the trigonal bipyramidal with center at the 0th index and the other 5 atoms following, where first come the planar ones, then the axial ones. Points that were provided always precede the ones that were generated.

Return type:

array-like

make_coords_from_one(center, length: float = None)[source]#

Get the coordinates of a trigonal bipyramidal

Parameters:

center (Atom or array-like) – The center of the trigonal bipyramidal
float (float) – The bond length to use for the trigonal bipyramidal. If not provided the default bond length is used.

Returns:

The coordinates of the trigonal bipyramidal with center at the 0th index and the other 5 atoms following, where first come the planar ones, then the axial ones.

Return type:

array-like

make_coords_from_three_mixed(center, other1, other2, length: float = None)[source]#

Make the coordinates of a trigonal bipyramidal given mixed nodes

Parameters:

center (Atom or array-like) – The center of the trigonal bipyramidal
other1 (Atom or array-like) – The first node (planar)
other2 (Atom or array-like) – The second node (axial)
float (float) – The bond length to use for the trigonal bipyramidal. If not provided the distance between other1 and other2 is used.

Returns:

The coordinates of the trigonal bipyramidal with center at the 0th index and the other 5 atoms following, where first come the planar ones, then the axial ones. Provided points always precede the ones that were generated. E.g. other1 will be at index 1 and other2 at index 2.

Return type:

array-like

make_coords_from_three_planar(center, other1, other2, length: float = None)[source]#

Make the coordinates of a trigonal bipyramidal given the planar nodes

Parameters:

other1 (Atom or array-like) – The first planar node
other2 (Atom or array-like) – The second planar node
float (float) – The bond length to use for the trigonal bipyramidal. If not provided the distance between other1 and other2 is used.

Returns:

The coordinates of the trigonal bipyramidal with center at the 0th index and the other 5 atoms following, where first come the planar ones, then the axial ones. Provided points always precede the ones that were generated. E.g. other1 will be at index 1 and other2 at index 2.

Return type:

array-like

make_coords_from_two_axial(center, other, length: float = None)[source]#

Make the coordinates of a trigonal bipyramidal given the central node and an axial node (node that is in the linear axis with the central node)

Parameters:

center (Atom or array-like) – The center of the trigonal bipyramidal
other (Atom or array-like) – The axial node
float (float) – The bond length to use for the trigonal bipyramidal. If not provided the distance between center and other is used.

Returns:

The coordinates of the trigonal bipyramidal with center at the 0th index and the other 5 atoms following, where first come the planar ones, then the axial ones. Provided points always precede the ones that were generated. E.g. other will be at index 1.

Return type:

array-like

make_coords_from_two_planar(center, other, length: float = None)[source]#

Make the coordinates of a trigonal bipyramidal given the central node and a planar node (node that is in the plane with the central node)

Parameters:

center (Atom or array-like) – The center of the trigonal bipyramidal
other (Atom or array-like) – The planar node
float (float) – The bond length to use for the trigonal bipyramidal. If not provided the distance between center and other is used.

Returns:

The coordinates of the trigonal bipyramidal with center at the 0th index and the other 5 atoms following, where first come the planar ones, then the axial ones. Provided points always precede the ones that were generated. E.g. other will be at index 1.

Return type:

array-like

max_points = 3#

size = 6#

class buildamol.structural.geometry.TrigonalPlanar(bond_length=1.2)[source]#

Bases: Geometry

Planar geometry for Sp2 hybridized atoms (or atoms with 3 substituents)

angle = np.float64(2.0943951023931953)#

make_coords(*coords, length: float = None, **kwargs)[source]#

Make the coordinates of a planar triangle

Parameters:

coords (array-like) – The coordinates of the atoms that define the planar triangle The first atom is the center of the planar triangle and the other 3 atoms follow.
float (float) – The bond length to use for the planar triangle . By default the bond length is either the default value or the distance between center and first other point (unless specified using this argument).

Returns:

The coordinates of the planar triangle with center at the 0th index and the other 3 atoms following. Provided points always precede the ones that were generated.

Return type:

array-like

make_coords_from_one(center, length: float = None)[source]#

Get the coordinates of a planar triangle

Parameters:

center (Atom or array-like) – The center of the planar triangle
float (float) – The bond length to use for the planar triangle . If not provided the default bond length is used.

Returns:

The coordinates of the planar triangle with center at the 0th index and the other 3 atoms following.

Return type:

array-like

make_coords_from_three(center, other1, other2, length: float = None)[source]#

Get the coordinates of a planar triangle

Parameters:

center (Atom or array-like) – The center of the planar triangle
other1 (Atom or array-like) – The first atom to define one axis of the planar triangle
other2 (Atom or array-like) – The second atom to define one axis of the planar triangle
float (float) – The bond length to use for the planar triangle . If not provided the distance between center and other1 is used.

Returns:

The coordinates of the planar triangle with center at the 0th index and the other 3 atoms following. Provided points always precede the ones that were generated. E.g. other1 will be at index 1 and other2 at index 2.

Return type:

array-like

make_coords_from_two(center, other, length: float = None)[source]#

Get the coordinates of a planar triangle

Parameters:

center (Atom or array-like) – The center of the planar triangle
other (Atom or array-like) – The other atom to define one axis of the planar triangle
float (float) – The bond length to use for the planar triangle . If not provided the distance between center and other is used.

Returns:

The coordinates of the planar triangle with center at the 0th index and other the 1st index, and remaing 2 atoms following. Provided points always precede the ones that were generated. E.g. other will be at index 1.

Return type:

array-like

max_points = 3#

size = 4#

buildamol.structural.geometry.linear = <buildamol.structural.geometry.Linear object>#: The default linear geometry

buildamol.structural.geometry.octahedral = <buildamol.structural.geometry.Octahedral object>#: The default octahedral geometry

buildamol.structural.geometry.square_planar = <buildamol.structural.geometry.SquarePlanar object>#: The default square planar geometry

buildamol.structural.geometry.tetrahedral = <buildamol.structural.geometry.Tetrahedral object>#: The default tetrahedral geometry

buildamol.structural.geometry.trigonal_bipyramidal = <buildamol.structural.geometry.TrigonalBipyramidal object>#: The default trigonal bipyramidal geometry

buildamol.structural.geometry.trigonal_planar = <buildamol.structural.geometry.TrigonalPlanar object>#: The default trigonal planar geometry

Functional Groups#

Important

Functional groups have now been superseded by the more general Reactivity classes! Please refer to the Reactivity tutorial for more information.

The groups module contains methods for describing functional groups in a molecule in order to guide connectivity between fragments.

Functional Groups

Geometric descriptors for chemical Functional Groups

class buildamol.structural.groups.AromaticGroup(*args, **kwargs)[source]#

Bases: BaseFunctionalGroup

A special functional group to handle aromatic rings

clear_cache()[source]#: Clear the assignment cache

find_matches(molecule, atoms: list)[source]#

Find all atoms in a molecule that match the functional group.

Parameters:

molecule (Molecule) – The molecule to search in.
atoms (list) – The atoms to consider.

Returns:

A list of tuples with the indices of the atoms that match the functional group.

Return type:

list

matches(molecule, atoms: list)[source]#

Check if the atoms match the functional group.

Parameters:: atoms (list) – The atoms to check. The first atom must be the center atom.
Returns:: True if the atoms match the functional group, False otherwise.
Return type:: bool

class buildamol.structural.groups.BaseFunctionalGroup(id: str, rank: int)[source]#

Bases: object

The base class for functional group objects. This class should not be used to directly define specific functional group instances!

apply_connectivity(molecule, atoms: list)[source]#

Apply the connectivity of the functional group to a set of atoms in a molecule. All matching atoms will be identified from the list, so this method can apply connectivity to multiple instances of the functional group.

Parameters:

molecule (Molecule) – The molecule to apply the bonds to.
atoms (list) – The atoms to apply the bonds to.

clear_cache()[source]#: Clear the assignment cache

find_matches(molecule, atoms: list)[source]#

Find all atoms in a molecule that match the functional group.

Parameters:

molecule (Molecule) – The molecule to search in.
atoms (list) – The atoms to consider.

Returns:

A list of tuples with the indices of the atoms that match the functional group.

Return type:

list

get_atom_assignment()[source]#: Get the atom assignment of the functional group.

infer_electrophile_atoms(molecule, residue=None)[source]#

Infer the atoms to use for a Linkage when the functional group is used as an electrophile.

Parameters:

molecule (Molecule) – The molecule that contains the functional group.
residue (Residue, optional) – The residue that contains the functional group. By default the attached residue is used.

Returns:

Atom – The bonder atom.
list – The atoms to delete.

infer_nucleophile_atoms(molecule, residue=None)[source]#

Infer the atoms to use for a Linkage when the functional group is used as a nucleophile.

Parameters:

molecule (Molecule) – The molecule that contains the functional group.
residue (Residue, optional) – The residue that contains the functional group. By default the attached residue is used.

Returns:

Atom – The bonder atom.
list – The atoms to delete.

matches(molecule, atoms: list) → bool[source]#

Check if the atoms match the functional group.

Parameters:: atoms (list) – The atoms to check. The first atom must be the center atom.
Returns:: True if the atoms match the functional group, False otherwise.
Return type:: bool

set_bonders(nucleophile: int = None, electrophile: int = None)[source]#

Set the bonder indices for the atoms that will connect to another atom when using the functional group to make a Linkage.

Parameters:

nucleophile (int) – The index of the nucleophile bonder.
electrophile (int) – The index of the electrophile bonder.

set_deletes(nucleophile: int | List[int] = None, electrophile: int | List[int] = None)[source]#

Set the delete indices for the atoms that should be deleted when the functional group is used to infer a Linkage. Alternatively, a callable can be provided that will receive the following arguments: molecule (Molecule), residue (Residue), bonder (Atom), assignment (list[Atom]). It must return a list of Atoms to delete.

Parameters:

nucleophile (list or callable) – The indices of atoms to delete if the functional group is used as a nucleophile. Or a function that will return a list of atoms to delete.
electrophile (list or callable) – The indices of atoms to delete if the functional group is used as an electrophile. Or a function that will return a list of atoms to delete.

set_reactivity(nucleophile_bonder: int = None, electrophile_bonder: int = None, nucleophile_deletes: list | callable = None, electrophile_deletes: list | callable = None)[source]#

Set the reactivity of the FunctionalGroup. Any reactivity that is not provided will not be changed from the current state.

Parameters:

nucleophile_bonder (int) – The index of the nucleophile bonder.
electrophile_bonder (int) – The index of the electrophile bonder.
nucleophile_deletes (list or callable) – The indices of atoms to delete if the functional group is used as a nucleophile. Or a function that will return a list of atoms to delete. This function will receive the following arguments: molecule (Molecule), residue (Residue), bonder (Atom), assignment (list[Atom] that were identified as belonging to the functional group).
electrophile_deletes (list or callable) – The indices of atoms to delete if the functional group is used as an electrophile. Or a function that will return a list of atoms to delete. This function will receive the following arguments: molecule (Molecule), residue (Residue), bonder (Atom), assignment (list[Atom] that were identified as belonging to the functional group).

Returns:

A new FunctionalGroup with the new reactivity.

Return type:

FunctionalGroup

with_reactivity(id: str = None, nucleophile_bonder: int = None, electrophile_bonder: int = None, nucleophile_deletes: list | callable = None, electrophile_deletes: list | callable = None)[source]#

Create a copy of the FunctionalGroup with a new reactivity. Any reactivity that is not provided will be copied from the original FunctionalGroup.

Parameters:

id (str) – The identifier of the new FunctionalGroup.
nucleophile_bonder (int) – The index of the nucleophile bonder.
electrophile_bonder (int) – The index of the electrophile bonder.
nucleophile_deletes (list or callable) – The indices of atoms to delete if the functional group is used as a nucleophile. Or a function that will return a list of atoms to delete. This function will receive the following arguments: molecule (Molecule), residue (Residue), bonder (Atom), assignment (list[Atom] that were identified as belonging to the functional group).
electrophile_deletes (list or callable) – The indices of atoms to delete if the functional group is used as an electrophile. Or a function that will return a list of atoms to delete. This function will receive the following arguments: molecule (Molecule), residue (Residue), bonder (Atom), assignment (list[Atom] that were identified as belonging to the functional group).

Returns:

A new FunctionalGroup with the new reactivity.

Return type:

FunctionalGroup

class buildamol.structural.groups.FunctionalGroup(id: str, rank: int, geometry: Geometry, atoms: Tuple[str], connectivity: List[int], constraints: List[tuple], invertable: bool = False)[source]#

Bases: BaseFunctionalGroup

A functional group that can be described by a single geometry around one central atom.

Parameters:

id (str) – The identifier of the functional group.
geometry (geometry.Geometry) – The geometry of the functional group.
atoms (str) – The elements of the atoms. The first element is the center atom. Then come all other atoms.
connectivity (list[int]) – The connectivity of the atoms. Where each entry describes the bond order of the central atom to the respective other atom.
constraints (list) – A list of functions that describe the constraints of the functional group. Each function describes the constraints of the respective atom in the same order as they were provided in the atoms parameter.
invertable (bool) – If the functional group is invertable.

Examples

>>> from buildamol.structural.neighbors import constraints
>>> carboxyl = FunctionalGroup(
...     id="carboxyl",
...     rank=2,
...     geometry=geometry.trigonal_planar,
...     # the first atom is the center atom (carboxyl carbon)
...     atoms=("C", "O", "O"),
...     # the connectivity of the carbonxyl carbon to the first O is a double
...     # bond and to the second O is a single bond
...     connectivity=(2, 1),
...     constraints=[
...     None, # the carboxyl carbon has no constraints
...     constraints.neighbors_exactly("C"), # the first oxygen must be connected to the carboxyl carbon only
...     constraints.neighbors_exactly("C", "H") # the second oxygen must be connected to the carboxyl carbon and a hydrogen
...     ],
...     invertable=False
... )

find_matches(molecule, atoms: list)[source]#

Find all atoms in a molecule that match the functional group.

Parameters:

molecule (Molecule) – The molecule to search in.
atoms (list) – The atoms to consider.

Returns:

A list of tuples with the indices of the atoms that match the functional group.

Return type:

list

matches(molecule, atoms: list) → bool[source]#

Check if the atoms match the functional group.

Parameters:: atoms (list) – The atoms to check. The first atom must be the center atom.
Returns:: True if the atoms match the functional group, False otherwise.
Return type:: bool

buildamol.structural.groups.add_group(group: FunctionalGroup)[source]#

Add a functional group to the list of all functional groups.

Parameters:: group (FunctionalGroup) – The functional group to add.

buildamol.structural.groups.all_functional_groups = [FunctionalGroup(hydroxyl), FunctionalGroup(amine), FunctionalGroup(thiol), FunctionalGroup(carbonyl), FunctionalGroup(carboxyl), FunctionalGroup(amide), FunctionalGroup(alkene), FunctionalGroup(alkyne), FunctionalGroup(aromatic)]#: All registered functional groups.

buildamol.structural.groups.globally_applied_groups = [FunctionalGroup(aromatic)]#

Functional groups whose definitions span not only directly neighboring groups but a larger set of atoms

(this list is used by the structural.infer.infer_bond_orders function)

buildamol.structural.groups.higher_order_groups = [FunctionalGroup(carbonyl), FunctionalGroup(carboxyl), FunctionalGroup(amide), FunctionalGroup(alkene), FunctionalGroup(alkyne), FunctionalGroup(aromatic)]#: Functional groups that contain bonds with a higher order than only single bonds.

Graph Neighborhood in Molecular Structures#

In order to infer the neighborhoods from connectivity information in molecules, the neighbors module defines a Neighborhood class that can be used to infer the neighborhoods of atoms in a molecule.

Graph Neighborhood in Molecular Structures

Classes to handle the atom and residue neighborhoods of a structure

class buildamol.structural.neighbors.AtomNeighborhood(graph)[source]#

Bases: Neighborhood

This class handles the bond connectivity neighborhood of atoms in a structure and can be used to obtain bonded atom triplets.

Parameters:: graph – An AtomGraph

property atoms#: Returns the atoms in the structure

property bonds#: Returns the bonds in the structure

get_neighbors(atom, n: int = 1, mode: str = 'upto')[source]#

Get the neighbors of an atom

Parameters:

atom (Bio.PDB.Atom) – The atom whose neighbors should be returned.
n (int) – The (maximal) number of bonds that should separate the target from the neighbors.
mode (str) – The mode of the neighbor search. Can be either “upto” or “at”. If “upto”, this will get all neighbors that are n bonds away from the target or closer. If “at”, this will get all neighbors that are exactly n bonds away from the target.

Returns:

neighbors – The neighbors of the atom

Return type:

set

class buildamol.structural.neighbors.Neighborhood(graph)[source]#

Bases: object

This class handles graph connectivity of connected nodes and is the basis for the AtomNeighborhood and ResidueNeighborhood classes.

Parameters:: graph – A networkx graph

get_neighbors(node, n: int = 1, mode: str = 'upto')[source]#

Get the neighbors of an atom

Parameters:

node (object) – The target node object.
n (int) – The (maximal) number of edges that should separate the target from neighbors.
mode (str) – The mode of the neighbor search. Can be either “upto” or “at”. If “upto”, this will get all neighbors that are n edges away from the target or closer. If “at”, this will get all neighbors that are exactly n edges away from the target.

Returns:

neighbors – The neighbors of the target node

Return type:

set

search_by_constraints(constraints: list)[source]#

Search for nodes that satisfy a set of constraints

Parameters:: constraints (list) – A list of constraint functions. Each function should take a graph and a node as arguments and return a boolean.
Returns:: nodes – The nodes that satisfy the constraints
Return type:: set

class buildamol.structural.neighbors.Quartet(atom1, atom2, atom3, atom4, improper: bool = False)[source]#

Bases: object

An atom quartet that can be used to compute internal coordinates

property angle_123#

property angle_234#

property atom1#

property atom2#

property atom3#

property atom4#

property atoms#

property center_atom#

property dihedral#

property dist_12#

property dist_13#

property dist_23#

property dist_34#

property improper#

class buildamol.structural.neighbors.ResidueNeighborhood(graph)[source]#

Bases: Neighborhood

This class handles the residue connectivity neighborhood of residues in a structure and can be used to obtain residue triplets.

Parameters:: graph – A ResidueGraph

property bonds#: Returns the bonds in the structure

get_neighbors(residue, n: int = 1, mode: str = 'upto')[source]#

Get the neighbors of a residue

Parameters:

residue (Bio.PDB.Residue) – The residue whose neighbors should be returned.
n (int) – The (maximal) number of bonds that should separate the target from the neighbors.
mode (str) – The mode of the neighbor search. Can be either “upto” or “at”. If “upto”, this will get all neighbors that are n bonds away from the target or closer. If “at”, this will get all neighbors that are exactly n bonds away from the target.

Returns:

neighbors – The neighbors of the residue

Return type:

set

property residues#: Returns the residues in the structure

buildamol.structural.neighbors.compute_quartets(bonds: list)[source]#

Compute all possible quartets of atoms from a list of bonds.

Parameters:: bonds (list) – A list of bonds
Returns:: quartets – A list of quartets
Return type:: list

Examples

``` ( 1 )—( 2 )—( 4 )

( 3 )

( 5 )

``` >>> bonds = [(1, 2), (2, 3), (2, 4), (3, 5)] >>> compute_quartets(bonds) {Quartet(1, 2, 3, 5, improper=False), Quartet(5, 3, 2, 4, improper=False), Quartet(1, 3, 2, 4, improper=True)}

buildamol.structural.neighbors.compute_triplets(bonds: list, unique: bool = True)[source]#

Compute all possible triplets of atoms from a list of bonds.

Parameters:

bonds (list) – A list of bonds
unique (bool) – Whether to return only unique triplets. If False, triplets (1,2,3) and (3,2,1) will be returned. Otherwise only one of them will be returned.

Returns:

triplets – A list of triplets

Return type:

list

Examples

``` ( 1 )—( 2 )—( 4 )

( 3 )

( 5 )

``` >>> bonds = [(1, 2), (1, 3), (2, 4), (3, 5)] >>> compute_triplets(bonds) [(2, 1, 3), (1, 2, 4), (1, 3, 5)]

class buildamol.structural.neighbors.constraints[source]#

Bases: object

Neighborhood structural constraints

alone(node)#: The node has no neighbors

extended_has_at_least_n_neighbors(m)#

extended_has_at_most_n_neighbors(m)#

extended_has_n_neighbors(m)#

extended_has_neighbor_hist(hist)#: The node has the specified number of neighbors for each element within n bonds Hist is a dictionary with element symbols as keys and the number of neighbors as values

extended_has_not_n_neighbors(m)#

extended_neighbors_all(*args)#: The node neighbors all the specified elements within n bonds but may have more

extended_neighbors_any(*args)#: The node has at least one neighbor with any of the specified elements within n bonds

extended_neighbors_exactly(*args)#: The node neighbors all and only the specified elements within n bonds

extended_neighbors_not(*args)#: The node does not have any neighbors with the specified elements within n bonds

has_any_element()#: The node has any of the specified elements

has_any_id()#: The node has any of the specified ids

has_at_least_n_neighbors()#

has_at_most_n_neighbors()#

has_bond_of_order_with(element)#

has_bond_order_hist()#: The node has the specified number of bonds for each bond order Hist is a dictionary with bond orders as keys and the number of bonds as values

has_double_bond_with()#

has_element()#: The node has the specified element

has_id()#: The node has the specified id

has_n_neighbors()#

has_neighbor_hist()#: The node has the specified number of neighbors for each element Hist is a dictionary with element symbols as keys and the number of neighbors as values

has_not_element()#: The node does not have the specified element

has_not_id()#: The node does not have the specified id

has_not_n_neighbors()#

has_single_bond_with()#

has_triple_bond_with()#

is_atom(node)#: The node is an atom

is_residue(node)#: The node is a residue

multi_constraint()[source]#

Combine multiple constraints into one

Parameters:: funcs (list) – A list of constraint functions to combine. Each of these must take a graph and a node as arguments and return a boolean.

neighbors_all()#: The node neighbors all the specified elements but may have more

neighbors_any()#: The node has at least one neighbor with any of the specified elements

neighbors_exactly()#: The node neighbors all and only the specified elements

neighbors_not()#: The node does not have any neighbors with the specified elements

none(node)#: No constraints

class buildamol.structural.neighbors.constraints_v2[source]#

Bases: object

Structural constraints for use not with the Neighborhood classes but with the Molecule class directly and only take one atom as argument.

and_()#: Combine multiple constraints with a logical AND as (all(f(atom) for f in funcs))

extended_has_neighbor_hist(hist)#: The atom has the specified number of neighbors for each element within n bonds Hist is a dictionary with element symbols as keys and the number of neighbors as values

has_any_element_of()#: The atom has any of the specified elements

has_bond_of_order_with(element)#

has_bond_order_hist()#: The atom has the specified number of bonds for each bond order Hist is a dictionary with bond orders as keys and the number of bonds as values

has_bonds_of_order()#: The atom has at least one bond of the specified order

has_double_bond_with()#

has_double_bonds()#

has_element()#: The atom has the specified element

has_n_bonds()#

has_neighbor_hist()#: The atom has the specified number of neighbors for each element Hist is a dictionary with element symbols as keys and the number of neighbors as values

has_single_bond_with()#

has_single_bonds()#

has_triple_bond_with()#

has_triple_bonds()#

nand_()#: Combine multiple constraints with a logical NAND as (not all(f(atom) for f in funcs))

neighbors_all()#

neighbors_any()#

neighbors_exactly()#

none()#: No constraints

nor_()#: Combine multiple constraints with a logical NOR as (not any(f(atom) for f in funcs))

not_()#: Negate a constraint function as (not func(atom))

not_has_any_element_of()#: The atom does not have any of the specified elements

not_has_element()#: The atom does not have the specified element

or_()#: Combine multiple constraints with a logical OR as (any(f(atom) for f in funcs))

xnor_(func2)#: Combine two constraints with a logical XNOR as (func1(atom) == func2(atom))

xor_(func2)#: Combine two constraints with a logical XOR as (func1(atom) != func2(atom))

buildamol.structural.neighbors.generate_quartets(bonds: list)[source]#

Generate all possible quartets of atoms from a list of bonds.

Parameters:: bonds (list) – A list of bonds
Yields:: quartet (Quartet) – A quartet of atoms

buildamol.structural.neighbors.generate_triplets(bonds: list)[source]#

Compute all possible triplets of atoms from a list of bonds.

Parameters:: bonds (list) – A list of bonds
Returns:: triplets – A generator of triplets
Return type:: generator

Examples

``` ( 1 )—( 2 )—( 4 )

( 3 )

( 5 )

``` >>> bonds = [(1, 2), (1, 3), (2, 4), (3, 5)] >>> list(generate_triplets(bonds)) [(2, 1, 3), (3, 1, 2), (1, 2, 4), (4, 2, 1), (1, 2, 4)]

Assembling Molecules#

In order to assemble two molecules together there are two modules that are used: stitch and patch. The patch module defines a patch function and corresponding Patcher class that can be used to assemble two molecules together using a patch (i.e. a Linkage with internal coordinates). The stitch module defines a stitch function and corresponding Stitcher class that can be used to assemble two molecules together using a recipe (i.e. a Linkage without internal coordinates).

patch module

Functions to patch molecules together

exception buildamol.structural.patch.PatchError[source]#: Bases: Exception

class buildamol.structural.patch.Patcher(copy_target: bool = False, copy_source: bool = False)[source]#

Bases: Connector

This class is responsible for patching molecules together based on a Linkage object and two Molecule objects, of which one is the target and one is the source. Residues from the source are integrated into the target molecule. The Linkage object must define a “patch”, meaning it must contain data on internal coodrinates (ICs) of the resulting molecule in the vicinity of the newly formed bond.

Parameters:

copy_target (bool) – Whether to copy the target molecule before patching
copy_source (bool) – Whether to copy the source molecule before patching

apply(patch: Linkage.Linkage = None, target: Molecule.Molecule = None, source: Molecule.Molecule = None, target_residue=None, source_residue=None)[source]#

Patch two molecules together. This will merge the source molecule’s residues into the target molecule. If no patch, target, and source have been set already, they can be provided as arguments to this method.

Parameters:

patch (Linkage) – The patch to apply (this needs to have ICs)
target (Molecule) – The target molecule
source (Molecule) – The source molecule
target_residue (int or str or Residue) – The residue in the target molecule to which the source molecule will be patched. By default, the last residue in the target molecule will be used if it contains appropriate anchor atoms.
source_residue (int or str or Residue) – The residue in the source molecule that will be patched into the target molecule. By default, the first residue in the source molecule will be used if it contains appropriate anchor atoms.

Returns:

The patched target and source molecules (not yet merged into one molecule)

Return type:

tuple

get_anchors(target_residue=None, source_residue=None)[source]#

Returns the two atoms that will be used for anchoring structure alignment. These atoms form a bond between the two molecules.

Parameters:

target_residue (int or str or Residue) – The residue in the target molecule to which the source molecule will be patched. By default, the last residue in the target molecule will be used if it contains appropriate anchor atoms.
source_residue (int or str or Residue) – The residue in the source molecule that will be patched into the target molecule. By default, the first residue in the source molecule will be used if it contains appropriate anchor atoms.

Returns:

The two atoms that form the bond between the two molecules the first atom is from molecule1 and the second is from molecule2.

Return type:

tuple

merge()[source]#

Merge the source molecule into the target molecule

Returns:: The target molecule with the source molecule merged into it
Return type:: Molecule

set_patch(patch: Linkage.Linkage)[source]#

Set the patch

Parameters:: patch (Linkage) – The patch

buildamol.structural.patch.patch(target: Molecule.Molecule, source: Molecule.Molecule, patch: Linkage.Linkage, target_residue=None, source_residue=None, copy_target: bool = False, copy_source: bool = False) → Molecule.Molecule[source]#

Patch two molecules together. This will merge the source molecule’s residues into the target molecule.

Parameters:

patch (Linkage) – The patch to apply
target (Molecule) – The target molecule
source (Molecule) – The source molecule
target_residue (int or str or Residue) – The residue in the target molecule to which the source molecule will be patched. By default, the last residue in the target molecule will be used if it contains appropriate anchor atoms.
source_residue (int or str or Residue) – The residue in the source molecule that will be patched into the target molecule. By default, the first residue in the source molecule will be used if it contains appropriate anchor atoms.
copy_target (bool) – Whether to copy the target molecule before patching it
copy_source (bool) – Whether to copy the source molecule before patching it

Returns:

The patched molecule

Return type:

Molecule

stitch module

Functions to stitch molecules together even in the absence of a patch

class buildamol.structural.stitch.Stitcher(copy_target: bool = False, copy_source: bool = False)[source]#

Bases: Connector

This class is responsible for stitching molecules together when there is not a patch available which specifies the immediate geometry of their connection. The only required input is a pair of atoms that should form a new bond, and two tuples of atoms (at least one from each molecule) that are being removed in the process.

Parameters:

copy_target (bool) – Whether to copy the target molecule before stitching
copy_source (bool) – Whether to copy the source molecule before stitching

apply(target: Molecule.Molecule, source: Molecule.Molecule, target_removals: tuple = None, source_removals: tuple = None, target_atom: int | base_classes.Atom = None, source_atom: int | base_classes.Atom = None, target_residue: int | base_classes.Residue = None, source_residue: int | base_classes.Residue = None, optimization_steps: int = 30, **kwargs) → Molecule.Molecule[source]#

Stitch the source and target molecules together

Parameters:

target (Molecule) – The target molecule
source (Molecule) – The source molecule. This will be attached to the target molecule.
target_removals (tuple) – A tuple of atoms to be removed from the target molecule. These must be the atom’s ids within the attaching residue. All atoms must be part fo the same residue as the attaching target_atom. If not provided, just any Hydrogen atom next to the target_atom will be used.
source_removals (tuple) – A tuple of atoms to be removed from the source molecule. These must be the atom’s ids within the attaching residue. All atoms must be part fo the same residue as the attaching source_atom. If not provided, just any Hydrogen atom next to the source_atom will be used.
target_atom (int or Atom) – The atom on the target molecule to which the source molecule will be attached. This may either be the atom object directly or its serial number. If none is provided, the molecule’s “root atom” is used (if defined).
source_atom (int or Atom) – The atom on the source molecule to which the target molecule will be attached. This may either be the atom object directly or its serial number. If none is provided, the molecule’s “root atom” is used (if defined).
target_residue (int or Residue) – The residue hosting the target atom. This is only required if the target atom is not given directly or specified by name.
source_residue (int or Residue) – The residue hosting the source atom. This is only required if the source atom is not given directly or specified by name.
optimization_steps (int, optional) – The number of steps to take in the optimization process.
**kwargs – Additional keyword arguments to pass to the optimizer. See the documentation for buildamol.optimizers.agents.optimize for more details.

Returns:

The target and source molecules after stitching. At this point, the source molecule is aligned to the target molecules but not yet integrated into it. Use the merge method to do this.

Return type:

tuple

merge() → Molecule.Molecule[source]#: Merge the source molecule into the target molecule

buildamol.structural.stitch.stitch(target: Molecule.Molecule, source: Molecule.Molecule, recipe: Linkage.Linkage = None, target_removals: tuple = None, source_removals: tuple = None, target_atom: int | base_classes.Atom = None, source_atom: int | base_classes.Atom = None, target_residue: int | base_classes.Residue = None, source_residue: int | base_classes.Residue = None, optimization_steps: int = 10000.0, copy_target: bool = False, copy_source: bool = False, **kwargs) → Molecule.Molecule[source]#

Stitch two molecules together. Thereby the source molecule is integrated into the target molecule.

Parameters:

target (Molecule) – The target molecule
source (Molecule) – The source molecule. This will be attached to the target molecule.
recipe (AbstractRecipe) – The recipe to be used for stitching. If none is provided, the stitching instructions can be submitted manually via the other parameters.
target_removals (tuple) – This parameter is only used if no recipe is provided. A tuple of atoms to be removed from the target molecule. These must be the atom’s ids within the attaching residue. All atoms must be part fo the same residue as the attaching target_atom.
source_removals (tuple) – This parameter is only used if no recipe is provided. A tuple of atoms to be removed from the source molecule. These must be the atom’s ids within the attaching residue. All atoms must be part fo the same residue as the attaching source_atom.
target_atom (int or Atom) – This parameter is only used if no recipe is provided. The atom on the target molecule to which the source molecule will be attached. This may either be the atom object directly or its serial number. If none is provided, the molecule’s “root atom” is used (if defined).
source_atom (int or Atom) – This parameter is only used if no recipe is provided. The atom on the source molecule to which the target molecule will be attached. This may either be the atom object directly or its serial number. If none is provided, the molecule’s “root atom” is used (if defined).
target_residue (int or Residue) – The residue hosting the target atom. This is only required if the target atom is not given directly or specified by name. If a recipe is provided, the “attach_residue” is used by default. A ValueError is raised if none is defined.
source_residue (int or Residue) – The residue hosting the source atom. This is only required if the source atom is not given directly or specified by name. If a recipe is provided, the “attach_residue” is used by default. A ValueError is raised if none is defined.
optimization_steps (int, optional) – The number of steps to take in the optimization process, by default 1e4
copy_target (bool, optional) – Whether to copy the target molecule before stitching, by default False
copy_source (bool, optional) – Whether to copy the source molecule before stitching, by default False
**kwargs – Additional keyword arguments to pass to the optimizer. See the documentation for buildamol.optimizers.agents.optimize for more details.

Returns:

The stitched molecule

Return type:

Molecule

connector module

The base class for the Patcher and Stitcher classes.

class buildamol.structural.connector.Connector(copy_target: bool = False, copy_source: bool = False)[source]#

Bases: object

get_anchors(_ref_atoms, target_residue=None, source_residue=None)[source]#

Find appropriate anchor atoms in the source and target molecules

Parameters:

_ref_atoms (tuple) – The two atoms that form the bond between the two molecules. These may be specified by name or by index.
target_residue (int or str or Residue) – The residue in the target molecule to which the source molecule will be patched. By default, the last residue in the target molecule will be used if it contains appropriate anchor atoms.
source_residue (int or str or Residue) – The residue in the source molecule that will be patched into the target molecule. By default, the first residue in the source molecule will be used if it contains appropriate anchor atoms.

Returns:

The two atoms that form the bond between the two molecules

Return type:

tuple

set_source(source: Molecule.Molecule)[source]#

Set the source molecule

Parameters:: source (Molecule) – The source molecule

set_target(target: Molecule.Molecule)[source]#

Set the target molecule

Parameters:: target (Molecule) – The target molecule