orthonym.rules.ortho_fused#

Note

Internal API. Names and behaviour may change between releases.

IUPAC Ortho-Fused Ring System Naming

This module implements comprehensive IUPAC naming for ortho-fused heterocyclic systems, including bicyclic lactones and other complex fused ring systems following Blue Book rules.

References: - IUPAC 2013: ortho-fused polycyclic hydrocarbons - IUPAC 2013: numbering of fused polycyclic hydrocarbons - IUPAC 2013: indicated hydrogen in fused ring systems - IUPAC 2013: von Baeyer nomenclature for bicyclic systems

orthonym.rules.ortho_fused.detect_lactone(ring_atoms, mol)#

Detect if a ring is a lactone (cyclic ester).

A lactone contains the -C(=O)O- pattern within the ring structure.

IUPAC lactone classification: - γ-lactone (5-membered): oxolan-2-one - δ-lactone (6-membered): oxan-2-one - ε-lactone (7-membered): oxepan-2-one

Parameters:

  • ring_atoms (List[int]) – List of atom indices forming the ring

  • mol (Mol) – RDKit Mol object

Returns:

Dictionary with keys –

  • ‘carbonyl_idx’: Index of the carbonyl carbon

  • ’ester_O_idx’: Index of the ester oxygen in the ring

  • ’ring_size’: Number of atoms in the ring

  • ’type’: Lactone type (‘gamma’, ‘delta’, ‘epsilon’, etc.)

Returns None if not a lactone

Return type:

Dict | None

orthonym.rules.ortho_fused.identify_fused_rings(mol)#

Identify pairs of ortho-fused rings (sharing 2 adjacent atoms and 1 bond).

Parameters:

mol (Mol) – RDKit Mol object

Returns:

List of tuples – (ring1_atoms, ring2_atoms, shared_atoms)

Return type:

List[Tuple[List[int], List[int], List[int]]]

orthonym.rules.ortho_fused.classify_heterocycle_priority(ring_atoms, mol)#

Classify heterocycle priority according to IUPAC rules.

IUPAC Priority (highest to lowest): 1. Nitrogen-containing heterocycles 2. Oxygen-containing heterocycles 3. Sulfur-containing heterocycles 4. Carbocycles (all carbon)

Within each class, larger rings have priority.

Parameters:

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

  • mol (Mol) – RDKit Mol object

Returns:

Priority score (higher = more preferred as base component)

Return type:

int

orthonym.rules.ortho_fused.determine_base_component(rings, mol)#

Determine the base component (parent ring) for a fused system.

IUPAC rules for base component selection: 1. Heterocyclic ring preferred over carbocyclic 2. Among heterocycles: N > O > S 3. Larger ring preferred 4. Lactone rings get special consideration

Parameters:

  • rings (List[Tuple[List[int], List[int], List[int]]]) – List of fused ring pairs from identify_fused_rings

  • mol (Mol) – RDKit Mol object

Returns:

Tuple of (base_ring_atoms, attached_ring_atoms) or None

Return type:

Tuple[List[int], List[int]] | None

orthonym.rules.ortho_fused.get_bicyclo_descriptor(base_ring, attached_ring, shared_atoms, mol)#

Generate bicyclo descriptor [x.y.z] for fused ring system.

For ortho-fused systems, one bridge has 0 atoms (the shared bond). Numbers are listed in descending order.

Parameters:

  • base_ring (List[int]) – Atoms in the base ring

  • attached_ring (List[int]) – Atoms in the attached ring

  • shared_atoms (List[int]) – The 2 atoms shared between rings

  • mol (Mol) – RDKit Mol object

Returns:

Bicyclo descriptor string like “[4.3.0]”

Return type:

str

orthonym.rules.ortho_fused.get_parent_name(total_carbons)#

Get parent alkane name for carbon count.

orthonym.rules.ortho_fused.number_bicyclic_system(base_ring, attached_ring, shared_atoms, mol, lactone_info=None)#

Number bicyclic system according to IUPAC bicyclo rules.

IUPAC bicyclo numbering: 1. Start at one bridgehead atom 2. Number along the longest bridge first 3. Then the second longest bridge 4. The fused bond (0-length bridge) is between the two bridgeheads

For bicyclo[4.3.0]nonane: - Position 1: first bridgehead - Positions 2-5: longest bridge (4 atoms) - Position 6: second bridgehead - Positions 7-9: second bridge (3 atoms back to pos 1)

Parameters:

  • base_ring (List[int]) – Atoms in base ring

  • attached_ring (List[int]) – Atoms in attached ring

  • shared_atoms (List[int]) – Bridgehead atoms

  • mol (Mol) – RDKit Mol object

  • lactone_info (Dict | None) – Lactone detection info if present

Returns:

Dict mapping atom index to IUPAC locant

Return type:

Dict[int, int]

orthonym.rules.ortho_fused.get_substituents(mol, ring_atoms, atom_to_locant)#

Identify substituents on the bicyclic system.

Parameters:

  • mol (Mol) – RDKit Mol object

  • ring_atoms (set) – Set of atoms in the bicyclic system

  • atom_to_locant (Dict[int, int]) – Mapping of atom idx to IUPAC locant

Returns:

List of (locant, substituent_name) tuples

Return type:

List[Tuple[int, str]]

orthonym.rules.ortho_fused.format_substituent_prefix(substituents)#

Format substituents as IUPAC prefix.

orthonym.rules.ortho_fused.name_fused_lactone_system(mol, base_ring, attached_ring, shared_atoms, lactone_info)#

Generate IUPAC name for a fused lactone system.

Format: [substituents]-bicyclo[x.y.z]parent-2-one

Parameters:

  • mol (Mol) – RDKit Mol object

  • base_ring (List[int]) – Atoms in lactone ring

  • attached_ring (List[int]) – Atoms in attached ring

  • shared_atoms (List[int]) – Bridgehead atoms

  • lactone_info (Dict) – Lactone detection info

Returns:

IUPAC systematic name

Return type:

str

orthonym.rules.ortho_fused.name_ortho_fused_system(mol)#

Name ortho-fused ring systems using IUPAC Blue Book rules.

Priority: 1. Check for retained names (handled by existing fused_heterocycles) 2. Identify lactone systems 3. Apply systematic bicyclo/fusion naming

Parameters:

mol (Mol) – RDKit Mol object

Returns:

IUPAC systematic name or None if naming fails

Return type:

str | None