`orthonym.rules.fused_rings`#

Note

Internal API. Names and behaviour may change between releases.

Fused ring system detection and naming.

Handles: - Classification of fused ring systems (ortho-fused, ortho-peri-fused, bridged-fused) - Naming of fused heterocycles with retained names priority - Substituent detection and locant assignment for fused systems - N-substitution handling for fused heterocycles

IUPAC 2013 Rules for fused systems: - Ortho-fused: rings share exactly one bond (2 atoms) - Ortho-peri-fused: at least one ring shares atoms with 3+ other rings - ALWAYS check retained names FIRST before systematic naming - Tautomer locants (1H-, 2H-, 9H-) must be preserved in names - N-substitution uses N-locant format (N-methyl, not 1-methyl)

Reference: IUPAC 2013 Blue Book, Section (Fused Ring Systems)

orthonym.rules.fused_rings.get_shared_atoms(mol, ring1, ring2)#

Get atoms shared between two rings.

Parameters:

mol – RDKit Mol object
ring1 (Tuple[int, ...]) – Tuple of atom indices in first ring
ring2 (Tuple[int, ...]) – Tuple of atom indices in second ring

Returns:

Set of atom indices shared by both rings

Return type:

Set[int]

Examples

>>> mol = Chem.MolFromSmiles('c1ccc2[nH]ccc2c1') # indole
>>> ri = mol.GetRingInfo
>>> rings = ri.AtomRings
>>> shared = get_shared_atoms(mol, rings[0], rings[1])
>>> len(shared) # 2 atoms shared in ortho-fused system
2

orthonym.rules.fused_rings.classify_fused_system(mol)#

Classify a fused ring system by its fusion type.

Classification: - ‘ortho-fused’: All ring pairs share exactly 2 atoms (one edge) - ‘ortho-peri-fused’: At least one ring shares atoms with 3+ other rings - ‘bridged-fused’: Bridges exist across fused system (like norbornane) - ‘not-fused’: Rings share 0-1 atoms (isolated or spiro)

Parameters:: mol – RDKit Mol object
Returns:: Classification string
Return type:: str

Examples

>>> mol = Chem.MolFromSmiles('c1ccc2[nH]ccc2c1') # indole
>>> classify_fused_system(mol)
'ortho-fused'
>>> mol = Chem.MolFromSmiles('c1cc2ccc3cccc4ccc(c1)c2c34') # pyrene
>>> classify_fused_system(mol)
'ortho-peri-fused'

orthonym.rules.fused_rings.is_fused_bicyclic(mol)#

Check if molecule is a fused bicyclic system (exactly 2 rings sharing one edge).

This distinguishes fused bicyclics from bridged bicyclics (like norbornane) which have bridgehead atoms shared by more than 2 rings conceptually.

Parameters:: mol – RDKit Mol object
Returns:: True if exactly 2 rings sharing exactly 2 atoms
Return type:: bool

Examples

>>> mol = Chem.MolFromSmiles('c1ccc2[nH]ccc2c1') # indole
>>> is_fused_bicyclic(mol)
True
>>> mol = Chem.MolFromSmiles('c1ccc2c(c1)[nH]c1ccccc12') # carbazole (tricyclic)
>>> is_fused_bicyclic(mol)
False

orthonym.rules.fused_rings.name_fused_heterocycle(mol)#

Generate IUPAC name for a fused heterocycle.

Naming priority: 1. Check xanthine derivatives FIRST (caffeine, theophylline, etc.)

These have specific N-position numbering (1,3,7-trimethyl format)

Check retained names (indole, quinoline, carbazole, etc.)
Add tautomer locant if present (1H-indole)
For substituted: find substituents and add prefixes
Handle N-substitution specially (N-methyl, not 1-methyl)

Parameters:: mol – RDKit Mol object
Returns:: Tuple of (name, ring_atoms, atom_to_locant, substituents_included) where substituents_included is True (fused heterocycle handler already discovers substituents via get_fused_heterocycle_substituents), or None if not a recognized fused heterocycle.

Examples

>>> mol = Chem.MolFromSmiles('c1ccc2[nH]ccc2c1') # indole
>>> result = name_fused_heterocycle(mol)
>>> result[0]
'1H-indole'

orthonym.rules.fused_rings.get_fused_heterocycle_substituents(mol, core_match)#

Find substituents on a fused heterocycle core.

Identifies atoms not in the core match as potential substituents, maps them to IUPAC locants using core numbering, and tracks N-substitution separately.

Parameters:

mol – RDKit Mol object
core_match (Dict[int, Any]) – Dict mapping mol atom indices to IUPAC locants (int or str like ‘3a’)

Returns:

Dict with –

‘c_substituents’: Dict[str, List[int]] - C-substituent name -> locants
’n_substituents’: Dict[str, int] - N-substituent name -> count
’other’: List[Dict] - Other substituents (halogens, etc.)

Return type:

Dict

Examples

