Chemical-Universe

Rough estimates of the number of chemically stable molecules made of a given set of elements, for every size up to a maximum number of heavy atoms. Counting follows GDB conventions:

• hydrogens are implicit;
• molecules are neutral, closed-shell and connected;
• only constitutional isomers count (no stereoisomers).

pip install -e ".[test]"
python -m chemuniverse --max-atoms 11 --elements C N O F --exact-up-to 6 --samples 10 --seed 0

  n    molecules       ± SE     mode   cumulative
  1            4               exact            4
  ...
  6         8738               exact    1.027e+04
  7    6.695e+04    2.1e+03 estimate    7.722e+04
 ...
 11     5.73e+08    4.2e+07 estimate    6.291e+08
total: 6.291e+08 ± 4.2e+07   (95.7 s)

From Python: chemuniverse.estimate(max_atoms, elements, RuleConfig(...), k_exact, samples, seed, method, jobs) returns one result per size.

--jobs N runs exact subtrees and sampling passes in N worker processes, or N threads with the Rust core. The results are identical for any N.

Optional Rust core

rust/ is a Rust port of the hot paths: tree, canonical labeling, payload and SMILES. It produces exactly the same tree, counts, SMILES and estimates as the Python code.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh   # once, if Rust is not installed
pip install ./rust                                                # builds and installs chemuniverse-core

• With the core installed it is used automatically. CHEMUNIVERSE_BACKEND=python forces the pure-Python code.
• Speed on a 10-core Mac (C, N, O, F), relative to pure Python on one core:
  • 15–23× faster on one core;
  • 75–107× faster with --jobs 10.
• Examples: exact counts up to 8 atoms take 1.5 s instead of 113 s, and 10 sampling passes to 12 atoms take 2.1 s instead of 193 s.
• Details are in design/prd/0002-performance.md.

Multi-node runs (shards)

Any run can be split into independent shards for a task farm. The reduced result is identical to a single-machine run.

python -m chemuniverse shard plan runs/cnof12 --kind exact --max-atoms 12 --elements C N O F --shards 4000
python -m chemuniverse shard run runs/cnof12 --jobs 10        # locally, or one task per shard on a cluster
python -m chemuniverse shard reduce runs/cnof12

• --kind is exact, export (SMILES) or passes (stratified sampling, with one shard per pass).
• Finished shards are skipped, so interrupted runs resume.
• On ALCF Crux, scripts/hpc/run_ensemble.py runs the shards with ensemble_launcher.
• Jobs are submitted through the DOE IRI API with the JobSpecs from scripts/hpc/crux/iri_job.py. See ADR 0012.

Molecule datasets

Exact enumeration builds every molecule exactly once, so it can write them out as a GDB-style dataset:

python -m chemuniverse export --max-atoms 9 --elements C N O F --out data/cnof9 --jobs 10

• Output files are n{size}_part{k}.smi.gz, with one Kekulé SMILES per line, plus a manifest.json that records the elements, the rules and the count per size.
• Every molecule appears once, so no canonicalization is needed.
• All rule flags of the main command apply.
• On 10 cores the export writes about 40,000 molecules per second in pure Python, or about 500,000 with the Rust core. C, N, O, F up to 9 atoms (6×10⁶ molecules) takes about 3 minutes; up to 10 atoms takes about 30 minutes. Compressed, the files take about 3 bytes per molecule: about 3 MB up to 8 atoms and about 200 MB up to 10.

Web explorer

docs/ is a static page, published with GitHub Pages: https://autonomous-scientific-agents.github.io/Chemical-Universe/

• You pick elements (C plus any of N, O, S, F, Cl, Br, I) and a maximum size.
• It compares the count with the number of atoms on Earth, in the galaxy and in the universe.
• Sizes up to the computed limit show chemuniverse results: exact, or sampled with ±2 SE.
• Larger sizes are an extrapolation of the computed growth rate, labelled as such.

A step-by-step guide to the method (graphs, stability rules, canonical augmentation and tree sampling) is at https://autonomous-scientific-agents.github.io/Chemical-Universe/method/

The data in docs/data.js is generated by:

python scripts/build_site_data.py --max-atoms 17 --samples 12 --jobs 10   # ~25 min with the Rust core

All halogens obey the same rules, so the 128 possible element choices reduce to 40 runs. Each run is cached in build/site/, so an interrupted build resumes.

Design records

design/ holds the reasons behind the code:

• decision records (ADRs), one per decision, in design/adr/;
• feature requirements (PRDs) in design/prd/;
• an index in design/README.md.

Agent traces

The AI coding sessions that built this project are archived in agent-traces/. Their replays are published at https://autonomous-scientific-agents.github.io/Chemical-Universe/agent-traces/

Method

1. Skeleton tree. The nodes are connected graphs whose vertices are labeled by element.

   • Each child adds one atom, using McKay canonical augmentation, so every skeleton appears exactly once.
   • Skeleton-level rules prune the tree as it is built: degree ≤ valence, banned element pairs, and optionally no rings.

