chematic

日本語 | 中文

A cheminformatics library for Python, Rust, and the browser.

Cheminformatics that's fast by default, safe by design.
Pure Rust · Zero C/C++ · Python · WebAssembly · Live Demo

All numbers are reproducible — see benchmark details.
WASM sizes: chematic 719 KB · RDKit.js ~30 MB · Indigo WASM ~40 MB

Feature maturity at a glance:

What you get

$ python -c "import chematic; print(chematic.from_smiles('CC(=O)Oc1ccccc1C(=O)O').describe())"
Molecular weight 180.2 Da, formula C9H8O4.
LogP 1.31 (mildly lipophilic), TPSA 63.6 Ų.
HBD 1, HBA 3, 3 rotatable bond(s), 1 aromatic ring(s).
Drug-likeness: no Lipinski rule-of-5 violations. likely orally bioavailable (passes Veber criteria).
QED 0.56 (0 = non-drug-like, 1 = ideal).
Structural alerts: Brenk alert.

One pip install. No RDKit, no conda, no C compiler. Works in Python, Rust, the browser, and AI agents.

# HTML report — self-contained, opens in any browser and renders in Jupyter
mols = [chematic.from_smiles(s) for s in smiles_list]
report = chematic.report(mols, names=compound_names)
report.save("report.html")   # or: display(report) in Jupyter

# Side-by-side comparison
cmp = chematic.compare(aspirin, ibuprofen, names=("Aspirin", "Ibuprofen"))
cmp.save("compare.html")

Common Use Cases

Full worked examples → Use cases

When to use chematic

Use chematic if:

• You want chemistry in the browser (WASM, 719 KB, no server required)
• You need a pure Rust stack with no C++ toolchain dependencies
• You deploy to environments where pip install rdkit is impractical (Cloudflare Workers, Lambda, embedded)
• You build AI agents and want native MCP tool integration
• You process molecules in batch at high throughput (ECFP4: 2–3× faster than RDKit, Rayon-parallel)
• You want pip install chematic to just work — anywhere, no compiler needed

Use RDKit if:

