`orthonym.namer`#

Note

Internal API. Names and behaviour may change between releases.

Main IUPAC nomenclature generator.

Architecture:: SMILES → Perception → Classification → Assembly → IUPAC Name
This is the inverse of OPSIN’s pipeline:: OPSIN: Name → Tokenize → Parse → Build Structure Orthonym: Structure → Perceive → Classify → Assemble Name

orthonym.namer.classify_compound_class(mol, canonical_smiles)#

Classify molecule into compound class for pre-routing.

Returns class label or None for general routing. Classification order per:

steroid -> alkaloid -> terpene -> peptide -> amino_acid -> carbohydrate -> general

Parameters:

mol – RDKit Mol object.
canonical_smiles (str) – Canonical SMILES string.

Returns:

One of ‘steroid’, ‘alkaloid’, ‘terpene’, ‘carbohydrate’, or None.

Return type:

str | None

class orthonym.namer.MolecularFeatures(mol, smiles='', canonical_smiles='', functional_groups=<factory>, principal_group=None, principal_group_atoms=<factory>, principal_chain=<factory>, atom_to_locant=<factory>, substituents=<factory>, ring_systems=<factory>, all_ring_atoms=<factory>, is_cyclic=False, is_aromatic=False, ring_type=None, principal_ring=None, senior_ring_system=None, oriented_ring=None, ring_substituents=<factory>, ring_double_bonds=<factory>, ring_double_bond_locants=<factory>, ring_triple_bonds=<factory>, ring_triple_bond_locants=<factory>, ring_assembly_info=None, is_benzene=False, benzene_ring=None, benzene_substituents=<factory>, polycyclic_name=None, polycyclic_substituents=<factory>, heterocycle_info=None, oriented_heterocycle=None, heterocycle_atom_to_locant=None, heterocycle_substituents=<factory>, stereocenters=<factory>, double_bond_stereo=<factory>, double_bonds=<factory>, triple_bonds=<factory>, is_polyfunctional=False, non_principal_groups=<factory>, ester_match=None, amide_type=None, n_substituents=<factory>, ring_substituents_as_groups=<factory>, chain_is_parent=False, species_type='neutral', ion_sites=<factory>, radical_sites=<factory>, total_charge=0, parent_selection_result=None)#

Bases: object

Container for perceived molecular features.

mol: Any#

smiles: str = ''#

canonical_smiles: str = ''#

functional_groups: Dict[str, List[tuple]]#

principal_group: str | None = None#

principal_group_atoms: List[tuple]#

principal_chain: List[int]#

atom_to_locant: Dict[int, int]#

substituents: Dict[int, List[List[int]]]#

ring_systems: List[set]#

all_ring_atoms: frozenset#

is_cyclic: bool = False#

is_aromatic: bool = False#

ring_type: str | None = None#

principal_ring: tuple | None = None#

senior_ring_system: tuple | None = None#

oriented_ring: List[int] | None = None#

ring_substituents: Dict[int, List[List[int]]]#

ring_double_bonds: List[tuple]#

ring_double_bond_locants: List[int]#

ring_triple_bonds: List[tuple]#

ring_triple_bond_locants: List[int]#

ring_assembly_info: Dict | None = None#

is_benzene: bool = False#

benzene_ring: tuple | None = None#

benzene_substituents: Dict[int, List[Dict]]#

polycyclic_name: str | None = None#

polycyclic_substituents: Dict[int, List[Dict]]#

heterocycle_info: Dict | None = None#

oriented_heterocycle: List[int] | None = None#

heterocycle_atom_to_locant: Dict[int, int] | None = None#

heterocycle_substituents: Dict[int, List[Dict]]#

stereocenters: List[dict]#

double_bond_stereo: List[dict]#

double_bonds: List[tuple]#

triple_bonds: List[tuple]#

is_polyfunctional: bool = False#

non_principal_groups: Dict[str, List[tuple]]#

ester_match: tuple | None = None#

amide_type: str | None = None#

n_substituents: List[Dict]#

ring_substituents_as_groups: List[tuple]#

chain_is_parent: bool = False#

species_type: str = 'neutral'#

ion_sites: Dict[str, List[Dict]]#

radical_sites: List[Dict]#

total_charge: int = 0#

