Getting started

AsciiChem is a language for chemistry. It has three implementations — Ruby, TypeScript, and Python — that pass the same shared corpus byte-for-byte. Pick the one that ships in your stack; the syntax and the model are identical everywhere.

Ruby

1. Install the gem

   gem install asciichem

2. Parse and render

   require "asciichem"
   
   formula = AsciiChem.parse("H_2O")
   formula.to_mathml        # => "<math>...</math>"
   formula.to_text          # => "H_2O"  (round trip)
   formula.to_structural_svg # 2D diagram

3. Use the CLI

   asciichem convert -i "2H_2 + O_2 -> 2H_2O" -t mathml
   asciichem lint -i "H_2 + O_2 -> H_2O"
   asciichem resolve --cas 50-78-2

Full reference: Ruby API.

TypeScript

1. Install the package

   npm install asciichem

2. Parse and render

   import { parse, renderMathml } from "asciichem";
   
   const formula = parse("H_2O");
   formula.toText();          // "H_2O"  (round trip)
   formula.toStructuralSvg(); // 2D diagram
   renderMathml(formula);     // "<math>...</math>"

3. Ingest database chemistry

   import { parseSmiles } from "asciichem";
   
   parseSmiles("CC(=O)OC1=CC=CC=C1C(=O)O") // aspirin, same model
     .toStructuralSvg();

Full reference: TypeScript API.

Python

1. Install the package

   pip install asciichem-py

2. Parse and render

   from asciichem import parse_text
   from asciichem.text import render
   from asciichem.mathml import render_mathml
   
   formula = parse_text("H_2O")
   render(formula)          # "H_2O"  (round trip)
   render_mathml(formula)   # "<math>...</math>"

3. Wire form for pipelines

   from asciichem.wire import to_model_json, from_model_json
   
   wire = to_model_json(formula)   # asciichem-model v1 JSON
   back = from_model_json(wire)    # ...and back, losslessly

Full reference: Python API.

AsciiChem or SMILES — try something your colleagues useCC(=O)OC1=CC=CC=C1C(=O)O

·Ruby

asciichem

gem install asciichemReference implementation.

·TypeScript

asciichem-ts

npm install asciichemPowers this page.

·Python

asciichem-py

pip install asciichem-pyZero runtime deps.

What’s in a parse?

AsciiChem parses text into a model tree. Each node has typed fields — chemistry semantics, not just typography. The tree is the same whether you parsed in Ruby, TypeScript, or Python.

Source	Model
H_2O	Molecule[Atom(H, sub:"2"), Atom(O)]
^14C	Molecule[Atom(C, isotope:"14")]
Ca^2+	Molecule[Atom(Ca, charge:"2+")]
Ca(OH)_2	Molecule[Atom(Ca), Group(...,mult:"2")]
2H_2+O_2 -> 2H_2O	Reaction(reactants:[...], products:[...], arrow::forward)

The headline semantic fix

For ^14C, AsciiChem binds the isotope to the atom — the model says “Carbon with isotope 14”. AsciiMath would produce an empty element followed by the atom — the binding is lost.

Where to next?

• Implementations — the three packages, side by side.
• Atoms — elements, isotopes, charges, oxidation states.
• Molecules — stoichiometry, groups, brackets.
• Reactions — forward, equilibrium, conditions.