>>> mol = Chem.MolFromSmiles('Cc1ccc2[nH]ccc2c1') # 5-methylindole
>>> core_match = match_fused_heterocycle_core(mol)[1]
>>> subs = get_fused_heterocycle_substituents(mol, core_match)
>>> 'methyl' in subs['c_substituents']
True

orthonym.rules.fused_rings.name_ortho_fused_bicyclic(mol)#

Generate name for an ortho-fused bicyclic system without a retained name.

This is a fallback for carbocyclic ortho-fused systems not covered by polycyclic_data. Most common fused systems should have retained names.

For systematic naming, uses fusion descriptors like benzo[x]parent.

Parameters:: mol – RDKit Mol object
Returns:: Tuple of (name, ring_atoms, atom_to_locant, substituents_included), or None if not an ortho-fused bicyclic.

Examples

>>> # For systems without retained names, would generate systematic names
>>> # Most common ones (naphthalene, indole) have retained names

orthonym.rules.fused_rings.is_fused_aromatic_system(mol)#

Check if molecule contains a fused aromatic ring system.

A fused aromatic system has 2+ aromatic rings sharing edges.

Parameters:: mol – RDKit Mol object
Returns:: True if fused aromatic system detected
Return type:: bool

Examples

>>> mol = Chem.MolFromSmiles('c1ccc2ccccc2c1') # naphthalene
>>> is_fused_aromatic_system(mol)
True
>>> mol = Chem.MolFromSmiles('c1ccccc1') # benzene
>>> is_fused_aromatic_system(mol)
False

orthonym.rules.fused_rings.is_fused_heterocyclic_system(mol)#

Check if molecule contains a fused heterocyclic ring system.

A fused heterocyclic system has at least one heterocyclic ring fused with another ring.

Parameters:: mol – RDKit Mol object
Returns:: True if fused heterocyclic system detected
Return type:: bool

Examples

>>> mol = Chem.MolFromSmiles('c1ccc2[nH]ccc2c1') # indole
>>> is_fused_heterocyclic_system(mol)
True

orthonym.rules.fused_rings.get_fused_ring_sizes(mol)#

Get the sizes of the two rings in a fused bicyclic system.

Parameters:: mol – RDKit Mol object with exactly 2 fused rings
Returns:: Tuple of (ring1_size, ring2_size), sorted largest first
Return type:: Tuple[int, int]

Examples

>>> mol = Chem.MolFromSmiles('C1CCC2CCCCC2C1') # decalin
>>> get_fused_ring_sizes(mol)
(6, 6)

orthonym.rules.fused_rings.name_saturated_fused_bicyclic(mol, parent_name='decahydronaphthalene')#

Generate IUPAC name for a saturated fused bicyclic with ring junction stereochemistry.

For saturated fused systems like decalin (decahydronaphthalene), the stereochemistry at ring junction atoms (bridgeheads) must be specified.

IUPAC format: (4aR,8aS)-decahydronaphthalene Alternative: cis-decalin or trans-decalin (for common cases)

Parameters:

mol – RDKit Mol object
parent_name (str) – The parent name for the saturated system

Returns:

IUPAC name with stereodescriptor prefix, or None if cannot determine

Return type:

str | None

Examples

>>> mol = Chem.MolFromSmiles('C1CC[C@@H]2CCCC[C@@H]2C1') # cis-decalin
>>> name_saturated_fused_bicyclic(mol)
'(4as,8as)-decahydronaphthalene'
>>> mol = Chem.MolFromSmiles('C1CC[C@@H]2CCCC[C@H]2C1') # trans-decalin
>>> name_saturated_fused_bicyclic(mol)
'(4ar,8ar)-decahydronaphthalene'

orthonym.rules.fused_rings.get_ring_junction_stereo_prefix(mol)#

Get the stereochemistry prefix for ring junction atoms in a fused system.

This is a utility function that can be used by other naming functions to add ring junction stereochemistry to a name.

Parameters:: mol – RDKit Mol object
Returns:: Stereodescriptor prefix like “(4aS,8aS)-” or “” if no stereo
Return type:: str

Examples

>>> mol = Chem.MolFromSmiles('C1CC[C@@H]2CCCC[C@@H]2C1')
>>> get_ring_junction_stereo_prefix(mol)
'(4as,8as)-'

orthonym.rules.fused_rings.get_simple_cis_trans_prefix(mol)#

Get simple cis/trans prefix for bicyclic ring junction.

For simple bicyclic systems, returns “cis-” or “trans-” instead of the full (4aR,8aS)- notation. This is a common simplification.

Parameters:: mol – RDKit Mol object
Returns:: “cis-” or “trans-” or “” if cannot determine
Return type:: str

Examples

>>> mol = Chem.MolFromSmiles('C1CC[C@@H]2CCCC[C@@H]2C1')
>>> get_simple_cis_trans_prefix(mol)
'cis-'
>>> mol = Chem.MolFromSmiles('C1CC[C@@H]2CCCC[C@H]2C1')
>>> get_simple_cis_trans_prefix(mol)
'trans-'

orthonym.rules.fused_rings#

`orthonym.rules.fused_rings`#