Updated README

README.md

@@ -4,54 +4,57 @@ license: cc-by-nc-4.0
 
 # Matcha: Multi-Stage Riemannian Flow Matching for Accurate and Physically Valid Molecular Docking
 
-This is a model card for the Matcha docking model introduced in the paper [Matcha: Multi-Stage Riemannian Flow Matching for Accurate and Physically Valid Molecular Docking](https://huggingface.co/papers/2510.14586).
-It can be loaded using the [Matcha repository](https://github.com/LigandPro/Matcha), where all the instructions are provided.
-You need to download the `pipeline` folder from the Files and versions tab.
+This repository hosts the Matcha pipeline checkpoints (three-stage flow matching models). The model is described in the paper [Matcha: Multi-Stage Riemannian Flow Matching for Accurate and Physically Valid Molecular Docking](https://arxiv.org/abs/2510.14586).
+
+**Code and full documentation:** [GitHub – LigandPro/Matcha](https://github.com/LigandPro/Matcha). The previous release is tagged `v1` there.
+
+Download the `matcha_pipeline` folder from the **Files and versions** tab and set `checkpoints_folder` in your paths config to the folder that contains it.
 
 ## Abstract
-Accurate prediction of protein-ligand binding poses is crucial for structure-based drug design, yet existing methods struggle to balance speed, accuracy, and physical plausibility. We introduce Matcha, a novel molecular docking pipeline that combines multi-stage flow matching with learned scoring and physical validity filtering. Our approach consists of three sequential stages applied consecutively to refine docking predictions, each implemented as a flow matching model operating on appropriate geometric spaces (R^3, SO(3), and SO(2)). We enhance the prediction quality through a dedicated scoring model and apply unsupervised physical validity filters to eliminate unrealistic poses. Compared to various approaches, Matcha demonstrates superior performance on Astex and PDBbind test sets in terms of docking success rate and physical plausibility. Moreover, our method works approximately 25 times faster than modern large-scale co-folding models.
+
+Accurate prediction of protein-ligand binding poses is crucial for structure-based drug design, yet existing methods struggle to balance speed, accuracy, and physical plausibility. We introduce Matcha, a novel molecular docking pipeline that combines multi-stage flow matching with learned scoring and physical validity filtering. Our approach consists of three sequential stages applied consecutively to refine docking predictions, each implemented as a flow matching model operating on appropriate geometric spaces (R³, SO(3), and SO(2)). We enhance the prediction quality through a dedicated scoring model and apply unsupervised physical validity filters to eliminate unrealistic poses. Compared to various approaches, Matcha demonstrates superior performance on Astex and PDBbind test sets in terms of docking success rate and physical plausibility. Moreover, our method works approximately 31× faster than modern large-scale co-folding models.
 
 ## Overview
-Matcha is a molecular docking pipeline that combines multi-stage flow matching with learned scoring and physical validity filtering. Our approach consists of three sequential stages applied consecutively to progressively refine docking predictions, each implemented as a flow matching model operating on appropriate geometric spaces (R^3, SO(3), and SO(2)).
-We enhance the prediction quality through a dedicated scoring model and apply unsupervised physical validity filters to eliminate unrealistic poses.
 
-More details can be found in the [GitHub repository](https://github.com/LigandPro/Matcha).
+Matcha is a molecular docking pipeline that combines multi-stage flow matching with learned scoring and physical validity filtering. Our approach consists of three sequential stages applied consecutively to progressively refine docking predictions, each implemented as a flow matching model operating on appropriate geometric spaces (R³, SO(3), and SO(2)). We enhance the prediction quality through a dedicated scoring model and apply unsupervised physical validity filters to eliminate unrealistic poses.
+
+More details, CLI usage, and the full pipeline (including GNINA) are in the [GitHub repository](https://github.com/LigandPro/Matcha).
 
 ![pipeline](https://github.com/LigandPro/Matcha/raw/main/data/img/matcha_pipeline.png)
 ![architecture](https://github.com/LigandPro/Matcha/raw/main/data/img/matcha_architecture.png)
 
-Compared to various approaches, Matcha demonstrates superior performance on Astex and PDBBind test sets in terms of docking success rate and physical plausibility. Moreover, our method works approximately 25× faster than modern large-scale co-folding models.
+Compared to various approaches, Matcha demonstrates superior performance on Astex, PDBBind and PoseBusters test sets in terms of docking success rate and physical plausibility. Moreover, our method works approximately 31× faster than modern large-scale co-folding models.
 
 <img src="https://github.com/LigandPro/Matcha/raw/main/data/img/time.png" alt="results" width="500"/>
 
 ## Installation
-To install the `matcha` package, do the following:
+
+Clone the [Matcha repository](https://github.com/LigandPro/Matcha) and install:
 
 ```bash
-cd matcha
-pip install -e .
+cd Matcha
+uv sync
+# or: pip install -e .
 ```
 
-## Sample Usage
-To run inference with one script, computing all preprocessing steps and docking predictions, use the following command. Provide `--compute_final_metrics` if your dataset has true ligand positions, so we can compute RMSD metrics and PoseBusters filters.
-Argument `-n inference_folder_name` is a name of a folder where to store inference results for dataset.
+Download the `matcha_pipeline` folder from this Hugging Face repo and set `checkpoints_folder` in `configs/paths/paths.yaml` to the parent folder of `matcha_pipeline`.
 
-```bash
-CUDA_VISIBLE_DEVICES=0 python scripts/full_inference.py -c configs/base.yaml -p configs/paths/paths.yaml -n inference_folder_name --n_samples 40 --compute_final_metrics
-```
-This script will provide a step-by-step computation of protein ESM embeddings, docking predictions, physically-aware unsupervised post-filtration, scoring and saving predictions to sdf.
+## Sample usage
+
+To run docking, save scored predictions and compute metrics, see the instructions provided in [GitHub README](https://github.com/LigandPro/Matcha).
 
 ## Citation
-If you use Matcha in your work, please cite our paper:
+
+If you use Matcha in your work, please cite:
 
 ```bibtex
 @misc{frolova2025matchamultistageriemannianflow,
-      title={Matcha: Multi-Stage Riemannian Flow Matching for Accurate and Physically Valid Molecular Docking},
-      author={Daria Frolova and Talgat Daulbaev and Egor Sevryugov and Sergei A. Nikolenko and Dmitry N. Ivankov and Ivan Oseledets and Marina A. Pak},
+      title={Matcha: Multi-Stage Riemannian Flow Matching for Accurate and Physically Valid Molecular Docking}, 
+      author={Daria Frolova and Talgat Daulbaev and Egor Sevriugov and Sergei A. Nikolenko and Dmitry N. Ivankov and Ivan Oseledets and Marina A. Pak},
       year={2025},
       eprint={2510.14586},
       archivePrefix={arXiv},
       primaryClass={cs.LG},
-      url={https://arxiv.org/abs/2510.14586},
+      url={https://arxiv.org/abs/2510.14586}, 
 }
 ```