chematic

Open in Colab

日本語 | 中文

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

Cheminformatics that's fast by default, safe by design.
Pure Rust by default · optional native InChI C FFI · Python · WebAssembly · Website · Live Demo

* RDKit.js gzip-over-the-wire size was not independently measured; raw figures are compared on a like-for-like basis. RDKit.js is currently in a maintainer transition (see its repo for current status).

The canonical and SDF rows are scoped 2026-09-04 macOS arm64 medians, not cross-platform claims; see the exact corpora and operation boundaries in the benchmark details. The chematic WASM size was measured 2026-09-04 from the v1.0.2 release candidate with wasm-pack 0.13.1 + wasm-opt 130 -O3: 3.30 MB raw (1.21 MB gzip). The pinned historical comparators are RDKit.js 6.91 MB (@rdkit/rdkit@2025.3.4-1.0.0's RDKit_minimal.wasm, via unpkg.com) · Indigo (Ketcher build) 11.24 MB (indigo-ketcher@1.45.1's main .wasm, via jsDelivr) — chematic's raw WASM binary is currently about 2.1× smaller than RDKit.js's and about 3.8× smaller than Indigo's Ketcher-oriented build, on a raw-to-raw basis. See the artifact record.

The separate 2026-08-23 benchmark rebuild reports 2.98 MB raw / 1.11 MB gzip; both figures are retained with their measurement dates because build outputs can vary slightly by toolchain and build environment.

Feature maturity at a glance:

v1.0.7 release boundary

The v1.0.7 release retains the v1.0.0 bounded compatibility contract while adding typed reaction documents, document-level CDXML edits, explicit bounded Markush/polymer expansion, crystal composition summaries, safer UFF rescue, and canonical/SDF hot-path improvements. Spectrophores is intentionally removed from the Rust and Python APIs while its patent/FTO status remains independently uncleared. The complete compatibility contract and reproducible local release gate are in docs/compatibility-scope.md and docs/v1.0-local-release-gate.md. The algorithm and third-party provenance boundary is recorded in docs/implementation-provenance.md.

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, 1.21 MB gzip, no server required)
• You need a pure Rust stack with no C++ toolchain dependencies
• You deploy to environments where installing RDKit is impractical or unsupported (Cloudflare Workers, Lambda, embedded — RDKit itself ships official pip install rdkit wheels, but those still assume a standard CPython environment)
• 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

Choose your interface

• Rust
• Python
• WebAssembly / Node.js
• Materials and simulation formats — mmCIF, PQR, QCSchema, ORCA, Gaussian Cube, OpenDX, LAMMPS
• Migrating from RDKit — feature-by-feature Supported/Partial/Not-supported breakdown
• Compatibility scope — v1.0 boundary for RWMol, CDXML, polymer expansion, and RDKit/Morgan compatibility

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 migration guide for the compatibility matrix, differential-validation results vs RDKit, and runnable examples.

Diagnostics

import chematic
chematic.doctor()
# chematic v1.0.7
# Python 3.12.x  |  darwin arm64
#
# Descriptor accuracy (benchmark 2026-08-23, v0.18.0 vs RDKit 2026.03.4):
#   MW                    99.82% within ±0.01 Da
#   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/E/Z labels    99.64% stable-oracle agreement (15 P rows fail closed)
# ...

For AI / LLM Developers

chematic ships a native MCP (Model Context Protocol) server for local AI agent integration.

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

20 chemistry tools are callable from any MCP-compatible agent (full list in the chematic-mcp README):

Transport: stdio (JSON-RPC 2.0 over stdin/stdout) only. Runs as a local process; there is no hosted Remote MCP endpoint, no authentication, and no public service SLA — a remote-ready refactor is under consideration but not implemented.

Protocol: speaks both the legacy (2024-11-05-style initialize handshake) and the modern MCP 2026-07-28 stateless dialect (server/discover, per-request _meta, cacheable tools/list, structuredContent) on the same stdio connection — see the chematic-mcp README for the protocol details. Remote HTTP, OAuth, the Tasks extension, and MCP Apps remain unsupported.

Why Pure Rust?

Fast

Rust's zero-cost abstractions and ownership model eliminate overhead at the source. The recorded v0.18.0 ECFP4 batch median is 54.7 µs/mol versus RDKit's 94.3 µs/mol on the same 5,000-molecule corpus and Apple M4 environment. This is a dated, corpus-specific result; current claims and reproduction details are kept in the benchmark guide.

