I Don't Know Chemistry, But I'm Building a Chemical Namer Anyway

Dagger Shoe — Sun, 21 Jun 2026 14:45:27 +0000

Whats all this about?

If you told me from the start that in order to make an actually viable IUPAC naming python library, I would have to read pages upon pages of the a dense, chemistry-jargon filled document called the Blue Book, I would have screamed. However, nothing ventured nothing gained, and while I'm sure there is a library for this somewhere out there, wheres the fun in that?

While I have made a decent chunk of progress on it already, It recently clicked that instead of screaming about my changes into the endless abyss that is a git commit, why not blog about it!

The entire process has taken me through a journey of chemistry, which actually made me enjoy the subject a lot more than in my high school days. With that said, welcome to my summer project, i.e. IUPACker.

The journey so far.

Part 1: Hubris.

Initially, I made the most foolish mistake. I decided that instead of sticking to well known and well used methods of expressing chemical formulae through text, why not just make one up from scratch?

Needless to say, this had the expected disastrous consequence of me being unable to handle every edge case that comes with the world of chemical molecules. That's not even mentioning the fact that I worked off of the assumption that people would just simply adapt to my standard... an assumption that was a tad too optimistic.

In trying to make it simple, I made the process too complex for a single person. Thus, I decided to stick with taking inputs for chemical formula ONLY in the standard SMILES format. Which meant rewriting all of my code... but it was a required sacrifice.

Part 2: No smiles with SMILES.

SMILES was actually a really satisfying system, which had a lot of interesting built in assumptions, and managed to express chemical formula using a regular grammar (which is very cool). I converted from a SMILES formula to a Molecule Graph object.

The first step was to create the relevant classes. Those being:

_Element: Stores chemical data (symbol, valence, etc.) for each element.
Atom: Represents an atom in the graph (element, bonds, charge, aromaticity, etc).
Molecule: Container for atoms; manages graph operations and validation.
SMILESParser: Parses SMILES strings into Molecule objects.

For now, I manually made a simple periodic table, though I will have to later implement an _Element method to scrap data from a formal periodic table.

The idea is simple, take the SMILES formula string, split it into a list of ordered tokens (the tokens being bracketed atoms, aliphatic and aromatic atoms, charge, bond order, branches and ring locators). Then parse these tokens individually, creating Atom vertices to store within the Molecule graph object, with edges between atoms representing bonds.

After handling the cases, it works well! For example, take

"C1CCC1C=[CH2+]"

which gets converted into

["C","1","C","C","C","1","C","=","[CH2+]"]

which can then be parsed element by atom. The numbers help denote which atoms connect back to each other, the "=" indicates a need for a bond order of 2 not the default of 1, and finally "[CH2+]" is parsed separately, with its charge and unorthodox hydrogen count stored in the Atom object representing C.

This portion does still have a bit of missing functionality, which will be added later as it handles more edge cases within chemical formulae, and I'd rather get a MVP running first!

Part 3: Validation, the bane of errors.

Of course, all my code so far assumed the user knows what they're doing. A naive and absolutely false assumption.

Thus, validation! This portion is very simple for now, and likely won't gain too much complexity in the future. All I do now is before parsing a SMILES, ensure all brackets, parenthesis and ring numbers are balanced. Then, once the molecule is built, a quick run through every atom in the molecule to make sure that the degree of each atom is under the maximum number of possible bonds (valences), raising an error otherwise.

All in all, my validation (usually) runs in linear time, under the number of atoms in the molecule. I will have to change it later to adapt for atoms with varying valences though!

Part 4: IUPACker, where we are now.

And now your mostly caught up! While I did skip quite a few technical details, this post was meant to be more of an overview of the work so far. Thus I thought it best to give you a simple breakdown, though if you'd like to get the juicy juicy details, just read the doc-strings for each function in the git repository!

Currently, I've built the skeleton for the IUPACker, the module in charge of naming a chemical formulae as per the IUPAC Blue Book rules. Stay tuned for my next post, which details the general plan for that system!

What's Next?

The IUPACker is where things get interesting. I'll be implementing:

Functional group detection – finding alcohols, acids, aldehydes, etc.
Parent chain identification – finding the longest chain containing the principal group
Substituent handling – identifying and naming branches
Numbering – assigning lowest possible locants
Name assembly – combining prefixes, suffixes, and locants

It's going to be a wild ride. See you in the next post!

*P.S. If you want to follow along, the code is on GitHub. Star it if you're feeling generous!

DEV Community: Dagger Shoe