parent_selection_result: Any | None = None#

orthonym.namer.compute_features(mol, smiles=None)#

a phase: thin module-level wrapper around Orthonym._perceive.

Provides a public-API perception entry for tests and downstream callers. Mirrors what name_compound does internally before naming.

Parameters:

mol – RDKit Mol object.
smiles (str | None) – Optional input SMILES; if None, derived via Chem.MolToSmiles(mol).

Returns:

MolecularFeatures populated by Orthonym._perceive.

Return type:

MolecularFeatures

Source: a phase Plan 02 fix (public-API perception entry).

orthonym.namer.BINDING_PROOF_MODES = ('off', 'audit', 'enforce')#: the accepted values of the binding-proof flag.

orthonym.namer.validate_binding_proof(value)#

Single source of truth for the binding-proof mode check.

Shared by Orthonym.__init__ and every surface that accepts the flag (notably the CLI’s --batch path, which builds its namers lazily inside a per-row except Exception and would otherwise degrade a typo into a row-level “ERROR:” line). Validate eagerly and identically everywhere: a misspelled mode that silently degraded to “off” would present as a clean run with the proof never executing – the one failure mode an audit flag must not have.

class orthonym.namer.Orthonym(style='pin', *, _disable_grammar_validation=False, _disable_opsin_validity_gate=False, enable_triviality_controller=False, enable_group_splitting=False, trivial_fallback=False, general_fallback=False, general_fallback_unverified=False, allow_aromatic_general=False, full_coverage=False, _principal_group_override=None, _forced_parent_rank=0, _seed_excluded_dispatch_classes=frozenset({}), binding_proof='off')#

Bases: object

The naming engine, with every option.

Build one instance and name as many molecules with it as you like; the options apply to every call.:func:name_compound builds a fresh instance for each call.

Creating an instance checks that the OPSIN and centres jars are present and stops with an error if they are not (run orthonym --fetch-jars). Set ORTHONYM_ALLOW_REDUCED=1 to name without them, with no OPSIN check.

Parameters:

style ({"pin", "general", "cas"}, default "pin") – Naming style, as for:func:name_compound.
enable_triviality_controller (bool) – As for:func:name_compound. All default to False.
enable_group_splitting (bool) – As for:func:name_compound. All default to False.
trivial_fallback (bool) – As for:func:name_compound. All default to False.
general_fallback (bool) – The switches behind the command line’s --emit-tier. All default to False, which is the default tier. valid sets general_fallback; complete adds allow_aromatic_general; best-effort adds general_fallback_unverified; full-coverage adds full_coverage.
general_fallback_unverified (bool) – The switches behind the command line’s --emit-tier. All default to False, which is the default tier. valid sets general_fallback; complete adds allow_aromatic_general; best-effort adds general_fallback_unverified; full-coverage adds full_coverage.
allow_aromatic_general (bool) – The switches behind the command line’s --emit-tier. All default to False, which is the default tier. valid sets general_fallback; complete adds allow_aromatic_general; best-effort adds general_fallback_unverified; full-coverage adds full_coverage.
full_coverage (bool) – The switches behind the command line’s --emit-tier. All default to False, which is the default tier. valid sets general_fallback; complete adds allow_aromatic_general; best-effort adds general_fallback_unverified; full-coverage adds full_coverage.
binding_proof ({"off", "audit", "enforce"}, default "off") – As for:func:name_compound.

Notes

The parameters whose names start with an underscore are for the engine’s own use and tests; leave them at their defaults.

Examples

>>> from orthonym import Orthonym
>>> namer = Orthonym
>>> namer.name("CCO")
'ethanol'
>>> namer.name("CC(=O)O")
'acetic acid'

get_dispatch_stats()#

Return how often each compound-class route was taken by this instance.

The engine tries compound classes in a fixed order (salts, ions, carbohydrates, natural products, the general rules and more) and counts which class named each molecule.

Returns:: dict – Compound class to count. The keys are members of orthonym.routing.StoutClass.
Return type:: Dict[Any, int]

reset_dispatch_stats()#

Set the route counters back to zero.

Resets this instance’s class counters and the finer counters of get_inner_dispatch_stats(). The finer counters are shared by every instance in the process, so this resets them for all instances.