2. Payload. For each skeleton, the program:

   • enumerates bond orders 1–3 by backtracking;
   • derives implicit H counts;
   • applies the rules;
   • counts the distinct (element, H) labelings up to symmetry.

   Resonance/Kekulé structures (e.g. benzene) therefore count once.

3. Exact counts up to --exact-up-to heavy atoms come from a full traversal of the tree.

4. Estimates for larger sizes come from sampling the tree below the exact frontier.

   • Stratified sampling (default, Chen 1992): each pass works level by level.
     • Children are grouped by a coarse type: the number of atoms with each free valence, plus the ring count.
     • One weighted representative is kept per group. Its weight is the total of everything merged into it, and it is swapped in with probability w/total.
     • Each pass is an unbiased estimate; the standard error comes from the spread across --samples passes.
     • With C, N, O, F the default 10 passes give about 7% error at 11 atoms.
   • Knuth probes (--method knuth): random root-to-leaf walks, each weighted by the product of branching factors along the way.
     • Unbiased and much cheaper per sample, but heavy-tailed: rare huge-weight probes dominate.
     • At equal cost its error bars are unreliable. A 300-probe and a 1000-probe run to 10 atoms disagreed by 3×.

Rules

Each group can be turned off from the command line.

Group	Rules	Flag
Valence	C4, N3, O2, S2, P3, Si4, B3, halogens 1; optional S 4/6 and P 5	--hypervalent
Bond orders	≤ 3; no triple bonds on O, S or halogens	--no-bond-order-limits
Strain	no triple bond in a ring < 8 atoms; no double bond in a 3- or 4-membered ring; no cumulated bonds at an atom in a ring < 9; Bredt (no multiple bond at a bridgehead of rings ≤ 7)	--no-strain
Heteroatoms	no O–O, N–O or halogen–(N, O, S, halogen) bonds; no enols; no hemiacetals, hemiaminals or gem-diols	--no-heteroatom, --allow-n-o
Validation	acyclic only / single bonds only	--no-rings, --no-multiple-bonds
Strict tier (--rules strict, off by default)	S1 no heteroatom chains X–X–X; S2 no S–O; S3 no 3/4-ring with ≥ 2 heteroatoms; S4 no enethiols, NH-enamines, ynols/ynamines, imidic/thiono acids, ketenes; S5 no hemithioacetals; S6 no thioaldehydes/thioketones. Keeps 24% of C,N,O,S and 56% of C,N,O,F molecules at 8 atoms (ADR 0015)	--no-hetero-chains, --allow-s-o, --no-small-ring-heteroatoms, --no-tautomer-filter, --no-thio-gem, --no-thiocarbonyl-filter

Checks

pytest checks:

• alkane counts against OEIS A000602;
• carbon skeleton counts against the known numbers of connected graphs with max degree 4;
• the generation tree against brute-force enumeration of every labeled graph with ≤ 4 atoms;
• hand counts for small molecules and for each rule;
• the estimator against exact counts.

With C, N, O, F up to 11 atoms there are exactly 698,073,917 molecules (6.98×10⁸; 8,303,267,373 up to 12 atoms). This is about 27× GDB-11 (2.6×10⁷), which uses much stricter functional-group and ring filters.

Exact C, N, O, F counts per size, computed on ALCF Crux (sizes 10–12 for the first time; 12 atoms took 86 core-hours on 4 nodes):

n	7	8	9	10	11	12
molecules	67,403	583,112	5,526,145	56,997,371	634,889,614	7,605,193,456

Exact C, N, O, S counts (exported as a dataset; see below):

n	7	8	9	10	11	12
molecules	219,566	2,129,403	22,382,806	253,018,485	3,057,059,302	39,320,382,465

Datasets

Dataset	Molecules	Size	Manifest
chemuniverse-CNOS-le12: all C, N, O, S molecules up to 12 heavy atoms, basic rules	42,655,220,742	132 GB (74 gzip SMILES chunks)	results/chemuniverse-CNOS-le12/manifest.json
chemuniverse-CNOS-le12-strict: the same with the strict tier (ADR 0015)	8,060,129,218	26 GB (23 chunks)	results/chemuniverse-CNOS-le12-strict/manifest.json

• The dataset is stored on ALCF Eagle; public Globus access is pending.
• Each line is one Kekulé SMILES, and every molecule appears exactly once.
• The dataset uses the basic rules. It therefore includes heteroatom chains, unstable tautomers and thioaldehydes, which the strict tier removes. Treat it as an upper-bound enumeration, not a list of stable compounds.
• The manifest lists every file with its molecule count and SHA-256 checksum, plus the rules and the code commit that produced it.

Limitations

• Tautomers count as separate molecules (apart from the enol ban).
• There are no charged species or radicals.
• The strain and Bredt rules are heuristics.
• Exact enumeration is pure Python and practical up to about 7 heavy atoms (for CNOF, 6 atoms take about 1 s and 7 atoms about 10 s).
• Stratified passes get slower with depth, because the number of strata grows: about 10 s per pass from 6 to 11 atoms for CNOF.