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 504 KB · RDKit.js ~30 MB · Indigo WASM ~40 MB

When to use chematic

Use chematic if:

• You want chemistry in the browser (WASM, 504 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: 5–14× faster than RDKit)
• 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 70+ 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 (for LLM / MCP agents)
print(mol.describe())
# → "Molecular weight 180.2 Da, formula C9H8O4. LogP 1.31 (mildly lipophilic)..."

# 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.

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 3.6 µs/mol — 5–14× faster than RDKit's Python API on the same hardware. No GIL, no interpreter overhead, no FFI call overhead hidden inside a _sys crate.

Safe

The entire default dependency tree contains ~6 unsafe blocks across 15,000+ lines of Rust. 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.

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 crates stay FFI-free.

Anywhere

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

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). All other crates remain FFI-free.

JavaScript / TypeScript (WebAssembly)

504 KB gzip — 60× 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                                          # 211 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.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 5 000-mol 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 5 000-mol corpus; TPSA 86.7% → 93.3% (5 000-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

v0.4.13 (2026-06-21): Template retrosynthesis + descriptor fixes

• chematic-rxn: retro_disconnect() — 60 retro-SMIRKS templates (AmideBond / Ester / Ether / CNBond / CCBond / CSBond) with SA Score ranking; Python mol.retro_disconnect(reaction_class=...)
• chematic-3d: ETKDG torsion KB 28 → 40 patterns; adaptive bond-flexibility noise scaling
• chematic-chem: hbd_count() now includes S-H (thiol); TPSA nitro-N / aromatic oxide bridge / Kekulé-N corrections

v0.4.9–v0.4.12 (2026-06-19–21): AutoDock, UFF, SMARTS atom-map, ring augmentation

• chematic-mol: AutoDock PDBQT parse/write; write_sdf_with_charges
• chematic-ff: UFF force field for metals/organometallics (Zn, Fe, Cu, …)
• chematic-smarts: atom map :N in SMARTS ([O;D1;H0:3] — stored as metadata)
• chematic-perception: iterative augmented_ring_set for fused polycyclic aromatic ring counting (222/222 bench5k fixes)
• MCP: 15th tool name_to_smiles via PubChem REST proxy

v0.4.5–v0.4.7 (2026-06-19): Kekulization blossom + BOILED-Egg + InChI E/Z

• Edmonds' blossom algorithm for non-bipartite aromatic graphs (128→2 failures)
• InChI /b E/Z layer, 6 new MCP tools, BOILED-Egg descriptor + Python/WASM bindings

v0.4.0–v0.4.4 (2026-06-17–18): PyO3 Python bindings + native-inchi

• chematic-py: PyO3/maturin bindings — from_smiles(), Mol.aromatic_ring_count, Mol.descriptors()
• native-inchi feature: IUPAC-exact InChI via vendored C lib v1.07.5
• HBA rewrite: 99.98% agreement with RDKit (5,000 molecule benchmark)

Full changelog: CHANGELOG.md

Known Limitations

• Kekulization: 2 of 5,000 tested molecules fail — a boron aromatic ring (b1ccccn1) and bare [H][H]. KekuleError is returned explicitly; no silent wrong output is produced.
• 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 5,000-molecule corpus: HBA/HBD/aromatic ring count 100%; TPSA 93.3% (±0.1 Ų).

Repository Structure

chematic/
├── Cargo.toml                    workspace root (v0.4.19)
├── 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/            70+ 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 — 15 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                                      # 211 lib tests
cargo test -p chematic-inchi --features native-inchi --test standard_inchi  # +16 InChI tests
cargo clippy --workspace -- -D warnings                                   # lints (zero warnings)

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.