get_inner_dispatch_stats()#

Return how often each handler inside the general class was used.

Within the general compound class, a second step picks one of several handlers (acids, esters, amines and so on). These counters are shared by every instance in the process;:meth:reset_dispatch_stats clears them.

Returns:: dict of str to int – Handler id to count; empty before the first molecule.
Return type:: Dict[str, int]

name_with_tree(smiles)#

Name one molecule and return the parts of the name.

Parameters:

smiles (str or rdkit.Chem.Mol) – The structure, as a SMILES string or an RDKit Chem.Mol. A Mol is named through RDKit’s SMILES of it, after a check that this SMILES holds the same molecule and stereo (see:ref:python-input).

Returns:

NamingResult – name is what:meth:name returns with on_failure="label"; tree is the NameTreeNode of its parts (a single coarse node when the part of the engine that built the name records no finer structure); atom_to_locant_hint maps atom indices to locants where one was recorded, else None.

Raises:

ValueError – If RDKit cannot read the SMILES, smiles is None, or a Mol fails the check (RDKit cannot sanitize it, or its SMILES does not hold the same molecule and stereo).
TypeError – If smiles is neither a string nor a Chem.Mol.

Examples

>>> from orthonym import Orthonym
>>> Orthonym.name_with_tree("OC1CCCCC1").name
'cyclohexanol'

get_validation_stats()#

Return how often the OPSIN grammar pre-check passed or repaired a name.

The engine checks a candidate against OPSIN’s grammar before the full round trip, and can fix brackets, stereodescriptors or hyphens. The counters belong to this instance and start at zero.

Returns:: dict of str to int – One counter per outcome, for example validate_passed and repair_succeeded_bracket.
Return type:: Dict[str, int]

name(smiles, *, raise_on_limit=False, on_failure='empty')#

Name one molecule with this instance’s options.

Parameters:

smiles (str or rdkit.Chem.Mol) – The structure, as a SMILES string or an RDKit Chem.Mol. A Mol is named through RDKit’s SMILES of it, after a check that this SMILES holds the same molecule and stereo (see:ref:python-input).
raise_on_limit (bool, default False) – The same as on_failure="raise", and it wins over on_failure.
on_failure ({"empty", "label", "raise"}, default "empty") – What a structure with no name gets: "" and a warning on the logger orthonym, the label, or:class:OrthonymLimitError. See:func:name_compound.

Returns:

str – The name, or what on_failure gives for a structure with no name.

Raises:

ValueError – If RDKit cannot read the SMILES, smiles is None, a Mol fails the check (RDKit cannot sanitize it, or its SMILES does not hold the same molecule and stereo), or on_failure is not one of its values.
TypeError – If smiles is neither a string nor a Chem.Mol.
OrthonymLimitError – If on_failure is "raise" and the structure is out of scope. For a ring system the engine cannot name yet the code is UNSUPPORTED_RING_SYSTEM; when that happens inside a part of the molecule, the code can be the more general UNNAMEABLE.

Return type:

str

Examples

>>> from orthonym import Orthonym
>>> Orthonym.name("C/C=C/C")
'(2E)-but-2-ene'

name_tiered(smiles)#

Name one molecule and say how the name was made and checked.

This is the row the command line prints with --provenance.

Parameters:

Returns:

dict –

name

The name, or a label when there is none.

tier

How the name was built: pin_verified (the strict path for the Preferred IUPAC Name built it, certified it and OPSIN read it back, or read back a twin spelling of it; or a name from an exact-match list, matched to the input’s exact structure, with verified identity), pin_unverified (a name in preferred-name form that OPSIN read back, but whose preferred status is not certified: a producer outside the strict path built it or a part of it), systematic_verified (a checked systematic name that is not the preferred name, for example from the general engine, a table of retained names, or the strict path when the name contains a part the engine records as not the preferred form), best_effort (the last-resort producers, or a name whose own string no round trip confirmed) or abstain (no name).

is_pin

True only for a certified Preferred IUPAC Name.

source

Which part of the engine produced the name, for example pin_path, general_engine, trivial_retained or abstain.

opsin

What the OPSIN check found: verified, verified_constitution_only, verified_twin (OPSIN has no grammar for the name and read a twin spelling of it back to your structure), verified_acid_split (OPSIN has no grammar for a poly-anhydride name and read each of its acids; the structure built from them is your structure), unverified or n/a.

