Atoms

The atom is the atomic unit of chemistry (and of AsciiChem). An atom captures:

Field	Source position	Example
element	element symbol	C, He, Fe
isotope	prefix	^14C
subscript	suffix (after _)	H_2
charge	suffix	Ca^2+
oxidation_state	suffix	Fe^(III)
lone_pairs	prefix (:)	::O
radical_electrons	suffix (.)	N.
atom_parity	suffix (@R/@S)	C@R
x2, y2	suffix (@(x,y))	C@(10,20)
x3, y3, z3	suffix (@(x,y,z))	C@(1,2,3)
spin_multiplicity	suffix (@m(N))	C@m(2)
atom_title	suffix (@t("..."))	C@t("C1")
x_fract, y_fract, z_fract	suffix (@f(x,y,z))	C@f(0.5,0.25,0.75)
ring_closures	suffix (digit)	C1

Multiple annotations chain in a fixed order: C@(10,20)@R@m(2)@t("C1")@f(0.5,0.5,0.5).

See also: Coordinates, Ring closures, Stereochemistry, Annotations.

Element symbols

A capital letter optionally followed by a lowercase letter.

Source

Source Rendered

H

$\mathrm{H}$

He

$\mathrm{He}$

Uue

Install the asciichem gem to see this rendered.

Notes

Two-letter symbols (He, Uue) are captured as a single element, not as H followed by e. The grammar requires capital-then-lowercase for the two-letter form.

Subscripts

A subscript multiplicity follows _ directly. The subscript binds to the immediately preceding atom.

Source Rendered

H_2

${\mathrm{H}}_2$

O_3

${\mathrm{O}}_3$

H_2O

${\mathrm{H}}_2\mathrm{O}$

For multi-character subscripts, use braces:

Source Rendered

H_{2a}

${\mathrm{H}}_{\mathrm{\{2a\}}}$

Implicit subscripts on Hydrogen

Hydrogen accepts bare digits as an implicit subscript, so common formulae can be written without _:

Source Rendered

H2

${\mathrm{H}}_2$

H2O

${\mathrm{H}}_2\mathrm{O}$

CH4

$\mathrm{C}{\mathrm{H}}_4$

NH3

$\mathrm{N}{\mathrm{H}}_3$

Each canonicalises to the explicit form on round-trip (H_2, H_2O, CH_4, NH_3).

Why only Hydrogen?

Bare digits after other elements are already used for SMILES-style ring closures (C1-C-C-C-C-C1 is cyclohexane). Hydrogen is the special case — it cannot form ring closures (only one bond), so bare digits after H are unambiguously subscripts.

For other elements, use the explicit _ form (O_3, S_2).

Charges

Charges are suffix superscripts in IUPAC number-then-sign form:

Source Rendered

Ca^2+

${\mathrm{Ca}}^{2+}$

Cl^-

${\mathrm{Cl}}^{-}$

SO_4^2-

$\mathrm{S}{\mathrm{O}}_4^{2-}$

Canonicalisation

AsciiChem canonicalises charge signs. ^+2 becomes ^2+ on round-trip per IUPAC convention.

Oxidation states

Oxidation states are Roman numerals wrapped in parens:

Source Rendered

Fe^(II)

${\mathrm{Fe}}^{\mathrm{II}}$

Fe^(III)

${\mathrm{Fe}}^{\mathrm{III}}$

Mn^(VII)

${\mathrm{Mn}}^{\mathrm{VII}}$

The model captures these as Atom#oxidation_state (“II”, “III”, “VII”), distinct from a generic superscript.

The prefix isotope — the headline semantic fix

The defining difference between AsciiChem and AsciiMath lives here.

Source Rendered

^14C

${}^{14}\mathrm{C}$

^131I

${}^{131}\mathrm{I}$

^238U

${}^{238}\mathrm{U}$

In AsciiChem, the ^14 prefix binds to the following atom. The parse produces one Atom with isotope: "14". The MathML output is:

<msup><mi>C</mi><mn>14</mn></msup>

In AsciiMath, the same input would force a phantom carrier:

<msup><mi></mi><mn>14</mn></msup><mi>C</mi>

— an empty base followed by a sibling atom. The semantic binding (isotope 14 belongs to Carbon) is lost.

Stoichiometric coefficients

Leading digits on a molecule are the coefficient, distinct from the leading digit of a subscript. The grammar uses positive lookahead to disambiguate.

Source Rendered

2H_2O

$2{\mathrm{H}}_2\mathrm{O}$

3H_2

$3{\mathrm{H}}_2$

The 2 in 2H_2O is the molecule’s coefficient; the 2 in H_2 is the atom’s subscript. Both are captured in the right place.