orthonym.rules.parent_selection#

Note

Internal API. Names and behaviour may change between releases.

Parent selection logic for ring vs chain compounds (IUPAC.

This module implements the IUPAC 2013 rules for selecting between a ring and a chain as the parent structure in organic compound naming.

Key rule: “The principal characteristic group cited as suffix must be attached to the principal chain or ring system.”

Key rule: “When the ring and the chain contain the same number of skeletal atoms in the ring or chain, the ring system is always preferred as the principal chain.”

This means: - If -COOH is on the chain, chain MUST be parent - If -COOH is directly on the ring, ring MUST be parent - For hydrocarbons (no FG), rings have seniority over chains - When FG count is tied, cascade (chain length > multiple bonds) applied before ring default - When multiple ring systems exist, the most senior one is the parent

class orthonym.rules.parent_selection.ParentSelectionResult(parent_type, parent_atoms, substituent_rings, reasoning, principal_ring_system=None, parent_pool_size=1)#

Bases: object

Result of parent structure selection.

Variables:

  • parent_type (str) – ‘ring’ or ‘chain’

  • parent_atoms (List[int]) – Atom indices of the parent structure

  • substituent_rings (List[Tuple[int, ...]]) – Rings that become substituents (when chain is parent)

  • reasoning (str) – Explanation for debugging

  • principal_ring_system (Tuple[int, ...] | None) – The senior ring system chosen by the single authoritative among-rings computation. Populated once by namer._classify (a phase chokepoint consolidation); the derived senior_ring_system / principal_ring feature fields are read from this one value. None until populated (e.g. pure acyclic, or before the post-pass runs).

parent_type: str#
parent_atoms: List[int]#
substituent_rings: List[Tuple[int, ...]]#
reasoning: str#
principal_ring_system: Tuple[int, ...] | None = None#
parent_pool_size: int = 1#
orthonym.rules.parent_selection.is_principal_group_on_ring(mol, ring_atoms, principal_group_atoms, principal_group=None)#

Check if the principal functional group is directly attached to the ring.

For carboxylic acid: the carbonyl carbon must be bonded to a ring atom. For alcohol: the carbon bearing -OH must be a ring atom.

The key distinction is: - “on ring” = FG attachment point is bonded to a ring carbon - NOT just anywhere connected through chain to ring

Parameters:

  • mol – RDKit Mol object

  • ring_atoms (Set[int]) – Set of atom indices in the ring

  • principal_group_atoms (List[tuple]) – List of tuples, each tuple is a SMARTS match

  • principal_group (str | None) – Optional FG name; when provided, attachment lookup honours PG_ATTACHMENT_INDICES .

Returns:

True if principal group is directly attached to ring

Return type:

bool

orthonym.rules.parent_selection.is_principal_group_on_chain(mol, chain_atoms, principal_group_atoms, principal_group=None)#

Check if the principal functional group is on the chain.

For carboxylic acid: the carbonyl carbon must be in chain_atoms. For alcohol: the carbon bearing -OH must be in chain_atoms.

Parameters:

  • mol – RDKit Mol object

  • chain_atoms (List[int]) – List of atom indices in the principal chain

  • principal_group_atoms (List[tuple]) – List of tuples, each tuple is a SMARTS match

  • principal_group (str | None) – Optional FG name; when provided, attachment lookup honours PG_ATTACHMENT_INDICES .

Returns:

True if principal group is on the chain

Return type:

bool

orthonym.rules.parent_selection.select_parent(mol, ring_systems, principal_chain, principal_group, principal_group_atoms, ring_info=None, _offer_rank=0)#

Select parent structure per IUPAC.

: the staged class-specific cascade (with its fail-open default-to-ring) was root-cause-replaced by ONE pooled Blue Book comparator over ring+chain candidates – see rules/p44_scorer.select_parent_unified for the rule cascade

PG count -> senior class -> ring>chain

-> among rings / among chains -> tiebreaks) and the preserved pre-empts (single-carbon PCG chain, natural products, admission).

Parameters:

  • mol – RDKit Mol object

  • ring_systems (List[set]) – List of sets of atom indices for each ring

  • principal_chain (List[int]) – Pre-computed principal chain (from namer.py)

  • principal_group (str | None) – Name of principal functional group (or None)

  • principal_group_atoms (List[tuple]) – List of tuples of atom indices

  • ring_info (dict) – Optional dict with ‘iupac_locants’ for IUPAC ring numbering (from fused heterocycle data). Used by locant comparison functions per.

Returns:

ParentSelectionResult with decision and metadata

Return type:

ParentSelectionResult