gates_passed

The checks this name passed, for example self_consistency (OPSIN read the name back to your structure) and atom_coverage.

gate_outcome

What the final OPSIN check did for this name, for example self_consistency_verified, suppressed or not_run, or carveout:<class> for a class OPSIN cannot read, or twin_verified:<rules> for a name read back through its twin, or acid_split_verified:<rule> for a poly-anhydride read through its acids.

formula

The molecular formula, given when there is no name.

limit_code

The reason code when there is no name, for example UNSUPPORTED_ELEMENT, or NO_VERIFIED_PIN when the default tier built a name that is not a verified PIN (a wider tier returns it).

stereo_unexpressed

True when the input configures a stereo element (a stereocentre or a double bond) that the name does not state: OPSIN’s read-back of the name configures fewer elements than the input does. A name of any producer; it changes no name, tier or label. A name OPSIN cannot read has no read-back and is not flagged.

suffix_free_prefix_name

True when the name states the principal characteristic group as a prefix with no suffix.

prefix_order_fallback

True when the name cites its substituent prefixes out of the alphanumerical order because the round trip of the ordered spelling fails at the stereo layer only (a stereocentre read differently by the SMILES hand-off, not by the name); such a name is best_effort, never a PIN.

verified

opsin (OPSIN read the whole name back to the same molecule), opsin_constitution (read back with the same constitution; the stereodescriptors were not confirmed by OPSIN), identity (a name from an exact-match list: a metal-complex name found by the input’s exact InChIKey, or a natural-product parent name found by its exact structure; OPSIN cannot read these names), opsin_split (OPSIN read the whole name back to the drawing of the input without its dative bonds, which has the reference key; the drawing as given has no standard InChIKey), opsin_twin (a PIN spelling OPSIN has no grammar for; OPSIN read a twin spelling of the same structure back to the same molecule), opsin_acids (a di- or poly-anhydride name OPSIN has no grammar for; OPSIN read each acid the name cites and the structure built from those acids is the same molecule) or unverified (no read-back recorded).

spelling_failures

The spelling rules of the PIN a name in PIN form breaks, as {"rule": "", "detail":...} entries (validation.pin_spelling; a round trip cannot see them), and the rule of a recorded non-PIN part that lowered the name (metrics.provenance.record_non_pin_label with a rule, e.g.

for a ring assembly of three or more components with

primed locants). Such a name is systematic_verified at most; the default tier declines it with NO_VERIFIED_PIN and keeps the entries as the reason. Empty otherwise.

producer

The code that built the name that ships (inner:tier_a_ring, engine:general,…), or None when no name ships. A diagnostic id: it follows the code and can change in any release.

Raises:

ValueError – If RDKit cannot read the SMILES, smiles is None, or a Mol fails the check (RDKit cannot sanitize it, or its SMILES does not hold the same molecule and stereo).
TypeError – If smiles is neither a string nor a Chem.Mol.

Return type:

dict

Examples

>>> from orthonym import Orthonym
>>> row = Orthonym.name_tiered("Cn1cnc2c1c(=O)n(C)c(=O)n2C")
>>> row["name"], row["tier"], row["verified"]
('1,3,7-trimethyl-3,7-dihydro-1H-purine-2,6-dione', 'pin_verified', 'opsin')

name_with_confidence(smiles)#

Name one molecule and return a coverage score with it.

Parameters:

Returns:

dict – name (the name), confidence (a score from 0 to 1, or None when no measurement was taken), verification, factors (the parts of the score), handler (the part of the engine that built the name), and further keys for the atom-to-locant map and the reason for a decline (limit, abstention, and spelling_failures: the spelling rules of the PIN that the declined name breaks).

Raises:

ValueError – If RDKit cannot read the SMILES, smiles is None, or a Mol fails the check (RDKit cannot sanitize it, or its SMILES does not hold the same molecule and stereo).
TypeError – If smiles is neither a string nor a Chem.Mol.

Return type:

dict

Examples

>>> from orthonym import Orthonym
>>> Orthonym.name_with_confidence("CCO")["name"]
'ethanol'

