SMILES and structure data

SMILES is how a structure travels — into Quodra as a typed string, out of it as one derived from your drawing. Here is exactly what that string carries, and what it leaves behind.

Quodra holds a molecule as a graph: atoms with an element, a position and a charge, and bonds with an order and an optional wedge or hash. SMILES is a projection of that graph, generated whenever the structure changes. The graph is the truth; the string is the interchange.

The live readout#

The SMILES box in the Molecule Studio inspector is written from your drawing, not typed into. Draw a bond and it changes. Click the box and the whole string selects, ready to copy.

On a slide, the object stores both forms. Every edit committed from the studio rewrites the object's SMILES from the structure, so the inspector's SMILES field on a drawn molecule is a readout of the same string.

The string is valid, not canonical. The same drawing always writes the same SMILES, but another program's string for the same compound may look nothing like it — do not compare two strings to decide whether two molecules are the same.

What the writer emits#

Hydrogens are otherwise implicit. They are counted for the formula from a small valence table adjusted for charge, and heteroatoms label theirs on the drawing, but the writer does not spell them out.

What it does not carry#

Three more edges worth knowing:

• Isotopes and explicit hydrogen counts are model-level only. The writer emits them and the schema stores them, but no tool in the studio sets them, and the importer does not read them back. An isotope label typed into a SMILES on a slide draws correctly, but is gone once the structure has been through the editor.
• Nothing raises a valence error. You can draw five bonds on a carbon. The formula will imply no hydrogens for it and the SMILES will be written out as drawn — Quodra does not refuse chemistry it thinks is wrong.
• Aromatic bonds are authored, not perceived. The benzene template makes them, and an imported string brings them in; the bond-click cycle deliberately stays at single, double and triple. Nothing scans a drawn ring afterwards and decides it is aromatic.

Reading a SMILES in#

There is one import path, and the depiction engine does the hard part: the string is drawn off-screen, and the laid-out graph is read straight back — element, position, bond order, aromaticity, and charges from bracket atoms. The coordinates are then rescaled so one bond is one unit and re-centred, which is why an imported structure and a hand-drawn one share the same scale and can be edited together.

Import runs in exactly two places:

• Opening the studio on a molecule that has a SMILES but no drawing yet — the typed string becomes an editable structure once, and from then on the structure is what you edit. A brief "Reading structure…" covers the moment it takes. This does not happen for a viewer on a read-only molecule.
• Creating a library molecule from a template — Benzene, Caffeine, Aspirin, Ethanol, Glucose and Pyridine are stored as strings and imported when you pick one.

What import keeps is exactly the list above. Stereo descriptors, isotope labels and hydrogen counts in the input string are not carried into the structure.

How the structure is stored#

An atom is an id, an element symbol, an x and a y in bond-length units, and optionally a charge, an isotope, an aromatic flag and a forced hydrogen count. A bond is an id, the two atom ids, an order — single, double, triple, or aromatic — and optionally wedge or hash. For a wedge or hash, the first atom is the narrow end, the stereocentre.

Ids are stable, which is what lets a comment stay pinned to an atom while the atom moves, and what lets two people editing the same molecule have their changes merged rather than one overwriting the other.

A library molecule is that structure inside a document: a version, an id, a name, a default atom palette, a revision number and a timestamp. The revision goes up on every committed change to the structure — renaming does not bump it — and it is what the revision-checked save compares against the server. Documents live in this browser's own storage, and in your account as well when you are signed in.

A molecule on a slide is an object in the deck. It keeps the structure and the SMILES side by side, plus the caption, the atom palette and the hydrogen setting. It has no live link back to a library molecule: Save to library copies the structure into a new document, and the two go their own ways from there.

The formula, and where its hydrogens come from#

The formula in the top bar and the inspector is derived from the same graph, in Hill order: carbon first, hydrogen second, everything else alphabetical.

Hydrogens are counted per atom, never stored. Quodra adds up the bond orders at an atom — an aromatic carbon's two aromatic bonds count as three — and fills the difference up to the smallest normal valence that still covers what is drawn, shifting that capacity for a formal charge. It is deliberately just enough chemistry to draw a structure and count its hydrogens:

• Elements the table knows are H, B, C, N, O, F, Si, P, S, Cl, Br and I. Sulfur and phosphorus carry their several valences, so a sulfone and a sulfide both come out right.
• An element outside that table still draws and still exports; it simply implies no hydrogens, and contributes none to the formula.
• An atom with an author-set hydrogen count uses that number instead, and no other rule applies to it.

Getting the string out#

• In the studio — click the SMILES box in the inspector. It selects the whole string; copy it.
• On a slide — the inspector's SMILES field holds the same string for a drawn molecule.
• Into another deck — paste the string into a fresh Molecule object's SMILES field. It draws immediately, and opening the studio on it imports it back into an editable structure.

Next#

• Molecule Studio — the editor, tool by tool.
• Tutorial: caffeine, from ring to slide — drawing a fused ring system end to end.