DEV Community: Dagger Shoe

When 10 Carbons Lose to 3 Nitrogens

Dagger Shoe — Sat, 01 Aug 2026 01:39:33 +0000

Where We Left Off

In my last post, I introduced the entire process of finding functional groups, but these groups live on the molecule's backbone. So now we need to begin the hunt for the parent chain.

The Challenge: What Even IS a Parent Chain?

The parent chain is the backbone of IUPAC naming. It's the main structure that determines the base name (e.g., "pentane" or "hexanoic acid"). But choosing it is surprisingly complex.

Imagine you're a chemist looking at a molecule. You have to decide:

"Which chain is the 'main' one?"
"What about atoms that aren't carbon, like nitrogen or oxygen?"
"What if there's a ring? Does that count?"

IUPAC has a whole decision tree for this. And I mean a whole decision tree.

The IUPAC Decision Tree (Simplified)

After a lot of reading and re-reading of the Blue Book, here's what I came up with:

Contains the principal functional group (highest priority)
Maximum number of principal characteristic groups
Parent based on senior element (N > P > Si > B > O > S > C)
Rings are senior to chains (if same elements)
Contains more atoms
Contains more multiple bonds
Lower locants for principal groups
Lower locants for unsaturation
Maximum number of substituents
Lowest set of substituent locants
Name cited earlier in alphabetical order

Yes, that's 11 rules. And I'm skipping a whole lot for feasibility.

The Journey: From Simple to Complex

Attempt 1: Just Find the Longest Chain

My first implementation was naive: just find the longest carbon chain and call it a day. This works for simple alkanes like CCCC (butane) or CCCCCC (hexane). But it fails spectacularly for anything with heteroatoms.

# This works:
"CCCCCC" → hexane (6 carbons)

# This doesn't:
"CSiCCNNN" → Wait, what's the parent here?

The issue is that IUPAC prioritizes heteroatoms (non-carbon atoms) over chain length. Nitrogen is more "senior" than silicon, which is more senior than carbon. So a chain with 3 nitrogen atoms beats a chain with 5 silicon atoms, which beats a chain with 10 carbons.

Attempt 2: Follow the Most Senior Element

I decided to build a system that could find chains for any element, not just carbon. The idea was simple:

For each senior element (N, P, Si, B, O, S, C), find all chains of that element and then score them.

This worked for simple heteroatom chains. But it still couldn't handle:

Molecules with functional groups
Molecules where the parent chain contains multiple elements (e.g., C-N-C-O-C)
Chains with rings

Attempt 3: The Two-Pass System (Current Implementation)

The current approach splits the problem into two cases:

Case 1: Molecules with functional groups

Find all functional groups (using the motif engine)
Pick the highest priority group (the "principal" group)
Find all chains that contain this group

Score them by:

- Number of principal groups in the chain

- Most senior heteroatoms

- Chain length

- Number of multiple bonds

The highest-scoring chain is the parent chain

Case 2: Molecules with NO functional groups (parent hydrides)

Find all chains of each senior element (N, P, Si, B, O, S, C)

Score them by:

- Most senior element present

- Chain length

- Number of multiple bonds

The highest-scoring chain is the parent hydride

The Code: How It Actually Works

The Candidate System

I introduced a _Candidate class to track each potential parent chain along with its element type:

python

class _Candidate(NamedTuple):
    chain: list[int]
    elem: str

This allows me to keep track of which element a chain is made of, which is crucial for the seniority-based selection.

The key function is _chains_through(), which finds all possible chains of a given element that pass through a specific atom:

python

def _chains_through(self, idx: int, element: str, visited=None) -> list[list[int]]:
    curr = self._molecule[idx]
    visited = visited
    visited.add(idx)

    chains = self._follow_chain(idx, element, visited)

    # If the current atom isn't the element type, or there's only one chain, return
    if curr.element.symbol != element or len(chains) < 2:
        return chains

    # Group chains by their first step to avoid duplicates
    by_subtree = {}
    for chain in chains:
        first_step = chain[1]
        best = by_subtree.get(first_step)
        if best is None or self._score_chain(_Candidate(best, element)) > self._score_chain(
                _Candidate(best, element)):
            by_subtree[first_step] = chain

    final_chains = list(by_subtree.values())

    # If there are at least two strong subtrees, merge them through the current atom
    if len(final_chains) >= 2:
        top_two = sorted(final_chains, key=lambda c: self._score_chain(_Candidate(c, element)), reverse=True)[:2]
        merged = list(reversed(top_two[0][1:])) + [idx] + top_two[1][1:]
        final_chains.append(merged)

    return final_chains

This is where the real magic happens. The function:

Finds all chains of a specific element starting from the current atom
Groups them by their first step (to avoid duplicates)
If there are at least two strong branches, merges them through the current atom

Then, the _follow_chain method uses DFS to find all chains of a given element:

python

