NoahHenrikKleinschmidt/buildamol: BuildAMol v.1.2.11

New Reaction and Reactivity classes for enhanced chemistry support

The new Reaction serves as an automated Linkage generator, by accepting functions rather than Atom instances to search for suitable linker and deleter atoms when connecting Molecules. The class is complemented by the new Reactivity classes that succeed the old FunctionalGroup classes (the latter will remain part of the codebase). The Reactivity classes define atom getter functions to mimic the reaction patterns of functional groups in a more flexible way than the old functional groups could.

Be sure to check out the Reaction tutorial and Reactivity tutorial to learn more about their usage.

Quick look

To let two molecules "react" via their functional groups do the following:

import buildamol as bam
from buildamol.structural.reactivity import Hydroxyl, Carboxyl

alcohol = bam.molecule("cyclohexanol")
acid = bam.molecule("acetic acid")

reaction = bam.Reaction.from_reactivities(
     electrophile=Carboxyl(), nucleophile=Hydroxyl(),
)

product = reaction(acid, alcohol)

<img width="200" height="200" alt="image" src="https://github.com/user-attachments/assets/921059b2-93e5-4efa-a29e-db439a1fd798" />

Larger leaving groups with Linkages

Linkages can now automatically delete all downstream atoms of the defined deleter atoms. This means that by defining a single deleter atom of a larger leaving group, all atoms of the group are removed. This behaviour is now default for all Linkages but can be disabled for individual linkages using automatically_delete_downstream_atoms=False.

To exemplify this. Let's say we want to delete an entire phosphate group from a molecule when attaching another molecule. We can specify the linkage as follows:

mol = bam.read_smiles("NCC")
mol = bam.phosphorylate(mol, "C2").squash()

# in this case specifying the O2 as deleter atom
# will automatically mark all other phosphate group atoms
# downstream of the C2-O2 bond for deletion as well
link = bam.linkage("C2", "N1", delete_in_target=["O2"])

out = mol % link + mol.copy()

<img width="745" height="263" alt="image" src="https://github.com/user-attachments/assets/b44caee9-5871-4fa9-a58c-51fb37b42986" />

Atoms know their Neighbourhood

So far, connectivity was exclusively known to Molecule instances. Child objects such as individual Atom instances had no access to such information. The base_classes now have a molecule attribute that allows them to access their toplevel entity. By extension, Atom and Residue objects now also support methods such as get_neighbors or get_bonds.

mol.get_neighbors(some_atom) # previously the only way to get neighbors
some_atom.get_neighbors() # ✅ since v.1.2.11 also supported

Methods of the Atom class thus newly supported are:

• get_neighbors (also supported by the Residue class)
• get_hydrogens
• get_equatorial_neighbor
• get_axial_neighbor
• get_equatorial_hydrogen
• get_axial_hydrogen
• get_left_hydrogen
• get_right_hydrogen
• get_bonds (also supported by the Residue class)

Improved Constraint Functions

The new constraints_v2 class defines improved constraint functions for atom filtering with get_atoms. They work with a single Atom instance as the only argument and build on the above-mentioned new get_neighbors support of the Atom class. The constraints_v2 are a separate entity from the existing constraints, which will remain an unchanged part of the codebase for now.

For example constraints such as "a carbon with a double bond to an oxygen and single bond to a nitrogen" would be a description for the central C of an R-C(=O)N-R amide group. To search for carbons matching this description, we can use:

from buildamol.structural import constraints_v2 as constraints

filters = constraints.and_(
constraints.has_double_bond_with("O"),
constraints.has_single_bond_with("N"),
)

matching_carbons = mol.get_atoms("C", by="element", filter=filters)

More powerful 2D visualizations

The Chem2DViewer received a few additional methods to highlight_atoms, highlight_bonds, highlight_residues, and label_atoms in more flexible ways. In addition to hard-coded values such as colour values, functions can now be used to set values for atom colors or labels dynamically.

The visualization tutorial was updated accordingly so be sure to check it out!

Other Changes

• the phosphorylate function had a bug with the attachment atoms, which is fixed now
• Bond instances can now get the "binding partner" based on one atom (i.e. if given atom1 they return atom2 and vice versa)
• Molecule instances can now get atoms that are in a specific spatial region using get_atoms_within (based on some anchor coordinate)
• the documentation received a small makeover
• other small bug fixes