Safe

The common chemistry core is safe Rust and public untrusted-input paths use finite defaults and typed failures. The optional native-inchi feature vendors the IUPAC InChI C library and is the documented FFI exception. Dependencies may contain their own unsafe code; see the security policy and unsafe- surface gate for the exact boundary.

Anywhere

Pure Rust compiles to wasm32-unknown-unknown natively — no Emscripten, no cmake, no clang. The npm package @kent-tokyo/chematic is 1.21 MB gzip (3.30 MB raw) — roughly 2.1× smaller than RDKit.js's RDKit_minimal.wasm (6.91 MB raw) on a like-for-like raw-size basis. One codebase targets Linux, macOS, Windows, and browser WASM; Chromium, Firefox, and WebKit are covered by the browser CI lane.

Benchmarks & Validation

These are dated, operation-specific measurements rather than universal performance or parity claims. See the benchmark guide, validation report, and dated records for versions, corpus hashes, hardware, tolerances, and commands.

Comparison with Other Cheminformatics Libraries

See the format capability matrix and the RDKit migration guide for detailed support differences. The table above is intentionally limited to deployment-level differences; detailed feature claims belong in those maintained pages.

JavaScript / TypeScript (WebAssembly)

1.21 MB gzip — roughly 2.1× smaller than RDKit.js's raw WASM. 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));

The WASM binding exposes selected descriptors, fingerprints, 2D/3D operations, reactions, diversity picking, and molecular-format conversions. See the WASM README and generated documentation for the current export surface.

Crate Reference

See format capabilities, language bindings, and the individual crate READMEs for supported operations and limitations.

Recent Development

Unreleased: closed the remaining #210 legacy UFF stereo-rescue cases and continued canonical SMILES and SDF hot-path work. The fixed-version measurements are recorded in benchmarks.

v1.0.7 (2026-09-05): carries forward the v1.0.6 descriptor provenance, shared cross-binding contracts, fused/non-alternant aromaticity and held-out CIP boundaries, and records the #149/#337 residuals as fail-closed or diagnostic-only contracts. It also adds the measured canonical/SDF hot-path improvements documented in the v1.0.7 benchmark record. Spectrophores remains excluded pending independent patent/FTO review.

For public release summaries, see the changelog; detailed development notes are retained in its linked archive.

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 a representation, not a cache or deduplication key. Use the fail-closed canonical_smiles_stable_key() and handle None; coupled E/Z systems using aromatic direction stashes are intentionally rejected until their spelling stability is proven.
• Aromaticity and CIP have explicit default and opt-in models; the default Hückel path has a bounded all-carbon odd/odd fused-envelope fallback, while other fused/non-alternant rings and symmetric cages are not claimed as universal RDKit parity. Accurate phosphorus CIP is fail-closed when the oracle is representation-unstable.
• 3D generation and MMFF94 are Experimental. Successful output is sanity-checked but does not promise ETKDGv3 quality or complete force-field coverage.
• Python RWMol, CDXML editing, and Markush/polymer expansion intentionally expose bounded subsets, not complete RDKit or ChemDraw compatibility.
• Pure-Rust InChI is approximate; enable native-inchi for standard IUPAC InChI.

See compatibility scope, validation, and error and resource limits for the precise contracts.

Repository Structure

chematic/
├── Cargo.toml                    workspace root (v1.0.7)
├── 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 JSON-RPC server over stdio
│   ├── chematic-wasm/            WASM/Node bindings → npm @kent-tokyo/chematic
│   ├── chematic-py/              PyO3 Python bindings → pip install chematic
│   ├── chematic-ewald/           PME Ewald summation, B-spline interpolation
│   ├── chematic-crystal/         Periodic crystal structures: lattice, PBC, neighbors, supercells, POSCAR/CONTCAR I/O (not Molecule)
│   └── 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 --all-targets --locked
cargo test -p chematic-inchi --features native-inchi --test standard_inchi
cargo clippy --workspace --all-targets --locked -- -D warnings

Citation

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

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

License

Licensed under either of Apache License 2.0 or MIT License, at your option. Copyright attribution: Kentaro Tanabe (kent-tokyo). See NOTICE for the redistribution attribution notice.

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