omgkit

中文说明

What is it?

omgkit is a cheminformatics toolkit written in Rust, with Python bindings. It is built around a columnar molecule representation so that large batches stay cheap to traverse, split across threads, and hand off to numpy or Arrow without a copy.

• BSD-3-Clause license
• Core data structures and algorithms in Rust, no unsafe
• Python 3.9+ wrapper built with PyO3 and maturin — one abi3 wheel covers every supported version, and there are no system dependencies
• SMILES parsing and writing, including tetrahedral chirality, double-bond geometry, dative bonds and explicit hydrogens
• Canonical SMILES
• A sanitization pipeline: valence, implicit hydrogens, ring perception, kekulization, aromaticity, conjugation, hybridization
• SMARTS parsing, substructure matching (VF2++, optionally stereo-aware), and SMARTS writing for both molecules and reactions
• Reaction templates and product generation, with optional atom-atom mapping
• Reconstruction of the fragments a template discards (the water an esterification drops) into balanced byproduct molecules — or an explicit "cannot tell" when the record itself does not balance
• Columnar batches (MolBatch) with zero-copy per-molecule views

Status: under development. The API still changes between commits. Every layer is checked against an external reference implementation record by record (see Documentation), but the surface is not yet stable enough for production use. Bug reports are welcome.

Installation

Python

Requires maturin:

$ maturin build --release -m crates/omgkit-py/Cargo.toml --out dist
$ pip install dist/omgkit-*.whl

Rust

[dependencies]
omgkit-core  = "0.0.1"   # data structures
omgkit-io    = "0.0.1"   # SMILES / SMARTS
omgkit-chem  = "0.0.1"   # sanitization
omgkit-match = "0.0.1"   # matching, reactions

Take only the layers you need; each depends only on the ones below it.

Getting started

import omgkit

m = omgkit.parse_smiles("OC(=O)c1ccccc1N")
m.sanitize()
m.to_canonical_smiles()

q = omgkit.parse_smarts("[C](=[O])[OH]")
q.match(m)                      # molecule atom indices, in query atom order

rxn = omgkit.parse_reaction("[C:1][OH:2]>>[C:1][Cl:2]")
for outcome in rxn.run([m], atom_mapping=True):
    outcome.products, outcome.reactants

The Rust equivalents live in omgkit_io::smiles, omgkit_chem::sanitize and omgkit_match; see the crate documentation for runnable examples.

Documentation

• docs/design.md — what each layer does, why it is built that way, and how each design choice was validated
• harness/README.md — the differential-testing setup: how the oracles are generated and how a test is kept from passing vacuously
• cargo doc --workspace --no-deps --open — API documentation

Contributing

Issues and pull requests are welcome. Five gates have to pass, and they are the same five that CI runs:

$ cargo fmt --all --check
$ cargo clippy --workspace --all-targets -- -D warnings
$ cargo test --release
$ cargo test --workspace
$ cargo doc --workspace --no-deps --document-private-items

cargo test is green on a fresh clone: the smoke oracles are committed. The large-corpus tier is marked #[ignore] and needs oracles you generate yourself — see harness/README.md.

License

Code released under the BSD-3-Clause license.

Test corpora and the element table are redistributed from other projects and carry their own terms; each file is traced to its origin in THIRD-PARTY-NOTICES.md.