orthonym.namer.name_with_tree(smiles, style='pin')#

Name one molecule and return the parts of the name.

A shortcut for Orthonym(style=style).name_with_tree(smiles).

Parameters:

smiles (str or rdkit.Chem.Mol) – The structure, as a SMILES string or an RDKit Chem.Mol. A Mol is named through RDKit’s SMILES of it, after a check that this SMILES holds the same molecule and stereo (see:ref:python-input).
style ({"pin", "general", "cas"}, default "pin") – Naming style, as for:func:name_compound.

Returns:

NamingResult – The name (what:func:name_compound returns with on_failure="label"), the tree of its parts as a:class:NameTreeNode, and a map from atom index to locant where one was recorded.

Raises:

ValueError – If RDKit cannot read the SMILES, smiles is None, or a Mol fails the check (RDKit cannot sanitize it, or its SMILES does not hold the same molecule and stereo).
TypeError – If smiles is neither a string nor a Chem.Mol.

Examples

>>> from orthonym import name_with_tree
>>> result = name_with_tree("OC1CCCCC1")
>>> result.name
'cyclohexanol'
>>> result.tree.parent_stem
'cyclohex'
>>> result.tree.suffix
'ol'

orthonym.namer.name_compound(smiles, style='pin', include_confidence=False, *, enable_triviality_controller=False, enable_group_splitting=False, trivial_fallback=False, general_fallback=None, general_fallback_unverified=None, allow_aromatic_general=None, full_coverage=None, raise_on_limit=False, binding_proof='off', on_failure='empty')#

Name one molecule.

Reads a structure, written as SMILES or given as an RDKit molecule, and returns its IUPAC name as a string. At the default settings a name is returned only when the strict path for the Preferred IUPAC Name built it and verified it, or when it is one of the default tier’s exceptions (the exact-match list names, the few name formats OPSIN cannot read, a PIN whose stereodescriptors OPSIN cannot read). Where no name passes, the result is the empty string, and one warning on the logger orthonym says why (on_failure below). The wider tiers (general_fallback and the options below) also return names that are not the preferred name. Use Orthonym.name_tiered() to learn which tier a name earned.

Parameters:

smiles (str or rdkit.Chem.Mol) – The structure, as a SMILES string or an RDKit Chem.Mol. A Mol is named through RDKit’s SMILES of it, after a check that this SMILES holds the same molecule and stereo (see:ref:python-input).
style ({"pin", "general", "cas"}, default "pin") – Naming style. "pin" aims at the Preferred IUPAC Name. "general" allows general IUPAC forms where the recommendations offer one (for example functional class names such as ‘dimethyl sulfoxide’, hydrate names such as ‘oxalic acid dihydrate’ and the axial descriptors Ra and Sa). The default tier’s PIN-only rule applies to "pin" only, so with "general" or "cas" a name that "pin" declines with NO_VERIFIED_PIN is returned. "cas" is accepted and at present gives the names of "general", except that hydrate names and axial descriptors keep their "pin" form.
include_confidence (bool, default False) – Return a dictionary instead of a string. Its "name" key holds the name, "handler" the part of the engine that built it, and "confidence" and "factors" a coverage score and its parts. "confidence" is None when no measurement was taken.
enable_triviality_controller (bool, default False) – Where the recommendations prefer a retained parent name to the systematic one, use the retained name. Each change is checked by an OPSIN round trip. The environment setting ORTHONYM_ENABLE_TRIVIALITY_CONTROLLER=1 turns this on as well.
enable_group_splitting (bool, default False) – When an ester or thioester group inside a larger molecule has no prefix form, write it as its parts (oxo plus ethoxy, for example) instead of giving up. Each split name must pass an OPSIN round trip. The environment setting ORTHONYM_ENABLE_GROUP_SPLITTING=1 turns this on as well.
trivial_fallback (bool, default False) – When no preferred name can be built, also allow a retained trivial name that is not a preferred name. A molecule whose preferred name can be built keeps it. Turns on enable_triviality_controller.
general_fallback (bool or None, default None) – When the strict path declines, try the general naming engine (the valid tier of the command line). Its names must pass an atom-coverage certificate and a full-InChIKey round trip. None means “off” for a call you make; the engine uses it to pass the setting on when it names parts of a molecule.
general_fallback_unverified (bool or None, default None) – Also switch on the best-effort tier: the last-resort producers, von Baeyer and spiro names for ring systems of up to 100 skeletal atoms and 15 rings (the other tiers build these names for ring systems of up to 40 skeletal atoms and 8 rings), and adducts with a one-atom ion. Their names still have to pass the full-InChIKey round trip, with one exception: a molecule that has no other name gets the name the default tier gives it when OPSIN cannot read the stereodescriptors of that name, with the label the default tier gives it (pin_unverified). None as for general_fallback.
allow_aromatic_general (bool or None, default None) – Let the general engine also name aromatic and heterocyclic ring systems (the complete tier). None as for general_fallback.
full_coverage (bool or None, default None) – Also try the coordination-name builder for metal tetrapyrrole and corrin complexes (the full-coverage tier). It builds a name or declines. None as for general_fallback.
raise_on_limit (bool, default False) – The same as on_failure="raise", and it wins over on_failure.
binding_proof ({"off", "audit", "enforce"}, default "off") – An extra check that every part of a general-engine name still maps onto the atoms it names in the final string. "audit" records the result and never changes the name; "enforce" also declines when the check fails.
on_failure ({"empty", "label", "raise"}, default "empty") – What the call gives for a structure that gets no name. "empty": the empty string, with one warning on the logger orthonym that holds the SMILES, the limit code and the label. "label": the label, such as 'unknown organic compound' (the result before this option). "raise": OrthonymLimitError. With include_confidence the "name" of the dictionary follows it. The limit codes are stable, the texts of labels are not. The choice is the caller’s; the engine’s own calls get labels.

