Use project README as model card

README.md

@@ -1,113 +1,106 @@
----
-license: cc-by-nc-4.0
-datasets:
-  - the-matter-lab/clari-data
-tags:
-  - chemistry
-  - materials-science
-  - crystal-structure-prediction
-  - organic-crystals
-  - diffusion-model
-  - flow-matching
-  - pytorch
-library_name: clari
----
-
-# CLARI
+<div align="center">
 
-CLARI predicts organic crystal structures from molecular inputs. The models in this repository are checkpoints for the paper **Fast Organic Crystal Structure Prediction with Unit Cell Flow Matching**.
+# Fast Organic Crystal Structure Prediction <br> with Unit Cell Flow Matching
 
-This repository contains model weights only. Dataset split metadata is kept separately in [`the-matter-lab/clari-data`](https://huggingface.co/datasets/the-matter-lab/clari-data), and the source code is expected at [`aspuru-guzik-group/clari`](https://github.com/aspuru-guzik-group/clari).
+[![arXiv](https://img.shields.io/badge/arXiv-XXXX.YYYYY-b31b1b.svg)](https://arxiv.org)
+[![data](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Data-blue)](https://huggingface.co/datasets/the-matter-lab/clari-data)
 
-## Model Variants
+<br>
 
-| Model name | File | Parameters | CLI alias |
-| --- | --- | ---: | --- |
-| CLARI-M | `clari-med.ckpt` | ~88M | `clari-m` |
-| CLARI-L | `clari-large.ckpt` | ~173M | `clari-l` |
+<img src="https://raw.githubusercontent.com/aspuru-guzik-group/clari/main/data/overview.png" width=600>
 
-Both checkpoints are PyTorch Lightning checkpoints loaded by the `clari` Python package.
+</div>
 
-## Intended Use
+<br>
 
-CLARI is intended for research on organic crystal structure prediction. Given a molecule specification, it samples candidate crystal packings including unit-cell and atomic-position information.
+This repository contains code to reproduce the paper: Fast Organic Crystal Structure Prediction with Unit Cell Flow Matching (arXiv).
 
-Example use cases:
-
-- sampling candidate crystal structures for an organic molecule
-- reproducing CLARI evaluation runs on the paper test splits
-- ranking/exporting generated crystal candidates with the CLARI tooling
+---
 
-## Usage
+## Installation
 
-Install CLARI, then run inference with one of the Hub aliases:
+Install everything needed for training, sampling, ranking, and most of the evaluation pipeline:
 
 ```bash
-uv run sample \
-  --from_hub clari-m \
-  --output_dir out/ethanol \
-  --smiles 'C([H])([H])([H])C([H])([H])O[H]' \
-  --ids ethanol \
-  --copies 4 \
-  --n_samples 20
+uv sync
 ```
 
-For the larger checkpoint:
+⚠️ To generate data and run COMPACK, we require the **CCDC SDK**, whose dependencies conflict with FairChem. Thus, some scripts run as standalone uv scripts that resolve their own isolated environments from the CCDC index. The first invocation of `uv run -s *.py ...` resolves and caches that environment. You will still need a valid CCDC license configured on the machine.
 
-```bash
-uv run sample --from_hub clari-l ...
+## Data
+
+### Generation
+
+We expect the final data folder to be structured as follows:
+
+```
+data/
+    raw/
+        csd_metadata.parquet
+        csd_conquest.parquet
+    csd/
+        config.json
+        metdata.parquet
+        {train,val,test}.pt
 ```
 
-To reproduce evaluation sampling on the CSD-derived test subsets:
+To generate the data, first extract the metadata of entries in CSD:
 
-```bash
-uv run sample-test clari-m <num_samples> <experiment_dir> --subset teaching
-uv run sample-test clari-l <num_samples> <experiment_dir> --subset oxtal
+```
+uv run -s scripts/data/0_metadata.py
 ```
 
-The first call downloads the selected checkpoint into the local Hugging Face cache. Subsequent calls reuse the cached file.
+This creates the `csd_metadata.parquet` file from above. Next, download **ALL** of CSD in `.mol2` and `.cif` format using ConQuest (not `csd-python-api` since it sanitizes molecules and removes some bond information) into the `csd_conquest.parquet` file. Finally, generate the `data/csd` folder with:
 
-## Inputs and Outputs
+```
+uv run python -m scripts.data.1_process --num_workers=16
+```
 
-Inputs are explicit-hydrogen SMILES strings or multi-component molecule specifications accepted by the CLARI package.
+For reference, the CSD refcodes we use and our dataset split are uploaded to [HuggingFace](https://huggingface.co/datasets/the-matter-lab/clari-data).
 
-Outputs are sampled crystal candidates written as parquet rows containing sample IDs and CIF strings. The CLARI package can also export CIF files from generated predictions.
+## Usage
 
-## Training Data
+The model can be trained with:
 
-The model was trained/evaluated using CSD-derived organic crystal data. The public split/refcode metadata is hosted in [`the-matter-lab/clari-data`](https://huggingface.co/datasets/the-matter-lab/clari-data).
+```
+uv run train --help
+```
+
+Checkpoints for Clari-M and Clari-L are uploaded to [HuggingFace](https://huggingface.co/the-matter-lab/clari).
+To run inference, see the [README.md](https://github.com/aspuru-guzik-group/clari/blob/main/clari/inference/README.md) in `clari.inference`.
+We also include a [SKILL.md](https://github.com/aspuru-guzik-group/clari/blob/main/clari/inference/SKILL.md) so that coding agents can run inference.
 
 ## Evaluation
 
-Evaluation scripts in the CLARI repository support:
+### OXtal and Teaching Test Sets
 
-- sampling on OXtal and teaching test subsets
-- collision checks
-- UMA energy computation
-- COMPACK packing similarity
-- summary metrics used in the paper
+To reproduce the paper numbers for a Hub model or local checkpoint, run the stages below in order. Each stage writes into the same `<experiment_dir>` and reads what the previous stage produced.
 
-Paper benchmark values should be reported in the repository README or paper release when finalized.
+```bash
+# 0. One-time: build the GT CIF cache the standalone compack script reads
+uv run python clari/evaluation/build_test_cifs_cache.py
 
-## Limitations
+# 1. Sample the CSD test set, creates a folder results/experiment_dir.
+#    Use clari-m, clari-l, or a local checkpoint path as the first argument.
+uv run sample-test clari-m <num_samples> <experiment_dir> --subset <teaching/oxtal>
 
-- CLARI is a research model for organic crystal structure prediction, not a replacement for experimental validation.
-- Generated candidates may be physically implausible, may contain clashes, or may require downstream ranking/filtering.
-- Results depend on copy count, molecule representation, checkpoint choice, and sampling settings.
-- The Hub checkpoints are distributed as PyTorch Lightning checkpoint files rather than `safetensors` because they include CLARI-specific training/module state.
+# 2. Clash check (writes collision.csv)
+uv run collision <experiment_dir>
 
-## License
+# 3. UMA energies (writes energies.csv)
+uv run compute-energies <experiment_dir>
 
-The model weights are released under the Creative Commons Attribution-NonCommercial 4.0 International license (`cc-by-nc-4.0`).
+# 4. COMPACK packing similarity (writes compack.csv, isolated uv script env)
+uv run -s clari/evaluation/compack.py <experiment_dir> --num_processes n
 
-## Citation
+# 5. Summary table (SolC per subset, all k)
+uv run summarize <experiment_dir>
+```
 
-If you use CLARI, cite the associated paper once the arXiv entry is available:
+### Ablations
 
-```bibtex
-@article{clari2026,
-  title = {Fast Organic Crystal Structure Prediction with Unit Cell Flow Matching},
-  author = {Lo, Alston and Mucko, Luka and Cheng, Austin and others},
-  year = {2026},
-}
+The exact commands used for to train our ablated and final models can be found in `scripts/train`. After running inference as above, the metrics used for ablations are defined in:
+
+```
+from clari.pipelines.utils.metrics import assess_crystals_eval
 ```