grimace-py is a Rust-first RDKit add-on for exact rooted SMILES support enumeration, online next-token decoding, seeded sampling, and reusable prepared molecules.

Use it when you need Grimace’s supported random-writer language for a molecule, exact legal next tokens while constructing a SMILES string, or one seeded legal path with its per-step choices. Use PrepareMol(...) when you want to prepare with RDKit once and later run Grimace without touching RDKit again.

GRIMACE stands for “graph representation integrating multiple alternate chemical equivalents”, motivated by research on NMR spectroscopy with language transformers (link).

Install the distribution named grimace-py, then import grimace:

python -m pip install grimace-py

import grimace

Plain pip install grimace installs an unrelated older package.

Repository: github.com/numpde/grimace-py.

Where to start

Install and run the first enumeration/decoder examples Intro
Understand support, roots, decoder tokens, and writer parity Concepts
See concrete RDKit parity examples Parity examples
Choose supported flags and root behavior Runtime
Check runtime limits and supported release assets Limitations
Understand pinned RDKit parity gaps Known gaps
Use prepared molecules, deviation diagnostics, or token inventories Guides
Compare measured benchmark snapshots Timings
Look up signatures and return objects API
Inspect checked-in RDKit evidence and counts Testing fixtures
Trace RDKit source-tree serializer coverage RDKit serializer coverage
Work on the codebase in containers Containerized development
Understand the Rust/Python implementation boundary Rust-first architecture

License

grimace-py is source-available under the PolyForm Noncommercial 1.0.0. Commercial use is not permitted under the current license.