CupOFMoCA-PDC/README.md

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