orthonym.decomposition#

Note

Internal API. Names and behaviour may change between releases.

Decomposition engine for multi-fragment molecule naming.

Detects cleavable functional bonds (ester, amide, glycosidic, carbamate), fragments molecules at those bonds, H/OH-caps the fragments, names each fragment recursively, and assembles multi-component IUPAC names.

Public API:
try_decompose(mol, style=”pin”) -> Optional[str]

Main entry point. Returns assembled name or None.

find_cleavable_bonds(mol) -> List[Dict]

Detect cleavable bonds in a molecule.

cleave_and_cap(mol, bond_infos, acid_side_oh=True) -> List[Dict]

Cleave molecule at bonds and return capped fragments.

orthonym.decomposition.try_decompose(mol, style='pin')#

Attempt decomposition of a molecule into named fragments.

This is the main entry point for the decomposition engine. It: 1. Finds cleavable bonds (ester, amide, phosphodiester, thioester,

glycosidic, sulfonamide, carbamate, ether – 8 types)

  1. Checks if the existing pipeline name is acceptable (quality gate)

  2. Selects the best bond to cleave

  3. Cleaves and caps the fragments

  4. Names each fragment recursively

  5. Assembles the multi-component IUPAC name

Returns None if: - No cleavable bonds exist - The existing pipeline name is good enough (quality gate passes) - Fragment naming fails - Size guard detects non-shrinking fragments

Parameters:

  • mol – RDKit Mol object to decompose.

  • style (str) – Naming style (“pin” for preferred IUPAC names).

Returns:

Multi-component IUPAC name string, or None to fall through to the existing naming pipeline.

Return type:

str | None

orthonym.decomposition.find_cleavable_bonds(mol)#

Find cleavable bonds in a molecule.

Detects 8 bond types: carbamate, phosphodiester, ester, thioester, amide, sulfonamide, glycosidic, and ether bonds. Excludes cyclic variants (lactones, lactams, thiolactones, sultams, cyclic phosphodiesters, epoxides) and overlapping patterns (carbamates, ureas, skeletal replacement chains).

The detection order matters: 1. Carbamates are detected first to mark overlapping carbonyl C atoms. 2. Phosphodiesters are detected (P-O bond to alkyl C). 3. Esters are detected, skipping any carbonyl C already in a carbamate. 4. Thioesters are detected (C(=O)-S-C), skipping carbamate overlap

and thiolactones.

  1. Amides are detected, skipping any carbonyl C already in a carbamate.

  2. Sulfonamides are detected (S(=O)(=O)-N), excluding sultams.

  3. Glycosidic bonds are detected independently.

  4. Ether bonds are detected with 5 guards (ring, ester-exclusion, glycosidic-exclusion, skeletal-replacement, minimum-fragment-size).

Parameters:

mol – RDKit Mol object

Returns:

List of dicts with keys – bond_idx, type, match, acid_atom, alkyl_atom (for esters/ethers/thioesters/phosphodiesters/sulfonamides) or amine_atom (for amides).

Return type:

List[Dict]

orthonym.decomposition.cleave_and_cap(mol, bond_infos, acid_side_oh=True)#

Cleave molecule at specified bonds and return H/OH-capped fragments.

Uses RDKit FragmentOnBonds to cleave, then replaces dummy atoms: - Acid-side fragments: cap with OH (produces carboxylic acid) if acid_side_oh=True

per IUPAC principal characteristic group preservation

  • Alkyl/amine-side fragments: cap with H

Fragment side labeling uses dummyLabels to track which dummy came from which side of the bond: label 1 = acid side, label 2 = alkyl/amine side.

Parameters:

  • mol – RDKit Mol object

  • bond_infos (List[Dict]) – List of bond info dicts from find_cleavable_bonds

  • acid_side_oh (bool) – If True, cap acid-side fragments with OH

Returns:

List of dicts with keys – smiles, side, original_atoms

Return type:

List[Dict]