`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’, 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)#

The bridged fused name of mol from the bridged fused PIN builder: the complex-ring tuple (name, ring_atoms, atom_to_locant, substituents_included), or None when the builder declines. substituents_included is True: the builder spells every prefix, suffix and stereodescriptor on its own numbering.

A dependent secondary bridge (tricyclo[...0^2,7]...), a polyvalent bridge and a ring bridge are bridge shapes the builder only ranks as competitors (selection._competitor_sets); a reading that one of them outranks declines, and the caller keeps the von Baeyer name.

orthonym.rules.bridged_fused.name_fused_carbocycle_pin(mol)#: The fusion name of mol whose ring system is an ortho- or ortho- and peri-fused system, carbocyclic or with ring heteroatoms, with at least two rings of five or more members, the Blue Book), from bridged_fused_pin.build_fused: the complex-ring tuple (name, ring_atoms, atom_to_locant, True) (the builder spells every prefix, suffix and stereodescriptor on its own numbering), or None when the builder declines. An internal error of the builder is a decline (builder_declining_on_error).

orthonym.rules.bridged_fused.joins_identical_hetero_ring_systems(mol, system)#

True when system (the ring atoms being named) has a ring heteroatom and a bond joins it to another ring system of mol with the same skeleton: a ring assembly, the Blue Book) is a parent of its own,:19461) and takes the assembly name (‘2’H-1,2’-biindole’), so a name with one component as the parent is not the PIN (ring_assembly_screen). The test is scoped to the ring system being named: a hetero ring elsewhere in the molecule, or a phenyl on a benzene ring, does not decide for a carbocyclic system, whose assemblies keep the older behaviour. On error it is True (fail closed).

orthonym.rules.bridged_fused.builder_declining_on_error(entry, *args)#

entry(*args) for an entry point of the bridged fused PIN builder (build, build_substituent); None when the builder raises: no name, never a different one.

The error is logged at ERROR level with its traceback, so a defect inside the builder shows in the eval and BB measure logs (the eval harness workers switch off logging up to WARNING) instead of looking like an ordinary decline. A deliberate refusal (OrthonymLimitError) still propagates, and a wall-clock limit (WallClockTimeout, a BaseException) is not caught.

orthonym.rules.bridged_fused.has_aromatic_mancude_bridge(mol)#

True when a FULLY-AROMATIC-perceived ring system is actually a mancude bridged fused ring system that the bridged fused PIN builder names etheno bridges: RDKit’s extended aromaticity marks the -CH=CH- bridge aromatic, so the von-Baeyer gate’s all-aromatic skip would otherwise strand it, as in 1,4-ethenonaphthalene and 4,7-ethenoazulene). 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#

`orthonym.rules.bridged_fused`#