chematic

Open in Colab

日本語 | 中文

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](https://github.com/kent-tokyo/chematic/blob/main/=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.16.0
# Python 3.12.x  |  darwin arm64
#
# Descriptor accuracy (benchmark 2026-07-17, v0.4.29 vs RDKit 2026.03.3 --
# descriptor calculation paths unchanged through v0.8.0, not re-measured since):
#   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" }
  }
}

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 and docs/mcp/2026-07-28-implementation-rfc.md. 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. 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 ~149,000 lines of Rust (tokei-measured code lines, all 18 crates, 2026-08-02) contain zero unsafe blocks outside one file: 9 unsafe {} blocks plus 1 unsafe extern "C" FFI declaration, all in the optional native-inchi 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/rfcs/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

§ RDKit itself has no built-in MolFromMMCIF/mmCIF writer; mmCIF interop is done via separate third-party tooling (e.g. PDBe CCDUtils) layered on top of RDKit, not RDKit's own I/O surface.

† 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 ~149,000 lines of Rust (tokei-measured): unsafe-free outside native-inchi's 9 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 (incl. retro_disconnect_json — single-step retrosynthetic disconnection), diversity picking, and SDF round-trips. See the full WASM API reference for all exports.

Crate Reference

cargo test --workspace --lib --quiet                                          # 3,235 tests, all passing (2026-08-02)
cargo test -p chematic-inchi --features native-inchi --test standard_inchi  # +16 IUPAC-exact InChI tests

Recent Development

v0.16.0 (2026-08-15): Periodic-structure interoperability (CIF/POSCAR/FPS) and generalized stereochemistry foundation

