| --- |
| license: apache-2.0 |
| library_name: pytorch |
| tags: |
| - chemistry |
| - drug-discovery |
| - molecular-generation |
| - peptide |
| - discrete-flow |
| - peptide-drug-conjugate |
| - protac |
| --- |
| |
| # CupOFMoCA |
|
|
| Code, model weights, configurations, and reported outputs for **CupOFMoCA: Coupled |
| Objective-Guided Discrete Flows for Molecular Conjugate Assembly** (NeurIPS 2026). |
|
|
|  |
|
|
| Molecular conjugates derive their function from interactions among multiple chemical |
| components. CupOFMoCA uses discrete flows to generate coupled components, enforce |
| assembly-validity constraints throughout sampling, and guide local transitions with |
| property objectives. This release supports the two conjugate modalities studied in the |
| paper. |
|
|
| | Folder | Generated component | Representations or systems | |
| |---|---|---| |
| | [`CupOFMoCA-PDC/`](CupOFMoCA-PDC) | peptide carrier assembled with a fixed payload and linker chemistry | SMILES, natural amino acids, and unnatural amino acids for ERBB2, GNRHR, and NRP1 | |
| | [`CupOFMoCA-PROTAC/`](CupOFMoCA-PROTAC) | linker connecting fixed target-binding and E3-ligase anchors | EGFR-VHL, BRD9-VHL, and CDK6-CRBN | |
|
|
| Each modality folder provides its own environment, paper configuration, model artifacts, |
| generation programs, integrity checker, and detailed README. The sections below contain |
| the shared setup, representative commands, and the information needed to choose and run |
| either modality. |
|
|
| ## Download |
|
|
| Install the [Hugging Face CLI](https://huggingface.co/docs/huggingface_hub/guides/cli) |
| and download the complete release with the following commands. |
|
|
| ```bash |
| hf download ChatterjeeLab/CupOFMoCA --local-dir CupOFMoCA |
| cd CupOFMoCA |
| ``` |
|
|
| A modality-specific download reduces local storage use. |
|
|
| ```bash |
| hf download ChatterjeeLab/CupOFMoCA \ |
| --include "CupOFMoCA-PDC/*" \ |
| --local-dir CupOFMoCA |
| ``` |
|
|
| Replace `CupOFMoCA-PDC/*` with `CupOFMoCA-PROTAC/*` for the PROTAC release. |
|
|
| ## Choose a workflow |
|
|
| Use the PDC workflow to generate peptide carriers in one of three molecular |
| representations and assemble them with the target-specific payload chemistry. Use the |
| PROTAC workflow to generate a molecular-graph linker between a fixed warhead and a fixed |
| E3 ligand. |
|
|
| | Capability | PDC | PROTAC | |
| |---|---|---| |
| | Base generator | SMILESReDi, PepReDi, or UAAReDi | DeFoG fine-tuned on PROTAC-DB linkers | |
| | Generated object | peptide carrier | linker subgraph | |
| | Fixed context | payload and conjugation chemistry | warhead and E3-ligand subgraphs | |
| | Released systems | ERBB2, GNRHR, NRP1 | EGFR-VHL, BRD9-VHL, CDK6-CRBN | |
| | Paper settings | `CupOFMoCA-PDC/configs/paper.json` | `CupOFMoCA-PROTAC/configs/paper.json` | |
| | Detailed guide | [`CupOFMoCA-PDC/README.md`](CupOFMoCA-PDC/README.md) | [`CupOFMoCA-PROTAC/README.md`](CupOFMoCA-PROTAC/README.md) | |
|
|
| Both workflows use custom PyTorch generation code and local checkpoints. A CUDA GPU is |
| recommended for generation. The released environments use Python 3.9 and CUDA 12.1. |
|
|
| ## PDC quickstart |
|
|
| From the release root, create the PDC environment and verify the bundled artifacts. |
|
|
| ```bash |
| cd CupOFMoCA-PDC |
| conda env create -f environment.yml |
| conda activate cupofmoca |
| python scripts/verify_release.py |
| ``` |
|
|
| Preview the configured NRP1 UAA experiment, then run it from the PDC folder. |
|
|
| ```bash |
| python scripts/run_experiment.py \ |
| --representation uaa \ |
| --variant cupofmoca \ |
| --method guided \ |
| --target NRP1 \ |
| --dry-run |
| |
| python scripts/run_experiment.py \ |
| --representation uaa \ |
| --variant cupofmoca \ |
| --method guided \ |
| --target NRP1 |
| ``` |
|
|
| The runner supports `smiles`, `aa`, and `uaa` representations; `guided` and `staged` |
| sampling methods; and `ERBB2`, `GNRHR`, and `NRP1` targets. It writes each seed to a |
| separate directory under `outputs/`. The PDC guide documents the complete command |
| surface, checkpoints, target chemistries, and evaluation programs. |
|
|
| ## PROTAC quickstart |
|
|
| From the release root, create the PROTAC environment, install the bundled DeFoG package, |
| and verify the release. |
|
|
| ```bash |
| cd CupOFMoCA-PROTAC |
| conda env create -f environment.yml |
| conda activate defog |
| pip install -e src/defog |
| python scripts/verify_release.py |
| ``` |
|
|
| Generate 100 EGFR-VHL candidates with one reported seed. |
|
|
| ```bash |
| cd scripts |
| python generate.py \ |
| --checkpoint ../checkpoints/protac_linker_finetune/epoch=99-v1.ckpt \ |
| --protac_module ErlotinibVHL \ |
| --fix_termini cooh \ |
| --fast_scoring \ |
| --num_samples 100 \ |
| --num_batches 1 \ |
| --num_steps 1500 \ |
| --warmup_steps 100 \ |
| --weights 4.0 2.0 4.0 \ |
| --seed 42 \ |
| --output_file ./protac_linkers_egfrvhl.smi \ |
| --output_dir ../generation_logs |
| ``` |
|
|
| Set `--protac_module` to `BRD9VHL` or `CDK6CRBN` for the other reported systems. |
| The PROTAC guide explains the three objective weights, target builders, evaluation |
| programs, archived paper outputs, and molecular-dynamics workflow. |
|
|
| ## Paper configurations |
|
|
| The machine-readable configuration files record the settings used for the reported |
| experiments. Both modalities use seeds 42, 123, and 456 with 100 candidates per seed. |
|
|
| The PDC configuration uses 128 optimization steps, equal objective weights, and a |
| target-specific conjugation builder. SMILES sequence lengths are 80 for ERBB2 and GNRHR |
| and 100 for NRP1. AA and UAA experiments use length 10. |
|
|
| The PROTAC configuration uses 1,500 sampling steps, 100 warmup steps, a hard validity |
| gate, and soft-objective weights of 4.0 for synthetic accessibility, 2.0 for PROTAC-DB |
| chemotype closeness, and 4.0 for connectivity. |
|
|
| ## Artifacts and reproducibility |
|
|
| Run the integrity checker inside a modality folder before generation. |
|
|
| ```bash |
| python scripts/verify_release.py |
| ``` |
|
|
| Each checker validates file sizes, SHA-256 hashes, and portability-sensitive source |
| paths against `docs/artifacts.json`. Human-readable artifact inventories appear in |
| `docs/ARTIFACTS.md`. The PDC inventory covers the three generators and the property |
| scorers. The PROTAC inventory covers the fine-tuned DeFoG checkpoint and the generic and |
| target-specific validity classifiers. |
|
|
| The paper settings remain in `configs/paper.json`, and detailed PROTAC outputs behind the |
| reported tables remain under `CupOFMoCA-PROTAC/results/`. Hardware, CUDA, PyTorch, and |
| runtime model revisions can introduce numerical variation across repeated runs. |
|
|
| ## Data and evaluation scope |
|
|
| The PDC release supports the paper experiments across ERBB2, GNRHR, and NRP1 with the |
| released target sequences and conjugation chemistries. The PROTAC release supports the |
| paper experiments across EGFR-VHL, BRD9-VHL, and CDK6-CRBN with fixed anchor chemistry. |
| The detailed modality guides describe the training sources and evaluation measurements. |
|
|
| All generated candidates and objective values are computational predictions. Use |
| chemical synthesis, experimental validation, toxicology, and safety assessment to |
| establish the properties of candidates selected for further study. DegradeMaster results |
| use an in-domain predictor trained with overlapping PROTAC databases and should be |
| interpreted within that evaluation setting. |
|
|
| ## Repository structure |
|
|
| ```text |
| CupOFMoCA/ |
| assets/ overview media |
| CupOFMoCA-PDC/ PDC generation and evaluation release |
| checkpoints/ SMILES, AA, and UAA generator weights |
| configs/ paper settings and target sequences |
| scripts/ experiment runner and integrity checker |
| smiles/ generation, assembly, scoring, and evaluation code |
| CupOFMoCA-PROTAC/ PROTAC linker generation and evaluation release |
| checkpoints/ fine-tuned DeFoG weights |
| configs/ paper settings |
| data/ derived linker table |
| md/ explicit-solvent molecular-dynamics workflow |
| results/ outputs and summaries used in paper tables |
| scripts/ generation, evaluation, and verification programs |
| src/ DeFoG, target builders, and classifiers |
| ``` |
|
|
| ## Citation |
|
|
| Please cite the CupOFMoCA paper when using this code or the released model artifacts. |
|
|
| ```bibtex |
| @inproceedings{zhang2026cupofmoca, |
| title = {CupOFMoCA: Coupled Objective-Guided Discrete Flows for Molecular Conjugate Assembly}, |
| author = {Zhang, Ruoxi Rosie and Li, Ziang and Gu, Jiatao and Chatterjee, Pranam}, |
| booktitle = {Advances in Neural Information Processing Systems}, |
| year = {2026} |
| } |
| ``` |
|
|
| Machine-readable citation metadata is available in [`CITATION.cff`](CITATION.cff). |
|
|
| ## License |
|
|
| The CupOFMoCA code is released under Apache-2.0. Third-party code and downloaded model |
| artifacts retain their respective terms, which are recorded in the modality-specific |
| `NOTICE` files. |
|
|
