CupOFMoCA for peptide-drug conjugates
This folder contains the PDC code, model weights, property scorers, target sequences, and paper configurations for CupOFMoCA: Coupled Objective-Guided Discrete Flows for Molecular Conjugate Assembly.
The PDC workflow generates a peptide carrier and assembles it with a fixed payload through a target-specific conjugation builder. CupOFMoCA applies property guidance and chemical assembly checks during sampling. The release supports peptide SMILES, natural amino-acid tokens, and an extended unnatural amino-acid vocabulary.
The main README provides the shared project overview and a quickstart for both conjugate modalities. This guide covers the PDC representations, targets, commands, artifacts, and evaluation code in greater detail.
Representations and checkpoints
| Representation | Checkpoint | Generated sequence |
|---|---|---|
| SMILES | checkpoints/SMILESReDi_base.ckpt |
peptide expressed with SMILES tokens |
| AA | checkpoints/PepReDi_base.pt |
10-residue peptide from canonical amino acids |
| UAA | checkpoints/UAAReDi_base.pt |
10-residue peptide from the extended amino-acid vocabulary |
The release also includes the binding, hemolysis, non-fouling, and solubility scorers used
by the PDC generation programs. The AA experiments use the bundled SMILES-input affinity
scorer through the reported --affinity_type smiles setting.
Installation
Run the following commands from this folder.
conda env create -f environment.yml
conda activate cupofmoca
python scripts/verify_release.py
The tested environment uses Python 3.9, PyTorch 2.5.1, and CUDA 12.1. A CUDA GPU is
recommended for full experiments. The first scoring run downloads
facebook/esm2_t33_650M_UR50D and aaronfeller/PeptideCLM-23M-all from Hugging Face.
Set HF_HOME to a persistent cache location when shared or temporary compute nodes are in
use.
The pinned pip packages are also available in requirements.txt for environments that
already provide a compatible PyTorch and CUDA installation.
pip install -r requirements.txt
Target configurations
| Target | Protein | Conjugation builder | Default SMILES length |
|---|---|---|---|
| ERBB2 | receptor tyrosine-protein kinase erbB-2 | SSCpt |
80 |
| GNRHR | gonadotropin-releasing hormone receptor | AoaDau |
80 |
| NRP1 | neuropilin-1 | DSPASN38 |
100 |
The target sequences are stored in configs/targets.fasta. The complete paper settings
are stored in configs/paper.json, including seeds 42, 123, and 456; 100 candidates per
seed; 128 optimization steps; equal objective weights; and the CupOFMoCA acceptance
parameter of 50.
Run generation
scripts/run_experiment.py provides one interface across representations, sampling
methods, variants, targets, and seeds. Preview a configured command before model loading
with --dry-run.
python scripts/run_experiment.py \
--representation uaa \
--variant cupofmoca \
--method guided \
--target NRP1 \
--dry-run
Remove --dry-run to launch the complete configured experiment.
python scripts/run_experiment.py \
--representation uaa \
--variant cupofmoca \
--method guided \
--target NRP1
A compact smoke run can verify the environment and code path.
python scripts/run_experiment.py \
--representation aa \
--variant baseline \
--method staged \
--target ERBB2 \
--num-candidates 1
The principal options are summarized below.
| Option | Accepted values | Function |
|---|---|---|
--representation |
smiles, aa, uaa |
selects the generator and tokenization |
--variant |
baseline, cupofmoca |
selects the sampling implementation |
--method |
guided, staged |
selects the guided or staged entry point |
--target |
ERBB2, GNRHR, NRP1 |
selects the sequence and conjugation builder |
--seeds |
one or more integers | sets the independent generation seeds |
--num-candidates |
positive integer | sets candidates generated per seed |
--gen-len |
positive integer | overrides the representation-specific length |
--force |
flag | replaces an existing output for the selected run |
Arguments placed after -- pass directly to the underlying generation module.
python scripts/run_experiment.py \
--representation smiles \
--variant cupofmoca \
--method guided \
--target GNRHR \
-- --top_k 100
Each seed receives a separate output directory with the following organization.
outputs/
<target>/
<representation>/
<variant>_<method>/
seed_<seed>/
molecules.txt
logs/
Direct generation modules
The wrapper dispatches to the modules under smiles/generation/. Their complete argument
surfaces remain available for method development and custom experiments.
| Representation | Baseline modules | CupOFMoCA modules |
|---|---|---|
| SMILES | guided.py, staged.py |
cupofmoca_guided.py, cupofmoca_staged.py |
| AA | guided_aa.py, staged_aa.py |
cupofmoca_guided_aa.py, cupofmoca_staged_aa.py |
| UAA | guided_uaa.py, staged_uaa.py |
cupofmoca_guided_uaa.py, cupofmoca_staged_uaa.py |
Invoke a module with --help to inspect its parameters.
python -m smiles.generation.cupofmoca_guided_uaa --help
Evaluation
The submitted evaluation routines are smiles/evaluation/run_metrics.py and
smiles/evaluation/run_metrics_uaa.py. They measure assembly validity and predicted
functional properties for the generated PDCs. Use each program's --help output to
select inputs and evaluation settings.
python smiles/evaluation/run_metrics.py --help
python smiles/evaluation/run_metrics_uaa.py --help
The paper reports PDC experiments across ERBB2, GNRHR, and NRP1 in the SMILES, AA, and UAA representations. Appendix E describes the model architecture, optimization, data construction, and scorers. The main paper and supplementary material define the reported evaluation protocol and results.
Training sources
AA-PepReDi was trained with peptides from PepNN and BioLip2 together with sequences of 6 to 49 residues from PPIRef. The training, validation, and test proportions were 80, 10, and 10 percent.
UAA-PepReDi was trained with 150,000 synthetic sequences generated with p2smi across
non-canonical and D-amino-acid compositions. The training, validation, and test
proportions were 80, 10, and 10 percent.
The SMILES workflow uses the released pretrained SMILESReDi weights. This repository distributes the trained weights and the code required by the paper workflow. Appendix E documents construction of the corresponding training collections.
Artifact verification
The integrity checker validates byte counts, SHA-256 hashes, and portability-sensitive source paths.
python scripts/verify_release.py
docs/artifacts.json provides the machine-readable manifest, and
docs/ARTIFACTS.md lists each artifact's role, size, and checksum.
The full release occupies approximately 1.9 GB before environment packages and runtime
model downloads. Git LFS tracks the large *.pt and *.ckpt files.
PyTorch loads the bundled checkpoints through its serialized checkpoint interface. Use weights from a trusted release location and verify their hashes before loading.
Research scope
The released configuration supports computational PDC generation for three receptor targets and their specified conjugation chemistries. All generated structures and property scores are computational predictions. Synthesis, biochemical and cellular testing, toxicology, and safety assessment establish the experimental properties of any candidate selected for further study.
Hardware, CUDA, PyTorch, and downloaded model revisions can introduce numerical variation. The paper reports experiments on NVIDIA RTX A6000 GPUs with 48 GB of memory. Smaller batches can support generation on devices with less memory.
Repository structure
checkpoints/ SMILES, AA, and UAA generator weights
configs/ paper settings and target sequences
docs/ artifact documentation and checksums
scripts/run_experiment.py unified experiment runner
scripts/verify_release.py release integrity checker
smiles/
conjugation/ target-specific PDC assembly builders
evaluation/ metrics and analyzers
generation/ baseline and CupOFMoCA sampling programs
models/ ReDi model and data code
scoring/ property scorers and checkpoints
smiles_tokenizer/ tokenizer code and vocabulary
third_party/ peptide-to-SMILES conversion helper
Citation and license
Citation metadata is available in CITATION.cff. The CupOFMoCA code is
released under Apache-2.0 through LICENSE and NOTICE. The vendored peptide-to-SMILES
helper retains its upstream license under third_party/SMILESToPeptide/.