orthonym.rules.cycloalkanes#

Note

Internal API. Names and behaviour may change between releases.

Cycloalkane and cycloalkene naming rules according to IUPAC 2013 (Blue Book).

Handles: - Ring numbering and orientation for lowest locants - Cycloalkene double bond positioning (C1-C2) - Ring substituent detection - Ring vs chain parent selection

IUPAC 2013 Rules: - Cycloalkenes: Double bond is at C1-C2 position - Mono-cycloalkenes: locant is omitted (cyclohexene, not cyclohex-1-ene) - Cycloalkadienes: locants required (cyclohexa-1,3-diene) - Substituent locants: use first-point-of-difference rule

orthonym.rules.cycloalkanes.get_ring_double_bonds(mol, ring_atoms)#

Get all double bonds within a ring.

Parameters:

  • mol – RDKit Mol object

  • ring_atoms (Tuple[int, ...]) – Tuple of atom indices defining the ring

Returns:

List of (atom_idx1, atom_idx2) tuples for each double bond in the ring

Return type:

List[Tuple[int, int]]

orthonym.rules.cycloalkanes.is_mancude_monocyclic_hydrocarbon(mol, ring_atoms)#

(b) / detection: a mancude monocyclic hydrocarbon that RDKit marks aromatic but which is NOT benzene is named as the cyclo-polyene (cyclodeca-1,3,5,7,9-pentaene), never as an [n]annulene component prefix.

Fail-closed scope: exactly one ring, all-carbon, every ring atom RDKit- aromatic, size >= 7 (benzene size 6 keeps its retained name), and every ring atom a bare CH (unsubstituted mancude hydrocarbon). Returns True only when the ring should be re-routed through the cycloalkene (polyene) path.

orthonym.rules.cycloalkanes.get_ring_substituents(mol, ring_atoms)#

Find substituents attached to ring atoms.

Parameters:

  • mol – RDKit Mol object

  • ring_atoms (Tuple[int, ...]) – Tuple of atom indices defining the ring

Returns:

Dict mapping ring atom index to list of substituent atom lists. Each substituent is a list of atom indices (found via BFS).

Return type:

Dict[int, List[List[int]]]

orthonym.rules.cycloalkanes.orient_cycloalkane(mol, ring_atoms, substituent_positions, principal_group_atoms=None)#

Orient a cycloalkane ring to give lowest locants to substituents.

For cycloalkanes without double bonds: - Single substituent: that carbon is position 1 - Multiple substituents: apply first-point-of-difference rule

When the principal characteristic group sits on ring atoms (expressed as a suffix: -ol, -one, -amine,…), numbering applies instead: the suffix anchor takes the lowest locant before any detachable prefix.

Parameters:

  • mol – RDKit Mol object

  • ring_atoms (Tuple[int, ...]) – Tuple of atom indices in the ring

  • substituent_positions (Dict[int, List[List[int]]]) – Dict mapping ring atom index to substituent lists

  • principal_group_atoms (Set[int] | None) – Optional set of ring atom indices bearing the principal characteristic group (e.g., the ring C of C-OH / C=O / C-NH2). Exocyclic-carbon suffixes (-carbaldehyde, -carboxylic acid) must NOT be included — they do not seize ring numbering.

Returns:

List of ring atom indices reordered so position 1 is first

Return type:

List[int]

orthonym.rules.cycloalkanes.ring_double_bond_locant(pos1, pos2, n)#

Locant of a ring double bond between two oriented positions (0-based).

Ring bonds connect consecutive positions; the locant is the lower position + 1 — EXCEPT the ring-closure bond (positions 0 and n-1), whose locant is n (a 6-ring bond between C6 and C1 is the 6-ene bond, never 1-ene). The naive min(pos)+1 called the closure bond “1”, which let the orientation comparator pick a direction whose emitted 1-ene described a DIFFERENT structure (canary rt75_0019 RT True->False).

orthonym.rules.cycloalkanes.orient_cycloalkene(mol, ring_atoms, double_bond_atoms, substituent_positions=None, principal_group_atoms=None)#

Orient a cycloalkene ring for IUPAC naming.

IUPAC 2013 rules: - When a principal characteristic group is on the ring, it receives

the lowest possible locant (ideally 1).

  • Double bond locant is secondary to principal group locant.

  • When no principal group is on the ring, double bond is at C1-C2.

  • Direction is chosen to give lowest locants to other substituents.

  • For mono-cycloalkenes, the locant is omitted in the name.

Parameters:

  • mol – RDKit Mol object

  • ring_atoms (Tuple[int, ...]) – Tuple of atom indices in the ring

  • double_bond_atoms (List[Tuple[int, int]]) – List of (atom1, atom2) tuples for double bonds

  • substituent_positions (Dict[int, List[List[int]]] | None) – Optional dict mapping ring atom index to substituent lists

  • principal_group_atoms (Set[int] | None) – Optional set of ring atom indices bearing the principal characteristic group (e.g., C bearing =O for ketone)

Returns:

List of ring atom indices reordered for IUPAC naming

Return type:

List[int]

orthonym.rules.cycloalkanes.select_ring_or_chain_parent(mol, rings, chain, principal_group=None)#

Determine whether ring or chain should be the parent structure.

IUPAC 2013 Method 1 (PIN): 1. Principal characteristic group location: If principal FG is on chain

but not ring, chain wins. If on ring but not chain, ring wins.

  1. Same class (both carbon): Ring has seniority over chain

  2. Exception: Chain is parent if it’s significantly longer than ring

For pure hydrocarbons (no FG): - Ring is parent when ring carbon count >= chain carbon count - Chain is parent when significantly longer than ring

Parameters:

  • mol – RDKit Mol object

  • rings (List[Tuple[int, ...]]) – List of ring atom tuples

  • chain (List[int]) – List of chain atom indices

  • principal_group (str | None) – Name of principal functional group, if any

Returns:

‘ring’ or ‘chain’

Return type:

str

orthonym.rules.cycloalkanes.get_substituent_name(mol, sub_atoms, ring_atoms=None)#

Get the name of a substituent from its atom list.

Parameters:

  • mol – RDKit Mol object

  • sub_atoms (List[int]) – List of atom indices in the substituent

  • ring_atoms (set) – Optional set of ring atom indices (for recursive naming)

Returns:

Substituent name (e.g., ‘methyl’, ‘ethyl’, ‘isopropyl’) or None

Return type:

str | None