# 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](../README.md) 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. ```bash 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. ```bash 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`. ```bash python scripts/run_experiment.py \ --representation uaa \ --variant cupofmoca \ --method guided \ --target NRP1 \ --dry-run ``` Remove `--dry-run` to launch the complete configured experiment. ```bash python scripts/run_experiment.py \ --representation uaa \ --variant cupofmoca \ --method guided \ --target NRP1 ``` A compact smoke run can verify the environment and code path. ```bash 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. ```bash 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. ```text outputs/ / / _/ 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. ```bash 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. ```bash 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. ```bash python scripts/verify_release.py ``` `docs/artifacts.json` provides the machine-readable manifest, and [`docs/ARTIFACTS.md`](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 ```text 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`](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/`.