orthonym.rules.fusion_numbering#

Note

Internal API. Names and behaviour may change between releases.

Deterministic peripheral numbering of fused polycyclic ring systems.

Given an oriented integer hex-lattice embedding (from fusion_orientation), this module assigns IUPAC locants to the peripheral skeletal atoms following : start from the uppermost ring (tie -> furthest right), begin at the most-counterclockwise non-fusion atom, and walk CLOCKWISE assigning integers to non-fusion atoms (and fusion heteroatoms), giving each fusion carbon the number of the preceding non-fusion atom modified by a Roman letter (‘a’, ‘b’,…).

The lowest-locant cascade is then applied across all surviving (orientation, start) candidates using the shared comparison primitives in rules/locants.py (compare_locant_sets / _compare_heteroatom_seniority via compare_numbering) — the comparison logic is NEVER reimplemented here.

Fixed-numbering exceptions /#

anthracene and phenanthrene are retained names with FIXED, traditional numbering (“special numbering” — Blue Book entries (11) and (12); also : “in purine, anthracene, and phenanthrene, this numbering must be used”). Their traditional numbers do NOT follow the systematic peripheral walk (anthracene numbers its meso carbons 9,10 last; phenanthrene uses 4a,4b/8a,10a fusion labels). A correct engine must encode these two exceptions, so compute_fused_numbering recognises their exact ring graph and returns the fixed numbering mapped onto the input atoms. Every other all-6 cata-fused carbocyclic system (naphthalene, tetracene, pentacene, chrysene, triphenylene,…) is numbered systematically by the peripheral walk.

Stage 1 scope#

compute_fused_numbering returns a map ONLY for all-six-membered, ortho- (cata-)fused, carbocyclic ring systems with no interior (peri-fusion) atom. Otherwise it returns None and the caller falls back to its existing path.

Locant shape: int for ordinary atoms, (int, 'a') tuples for fusion carbons — the existing rules.locants._Locant type, so downstream consumers (compare_locant_sets, the cascade) are unchanged.

Source: IUPAC 2013 Blue Book (the Blue Book Blue Book ~line 12501);

/ (anthracene/phenanthrene fixed numbering).

orthonym.rules.fusion_numbering.compute_fused_numbering(mol, ring_system_atoms)#

Deterministic IUPAC fused-ring numbering for an all-6 cata-fused PAH.

Returns {atom_idx -> locant} (int or (int, 'a') tuple) when the ring system is all-six-membered, ortho-(cata-)fused, carbocyclic, and has no interior (peri-fusion) atom. Returns None otherwise (the caller then keeps its existing numbering path — fail-closed, never a regression).

The numbering is selected by the IUPAC cascade over every (surviving-orientation, start-atom) candidate, compared via the shared rules.locants primitives so the choice is fully deterministic and coordinate-free.

Parameters:

  • mol (Mol) – RDKit Mol.

  • ring_system_atoms – iterable of atom indices forming the fused ring system (the ring atoms of the parent — substituents excluded).

Source: IUPAC 2013 Blue Book /.