Returns:

str or dict – The name, or what on_failure says for a structure with no name. A dictionary when include_confidence is true.

Raises:

ValueError – If RDKit cannot read the SMILES, smiles is None, a Mol fails the check (RDKit cannot sanitize it, or its SMILES does not hold the same molecule and stereo), or binding_proof or on_failure is not one of its values.
TypeError – If smiles is neither a string nor a Chem.Mol.
OrthonymLimitError – If on_failure is "raise" (or raise_on_limit is true) and the structure is out of scope.

Examples

>>> from orthonym import name_compound
>>> name_compound("CC(C)Cc1ccc(cc1)[C@@H](C)C(=O)O")
'(2R)-2-[4-(2-methylpropyl)phenyl]propanoic acid'
>>> name_compound("O=[U](=O)=O")
''
>>> name_compound("O=[U](=O)=O", on_failure="label")
'inorganic compound (not supported)'

orthonym.namer.name_pipeline_only(smiles, style='pin')#

Name a molecule using only the systematic pipeline, skipping decomposition.

This provides the non-decomposition name without consuming any depth budget on decomposition probes. Used by the decomposition engine to compare its result against what the systematic pipeline would produce.

Returns:: IUPAC name string, or None if naming fails.

orthonym.namer.classify_limit(smiles)#

Say whether a structure is out of scope, without raising.

A wildcard atom (*) is refused at once. Any other structure is named with the default settings; if that gives a label instead of a name, the reason is returned.

Parameters:: smiles (str or rdkit.Chem.Mol) – The structure, as a SMILES string or an RDKit Chem.Mol. A Mol is named through RDKit’s SMILES of it, after a check that this SMILES holds the same molecule and stereo (see:ref:python-input).
Returns:: OrthonymLimitError or None – The reason, with its code (for example UNSUPPORTED_ELEMENT, WILDCARD_ATOMS, or NO_VERIFIED_PIN when the default settings built a name that is not a verified preferred IUPAC name) and message. None when the structure gets a name, and also when RDKit cannot read the SMILES at all, smiles is None, or a Mol fails the check described under name_compound() (that is a reading error, not a scope limit).
Raises:: TypeError – If smiles is neither a string, a Chem.Mol nor None.
Return type:: OrthonymLimitError | None

Examples

>>> from orthonym import classify_limit
>>> classify_limit("O=[U](=O)=O").code
'UNSUPPORTED_ELEMENT'
>>> classify_limit("CC*").code
'WILDCARD_ATOMS'
>>> classify_limit("CCO") is None
True

orthonym.namer#

`orthonym.namer`#