orthonym.rules.bridged_fused

Note

Internal API. Names and behaviour may change between releases.

Bridged fused nomenclature - systems that are part fused and part bridged.

Implements IUPAC 2013 rules for naming systems like 1,4-methanonaphthalene where a fused core (naphthalene) has additional bridges across non-adjacent positions.

Key concepts: - Bridged fused = fused core + additional bridges across the fused system - Different from pure von Baeyer (no fused component) - Different from pure fused (no bridges across) - Name format: [locants]-[bridge_prefix][fused_parent_name]

e.g., “1,4-methanonaphthalene”, “1,4:5,8-dimethanonaphthalene”

Bridge prefixes (.3): - Carbon bridges: methano (1C), ethano (2C), propano (3C), butano (4C) - Heteroatom bridges: epoxy (O), epithio (S), epimino (NH), epidioxy (O-O)

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

orthonym.rules.bridged_fused.GENERAL_ONLY_BRIDGE_PREFIXES = frozenset({'epidithio', 'epimino', 'episeleno', 'epitelluro', 'epithio'})

these bridge prefixes are general nomenclature; the preselected (PIN) prefixes are ‘sulfano’, ‘disulfano’, ‘selano’, ‘tellano’ and ‘azano’, which OPSIN 2.9.0 cannot read, so a name that uses one of these is never certified a PIN.

Type:

(the Blue Book-14110)

orthonym.rules.bridged_fused.detect_bridged_fused(mol)

Detect whether a molecule is a bridged fused system.

A bridged fused system has BOTH: 1. A fused ring core (two or more rings sharing edges) 2. Additional bridges connecting non-adjacent atoms of the fused core

This distinguishes bridged fused from: - Pure fused systems (like naphthalene) - no bridges - Pure bridged systems (like norbornane) - no fused core

Parameters:

mol – RDKit Mol object

Returns:

True if molecule is a bridged fused system, False otherwise

Return type:

bool

Examples

>>> mol = Chem.MolFromSmiles("c1ccc2ccccc2c1") # naphthalene
>>> detect_bridged_fused(mol)
False # pure fused, no bridges
>>> mol = Chem.MolFromSmiles("C1CC2CCC1C2") # norbornane
>>> detect_bridged_fused(mol)
False # pure bridged, no fused core

orthonym.rules.bridged_fused.identify_fused_core(mol)

Identify the maximal fused ring component (.2 algorithm).

For a bridged fused system, the fused core is the largest set of rings that share edges (ortho-fused or ortho-peri-fused).

Maximization priority (.2): 1. Maximum number of fused rings 2. Maximum number of skeletal atoms

Parameters:

mol – RDKit Mol object

Returns:

Dict with –

• ‘core_atoms’: Set of atom indices in the fused core

• ’core_name’: Name of the fused parent if recognized

• ’core_numbering’: Dict mapping atom index to IUPAC locant

• ’ring_count’: Number of rings in the fused core

Or None if no fused core found

Return type:

Dict[str, Any] | None

Examples

>>> mol = Chem.MolFromSmiles("c1ccc2ccccc2c1") # naphthalene
>>> core = identify_fused_core(mol)
>>> len(core['core_atoms'])
10

orthonym.rules.bridged_fused.identify_bridges(mol, fused_core_atoms)

Find bridges across the fused core.

A bridge connects two atoms of the fused core via atoms NOT in the fused core.

Parameters:

• mol – RDKit Mol object

• fused_core_atoms (Set[int]) – Set of atom indices in the fused core

Returns:

List of bridge info dicts, each containing –

• ‘atoms’: List of atom indices in the bridge (excluding endpoints)

• ’length’: Number of atoms in the bridge

• ’start_locant’: Locant of starting endpoint on fused core

• ’end_locant’: Locant of ending endpoint on fused core

• ’element’: Primary element type (‘C’, ‘O’, ‘S’, ‘N’)

• ’heteroatom’: Heteroatom type if not all carbon

Return type:

List[Dict[str, Any]]

Examples

>>> mol = Chem.MolFromSmiles("c1ccc2ccccc2c1") # naphthalene
>>> bridges = identify_bridges(mol, set(range(10)))
>>> len(bridges)
0 # No bridges in pure naphthalene

orthonym.rules.bridged_fused.get_bridge_prefix(bridge_info)

Get the IUPAC bridge prefix for a bridge.

Carbon bridges: methano (1), ethano (2), propano (3), etc. Heteroatom bridges: epoxy (O), epithio (S), epimino (NH)

Parameters:

bridge_info (Dict[str, Any]) – Dict with ‘length’, ‘element’, and optionally ‘heteroatom’

Returns:

Bridge prefix string

Return type:

str

Examples

>>> get_bridge_prefix({'length': 1, 'element': 'C', 'atoms': [1]})
'methano'
>>> get_bridge_prefix({'length': 1, 'element': 'O', 'heteroatom': 'O'})
'epoxy'

orthonym.rules.bridged_fused.name_bridged_fused_system(mol)

Generate the IUPAC name for a bridged fused system.

Name format : [locants]-[bridge_prefix][fused_parent_name] Examples: - 1,4-methanonaphthalene - 1,4:5,8-dimethanonaphthalene

For multiple identical bridges, use multiplicative prefix (di-, tri-). For different bridges, alphabetize.

Parameters:

mol – RDKit Mol object

Returns:

Tuple of (name, ring_atoms, atom_to_locant, substituents_included) where substituents_included is False (bridged-fused handler does not discover substituents), or None if not a bridged fused system.

Examples

>>> mol = Chem.MolFromSmiles("c1ccc2ccccc2c1") # naphthalene
>>> name_bridged_fused_system(mol)
None # Not bridged fused

orthonym.rules.bridged_fused.is_bridged_fused(mol)

Alias for detect_bridged_fused for API consistency.

Parameters:

mol – RDKit Mol object

Returns:

True if molecule is a bridged fused system

Return type:

bool

orthonym.rules.bridged_fused.name_bridged_fused_pin(mol)

Name a bridged-fused ring system by the cascade (DD7).

Returns the standard complex-ring tuple (name, ring_atoms, atom_to_locant, substituents_included) for the handled class, else None (the caller then falls through to G0 fail-closed). The name is assembled as: bridge + hydro prefixes cited TOGETHER in alphanumerical order, ignoring multiplying prefixes (‘epoxy’ < ‘ethano’ < ‘hydro’ < ‘methano’), each with its own locant set, then the parent (Blue Book /: ‘1,4-dihydro-1,4-methanonaphthalene’, ‘1,4-epoxy-1,4-dihydronaphthalene’, ‘1,4-ethano-1,2,3,4-tetrahydronaphthalene’.

SECONDARY BRIDGES /.2.4/.2.5) are NOT handled here: a dependent secondary bridge (a bridge whose termini are themselves bridge atoms, numbered with superscript locants like 0^2,7) is von Baeyer territory (tetracyclo[...0^2,7]...), owned by polycyclic_von_baeyer.py. Such a topology never yields a clean naphthalene/anthracene residual through the excision/partition guards below, so it fails closed here and cascades to the von Baeyer engine — a documented follow-up if a fused-parent secondary-bridge PIN ever needs Orthonym emission.

orthonym.rules.bridged_fused.has_aromatic_mancude_bridge(mol)

True when a FULLY-AROMATIC-perceived ring system is actually a mancude bridged-fused hydrocarbon that name_bridged_fused_pin can name

etheno/buta[1,3]dieno on naphthalene: RDKit’s extended

aromaticity marks the -CH=CH- bridge aromatic, so the von-Baeyer gate’s all-aromatic skip would otherwise strand it). Used only to EXEMPT this class from that skip; returns False for a plain fused PAH (no bridge) so the retained-name / fusion path keeps it.

orthonym.rules.bridged_fused.has_aromatic_chalcogen_bridge(mol)

True when a divalent O/S ring atom is a genuine BRIDGE that RDKit’s extended aromaticity model hides (Wave-2 completion, (a)): its two neighbours share a ring that does NOT contain the chalcogen, at NON-ADJACENT positions of that ring (1,4-epoxynaphthalene). A fusion chalcogen (dibenzofuran O) shares only its own ring with its neighbours and returns False. Used to exempt this class from the all-aromatic routing skips that would otherwise strand it on a partial-parent namer.

orthonym.rules.bridged_fused.get_bridged_fused_info(mol)

Get complete information about a bridged fused system.

Combines detection, core identification, and bridge analysis into a single comprehensive dict.

Parameters:

mol – RDKit Mol object

Returns:

Dict with all bridged fused information, or None if not applicable –

• ‘is_bridged_fused’: True

• ’core’: Result from identify_fused_core

• ’bridges’: Result from identify_bridges

• ’name’: Generated IUPAC name

Return type:

Dict[str, Any] | None

Examples

>>> mol = Chem.MolFromSmiles("...") # bridged fused system
>>> info = get_bridged_fused_info(mol)
>>> info['is_bridged_fused']
True