MoRACE

Source-locked compilation of small-model molecular rules into executable features.

Small language models can propose plausible molecular rules, but rule text alone is not an executable feature. MoRACE treats these rules as drafts, compiles supported operations into RDKit-backed features, and preserves the validation records needed to trace each feature to its source.

Method | Quick Start | Run Experiments | Citation

Method

Figure 2 from the accompanying manuscript.

• Constrained compilation. Map supported descriptor, count and substructure rules to executable features without running model-written Python.
• Explicit validation. Check feature execution and variation across molecules. The rule-validation analysis records unsupported, conflicting and task-label-only claims as rejections.
• Source-locked provenance. Link retained features to their originating rules, model routes, datasets and validation records.

The resulting features complement existing molecular representations. Paired evaluation compares Morgan fingerprints with the same fingerprints augmented by retained rule features.

Quick Start

Use Python 3.10 or 3.11. This CPU example needs no model checkpoint or GPU:

git clone https://github.com/MasterDGL/MoRACE.git
cd MoRACE
python -m pip install -e .
python scripts/verify_repository.py
python examples/compile_rules.py

The example prints a CSV feature matrix for four molecules using three hand-written rules. It demonstrates compilation only; it does not generate rules or train a predictor.

Run Experiments

Follow the paper reproduction guide to configure local checkpoints and model runtimes, generate and audit rules, then evaluate their contribution to prediction. Generation requires Linux/Bash and a compatible model runtime.

To preview the configured generation runs without loading models or launching jobs:

python scripts/run_paper_experiments.py

The generation pipeline reports rule-only predictions. The separate paired feature evaluation measures Morgan+rules against Morgan alone and count-matched controls.

All seven fixed dataset split sets are included: BACE, BBBP, ClinTox, HIV, ESOL, FreeSolv and Lipophilicity. See data documentation for endpoints and provenance. Model weights and historical experiment artifacts are not bundled; exact historical replay requires the corresponding original inputs and recorded protocol.

For programmatic use, see the Python API. For development and checks, see CONTRIBUTING.

Citation

Code reference:

@misc{morace_code_2026,
  title = {MoRACE: Molecular Rule-to-Feature Validation and Compilation
           Framework for Molecular Property Prediction},
  year = {2026},
  howpublished = {\url{https://github.com/MasterDGL/MoRACE}},
  note = {Source code}
}

Record the exact source commit and resolved protocol when using this code.

License

Source code is licensed under Apache-2.0. Dataset and model rights remain with their respective providers.