| # 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/ |
| <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. |
|
|
| ```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/`. |
|
|
