grimace-py

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

• exact support enumeration for Grimace's supported writer language
• exact token inventories implied by that support
• legal next-token choices from a current SMILES prefix
• prepared molecule bytes for reuse outside RDKit

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

The public import name is grimace. Install the PyPI distribution named grimace-py:

python -m pip install grimace-py

import grimace

Plain pip install grimace installs an unrelated older package.

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

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

Quick example

This example uses the currently supported runtime mode. See Limitations for scope and known gaps.

from rdkit import Chem
import grimace

mol = Chem.MolFromSmiles("CC(=O)Oc1ccccc1C(=O)O")

all_smiles = tuple(
    grimace.MolToSmilesEnum(
        mol,
        rootedAtAtom=-1,
        isomericSmiles=False,
        canonical=False,
        doRandom=True,
    )
)

assert len(all_smiles) == 304

What to use

• Enumerate every supported string with MolToSmilesEnum(...).
• Step through legal next tokens with MolToSmilesDecoder(...) or MolToSmilesDeterminizedDecoder(...).
• Diagnose rejected candidates with MolToSmilesDeviation(...).
• Build dataset token coverage with MolToSmilesTokenInventorySuperset(...).
• Reuse prepared molecules with PrepareMol(...) and PreparedMol.

Documentation

Please find the main documentation at numpde.github.io/grimace-py.

Install matrix

Package metadata declares Python >=3.11 and rdkit>=2026.3.

The currently exercised release matrix publishes Linux x86_64 wheels for CPython 3.12 and 3.13, plus a source distribution. Other Python versions and non-Linux platforms are expected source-build paths today.

For a host source build, you need Rust >=1.83 and maturin:

python -m venv .venv
. .venv/bin/activate
python -m pip install maturin
maturin develop --release

Development

Routine local checks are Docker-backed:

make checks
make ci
make package
make docs
make docs-serve

See containerized development for the lane contract.

License

grimace-py is source-available under PolyForm Noncommercial 1.0.0. Third-party components remain under their own licenses; see THIRD_PARTY_NOTICES.md. Commercial use requires a separate commercial license from the author.