def _follow_chain(self, curr_idx: int, element: str, visited=None) -> list[list[int]]:
    if visited is None:
        visited = set()

    curr = self._molecule[curr_idx]
    visited.add(curr_idx)
    branches = []

    for neighbour_idx, _ in curr.bonds.items():
        if neighbour_idx in visited:
            continue

        neighbour = self._molecule[neighbour_idx]
        if neighbour.element.symbol == element:
            visited.add(neighbour_idx)
            branches.extend(self._follow_chain(neighbour_idx, element, visited.copy()))

    if branches:
        return [[curr_idx] + chain for chain in branches]
    elif self._molecule[curr_idx].element.symbol == element:
        return [[curr_idx]]
    else:
        return []

Now that we have potential chains, the scoring system prioritizes chains by:

Length (more atoms = better)
Multiple bonds (more double/triple bonds = better)
Double bonds (within multiple bonds, more double bonds = better)

python

def _score_chain(self, candidate: _Candidate) -> tuple[int, int, int]:
    chain = candidate.chain
    if not chain:
        return 0, 0, 0

    length = len(chain)
    double_bonds = 0
    triple_bonds = 0

    for i in range(len(chain) - 1):
        atom = self._molecule[chain[i]]
        bond_order = atom.bonds.get(chain[i + 1])

        if bond_order == 3:
            triple_bonds += 1
        elif bond_order == 2:
            double_bonds += 1

    multiple_bonds = double_bonds + triple_bonds
    return length, multiple_bonds, double_bonds

Selecting the Best Parent Chain

The _select_best_parent method applies the IUPAC rules in order:

python

def _select_best_parent(self, candidates: list[_Candidate], princip_idxs: Optional[set[int]] = None) -> Optional[_Candidate]:
    if not candidates:
        return None

    # Rule 1: Maximize principal characteristic groups
    if princip_idxs:
        max_count = max(self._princip_count(candidate.chain, princip_idxs) for candidate in candidates)
        candidates = [
            candidate for candidate in candidates
            if self._princip_count(candidate.chain, princip_idxs) == max_count
        ]

    # Rule 2: Most senior element (N > P > Si > B > O > S > C)
    for element in self._SENIOR_ELEMENTS:
        element_candidates = [candidate for candidate in candidates if candidate.elem == element]
        if element_candidates:
            return self._score_chains(element_candidates)

    return None

The "Aha!" Moment

The biggest insight came when I realized that the parent chain doesn't have to be pure carbon. IUPAC allows chains of N, P, Si, B, O, and S to be parent hydrides. This means a molecule like CSiSiSiSiSiCNNNNNNNNNCNNNN has a parent chain of 9 nitrogen atoms (nonazane), not the carbon-silicon chain.

This is why the scoring system prioritizes the most senior element present, not just the longest chain. Nitrogen (N) is more senior than silicon (Si), which is more senior than carbon (C). So a chain with 9 N atoms beats a chain with 5 Si atoms, which beats a chain with 10 C atoms.

This is hardcoded into the scoring system, and it's what allows me to correctly select, for example, a nitrogen chain over a silicon chain.

The Takeaway

Building a parent chain finder from scratch has been one of the most challenging parts of this project. It forced me to understand IUPAC rules deeply and translate them into code. The recursive DFS approach, combined with the candidate system, gives me a flexible way to handle the complex decision tree.

Is it perfect? Not yet. But it's getting there. It's important to have an MVP running rather than hunting for optimizations at every step, that we we can learn much more about the product. Plus, this implementation works wonderfully!

What's Next?

Now onto a part I left behind! I'll be implementing:

Ring Detection – finding rings for cyclic compounds
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!

The Day I Realized I Was Solving One Problem 17 Times

Dagger Shoe — Sat, 01 Aug 2026 01:29:27 +0000

Where We Left Off

In my last post, I introduced IUPACker: a tool that converts SMILES strings into IUPAC names. I covered the SMILES parser, the molecular graph, and the motif engine for functional group detection. Now it's time to tackle the heart of the problem: finding the functional groups.

17 Functions and Counting

When I started building the functional group detector for IUPACker, I did what any naive programmer would do: I wrote a function for each group. Every. Single. One.

python
def _is_carboxylic_acid(self, atom):
    # Check for C(=O)OH pattern
    for neighbor in atom.bonds:
        if neighbor is O and order == 2:
            # It's a carbonyl!
        if neighbor is O and order == 1 and neighbor.has_h:
            # It's a hydroxyl!
    # ... 20 more lines

def _is_ester(self, atom):
    # Check for C(=O)OR pattern
    # ... almost the same code, slightly different

def _is_aldehyde(self, atom):
    # Check for CHO pattern
    # ... more of the same

# ... and 14 more functions

This was incredibly ugly. Every new functional group meant copying, pasting, and tweaking the same loop structure. The code was repetitive, and worse, adding a new functional group was a chore. Each one took 20-30 lines of boilerplate.

