Metadata-Version: 2.4
Name: omgkit
Version: 0.0.1
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Chemistry
License-File: LICENSE
Summary: Cheminformatics toolkit in Rust with Python bindings
Keywords: chemistry,cheminformatics,smiles,smarts,molecule
Home-Page: https://zbc0315.github.io/omgkit/
Author: zbc0315
License-Expression: BSD-3-Clause
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Repository, https://github.com/zbc0315/omgkit

# omgkit

[![CI](https://github.com/zbc0315/omgkit/actions/workflows/ci.yml/badge.svg)](https://github.com/zbc0315/omgkit/actions/workflows/ci.yml)

[中文说明](README.zh-CN.md)

## 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](LICENSE)
  * Core data structures and algorithms in Rust, no `unsafe`
  * Python 3.9+ wrapper built with [PyO3](https://pyo3.rs) and
    [maturin](https://github.com/PyO3/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](#documentation)), but the surface is not yet stable enough
for production use. Bug reports are welcome.

## Installation

### Python

Requires [maturin](https://github.com/PyO3/maturin):

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

### Rust

```toml
[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

```python
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`](docs/design.md) — what each layer does, why it is built
    that way, and how each design choice was validated
  * [`harness/README.md`](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:

```shell-session
$ 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`](harness/README.md).

## License

Code released under the [BSD-3-Clause license](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`](THIRD-PARTY-NOTICES.md).

