🧪 ChemReporter

📚 Full documentation: https://instadeepai.github.io/chemreporter

👀 Overview

ChemReporter is a framework that converts molecular and materials datasets into a unified, queryable representation, and exports the result directly into training data for Machine Learning Interatomic Potentials (MLIPs).

It operates in three decoupled stages:

1. Process — parse raw source datasets into a partitioned Apache Parquet repository, the Query Database, enriched with structural, physical, and chemical metadata.
2. Query — filter and sample the Query Database via the CLI using SQL-like selection criteria, from simple physical constraints (e.g., number of atoms, force magnitude) to custom, user-defined strategies.
3. Export — stream the selected subset into an HDF5 file, ready for direct use in modern MLIP training frameworks.

ChemReporter currently supports five source datasets: OMOL25, OC20, OMAT24, OMC25, and ODAC. See Supported Source Datasets for details on each one.

ChemReporter is released under the Apache License 2.0.

📦 Installation

ChemReporter requires Python 3.11 or newer. Install the package with pip:

pip install chemreporter

This gives you the chemreporter command-line tool along with the Python library. See the Installation guide for more details, including the development install.

🚀 Quick Start

Once installed, the chemreporter CLI gives you three commands, one for each stage of the workflow. Each command is configured via a YAML configuration file, passed with the -c flag:

chemreporter process -c /path/to/process.yaml
chemreporter query -c /path/to/query.yaml
chemreporter export -c /path/to/export.yaml

See the CLI guide for a full walkthrough of each command and its configuration options.

🧭 Next Steps

The full documentation covers everything in more depth, including:

• CLI guide — a detailed walkthrough of the process, query, and export commands, plus how to write custom I/O plugins for other storage backends.
• Configuration reference — every field of the process, query, and export YAML configs, backed by their Pydantic schemas.
• Query examples — common SQL-like filtering patterns, from basic property filters to drug-likeness heuristics.
• Query Database schema and Units and physical quantities — every field you can query on, and the units it is stored in.
• Export schema — the internal layout of the exported HDF5 files, and how they plug into the [mlip](https://github.com/instadeepai/mlip) training library.
• Supported source datasets — details and a computational setup comparison for each supported source dataset.

📚 Citing our work

We kindly request that you cite our white paper when using this library:

Marie Bluntzer, Jules Tilly, Christoph Brunken, ChemReporter: A Framework for Curating and Exporting Large-Scale Chemical Datasets for MLIP Training, arXiv, 2026, arXiv:2608.16418

BibTeX

@misc{bluntzer2026chemreporterframeworkcuratingexporting,
  title={ChemReporter: A Framework for Curating and Exporting Large-Scale Chemical Datasets for MLIP Training},
  author={Marie Bluntzer and Jules Tilly and Christoph Brunken},
  year={2026},
  eprint={2608.16418},
  archivePrefix={arXiv},
  primaryClass={physics.chem-ph},
  url={https://arxiv.org/abs/2608.16418},
}