grimace-py

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. 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
• seeded legal samples with per-step token choices
• prepared molecule bytes for reuse without RDKit at read time

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 Runtime for flags and roots, and 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(...).
• Draw one seeded legal string with per-step token choices using MolToSmilesSample(...).
• 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

Package metadata declares Python >=3.11 and rdkit>=2026.3. See Runtime for the exercised wheel and source-distribution matrix.

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 test-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.