• chematic-mol: new optional crystal feature bridges the existing CIF reader/writer to chematic_crystal::PeriodicStructure (parse_cif_periodic_structure/write_cif_periodic_structure) — cell parameters to Lattice, _atom_site_occupancy to Occupancy, disorder-sharing atom-site rows merged into one PeriodicSite's multi-species list. New CifSymmetryStatus enum distinguishes genuinely-P1 CIFs from CIFs that declared symmetry this parser doesn't expand, rather than silently treating the latter as P1. chematic-crystal itself remains independent of chematic-mol/Molecule (dependency direction is one-way: chematic-mol → chematic-crystal, optional)
• chematic-crystal: native POSCAR/CONTCAR (VASP structure format) read/write — parse_poscar/parse_contcar/write_poscar, VASP 5 only, both scale-factor conventions, Direct/Cartesian coordinates, selective dynamics, ion velocities, and CONTCAR's predictor-corrector MD-restart section preserved verbatim (VASP's own docs don't specify its numeric layout)
• chematic-fp: new fps module — streaming read/write for the FPS ("Fingerprint file format") text-based interchange format popularized by chemfp/OpenBabel, hex bit-ordering verified against the chemfp spec, reuses BitVec2048/BitVecN as the sole bit-vector representation
• chematic-core: new stereo_geometry module — stereo configuration modeled as a coordination geometry (Tetrahedral/SquarePlanar, #[non_exhaustive] for future TBP/octahedral) plus the equivalence class of ligand-slot permutations under that geometry's proper rotation group (A4, order 12, for tetrahedral; the order-8 S4-stabilizer of a trans-pair partition, not the naive order-4 in-plane-only group, for square-planar). Replaces two independent hand-written stereo-remapping algorithms in chematic-smiles; @/@@/@SP1/@SP2/@SP3 semantics fully preserved (88-fixture byte-identical canonical-SMILES regression). Fixed a real bug found along the way: a square-planar-tagged atom in chematic-3d could be silently coerced into a tetrahedral chiral-volume check decided by floating-point noise; also fixed a transient allene-end-carbon parity regression surfaced during development, pinned by an exact golden-value test. See docs/rfcs/generalized_stereo_geometry_rfc.md
• Release-grade re-measurement of the pipeline_v2 vs RDKit 2026.03.4 benchmark (superseding stale 2026-08-06 numbers): mmff94_strict 149/265 → 239/265. New finding: torsion parameter coverage, not bond/angle, is now the dominant remaining MMFF94 gap (71% of complete_bonded_term_gated failures cite missing torsion parameters, 0% OOP, 0% bonds) — direct evidence for the project's next MMFF94 roadmap item
• Full details in CHANGELOG.md's [0.16.0] section

v0.15.0 (2026-08-14): chematic-crystal — periodic (crystal) structure foundation crate, MMFF94 Bond/Angle empirical-rule fallback (issue #227)

• New crate chematic-crystal: periodic (crystal) structure representation and geometry — Lattice (triclinic-capable, validated matrix/inverse/reciprocal vectors), FractionalCoord/CartesianCoord, PeriodicSite/SiteSpecies/Occupancy (multi-species disorder-ready), and PeriodicStructure with exact (not round()-approximate) periodic minimum-image distance — equidistant periodic images resolve deterministically to the lexicographically smallest image — cutoff neighbor enumeration, and diagonal supercells. Deliberately not an extension of chematic_core::Molecule (a bond graph); see docs/rfcs/chematic_crystal_foundation.md. Optional serde feature; optional crystal feature on the chematic facade, included in full (does not change default, which stays empty). No symmetry, no CIF parser changes, no Python/WASM/MCP bindings yet
• chematic-ff: ported Halgren's MMFF.V eq. 18-20 empirical Bond-stretch/Angle-bend rule (mmff94_bond_energy_resolved/mmff94_angle_energy_resolved, new additive functions — the existing mmff94_bond_energy/mmff94_angle_energy keep their original signatures), tried strictly after the existing exact-table/eqLevel-ladder lookup so it never overrides a real table hit. Along the way, found and fixed a real data gap: 97 rows present in RDKit's real Angle table (generic central-atom-type-only theta0 defaults) were missing from chematic's port. One triple is deliberately left unresolved (fails closed) rather than guessed — the outer atom type has no equivalence-class entry and RDKit's own real code dereferences that unchecked (undefined behavior), so its live-oracle answer couldn't be attributed to any well-defined mechanism. Also fixed 5 pre-existing MMFF94 atom-typing gaps and ported RDKit's eqLevel atom-type-equivalence ladder for Angle lookup. Net effect on the 265-molecule Wave 1 corpus (production minimization path), reported as two separately-verified numbers (both via a full per-molecule join, zero regressions either way): full v0.14.1→v0.15.0 change 158/265 → 248/265 (107 → 17 failing); the empirical-rule work specifically (isolated from the atom-typing/eqLevel prerequisites merged earlier in this same release) 178/265 → 248/265 (87 → 17 failing). The 3 molecules still MinimizationFailed in the final state were already non-Ok in v0.14.1 — a pre-existing geometry issue newly exposed once real parameters became available, not a regression
• Full details in CHANGELOG.md's [0.15.0] section

v0.14.1 (2026-08-12): Anticancer platinum coordination-chemistry compatibility fixes, Extended XYZ (extxyz) read/write

• chematic-core: valence_inferred_hcount treated a BondOrder::Dative bond's donor side exactly like a covalent single bond when computing implicit hydrogen count — an un-bracketed dative donor like N->[Pt]Cl computed as NH2 instead of the chemically correct NH3. Donor-side dative bonds now contribute 0 to the valence sum; found via a platinum coordination-chemistry benchmark but general (verified against Fe/Co/Pd/Ru acceptors too), not platinum-specific
• chematic-mol: MDL bond type 9 (dative/coordinate — RDKit's own V3000 convention for Bond::BondType.DATIVE) silently mapped to BondOrder::Single in both V2000 and V3000 readers, quietly discarding coordination-bond semantics on read. Both readers now map code 9 to BondOrder::Dative; V3000's writer now emits code 9 instead of collapsing to plain single
• chematic-chem: `avg_m