--- 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). ![CupOFMoCA overview](assets/CupOFMoCA.gif) 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.