vibesketcher.chem.mapping¶
Which reactant atom becomes which product atom: an atom mapping for a reaction (#29).
A reaction path between two sketches needs both endpoints’ atoms in the same order, so every reactant atom must be paired with one product atom of the same element and explicit isotope label. The pairing chosen changes the fewest bonds, the principle of minimum chemical distance (I. Ugi et al., Angew. Chem. Int. Ed. 18, 111-123 (1979); J. Jauffret, C. Tonnelier, J.-E. Dubois, Tetrahedron Comput. Methodol. 3, 335-349 (1990)):
the cost of a pairing of the heavy atoms is the number of bonds between them it forms and breaks, plus two for every hydrogen that has to move to another atom (one bond broken, one formed);
every cheapest pairing is found by a depth-first branch and bound over the heavy atoms, element by element, breadth first through each molecule, so a partial pairing’s cost prunes early; a search that grows too large stops and asks for pinned atoms instead of guessing;
pairings that cost the same and differ only by the molecules’ own symmetry describe the same reaction. When the cheapest pairings describe different reactions (which oxygen leaves in an esterification; a [3,3] or a [1,3] shift in a Claisen rearrangement, which break and form the same number of bonds), the mapping is ambiguous: no writer guesses, and the user pins atoms. Of the cheapest, the one changing the fewest bond orders is shown first; that is a presentation order, not a chemical argument.
Hydrogens are paired here by the heavy atoms they sit on; where several are
equivalent, the reaction-path endpoints pair them by position
(vibesketcher.chem.endpoints). RXNMapper (MIT) maps from learned
attention, but needs torch, too heavy for a core dependency.
Functions
|
Why the two sides cannot be paired atom for atom; empty if they can. |
|
All admissible spectator-H choices (including the selected one), or an explicit limit. |
|
The cheapest pairing of the reactants' atoms with the products'. |
|
The side made of |
|
Refuse anything except a pin-preserving spectator-H automorphism. |
Classes
|
A pairing of every reactant atom with a product atom. |
|
Complete bounded choices on fixed endpoints, never a physical path ranking. |
|
One side of a reaction: its species as one molecule, with explicit hydrogens. |
Exceptions
The reaction's atoms cannot be paired; the message says why. |
- class vibesketcher.chem.mapping.AtomMapping(reactants, products, pairs, cost, alternatives=(), pinned=<factory>, unconstrained_pairs=())[source]¶
Bases:
objectA pairing of every reactant atom with a product atom.
- Parameters:
- alternatives: tuple[tuple[int, ...], ...] = ()¶
Other cheapest pairings that describe a different reaction, as
pairs.
- unconstrained_pairs: tuple[int, ...] = ()¶
Mapping before optional spectator-H pins; geometry selection uses this baseline.
- exception vibesketcher.chem.mapping.MappingFailed[source]¶
Bases:
ValueErrorThe reaction’s atoms cannot be paired; the message says why.
- class vibesketcher.chem.mapping.Side(mol, owners, species)[source]¶
Bases:
objectOne side of a reaction: its species as one molecule, with explicit hydrogens.
Each species contributes its atoms in the order of its 3D structure (
vibesketcher.chem.embed.embed_3d()): its SMILES atoms, then the hydrogens RDKit adds.- Parameters:
- owners: tuple[tuple[str, int], ...]¶
the species id and the atom’s index within that species.
- Type:
Per atom
- vibesketcher.chem.mapping.balance_problems(reactants, products)[source]¶
Why the two sides cannot be paired atom for atom; empty if they can.
- vibesketcher.chem.mapping.map_reaction(reactants, products, pinned=())[source]¶
The cheapest pairing of the reactants’ atoms with the products’.
pinnedholds (reactant atom, product atom) pairs the pairing must keep: heavy atoms, or equivalent same-parent spectator hydrogens, of the same element and isotope. Hydrogen pins do not select a different reaction. RaisesMappingFailedwhen the sides are not balanced or a pin is impossible.