I realized quite quickly that this system was far from sustainable. It did the exact opposite of abstraction, leaving me knee-deep in messy code. I was writing the same loop over and over, just changing which bonds to look for.

What if I could define these patterns as data, not code? What if I could write one generic matching engine that could handle any pattern I threw at it?

Declaring my love for Declarative Patterns!

The answer? Declarative patterns! The idea was simple:

Define a pattern as a set of bond requirements and atom conditions
Write one matching engine that can match any pattern
Add new functional groups by adding a new pattern definition (10 lines) instead of a new function (30 lines).

Here's what a pattern looks like now:

python

CARBOXYLIC_ACID = MotifPattern(
    name="carboxylic acid",
    priority=100,
    suffix="oic acid",
    prefix="carboxy-",
    center_symbol="C",
    center_conditions=[
        COND_NO_CHARGE,
        COND_AROMATIC_FALSE
    ],
    bonds=[BondReq(symbol="O",
            order=2,
            count=1,
            conditions=[
                COND_NO_H,
                COND_BOND_SUM_2
            ],
        ),
        BondReq(
            symbol="O",
            order=1,
            count=1,
            conditions=[
                COND_HAS_H,
                COND_BOND_SUM_2
            ],
        ),
    ],
    excludes=[],
)

Compare that to the 20+ line function I had before. It's cleaner, more readable, and self-documenting.

Power up the Engines!

The matching engine is surprisingly simple. It walks through the molecule, finds candidate atoms, and checks if they match the pattern:

python

def _match_single(self, atom: Atom, pattern: MotifPattern, visited: set[int] = None) -> Optional[MotifMatch]:
    if not visited:
        visited = set()

    if atom.idx in visited:
        return None

    visited.add(atom.idx)
    used = set()  # Tracks consumed neighbours
    matches = []  # Tracks any matched neighbours

    for req in pattern.bonds:
        found_count = 0

        for neighbour_idx, order in atom.bonds.items():
            if neighbour_idx in used:
                continue

            neighbour = self.molecule[neighbour_idx]
            if neighbour.element.symbol == req.symbol and order == req.order:
                if all(self._condition_single(neighbour, cond) for cond in req.conditions):
                    used.add(neighbour_idx)
                    matches.append(neighbour_idx)
                    found_count += 1

                    # Checks for any further bonds that need to be made
                    if req.future_req:
                        future_match = self._match_single(neighbour, pattern, visited)
                        if not future_match:
                            return None
                        matches.extend(idx for idx in future_match.matched_atoms if idx not in matches)

        if found_count != req.count:
            return None

    return MotifMatch(pattern=pattern, matched_atoms=matches, center_idx=0)

The engine uses a handler system to check atom properties. This makes it easy to add new conditions later:
python

python

CONDITION_HANDLER = {
    "charge": lambda atom: atom.charge,
    "aromatic": lambda atom: atom.is_aromatic,
    "has_h": lambda atom: atom.get_hydrogen_count() >= 1,
    "bond_sum": lambda atom: atom.bond_sum()
}

Each condition is just a function that takes an atom and returns a value. The engine then compares that value to the expected value using the specified operator (eq, ne, lt, gt, le, ge).

Uh-oh Identity Crisis

One of the trickiest problems was overlapping functional groups. For example, acetic acid (CH3-COOH) matches:

Carboxylic acid (correct)

Carbonyl (sub-pattern)

Hydroxyl (sub-pattern)

The solution? Priority-based overlap resolution:

python
@staticmethod
def resolve_overlaps(matches: list[MotifMatch]) -> list[MotifMatch]:
    used_atoms = set()
    resolved = []

    for match in matches:
        if any(idx in used_atoms for idx in match.matched_atoms):
            continue
        used_atoms.update(match.matched_atoms)
        resolved.append(match)

    return resolved

The Sweet, Sweet Benefits

Because patterns are defined as data, users can add their own functional groups without touching the engine code, extending the usefulness of the library!

Plus, when I found a bug in the matching logic, I fixed it once in the engine, not 17 times in 17 functions.

Later, the same engine that detects functional groups can also be used for:

Substructure search (find molecules with specific patterns)
Toxicity checking (find dangerous patterns)
Reaction prediction (find reactive sites)
Drug-likeness filtering (check for specific pharmacophores)

Up and Running.

Sometimes, the best way to solve a problem is to step back and look for the pattern. By recognizing that all functional groups are just patterns, I was able to build a system that's:

More maintainable (one engine, many patterns)
More extensible (users can add their own patterns)
More reusable (the same engine handles multiple use cases)
More readable (patterns are self-documenting)

If you're writing the same loop over and over, ask yourself: "Am I really solving 17 different problems, or am I solving one problem 17 times?"

What's Next?

Now comes the hard part. I'll be implementing:

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!

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!