• You need maximum ecosystem compatibility and 20+ years of production validation
• You need publication-quality 3D structures with ML-assisted torsion corrections (RDKit's ETKDGv3)
• You need bit-exact standard InChI without enabling the native-inchi feature
• You depend on community plugins written against the RDKit Python API

Quick Start

Installation

# Python — no C/C++ compiler required
pip install chematic

# Rust
cargo add chematic --features "smiles,perception,chem,3d,fp"

# JavaScript/TypeScript
npm install @kent-tokyo/chematic

Python

import chematic

mol = chematic.from_smiles("CC(=O)Oc1ccccc1C(=O)O")  # aspirin

# In Jupyter, type `mol` in a cell — 2D structure renders automatically
mol

# Access 190+ descriptors as properties
print(mol.mw, mol.logp, mol.tpsa)           # 180.16  1.31  63.6
print(mol.lipinski_passes, mol.pains_passes) # True   True

# Substructure search
mol.has_substructure("[OH]")   # True
mol.find_matches("[CX3](=O)O") # → [[1, 2, 3], [7, 8, 9]]

# Natural-language summary (one paragraph)
print(mol.describe())

# Structured Markdown report — paste into LLM, Jupyter, or save as .md
print(mol.review())
# → # Molecular Review\n## Structure\n## Physical Properties\n## Drug-likeness\n## ADMET...

# Structural diff between two molecules
ibuprofen = chematic.from_smiles("CC(C)Cc1ccc(CC(C)C(=O)O)cc1")
d = mol.diff(ibuprofen)  # {"summary": "+C7, -O2. ΔLogP +2.75 ...", "delta_mw": 66.1, ...}

# Batch processing — parallel, numpy-ready
fps = chematic.bulk.ecfp4(["CCO", "c1ccccc1", "CC(=O)O"])  # (3, 2048) uint8

# One-liner DataFrame
df = chematic.descriptors_df(["CCO", "c1ccccc1", "CC(=O)O"])
df[["mw", "logp", "tpsa", "qed"]]

For Rust and JavaScript/TypeScript examples, see the documentation.

Migrating from RDKit

chematic.rdkit_compat provides a lightweight RDKit-compatible subset so existing scripts port with minimal changes:

from chematic import rdkit_compat as Chem
from chematic.rdkit_compat import Descriptors, rdMolDescriptors, DataStructs

mol = Chem.MolFromSmiles("CC(=O)Oc1ccccc1C(=O)O")
Descriptors.MolWt(mol)                       # 180.16
fp = rdMolDescriptors.GetMorganFingerprintAsBitVect(mol, 2, nBits=2048)
DataStructs.TanimotoSimilarity(fp, fp)       # 1.0

It is not a full RDKit clone, and unsupported options fail loudly. See the RDKit compatibility guide for the compatibility matrix, differential-validation results vs RDKit, and runnable examples.

Diagnostics

import chematic
chematic.doctor()
# chematic v0.4.30
# Python 3.12.x  |  darwin arm64
#
# Descriptor accuracy (benchmark 2026-07-17, v0.4.30 vs RDKit 2026.03.3):
#   MW / HBA / HBD / ARC  100%   (4,999-mol ChEMBL subset)
#   TPSA                  100%   within ±0.1 Ų
#   LogP (Crippen)        100%*  (max Δ = 1.1×10⁻¹³)
#   Stereocenter count    99.96% (legacy) / 98.6% (new CIP FindPotentialStereo)
#   CIP R/S label         96.30% vs modern rdCIPLabeler (96.83% vs legacy)
# ...

For AI / LLM Developers

chematic ships a native MCP (Model Context Protocol) server — the first cheminformatics library with built-in AI agent integration.

// Claude Desktop (~/.config/claude/claude_desktop_config.json)
{
  "mcpServers": {
    "chematic": { "command": "chematic-mcp" }
  }
}

15 chemistry tools are callable from any MCP-compatible agent:

Why Pure Rust?

Fast

Rust's zero-cost abstractions and ownership model eliminate overhead at the source. chematic's ECFP4 fingerprint batch pipeline runs at ~78 µs/mol on a diverse molecule corpus — 2–3× faster than RDKit's Python API on the same hardware, via Rayon parallelism across all CPU cores. No GIL, no interpreter overhead, no FFI call overhead hidden inside a _sys crate.

Safe

chematic's own ~15,000 lines of Rust contain ~6 unsafe blocks, all confined to the optional native-inchi FFI layer (below). No C++ heap corruptions. No segfaults from malformed SMILES input. No platform-specific build failures from -sys crates. The compiler enforces memory safety at every call site chematic itself wrote.

The native-inchi feature is the single opt-in exception — it vendors the IUPAC InChI C library (v1.07.5) for bit-exact standard InChI. All other chematic crates stay FFI-free and unsafe-free. This count is chematic's own source only, not its dependency tree — the optional depict feature (SVG/PDF/EPS rendering) pulls in a font/image-rendering stack (resvg/usvg/rustybuzz/tiny-skia/zune-jpeg) that is not unsafe-free; see the comparison table footnote below for a measured count.

Anywhere

Pure Rust compiles to wasm32-unknown-unknown natively — no Emscripten, no cmake, no clang. The npm package @kent-tokyo/chematic is 719 KB gzip — ~42× smaller than RDKit.js. One codebase runs on Linux, macOS, Windows, and in every browser.

Benchmarks & Validation

*LogP max Δ = 1.1×10⁻¹³ across 4,999 molecules — within float64 rounding error.
†Stereocenter count: ~99.96% vs legacy CalcNumAtomStereoCenters (a handful of molecules where chematic matches FindPotentialStereo and legacy under-counts); ~98.6% vs new-CIP FindPotentialStereo (cage/bridgehead molecules where both chematic and legacy correctly return fewer than the new oracle). chematic is calibrated between both extremes. This measures whether an atom is flagged as a stereocenter, not whether its R/S label is correct — see the next row.
‡CIP R/S label agreement measures, for atoms both oracles agree are stereocenters, whether the assigned R/S descriptor matches — a stricter, separate check from stereocenter count agreement above. This row is chematic's default assign_cip() path. The separate chematic-cip engine now reaches 99.38% raw / 99.64% oracle-stable (Milestone 4 gate closed) and is reachable opt-in via assign_cip_with_mode(mol, CipMode::Accurate) (Rust), Mol.cip_stereo(mode="accurate") (Python), or cip_assignments_accurate_json (WASM) — see docs/cip_accurate_rfc.md. No default path changed; this row's 96.30% is unaffected.

All numbers are reproducible with the scripts in this repo.
Full history → benchmarks/ · Methodology → validation/

Comparison with Other Cheminformatics Libraries

† Default build only. The optional native-inchi feature adds a C-compiler dependency for the vendored IUPAC InChI C library (v1.07.5). This is about C/C++ FFI specifically — the depict feature below pulls in pure-Rust rendering crates, so it doesn't add a C compiler dependency even though it isn't unsafe-free (see ‡).

‡ chematic's own ~15,000 lines of Rust: unsafe-free outside native-inchi's ~6 FFI blocks (see "Safe" above) — a real, verifiable claim about code chematic wrote, and categorically different from RDKit/OpenBabel's C++ FFI unsafe (uncheckable by any compiler at that boundary) even where the raw count is comparable. It is not true of the full dependency tree: the optional depict feature (SVG/PDF/EPS rendering) pulls in resvg/usvg/rustybuzz/tiny-skia/zune-jpeg, pure-Rust crates that are themselves not unsafe-free — measured directly (unsafe fn/impl/trait/{ openings): tiny-skia 151, zune-jpeg 79, rustybuzz 14, image 8, fontdb 3, tiny-skia-path 3 (258 total in this set alone). chematic-py (pip install chematic) and the npm package both depend on chematic-depict directly, so this applies to both real-world install paths, not just an edge case.

JavaScript / TypeScript (WebAssembly)

719 KB gzip — ~42× smaller than RDKit.js. No Emscripten, no cmake. Drop-in for browser or Node.js.

npm install @kent-tokyo/chematic

import init, { parse_smiles, get_descriptors_json, tanimoto_ecfp4,
               generate_3d_minimized_pdb, enumerate_stereo_isomers_json,
               maxmin_picks_ecfp4_json } from '@kent-tokyo/chematic';

await init();

const mol = parse_smiles('CC(=O)Oc1ccccc1C(=O)O'); // aspirin
console.log(mol.molecular_weight(), mol.qed(), mol.lipinski_passes());

// All descriptors as a JSON object
const desc = JSON.parse(get_descriptors_json(mol));

// Fingerprint similarity
const caffeine = parse_smiles('Cn1cnc2c1c(=O)n(c(=O)n2C)C');
console.log(tanimoto_ecfp4(mol, caffeine));  // 0.26

// 3D coordinates, stereoisomers, diversity picking
const pdb = generate_3d_minimized_pdb(mol);
const isomers = JSON.parse(enumerate_stereo_isomers_json(parse_smiles('C(F)(Cl)Br')));
const picks = JSON.parse(maxmin_picks_ecfp4_json('["CC","c1ccccc1","CCO","CCCC"]', 2));

130+ exported functions cover descriptors, fingerprints, 3D geometry, reactions, diversity picking, and SDF round-trips. See the full WASM API reference for all exports.

Crate Reference

cargo test --workspace --lib --quiet                                          # 2,366 tests, all passing
cargo test -p chematic-inchi --features native-inchi --test standard_inchi  # +16 IUPAC-exact InChI tests

Recent Development (v0.4.x Era)

v0.4.30 (2026-07-17): chematic-cip opt-in wired to every surface, SMARTS [rN] fix, new RDKit-parity aromaticity engine, 5 stereo-metadata bug fixes

• chematic-smarts: fixed [rN] (ring-size SMARTS, e.g. [r5]/[r6]) being wrongly aliased to [kN]'s any-ring semantics — RDKit's real [rN] means "this atom's smallest ring is exactly size N", a materially different predicate (confirmed empirically: on a fusion atom shared between a 5-ring and 6-ring, RDKit's [k6] matches but [r6] doesn't). No ring-model change — [rN] now has its own MinRingSize primitive computed from chematic's existing SSSR. SMARTS match-set agreement vs RDKit 96.9% → 99.93% on a 5,000-molecule corpus, 0 regressions; see docs/rdkit_compat.md's "SMARTS-R0"/"SMARTS-R1" entries
• Milestone 5A: opt-in access to the accurate engine from every public surface — chematic_chem::assign_cip_with_mode(mol, CipMode::Accurate) (Rust), Mol.cip_stereo(mode="accurate") + Mol.cip_stereo_unresolved() (Python), cip_assignments_accurate_json/cip_unresolved_json (WASM). Every default (assign_cip(), cip_stereo(), the un-suffixed WASM functions) is unchanged — this is additive only, not a default switch; see docs/cip_accurate_rfc.md's Milestone 5A entry for the merge semantics (accurate tetrahedral R/S + legacy E/Z, since the accurate engine doesn't compute bond stereo) and the "never guess" contract (ties/budget-outs surface explicitly, never silently backfilled)
• Milestone 4 gate closed: 99.64% oracle-stable agreement (raw 99.38%, 4160/4186) on a full-corpus, representation-stability-stratified score — the last residual (11 phosphorus cyclophosphazene rows) turned out to be an oracle instability (RDKit's own labels change under a chemically-neutral Kekulé respelling of the identical molecule), not a chematic defect; the 15-row Rule 5 cage family remains deferred, unaffected by this gate
• The accurate engine (a provenance-carrying, sphere-by-sphere digraph comparator — Rules 1a/1b/2 — plus RDKit-compatible MANCUDE fractional atomic numbers for aromatic ring stereocenters) is available through the opt-in APIs above but is not yet the default implementation behind assign_cip()
• Found and fixed a real ~10-14x perf regression (SSSR misused for a boolean ring-bond check, replaced with an O(V+E) bridge-edge DFS); CI Criterion-gate bootstrap fix; a Criterion-gate reliability finding (pseudo-replication, #70) — process-level redesign (independent process-run observations, two-stage screening, same-binary null control) landed, gate stays non-required until calibration completes
• Milestone 4A: CipCode::LowerR/LowerS — Rule 5 (pseudoasymmetry), scoped to 2 verified-independent rows; a three-armed symmetric-cage family (15 rows) was found to be provably unreachable by this pairwise architecture and deferred as Milestone 4A-2 (needs symmetry/automorphism detection)
• Milestone 4A-0: re-froze the residual fresh at 34 rows and mechanically classified 100% of it (0 unexplained) — 15 Rule 5/pseudoasymmetry (the 4A-2 cage family), 8 Rule 4 candidate (positively confirmed via a structural-identity check, not inferred), 11 phosphorus (9 comparator-bug "wrong" + 2 genuinely-tied)
• chematic-perception: new opt-in assign_aromaticity_rdkit_parity_experimental/apply_aromaticity_rdkit_parity_experimental — a source-verified port of RDKit's actual aromaticity algorithm, 100.0000% atom/bond agreement with real RDKit on 4,999/5,000 comparable molecules. Not wired into the default path (RdkitLike/Huckel unchanged); default-promotion is blocked on a pre-existing, unrelated canonical-SMILES-writer sensitivity, not this engine
• Fixed 5 instances of the same missing-metadata-copy bug (a MoleculeBuilder rebuild not calling copy_stereo_groups_from/copy_stereo_from/copy_bond_directions_from), each silently dropping stereo_neighbor_order or worse: apply_kekule (P0), enumerate_stereoisomers (could silently flip a newly-assigned stereocenter's CIP code), transfer_hydrogen_aromatic/clone_mol (now deleted, replaced by Molecule::clone), transfer_hydrogen, and invert_stereocenter (which turned out to be a functional no-op on plain @/@@ SMILES input, a separate and more severe bug)
• chematic-smiles: consolidated aromatic bond-direction stashing across all 3 parser bond-creation paths (chain-edge/ring-closure/branch-attachment) into one shared helper — fixes a canonical-round-trip representation instability (4,994/5,000 → 5,000/5,000 stable); does not fix assign_ez's pre-existing blindness to this side channel (tracked as follow-up)
• Full-corpus accuracy on the experimental CIP engine 96.68% → 99.38% raw / 99.64% oracle-stable vs modern RDKit rdCIPLabeler (0 regressions) — see docs/cip_accurate_rfc.md for the full milestone history
• Benchmarks refreshed (benchmarks/2026-07-17.md, Apple M4): the previous ECFP4 throughput headline (3.6 µs/mol, 5–14× vs RDKit) does not reproduce on a clean remeasurement — updated to today's measured numbers (~78 µs/mol / 2–3× on a diverse corpus) throughout this README and docs/; descriptor accuracy numbers reproduce cleanly

v0.4.29 (2026-07-10): Kabsch rotation bug fix + SDF V3000/CDXML write, Avalon FP, O3A

• chematic-3d: fixed align_coords's Kabsch rotation computed in the wrong direction — was giving grossly inflated RMSD for any non-pure-translation alignment (live on v0.4.28 across crates.io/PyPI/npm before this patch); correspondence_search for O3A atom correspondence
• chematic-mol: SDF V3000 write wiring; CDXML write
• chematic-fp: Avalon fingerprint

v0.4.28 (2026-07-09): SMARTS perf, registry re-sync

• chematic-smarts: existence-check short-circuit — bulk.substructure_search 2.2× faster than RDKit
• No git tag had been pushed for v0.4.23–v0.4.27 (crates.io stayed current via manual cargo publish, but PyPI/npm/GitHub Releases fell behind) — this release re-syncs all three registries

v0.4.27 (2026-07-04): Descriptor fixes, RWMol/FCFP, veridict CI gates

• chematic-chem: kappa1-3, balaban_j, labute_asa, bcut2d, hall_kier_alpha descriptor fixes
• chematic-fp: useFeatures=True FCFP
• chematic-mol: RWMol in-place editing
• CI: veridict-based performance/Criterion/accuracy-drift regression gates; integration-test CI coverage gap fix

v0.4.26 (2026-06-29): E/Z stereo transfer in reactions + validation Sprint 6/7

• chematic-rxn: reaction products now preserve //\ double-bond geometry from reactants in run_reactants() (previously lost on transformation)
• Validation: canonical SMILES differential validation vs RDKit (Sprint 6); SMARTS/aromaticity differential tests + I/O compatibility (rdkit_compat Sprint 7); root-caused remaining RDKit canonical divergence to aromaticity round-trip, not Morgan ranks

v0.4.25 (2026-06-29): chematic.rdkit_compat layer

• chematic-py: RDKit API compatibility surface (Sprints 1–5) — Morgan bitInfo, Fingerprint/Mol/Atom/Bond/RingInfo compatibility, differential tests against RDKit; streaming SDMolSupplier/SDWriter/Mol.GetProp
• chematic-perception: AromaticityAlgorithm::RdkitLike — Se/Te chalcogen aromaticity matching RDKit's model

v0.4.24 (2026-06-29): CIP Rule 5, bridgehead/rotatable-bonds/TPSA/MR to 100%, HDF fingerprints

• chematic-chem: CIP Rule 5 stereo tie-breaking (stereocenters 99.8% → 99.98% vs RDKit); bridgehead detection 98.5% → 100%; rotatable bonds 99.1% → 100%; TPSA 100%; molar refractivity 97.5% → 100% (3-ring XOR augmentation) — all on the 5,000-mol ChEMBL corpus
• chematic-py: bulk.descriptors_array() columnar numpy output; true-streaming SDF (SdfFileReader/iter_sdf_batched); screen() compound-filter workflow
• LLM/RAG: representation router (to_llm_text, best_representation), molecule context pack, Hyper-Dimensional Fingerprints (HDF) — training-free dense molecular vectors

v0.4.23 (2026-06-26): LogP 96.5% → 99.7%

• chematic-chem: crippen_anchor_sets fixed to use uniquify: false, so symmetric triple bonds (internal alkynes) yield both VF2 match orientations instead of one falling back to the generic [#6] value

v0.4.22 (2026-06-26): CITATION.cff + chematic.doctor()

• chematic-py: doctor() self-diagnostic; Reliability-by-Feature matrix added to README

v0.4.21 (2026-06-25): HTML/Markdown reporting for LLM/Jupyter

• chematic-py: chematic.report() self-contained HTML compound grid, chematic.compare(), mol.review() Markdown analysis
• Docs: benchmarks//validation/ reproducible accuracy history

v0.4.20 (2026-06-25): ETKDG torsion KB 44 → 80 rules, mol.describe()/diff()

• chematic-3d: chair/envelope ring conformations for 6/5-membered aliphatic rings; SMARTS-based torsion rules as a high-precision pre-check layer
• chematic-py: mol.describe()/mol.diff(other) for LLM/MCP agents; bulk.generate_3d/tanimoto_matrix/standardize

v0.4.19 (2026-06-23): PDF/EPS output, ChemicalJSON, new descriptors, WASM −38.5%

• chematic-depict: depict_pdf() / depict_eps() — PDF and EPS output; pure Rust, no external tools
• chematic-mol: ChemicalJSON — parse_cjson() / write_cjson() for Avogadro2 / MolSSI interop
• chematic-chem: 4 new descriptors — schultz_mti(), gutman_mti(), vabc() (Bondi vdW volume), gravitational_index()
• chematic-3d: Spectrophores 3D fingerprints (pharmacophore shell encoding)
• chematic-py: mol.to_pdf(), mol.to_eps(), mol.to_cjson(), from_cjson(); bulk.substructure_match(smarts, mols) parallel VF2; estate_all() and ring_bundle in bulk
• WASM bundle: 819 → 504 KB gzip (−38.5%) — tiny_skia made optional, inline SHA-256, opt-level="z" lto=true codegen-units=1

v0.4.18 (2026-06-23): Python API expansion + benchmark docs

• chematic-py: Jupyter auto-display — writing mol in a cell renders 2D structure via _repr_svg_(); mol.has_substructure(smarts), mol.find_matches(smarts); from_smiles_list(), descriptors_df()
• chematic-chem: chi_all() — all 10 Hall-Kier connectivity indices in a single pass; cns_mpo_from_parts(); pains_passes_and_matches() / brenk_passes_and_matches() — combined pass/match in one scan
• Docs: benchmark page added (ECFP4 5–14× vs RDKit, 100% descriptor accuracy on 4,999-mol ChEMBL corpus)

v0.4.16–v0.4.17 (2026-06-22–23): SSSR sharing performance sprint

• chematic-smarts: find_matches_with_rings() — share a pre-computed RingSet across all patterns in a batch
• chematic-chem: Crippen 117 SSSR → 1 per logp_crippen call; PAINS ~480 → 1; QED 113 → 1; pKa 42 → 1; new logp_and_mr(), logd_from_logp(), pka_both() to avoid redundant passes
• chematic-fp: MHFP incremental BFS — 3N → N BFS operations per molecule at radius=2

v0.4.15 (2026-06-21): TPSA calibration + E/Z stereo in reactions

• chematic-chem: TPSA ±0.1 Ų calibration sprint — HBA 100%, HBD 100%, aromatic ring count 100% on 4,999-mol ChEMBL subset; TPSA 86.7% → 93.3% (4,999-mol), 100% on 175-mol drug-like set
• chematic-rxn: E/Z double-bond stereo filtering in run_reactants — SMIRKS //\ geometry matching via smirks_ez_stereo_ok() / ez_stereo_outward()

v0.4.14 (2026-06-21): Topological descriptors + stereo correctness

• chematic-chem: 8 topological descriptors — petitjean_index(), graph_eccentricities(), graph_diameter(), graph_radius(), eccentric_connectivity_index(), hosoya_index(), moran_autocorr(), geary_autocorr()
• chematic-3d: GETAWAY HATS-matrix (19-dim); whim_getaway_combined() now 29-dim
• chematic-smiles: allene cumulated stereo C=C=C @/@@ — round-trip stable
• chematic-smarts: [kN] ring-size primitive; VF2 early-exit when query > target atom count
• chematic-rxn: parity-aware SMIRKS chirality matching; product bracket cleanup ([O:1] → O)
• chematic-perception: zero-order/dative bonds excluded from SSSR; count_aromatic_rings() handles Kekulé input

Earlier v0.4.x work (template retrosynthesis, AutoDock/UFF, Kekulization blossom algorithm, PyO3 bindings, native-inchi) and the full v0.1–v0.3 history: CHANGELOG.md

Built with chematic

Using chematic in a project? Share it in Discussions or open a PR to add it here.

Reliability by Feature

Not all features have the same validation depth. This table tells you what to trust.

Full benchmark methodology → validation/ · History → benchmarks/

Known Limitations

• canonical_smiles() is now partially normalized for E/Z stereochemistry — still not safe as a dedup or cache key. Isolated/simple E/Z double bonds have two equally correct //\ spellings (e.g. /N=N/ vs \N=N\); the writer previously never normalized between them. Fixed for the general case: every connected E/Z system (a double bond plus every directional bond geometrically tied to it, including whole conjugated chains) is now normalized so its first directional bond in canonical write order is always /, regardless of input spelling. Measured on the 5,000-mol ChEMBL corpus, worst-of-10: E/Z-only self-instability (tetrahedral stereo stripped) improved 9.76% → 5.50% (275/5000 still unstable); structural correctness unaffected by this change (re-verified 0/5000 ChEMBL and 0/33 acyclic-polyene corpus). The residual 275 are confirmed 100% cosmetic — every unstable case's variants represent the same molecule per RDKit, zero corruption — but the cause is a mixed pool, not fully root-caused: about half match a specific motif (a small ring bearing two or more exocyclic double bonds, e.g. cross-conjugated cyclic diimines) where which physical bonds count as "one system" is not yet input-spelling-invariant; the other half is uncharacterized. Until this closes fully, ~1 in 18 stereo-bearing molecules (down from ~1 in 10) can still produce two different, individually valid canonical_smiles() strings for the same molecule — do not use it as a dedup or cache key today; document your own dedup key as apply_aromaticity()-normalized in the meantime if this matters for your use case.
• Canonical SMILES structural corruption — fixed. Before this fix, canonical_smiles(parse(x)) could silently emit a different stereoisomer (not just a differently-spelled but equivalent string) depending on x's input traversal order. Measured on a 5,000-mol ChEMBL subset, worst-of-10 independently-traversed representations per molecule, RDKit-verified structural correctness: 4.28% (214/5000) of molecules had at least one variant round-trip to the wrong molecule. Root-caused to two independent parser bugs (not the originally-suspected "conjugated double-bond markers are geometrically coupled across bonds" — that diagnosis was disproven, see below), each confirmed via a real found molecule and a minimal regression test: (1) a ring-closure directional-bond (//\) marker read at the closing occurrence of a ring digit was stored raw instead of flipped to the opening→closing sense, corrupting a conjugated E/Z chain whenever its connecting bond happened to be routed through a ring closure; (2) a stereocenter that opens a ring whose partner closes inside its own branch had its neighbor-order resolution keyed by the reusable ring digit rather than a unique per-occurrence id, so a later, unrelated reuse of the same digit elsewhere in the SMILES could silently steal and corrupt the stereocenter's neighbor order. After both fixes: structural correctness is 100% (0/5000) on ChEMBL, confirmed three times over via independently-ordered reconstructions of the fix (with and without an unrelated third ranking fix, to rule out a hidden dependency). Because both root causes are ring-closure-specific — and retinoids, carotenoids, prostaglandins, leukotrienes, and polyene macrolides carry their long conjugated systems in acyclic chains, essentially absent from ChEMBL-random sampling — this was independently re-verified on a dedicated 33-compound corpus of exactly those classes (tretinoin, β-carotene, lycopene, amphotericin B, leukotriene B4, and 28 others; scripts/polyene_corpus.csv): 0/33 (0.00%) at worst-of-30, with a positive control confirming 12/33 (36.36%) corruption on the pre-fix code for this same corpus (all 12 failures were ring-closure-heavy structures; zero purely-acyclic examples — including fully acyclic lycopene — ever failed, even unpatched). This directly disproves the original "any conjugated chain" diagnosis and closes the investigation with no remaining corruption class identified. Skeleton-only and tetrahedral-only self-stability also reached 0% (were 0.16% and 4.36%); raw combined self-stability (all stereo intact) improved 86.02% → 90.28% (13.98% → 9.72% unstable) — the entire remainder is the separate, non-corrupting direction-normalization gap described above, not residual corruption. Round-trip invariance (canonical(parse(canonical(m))) == canonical(m)) improved slightly, 98.26% → 98.32%, since it was never measuring the corruption class directly.
• Ring perception (SSSR) was non-deterministic and non-minimal — fixed. The old find_sssr built a single spanning tree and took one fundamental cycle per non-tree edge, with no redundancy to recover a smaller ring when the tree's shape made one unnecessarily large (naphthalene, c1ccc2ccccc2c1, deterministically returned ring sizes [6, 10] instead of [6, 6]). find_sssr now uses Horton's algorithm (candidate cycles from every vertex × every edge via shortest-path trees, O(V·E) candidates, canonical-rank tie-break for determinism), giving a genuinely minimum-weight, deterministic basis. Measured on a 5,000-mol ChEMBL subset, worst-of-10 independently-traversed representations per molecule: self-stability 100% (was 50.6%); single-parse ring-size agreement with RDKit 98.9% (was 72.4%) — the residual ~1.1% gap is RDKit's own GetSymmSSSR legitimately returning more rings than the topological minimum for symmetric fused systems (e.g. cubane: μ=5, RDKit=6), not a chematic bug; full symmetrization (Vismara relevant cycles) is future work, not required for correctness. Downstream wins, same corpus: ring-size SMARTS [r5]/[r6] 0% instability (was 29–55%), NumAromaticRings 0% (was ~4%), RingCount/MW/TPSA/HBA/HBD/LogP/MR unaffected (were already 0%). Two known-narrow exceptions where the old SSSR bug had accidentally compensated for a separate, still-open aromaticity bug — see the Aromaticity model bullet below. Full methodology: scripts/ringinfo_parity.py.
• Murcko scaffold: ring topology and normalized string output are now fully stable. The previously-reported "100% traversal-order instability" was itself a measurement-harness bug (comparing Mol objects by Python identity instead of value — always reported "unstable" regardless of the real result); that script bug is fixed (scripts/ring_collateral_damage.py). Re-measured on a 5,000-mol worst-of-10 run after the canonical-SMILES corruption fixes above: after normalizing (apply_aromaticity().canonical_smiles_mode("nostereo")), self-stability is 100% (0/5000 unstable), down from a 0.8% residual — confirming that residual was the same canonical-SMILES structural corruption, not a Murcko ring-selection bug, and it is now fully resolved. Raw isomeric scaffold().smiles string comparison (no normalization) is 79.30% stable (20.70% unstable, was ~45%, essentially unchanged by the partial E/Z-normalization fix above — scaffolds strip most of the side-chain motifs that fix improves) — the remainder is the still-partially-open, non-corrupting //\ direction-normalization gap described above, not a scaffold-specific issue. scaffold() extracts the correct ring system reliably; compare via mol.apply_aromaticity().canonical_smiles_mode("nostereo") rather than raw .smiles if you need string equality across differently-ordered input.
• Aromaticity model: chematic applies Hückel 4n+2 per SSSR ring independently; RDKit uses fused-ring electron delocalization. Visible differences in N-heterocycles (pyridone, quinolone, indolizine). Current benchmark on 4,999-mol ChEMBL subset: HBA/HBD/aromatic ring count 100%; TPSA 99.7% (±0.1 Ų); LogP 100% (±0.01). Aromaticity-flag parity on Kekulized input measured worst-of-10-representations: 96.3% (scripts/aromaticity_atom_parity.py) — bit-for-bit unchanged by the SSSR fix above, confirming the SSSR bug and the aromaticity gap are independent; the aromaticity gap is root-caused separately to an aromatic_context bypass mechanism, not yet fixed. Two molecules (azulene, purine) are known to have regressed by the SSSR fix specifically — the old, broken SSSR had accidentally been masking the aromatic_context bug for these non-alternant/bridgehead-heavy structures. They are not present in the 5,000-mol measured corpus at all (confirmed by direct search — ChEMBL-derived drug-like corpora don't contain bare azulene/purine), so the 96.3% figure is unchanged because it cannot see them, not because they have zero impact; both are pinned as #[ignore]d regressions in chematic-perception's test suite with the root cause documented in-code, pending the aromatic_context fix.
• TPSA edge cases: remaining 0.3% discrepancy (16 of 4,999 molecules) concentrated in exotic phosphazene ring-N calibration and cyclic sulfurimide/S=N=P chemistry — not relevant for drug-like molecules.

Repository Structure

chematic/
├── Cargo.toml                    workspace root (v0.4.30)
├── CHANGELOG.md
├── crates/
│   ├── chematic-core/            Atom, Bond, Molecule, Element, kekulization (4-pass + blossom)
│   ├── chematic-smiles/          OpenSMILES parser/writer, canonical SMILES
│   ├── chematic-perception/      SSSR, 2-pass Hückel aromaticity, CIP stereo
│   ├── chematic-smarts/          SMARTS parser, VF2 subgraph isomorphism, MCS, LRU cache
│   ├── chematic-chem/            190+ descriptors, pKa, ADMET, BOILED-Egg, QED, SA Score,
│   │                             PAINS/Brenk filters, scaffold, standardization, BRICS/RECAP
│   ├── chematic-fp/              ECFP/FCFP, MACCS, MAP4, AtomPair, Torsion, MHFP, ERG
│   ├── chematic-ff/              MMFF94 full stack (7 terms), DREIDING, L-BFGS minimizer
│   ├── chematic-3d/              ETKDG, MD, SASA, USR shape screen, WHIM, GETAWAY, XYZ/PDB I/O
│   ├── chematic-depict/          2D SVG rendering, grid layout, CPK colors, highlighting
│   ├── chematic-rxn/             Reaction SMILES/SMIRKS, RunReactants, RECAP/BRICS
│   ├── chematic-mol/             SDF/MOL V2000+V3000, CML, CDXML parser/writer
│   ├── chematic-inchi/           InChI/InChIKey (pure-Rust approx + IUPAC-exact via native-inchi)
│   ├── chematic-iupac/           IUPAC name generation (25+ compound classes)
│   ├── chematic-mcp/             MCP server — 20 AI-callable tools (JSON-RPC 2.0 over stdio)
│   ├── chematic-wasm/            130+ WASM exports → npm @kent-tokyo/chematic
│   ├── chematic-py/              PyO3 Python bindings → pip install chematic
│   ├── chematic-ewald/           PME Ewald summation, B-spline interpolation
│   └── chematic/                 Umbrella crate with feature flags
├── demo/                         Interactive WASM playground (→ /playground/ on GitHub Pages)
│   ├── index.html
│   └── pkg/                      Pre-built WASM bundle (rebuilt on each release)
└── docs/                         MkDocs documentation site source
    ├── cookbook.md
    ├── getting_started/
    └── api/

Development Commands

cargo build --workspace                                                   # build all crates
cargo test --workspace --lib --quiet                                      # 2,366 lib tests
cargo test -p chematic-inchi --features native-inchi --test standard_inchi  # +16 InChI tests
cargo clippy --workspace -- -D warnings                                   # lints (zero warnings)

Citation

If you use chematic in academic or research work, please cite:

@software{chematic,
  author    = {kent-tokyo},
  title     = {chematic: A pure-Rust cheminformatics toolkit},
  url       = {https://github.com/kent-tokyo/chematic},
  version   = {0.4.30},
  year      = {2026},
}

License

Licensed under either of Apache License 2.0 or MIT License, at your option.

If chematic saves you time, a GitHub star helps others discover it.