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.get_ring_triple_bonds(mol, ring_atoms)#

All triple bonds within a ring, as (atom_idx1, atom_idx2) tuples.

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, triple_bond_atoms=None)#

Orient an unsaturated carbocycle (double and/or triple ring bonds) for IUPAC naming.

IUPAC 2013 rules: - (c) (the Blue Book): a principal characteristic group on the

ring receives the lowest possible locant (ideally 1).

  • (e)(ii) (:3290): “low locants are given first to multiple bonds as a set and then to double bonds”; (:21366) “lower locants are assigned first to the endings as a set without regard to type and then to ‘ene’ endings” (‘cycloicosa-1,3-dien-5-yne (PIN)’,:21372).

  • When no principal group is on the ring, one double or triple bond takes the locant 1,:16548).

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

  • For a ring with a single multiple bond, the locant is omitted in the name.

With no triple bond the multiple-bond set IS the double-bond set, so the criteria reduce to the double-bond ones.

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)

  • triple_bond_atoms (List[Tuple[int, int]] | None) – Optional list of (atom1, atom2) tuples for triple bonds

Returns:

List of ring atom indices reordered for IUPAC naming

Return type:

List[int]

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