kartograf.atom_aligner#

kartograf.atom_aligner.align_mol_shape(mol: SmallMoleculeComponent, ref_mol: SmallMoleculeComponent) → SmallMoleculeComponent#

Aligns a molecule to a reference by maximising the overlap of their 3D shapes using the Open3DAlign (O3A) algorithm.

This function wraps RDKit’s GetO3A(), which scores alignment quality using a combination of atom-pair distances and partial-charge similarities. The alignment is purely geometry-driven and does not require any shared substructure.

Parameters:
Returns:

An aligned copy of mol whose 3D shape best overlaps ref_mol.

Return type:

SmallMoleculeComponent

When to use this algorithm

Choose shape-based alignment when:

  • You are not using a method that requires a well mapped common core (e.g. openfe’s SepTopProtocol).

  • The molecules belong to different chemical series (scaffold hops, bioisosteric replacements) but are expected to occupy a similar binding volume.

  • No obvious MCS exists or the MCS is too small to anchor a reliable structural overlay.

  • You wish to compare or cluster molecules by 3D pharmacophoric shape.

Algorithm outline

  1. Compute the Open3DAlign score between the probe and reference molecules using GetO3A().

  2. Call Align() to apply the optimal rigid-body rotation and translation that maximises shape overlap.

  3. The alignment score (a float) is logged at DEBUG level for diagnostic purposes.

Example

from kartograf import align_mol_shape
from gufe import SmallMoleculeComponent

mol = SmallMoleculeComponent.from_sdf_file("ligand.sdf")
ref_mol = SmallMoleculeComponent.from_sdf_file("reference.sdf")

aligned_mol = align_mol_shape(mol, ref_mol)

Note

Open3DAlign requires that both molecules carry 3D coordinates and (optionally) partial charges for optimal scoring. Ensure that conformers have been generated before calling this function.

kartograf.atom_aligner.align_mol_skeletons(mol: SmallMoleculeComponent, ref_mol: SmallMoleculeComponent) → SmallMoleculeComponent#

Aligns a molecule to a reference by superimposing their shared Maximum Common Substructure (MCS).

This function uses RDKit’s rdkit.Chem.rdFMCS module to identify the largest common subgraph between the two molecules, then calls AlignMol() to minimise the RMSD over the matched atom pairs. Because the atom-type comparator is set to CompareAny the MCS search matches atoms regardless of their element, making it tolerant of scaffold hops and heteroatom substitutions.

Parameters:
Returns:

An aligned copy of mol superimposed on ref_mol via the MCS.

Return type:

SmallMoleculeComponent

When to use this algorithm

Choose skeleton-based alignment when:

  • The two molecules share a recognisable common scaffold (e.g. an R-group optimisation series).

  • You are using a method that requires a well mapped common core (e.g. openfe’s HybridTopologyProtocol).

  • You want the alignment to reflect chemical similarity rather than overall 3D shape.

  • The molecules differ primarily in peripheral substituents and the core geometry should be conserved.

Algorithm outline

  1. Find the MCS of the two molecules using CompareAny atom typing (topology-only matching).

  2. Convert the MCS SMARTS pattern to an atom-index mapping between the two molecules.

  3. Call rdkit.Chem.rdMolAlign.AlignMol() with the explicit atom map to minimise the RMSD over the MCS atoms only.

Example

from kartograf import align_mol_skeletons
from gufe import SmallMoleculeComponent

mol = SmallMoleculeComponent.from_sdf_file("ligand.sdf")
ref_mol = SmallMoleculeComponent.from_sdf_file("reference.sdf")

aligned_mol = align_mol_skeletons(mol, ref_mol)

Warning

If the two molecules share no common substructure the MCS will be empty and the alignment will be undefined. Pre-check your molecules if a shared scaffold cannot be assumed.