ChRIMP

This repo is linked with the ChRIMP and MechSMILES paper released by the SchwallerGroup (More info below)

Installation

The requirements needed to run the code in this repository smoothly is mentioned in requirements.txt. We highly recommend to create a new environment to avoid any unexpected behavior:

conda create -n chrimp python=3.12
conda activate chrimp

The dependencies can be easily installed with:

pip install -r requirements.txt

Models

Models trained during this work can be found as follows:

agent.load_model(
    tokenizer_path="SchwallerGroup/MechSMILES_tokenizer",
    model_path="SchwallerGroup/chrimp_<architecture>_<task>_<dataset><variant>",
)

Available model configurations:

Component	Options	Description
Architecture	T5, LLaMa	Model architecture
Task	min_min_1 equ_equ_n equ_min_n spe_min_n	Elementary steps Equilibrated Rxn w/o by-prod. Rxn w/o stoichio.
Dataset	flower, mech-uspto-31k, pmechdb	Training dataset
Variant	(optional)	Can be left empty, additional details

All available models

Example:

# Load a T5 model trained on reactions without by-products with the FlowER dataset
agent.load_model(
    tokenizer_path="SchwallerGroup/MechSMILES_tokenizer",
    model_path="SchwallerGroup/chrimp_T5_equ_min_n_flower",
)

Notebooks

The notebooks of this repository are stored as .py files in the notebooks directory, and can be directly run as Python scripts. However, they are "inflatable" to traditional .ipynb using jupytext. To convert them, you can run the following command:

jupytext --to notebook notebooks/<notebook_py_path>

If you happen to do changes to these notebooks in .ipynb format, you can convert them back to .py with the inverse command:

jupytext --set-formats ipynb,py:percent notebooks/<notebook_ipynb_path>

Article

Teaching Language Models Mechanistic Explainability Through Arrow-Pushing (ArXiv | PDF)

Citation:

@article{neukomm2025teaching,
  title={Teaching Language Models Mechanistic Explainability Through Arrow-Pushing},
  author={Neukomm, Th{\'e}o A and Jon{\v{c}}ev, Zlatko and Schwaller, Philippe},
  journal={arXiv preprint arXiv:2512.05722},
  year={2025}
}

Acknowledgements

This project has been set up using PyScaffold 4.6. For details and usage information on PyScaffold see https://pyscaffold.org/.