README.md

---
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.