orthonym 1.0.8

  

A SMILES string goes in. A verified IUPAC name comes out, or a clear "no". Never a guess.

_{Part of the Orthonym project: orthonym-skills, the Claude Code skills that Orthonym was built with (how).}

How names are checked

Deterministic. Orthonym builds its names from the nomenclature rules of the IUPAC 2013 recommendations, the "Blue Book". Where those rules do not yet reach a molecule, a wider tier (--emit-tier) can give a general systematic name, a retained name from a table or a natural-product name instead, labelled as not the preferred name. The default tier declines these names; Output tiers lists its exceptions. There is no neural network and no sampling: the same input always gives the same output.

Checked. A name is handed to OPSIN, which never saw your structure, and parsed back. The structure OPSIN reads must match yours in constitution, charge and stereo, so a name that leaves out or adds an atom cannot pass. The default tier makes a few exceptions for names OPSIN cannot read in full: names from exact-match lists (metal-complex and natural-product parent names), a few name forms that OPSIN's grammar lacks or misreads, and names whose stereodescriptors OPSIN cannot parse (OPSIN confirms their constitution, and each descriptor is checked against its CIP label). --provenance marks each of them. The wider tiers ship none of them, except the names from the exact-match lists: a metal-complex name, and a natural-product parent name when no verified systematic name is found.

Honest. A candidate that fails a check is withdrawn, and when no name is left Orthonym says so instead of guessing. --provenance reports the tier each name landed on and, in its verified field, how it was checked.

See it working

