Steinbeck-Lab/Orthonym

  

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).}

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, it can give a general systematic name or a retained name from a table instead, labelled as not the preferred name. 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 (metal-complex and natural-product parent names).

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.

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

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

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'

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

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

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.

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. Otherwise it declines. 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, or 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) or unverified.

When Orthonym cannot name a molecule, the plain call returns a label in place of a name, such as inorganic compound (not supported), and --provenance marks the row abstain with a reason code. More on declines.

• 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

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.

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.3},
  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.

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

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}