{"id":51230535,"url":"https://github.com/LigandPro/Matcha","last_synced_at":"2026-07-06T02:00:30.260Z","repository":{"id":319068658,"uuid":"1073484574","full_name":"LigandPro/Matcha","owner":"LigandPro","description":"Multi-stage Riemannian flow matching for physically valid molecular docking, with GNINA scoring, PoseBusters filtering, CLI inference, and benchmarks.","archived":false,"fork":false,"pushed_at":"2026-05-13T14:20:21.000Z","size":2882,"stargazers_count":24,"open_issues_count":3,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-13T16:24:50.615Z","etag":null,"topics":["alphafold3","computational-chemistry","docking","drug-design","drug-discovery","flowmatching","geometric-deep-learning","gnina","ml","molecular-docking","posebusters","protein-ligand","pytorch","rdkit"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LigandPro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-10T07:20:15.000Z","updated_at":"2026-05-08T15:58:07.000Z","dependencies_parsed_at":"2025-10-18T01:08:08.213Z","dependency_job_id":"59288054-7588-4650-b8a4-3981cdbb01f6","html_url":"https://github.com/LigandPro/Matcha","commit_stats":null,"previous_names":["ligandpro/matcha"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/LigandPro/Matcha","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LigandPro%2FMatcha","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LigandPro%2FMatcha/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LigandPro%2FMatcha/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LigandPro%2FMatcha/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LigandPro","download_url":"https://codeload.github.com/LigandPro/Matcha/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LigandPro%2FMatcha/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35175119,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alphafold3","computational-chemistry","docking","drug-design","drug-discovery","flowmatching","geometric-deep-learning","gnina","ml","molecular-docking","posebusters","protein-ligand","pytorch","rdkit"],"created_at":"2026-06-28T16:00:21.739Z","updated_at":"2026-07-06T02:00:30.250Z","avatar_url":"https://github.com/LigandPro.png","language":"Python","funding_links":[],"categories":["Machine Learning Tasks and Models","Cheminformatics \u0026 Molecular Modeling"],"sub_categories":["Drug Discovery"],"readme":"# Matcha: Multi-Stage Riemannian Flow Matching for Accurate and Physically Valid Molecular Docking\n\nThis is an official implementation of the paper [Matcha: Multi-Stage Riemannian Flow Matching for Accurate and Physically Valid Molecular Docking](https://arxiv.org/abs/2510.14586).\n\n## News\n\nWe have updated the repository and the [Hugging Face checkpoints](https://huggingface.co/LigandPro/Matcha): the current code and weights correspond to the improved pipeline and **much better results**! The previous version, however, remains available as tag `v1` (`git checkout v1`).\n\n## Overview\n\nMatcha is a molecular docking pipeline that combines multi-stage flow matching with physical validity filtering. It consists of three sequential stages that progressively refine docking predictions, each implemented as a flow matching model operating on appropriate geometric spaces (R³, SO(3), and SO(2)). Physical validity filters eliminate unrealistic poses, and GNINA minimization and scoring ranks final predictions.\n\n![pipeline](data/img/matcha_pipeline.png)\n![architecture](data/img/matcha_architecture.png)\n\nCompared 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.\n\n\u003cimg src=\"data/img/time.png\" alt=\"results\" width=\"500\"/\u003e\n\n## Content\n\n- [Installation](#install)\n- [CLI usage](#cli)\n- [Datasets](#datasets)\n  - [Existing datasets](#exist_datasets)\n  - [Adding new dataset](#new_datasets)\n- [Preparing the config file](#config)\n- [Protein preprocessing (for GNINA)](#protein_preprocessing)\n- [Running inference step-by-step](#inference_steps)\n  - [Preprocessing](#preproc)\n  - [Matcha inference](#inf)\n  - [Pose selection and filtration](#gnina)\n- [Benchmarking and pocket-aligned RMSD computation](#benchmarking)\n- [License](#license)\n- [Citation](#citation)\n\n## Installation \u003ca name=\"install\"\u003e\u003c/a\u003e\n\n```bash\n# Install with uv\nuv sync\n```\n\nOr with pip:\n\n```bash\npip install -e .\n```\n\n## CLI usage \u003ca name=\"cli\"\u003e\u003c/a\u003e\n\nThe `matcha` CLI wraps the full inference pipeline (ESM embeddings, 3-stage docking, PoseBusters filtering) with GNINA minimization and scoring into a single command.\n\n### Single ligand\n\n```bash\nuv run matcha -r protein.pdb -l ligand.sdf -o results/\n```\n\n### Batch mode (multi-ligand file or directory)\n\n```bash\nuv run matcha -r protein.pdb --ligand-dir ligands.sdf -o results/\n```\n\nAll molecules are processed in a single pipeline pass (native batching).\n\n### Key options\n\n| Flag | Description |\n|------|-------------|\n| `-r`, `--receptor` | Protein structure (`.pdb`) |\n| `-l`, `--ligand` | Single ligand (`.sdf`/`.mol`/`.mol2`/`.pdb`) |\n| `--ligand-dir` | Multi-ligand `.sdf` file or directory |\n| `-o`, `--out` | Output directory |\n| `-g`, `--device` | `auto`, `cpu`, `cuda`, `cuda:N`, or `mps` (Apple Metal) |\n| `--gpus` | Multi-GPU batch sharding, e.g. `--gpus 2,3` (batch dir mode only) |\n| `--n-samples` | Poses per ligand (default: 40) |\n| `--scorer` | `gnina` (default), `custom`, or `none` |\n| `--scorer-minimize` / `--no-scorer-minimize` | GNINA minimization (default: on) |\n| `--autobox-ligand` | Box center from reference ligand |\n| `--center-x/y/z` | Manual box center (Å) |\n| `--overwrite` | Overwrite existing run |\n\nRun `matcha --help` for the full list.\n\n### Multi-GPU batch mode (2/3 GPUs)\n\nFor large ligand directories, Matcha can shard ligands across multiple GPUs by launching one process per GPU.\n\n```bash\n# 2 GPUs\nuv run matcha -r protein.pdb --ligand-dir ligands/ --gpus 2,3 --box-json target_box.json -o out_2gpu\n\n# 3 GPUs\nuv run matcha -r protein.pdb --ligand-dir ligands/ --gpus 1,2,3 --box-json target_box.json -o out_3gpu\n```\n\nOutputs are merged into:\n- `out_\u003c...\u003e/\u003crun-name\u003e/merged/`\n- `out_\u003c...\u003e/\u003crun-name\u003e/benchmark_summary.json`\n- `out_\u003c...\u003e/\u003crun-name\u003e/benchmark_summary.md`\n\n### Search space\n\n- **Blind docking** (default): searches the entire protein surface.\n- **Autobox**: `--autobox-ligand ref.sdf` — centers the search on a reference ligand.\n- **Manual box**: `--center-x X --center-y Y --center-z Z` — explicit coordinates.\n\n### Output\n\nSingle mode produces `\u003crun-name\u003e_best.sdf` (top pose) and `\u003crun-name\u003e_poses.sdf` (all ranked poses). Batch mode creates `best_poses/` and `all_poses/` directories with per-ligand SDFs. A detailed log file is written alongside the results.\n\n## Datasets \u003ca name=\"datasets\"\u003e\u003c/a\u003e\n\n### Existing datasets \u003ca name=\"exist_datasets\"\u003e\u003c/a\u003e\n\nAstex and PoseBusters datasets can be downloaded [here](https://zenodo.org/records/8278563). PDBBind_processed can be found [here](https://zenodo.org/records/6408497). DockGen can be downloaded from [here](https://zenodo.org/records/10656052).\n\n### Adding new dataset \u003ca name=\"new_datasets\"\u003e\u003c/a\u003e\n\nUse a dataset folder with the following structure:\n\n```\ndataset_path/\n    uid1/\n        uid1_protein.pdb\n        uid1_ligand.sdf\n    uid2/\n        uid2_protein.pdb\n        uid2_ligand.sdf\n    ...\n```\n\n## Preparing the config file \u003ca name=\"config\"\u003e\u003c/a\u003e\n\n1. Edit `configs/paths/paths.yaml`: set `posebusters_data_dir`, `astex_data_dir`, `pdbbind_data_dir`, `dockgen_data_dir` (or `any_data_dir` for a new dataset). Comment out unneeded entries in `test_dataset_types`.\n\n2. Set paths for intermediate and final data:\n   - `cache_path`, `data_folder`, `inference_results_folder`\n   - `preprocessed_receptors_base`: root directory for **preprocessed** protein structures used by the GNINA affinity scripts (see [Protein preprocessing](#protein_preprocessing)). Required when using GNINA steps; layout: `{preprocessed_receptors_base}/{dataset}_{uid}/{dataset}_{uid}_protein.pdb`.\n\n3. Download checkpoints from [Hugging Face (LigandPro/Matcha)](https://huggingface.co/LigandPro/Matcha) (the `matcha_pipeline` folder). Set `checkpoints_folder` in paths.yaml to the folder that contains it.\n\n## Protein preprocessing (for GNINA) \u003ca name=\"protein_preprocessing\"\u003e\u003c/a\u003e\n\nProtein structures used by the GNINA affinity scripts must be preprocessed (hydrogenation, PDBQT, etc.). We use the [dockprep-pipeline](https://github.com/LigandPro/dockprep-pipeline) for receptor and ligand preparation; see that repository for a minimal pipeline (Reduce/OpenMM hydrogenation, Meeko PDBQT). Further details are in the paper.\n\n## Running inference step-by-step \u003ca name=\"inference_steps\"\u003e\u003c/a\u003e\n\n### Preprocessing \u003ca name=\"preproc\"\u003e\u003c/a\u003e\n\n```bash\nuv run python scripts/prepare_esm_sequences.py -p configs/paths/paths.yaml\nCUDA_VISIBLE_DEVICES=0 uv run python scripts/compute_esm_embeddings.py -p configs/paths/paths.yaml\n```\n\n### Matcha inference \u003ca name=\"inf\"\u003e\u003c/a\u003e\n\n```bash\nCUDA_VISIBLE_DEVICES=\u003cgpu_device_id\u003e uv run python scripts/run_inference_pipeline.py -c configs/base.yaml -p configs/paths/paths.yaml -n inference_folder_name --n-samples 20\n```\n\n### Pose selection and filtration \u003ca name=\"gnina\"\u003e\u003c/a\u003e\n\nTo run the full pipeline including GNINA affinity, minimization, top-pose selection, and metrics:\n\n```bash\nuv run bash scripts/final_inference_pipeline.sh -n inference_folder_name -c configs/base.yaml -p configs/paths/paths.yaml -d \u003cgpu_device_id\u003e -s 20 -g \u003c/path/to/gnina_executable\u003e [--compute_final_metrics]\n```\n\nYou must set `preprocessed_receptors_base` in paths.yaml (or provide preprocessed structures as required by the GNINA scripts) and pass `-g` with the path to your GNINA runner script.\nIf you pass `--compute_final_metrics`, the script will compute dataset-level metrics for top-1 pose for each complex. \nMetrics include the computation of symmetry-corrected RMSD and PoseBusters filters.\n\n## Benchmarking and pocket-aligned RMSD computation \u003ca name=\"benchmarking\"\u003e\u003c/a\u003e\n\nFor other docking methods, prepare a folder of predictions with the structure described in the script. Then:\n\n```bash\nuv run python scripts/compute_aligned_rmsd.py -p configs/paths/paths.yaml -a base --init-preds-path \u003cpath_to_initial_preds\u003e\n```\n\nSet `methods_data` and `dataset_names` inside the script as needed.\nFor each method in `methods_data`, set flag `has_predicted_proteins` that indicates that the protein pdb itself has coordinates that differ from the original holo structure.\nChoose between `base` and `pocket` alignment (see Appendix G in the paper). \nBy default we use `pocket` alignment for methods that have predicted protein structures (eg. AlphaFold3), and `base` for rigid docking methods (eg. DiffDock). In the latter case for rigid docking the alignment is not performed, but the results are rearranged for the further metrics computation.\nThe resulting structures will appear in the `inference_results_folder/\u003cbaseline_method_name\u003e_\u003cpocket_alignment_type\u003e`.\n\nAfter aligning the predicted structures to the original holo protein structure, metrics from the best SDF predictions can be computed with:\n\n```bash\nuv run python scripts/compute_metrics_from_sdf.py -p configs/paths/paths.yaml -n \u003cbaseline_method_name\u003e_\u003cpocket_alignment_type\u003e --prediction-type best_base_predictions\n```\n\n## License \u003ca name=\"license\"\u003e\u003c/a\u003e\n\nThis work is licensed under a [Creative Commons Attribution-NonCommercial 4.0 International License](https://creativecommons.org/licenses/by-nc/4.0/).\n\n[![CC BY-NC 4.0](https://licensebuttons.net/l/by-nc/4.0/88x31.png)](https://creativecommons.org/licenses/by-nc/4.0/)\n\n## Citation \u003ca name=\"citation\"\u003e\u003c/a\u003e\n\nIf you use Matcha in your work, please cite:\n\n```bibtex\n@misc{frolova2025matchamultistageriemannianflow,\n      title={Matcha: Multi-Stage Riemannian Flow Matching for Accurate and Physically Valid Molecular Docking}, \n      author={Daria Frolova and Talgat Daulbaev and Egor Sevriugov and Sergei A. Nikolenko and Dmitry N. Ivankov and Ivan Oseledets and Marina A. Pak},\n      year={2025},\n      eprint={2510.14586},\n      archivePrefix={arXiv},\n      primaryClass={cs.LG},\n      url={https://arxiv.org/abs/2510.14586}, \n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLigandPro%2FMatcha","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLigandPro%2FMatcha","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLigandPro%2FMatcha/lists"}