orthonym.rules.ring_selection#

Note

Internal API. Names and behaviour may change between releases.

Ring system type classification, scoring, and selection per IUPAC.

Provides the foundation for correct principal ring system selection. Implements: - type hierarchy (RingSystemType enum) - general criteria (ring_system_score tuple) - Principal ring system selection (select_principal_ring_system)

These are pure functions that can be tested independently before integration.

Reference: IUPAC 2013 Blue Book, (Selection of Preferred Ring System)

class orthonym.rules.ring_selection.RingSystemType(*values)#

Bases: IntEnum

type hierarchy. Lower value = more senior.

IUPAC 2013: 1. Spiro ring systems 2. Cyclic phane parent hydrides 3. Fused ring systems 4. Bridged fused ring systems 5. Von Baeyer ring systems 6. Linear phane parent hydrides 7. Ring assemblies

MONOCYCLIC is not in but needed as fallback for simple rings.

SPIRO = 1#
CYCLIC_PHANE = 2#
FUSED = 3#
BRIDGED_FUSED = 4#
VON_BAEYER = 5#
LINEAR_PHANE = 6#
RING_ASSEMBLY = 7#
MONOCYCLIC = 8#
orthonym.rules.ring_selection.classify_ring_system_type(mol, ring_system_atoms)#

Classify a ring system into its type.

Reuses existing detection functions from the codebase, operating on a sub-molecule built from the ring system atoms when necessary.

Classification priority (same as _classify_complex_ring in composer.py): 1. Spiro junction detected -> SPIRO 2. Fused core + extra bridges -> BRIDGED_FUSED 3. Ortho-fused or ortho-peri-fused -> FUSED 4. Bicyclo or polycyclic bridged -> VON_BAEYER 5. Fallback -> MONOCYCLIC

Parameters:

  • mol (Mol) – RDKit Mol object (full molecule)

  • ring_system_atoms (Set[int]) – Set of atom indices belonging to this ring system

Returns:

RingSystemType enum value

Return type:

RingSystemType

orthonym.rules.ring_selection.ring_system_score(mol, system_atoms)#

Memoised per (mol object, ring-system atom set) within one naming call (Lever E, 2026-09-12). The key also carries what the score reads from the live molecule (element, aromatic flag and charge of the system’s atoms; type and aromatic flag of its bonds), so an in-place edit forces a recompute. See:func:_ring_system_score_impl for the scoring.

orthonym.rules.ring_selection.select_principal_ring_system(mol, ring_systems, principal_group_atoms=None)#

Select the most senior ring system from a list of candidates.

Uses ring_system_score to compare candidates. The system with the minimum score tuple is the most senior hierarchy).

Parameters:

  • mol (Mol) – RDKit Mol object

  • ring_systems (List[Set[int]]) – List of sets, each set contains atom indices in one ring system (from get_ring_systems)

Returns:

Tuple of sorted atom indices of the most senior ring system, or empty tuple if no ring systems provided

Return type:

Tuple[int, …]