_{Real output. The command line prints the plain line; the mark under it and the tier at its right come from the same command run with --provenance. The pictures are generated from the engine's own output, so they show what it prints.}

The same from Python:

>>> 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'

Quick start

Needs Python 3.10+ and a Java 11+ runtime on your PATH (see Installation).

pip install "git+https://github.com/Steinbeck-Lab/Orthonym.git"
orthonym --fetch-jars          # one-time: downloads and checks the OPSIN and centres jars

If you skip --fetch-jars, the first call that names a molecule downloads the two jars (about 17 MB) and says so; later calls are fast. If your shell does not find orthonym right after the install, open a new terminal (or run hash -r); python -m orthonym works in any case.

from orthonym import name_compound

name_compound("CCO")                          # 'ethanol'
name_compound("CC(=O)Oc1ccccc1C(=O)O")        # '2-(acetyloxy)benzoic acid'
name_compound("Cn1cnc2c1c(=O)n(C)c(=O)n2C")   # '1,3,7-trimethyl-3,7-dihydro-1H-purine-2,6-dione'
name_compound("C/C=C/C")                      # '(2E)-but-2-ene'
name_compound("C[C@H](O)CC")                  # '(2S)-butan-2-ol'

name_compound and the other naming functions also take an RDKit Chem.Mol in place of the SMILES string, for example a molecule read from an SDF file. The Mol is named through RDKit's SMILES of it (Chem.MolToSmiles(mol)), after a check that this SMILES holds the same molecule and stereo; when it does not, the call raises ValueError. Your Mol is not changed.

From the command line:

orthonym "CCO"                                # ethanol
orthonym "CC(=O)Oc1ccccc1C(=O)O" --provenance # the name plus tier, validation and source, as JSON
orthonym --batch molecules.smi -o names.txt   # one SMILES per line
python -m orthonym "c1ccccc1"                 # module form

Installation

Install from GitHub as in Quick start. For a development install from a clone, see CONTRIBUTING.md.

The OPSIN and centres jars

Orthonym does not ship any Java jars. It uses two, and downloads them from their official releases, checking each download against a pinned SHA-256 checksum:

pip install tries to fetch them for you, and a jar that is still missing is downloaded and checked the first time Orthonym needs it. To fetch them, or re-check the ones in the jar directory, run orthonym --fetch-jars. If a jar cannot be found or downloaded (or ORTHONYM_NO_DOWNLOAD=1 forbids the download), Orthonym stops with a clear error rather than quietly naming with less validation; without a working Java runtime it declines every molecule rather than naming it unchecked. For offline machines, point Orthonym at jars you copied yourself (a jar given this way is used as given, without the checksum check):

Licences and sources of the third-party components are listed in NOTICE.

Output tiers

The default returns a name only when the strict PIN path built it and verified it, or when the name is one of the few exceptions: a name from the exact-match lists, a name format absent from OPSIN's grammar, or a PIN whose stereodescriptors OPSIN cannot read. With --trivial it also returns a retained trivial name, labelled systematic_verified. Otherwise it declines. This rule applies to the default --style pin. Wider tiers are opt-in with --emit-tier:

At valid, complete and best-effort every name must pass a full-InChIKey OPSIN round trip (a name from the natural-product and metal-complex lists excepted), so the name formats absent from OPSIN's grammar, which the default tier ships without a full read-back, are not shipped there, and a wider tier can, rarely, decline a molecule that a narrower tier names.

Whatever the tier, --provenance (one SMILES at a time) says what each name is: pin_verified (the strict PIN path built it and verified it), pin_unverified (a name in PIN form whose preferred status is not certified), systematic_verified (a correct systematic name that is not the PIN, for example from the general engine, from a table of retained names, a strict-path name with a part the engine records as not the preferred form, a natural-product name of a molecule whose bridged fused PIN the engine does not build yet, a name reached through another drawing of the same compound, or a name of a class for which the Blue Book gives no PIN, such as Group 1-12 organometallic compounds), best_effort (a last-resort producer's name, or one that no round trip confirmed) or abstain (no name). The tier says how a name was built. The verified field says how it was checked: opsin (OPSIN read the whole name back to your structure), opsin_constitution (OPSIN read it back without its stereodescriptors, and each descriptor was checked against its CIP label), identity (a name from an exact-match list: a metal-complex name found by your structure's exact InChIKey, or a natural-product parent name found by its exact structure; OPSIN cannot read these names), opsin_split (OPSIN read the name back to your structure drawn without its dative bonds, because RDKit gives a drawing with dative bonds no standard InChIKey to read a name back against; a count of atoms and charges ties the two drawings) or unverified.

When Orthonym cannot name a molecule, the plain call returns the empty string and logs the reason (a limit code and a label) on the orthonym logger; the command line prints an empty name and the reason on the error stream. on_failure="label" (--on-failure label) returns the label instead, such as inorganic compound (not supported), and --provenance marks the row abstain with a reason code. More on declines.

Metal compounds

Orthonym names a compound of a metal when OPSIN reads the name back to your structure. Zinc is admitted to every naming mechanism, and the tiers differ in how much of it they name.

• best-effort names the widest range: a salt, the atom with its ions and isotopes, an organozinc compound, a complex drawn with bonds to zinc or with dative bonds, a porphyrin or phthalocyanine complex, and the adducts of zinc (the ammine, the aqua ion, a complex with a neutral ligand such as pyridine, a porphyrin drawn beside a zinc ion). A compound of these kinds can still be left unnamed.
• valid names a salt, the atom with its ions and isotopes, most compounds drawn with bonds to zinc or with dative bonds (zinc diacetate for the dative drawing of the acetate), the zinc porphyrin complexes, and an organozinc compound whose organyl groups are hydrocarbon groups (diethylzinc, phenylzinc chloride). It does not name the adducts: the ammine, the aqua ion, a complex with a neutral ligand, a zincate anion drawn alone, a free porphyrin beside a zinc ion. It does not name a phthalocyanine complex or an organozinc compound with a halogen or an ester on its organyl group either. Those names come at best-effort only.

A standard InChIKey does not record the bonds between a metal and its ligands, so the round trip cannot tell two drawings of one compound apart. Zinc chloride drawn with two zinc-chlorine bonds is named zinc dichloride, the name of its ionic drawing, after a separate count has confirmed that the two drawings hold the same atoms and differ in charge only by the charge that the broken bonds move. The name is systematic_verified, and the spelling_failures entry of --provenance says that it describes another drawing of the same compound. A drawing with dative bonds has no standard InChIKey in RDKit; its name is read back to the same drawing without the dative bonds, and verified is opsin_split.

The default tier names a zinc salt drawn as ions when the strict PIN path builds a name that carries a PIN label: a salt of an acid, an alcohol or a thiol, or a carbon-free salt (zinc diacetate, zinc dichloride). It declines the zinc names that carry no PIN label: organozinc compounds, drawings with bonds to zinc, the atom and its ions, salts of carbanions, ammines and complexes.

Other metals are admitted one at a time. A compound of a metal that is not admitted is named where the general producers can name it (copper(II) sulfate) and is otherwise declined, usually with UNSUPPORTED_ELEMENT.

More

• How it works: the four parts of the engine and the source layout.
• Declines: what a "no" looks like, and how to tell one from a name in code.
• How accuracy is measured: the three measures the engine is judged by.
• Contributing: development install, tests, source layout, how to add a compound class.
• orthonym-skills: the Claude Code skills, hooks and agent Orthonym was built with.
• Changelog · Security · Code of conduct · Open an issue

How Orthonym was built

Orthonym was built with Claude Code, under a fixed set of working rules. The rules are published as orthonym-skills, part of the Orthonym project: 20 skills, 2 hooks and 1 agent. Each one makes a step rest on a measurement instead of a confident guess:

• Measure on fixed, hashed test sets before and after each change (run-eval, cluster-failures, refusal-census).
• Prove that the code to change is on the execution path before editing it (spy-site, check-target).
• Change an expected value in a test only with a primary source, an independent check and a mutation test (change-asserted-value, verify-source).
• Run the regression gate before a merge (run-gate), and get a review from a second model before a claim ships (fable-review).
• Hand the work from one session to the next through a written note (handoff, kickoff).

The skills were written for Orthonym and then made general, so that other chemistry and machine learning software projects can use them.

How to cite

A paper describing Orthonym is in preparation. Until it is published, please cite the software: GitHub's Cite this repository button, built from CITATION.cff, gives the entry in APA and BibTeX. In BibTeX:

@software{orthonym,
  author  = {Rajan, Kohulan and Zielesny, Achim and Steinbeck, Christoph},
  title   = {{Orthonym}},
  version = {1.0.8},
  year    = {2026},
  doi     = {10.5281/zenodo.23044199},
  url     = {https://github.com/Steinbeck-Lab/Orthonym}
}

Every release is archived on Zenodo. The DOI 10.5281/zenodo.23044199 stands for all versions and resolves to the newest one.

Built on

Orthonym stands on the IUPAC 2013 recommendations and on open cheminformatics software: RDKit reads the structure, OPSIN 2.9.0 reads the names back to check them, and centres 1.2.1 assigns the CIP descriptors. Without them there would be no Orthonym.

Favre, H. A.; Powell, W. H. Nomenclature of Organic Chemistry: IUPAC Recommendations and Preferred Names 2013. Royal Society of Chemistry, 2013. doi:10.1039/9781849733069

Lowe, D. M.; Corbett, P. T.; Murray-Rust, P.; Glen, R. C. Chemical Name to Structure: OPSIN, an Open Source Solution. J. Chem. Inf. Model. 2011, 51 (3), 739–753. doi:10.1021/ci100384d

Hanson, R. M.; Musacchio, S.; Mayfield, J. W.; Vainio, M. J.; Yerin, A.; Redkin, D. Algorithmic Analysis of Cahn–Ingold–Prelog Rules of Stereochemistry: Proposals for Revised Rules and a Guide for Machine Implementation. J. Chem. Inf. Model. 2018, 58 (9), 1755–1765. doi:10.1021/acs.jcim.8b00324

Licence

MIT, see LICENSE. The OPSIN and centres jars are not part of this repository; they are downloaded from their official releases and keep their own licences (see NOTICE).

_{Made with by Kohulan Rajan at}