diff --git a/.gitattributes b/.gitattributes index a5fc709a9f9f7c579dae5c731484697b1e29a9b5..4b5eeeb7deb4177648236e3a6f001e11d4a719c8 100644 --- a/.gitattributes +++ b/.gitattributes @@ -34,3 +34,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text *.zst filter=lfs diff=lfs merge=lfs -text *tfevents* filter=lfs diff=lfs merge=lfs -text assets/CupOFMoCA.gif filter=lfs diff=lfs merge=lfs -text +CupOFMoCA-PDC/assets/CupOFMoCA.gif filter=lfs diff=lfs merge=lfs -text diff --git a/CITATION.cff b/CupOFMoCA-PDC/CITATION.cff similarity index 100% rename from CITATION.cff rename to CupOFMoCA-PDC/CITATION.cff diff --git a/LICENSE b/CupOFMoCA-PDC/LICENSE similarity index 100% rename from LICENSE rename to CupOFMoCA-PDC/LICENSE diff --git a/NOTICE b/CupOFMoCA-PDC/NOTICE similarity index 100% rename from NOTICE rename to CupOFMoCA-PDC/NOTICE diff --git a/CupOFMoCA-PDC/README.md b/CupOFMoCA-PDC/README.md new file mode 100644 index 0000000000000000000000000000000000000000..9a3f12d40cf1b390f88693d7ba52699525bb34e9 --- /dev/null +++ b/CupOFMoCA-PDC/README.md @@ -0,0 +1,228 @@ +--- +license: apache-2.0 +library_name: pytorch +tags: + - chemistry + - drug-discovery + - molecular-generation + - peptide + - discrete-flow + - peptide-drug-conjugate +--- + +# CupOFMoCA + +Code and PDC model artifacts for **CupOFMoCA: Coupled Objective-Guided Discrete Flows for +Molecular Conjugate Assembly** (NeurIPS 2026). + +CupOFMoCA performs coupled, objective-guided discrete-flow generation while enforcing chemical +assembly constraints. This release supports the paper's peptide-drug conjugate (PDC) experiments +across SMILES, natural amino-acid (AA), and unnatural amino-acid (UAA) representations. + +## Model overview + +![CupOFMoCA overview](assets/CupOFMoCA.gif) + +CupOFMoCA is a research pipeline for generating peptide-drug conjugate candidates. It couples a +pretrained discrete-flow generator with property guidance and conjugation-validity checks during +sampling. This repository contains three generator checkpoints and the property scorers used by the +released PDC pipeline: + +| Checkpoint | Representation | Role | +|---|---|---| +| `SMILESReDi_base.ckpt` | peptide SMILES | pretrained SMILES discrete-flow generator | +| `PepReDi_base.pt` | canonical amino acids | pretrained AA discrete-flow generator | +| `UAAReDi_base.pt` | extended amino-acid vocabulary | pretrained UAA discrete-flow generator | + +The checkpoints are loaded by the repository's custom PyTorch code; this is not a Transformers +pipeline and does not provide a hosted-inference widget. + +### Intended uses + +- Reproduce and inspect the paper's PDC generation experiments. +- Generate computational PDC candidates for research and method development. +- Extend or compare constrained, multi-objective molecular-generation methods. + +The release is not intended for clinical decisions, direct therapeutic use, or as a substitute for +chemical synthesis, experimental validation, toxicology, or safety assessment. + +### Training data + +- **AA-PepReDi:** peptides from PepNN and BioLip2, together with 6--49-residue sequences from + PPIRef, using an 80:10:10 train/validation/test split. +- **UAA-PepReDi:** 150,000 synthetic sequences constructed with `p2smi` across combinations of + non-canonical and D-amino-acid composition, using an 80:10:10 split. +- **SMILESReDi:** the released pretrained SMILESReDi weights are used without additional + CupOFMoCA fine-tuning. + +Architecture, optimization, data construction, and scorer details are reported in Appendix E of +the paper. Training datasets are not redistributed in this repository. + +### Evaluation + +The paper evaluates generated PDCs for assembly validity and predicted functional properties across +ERBB2, GNRHR, and NRP1, using SMILES, AA, and UAA representations. The reported results and +experimental protocol are in the paper; the submitted evaluation routines are included under +`smiles/evaluation/`. + +### Limitations + +- Outputs and objective values are computational predictions, not experimentally validated + compounds or guarantees of efficacy, synthesizability, toxicity, or safety. +- The released configurations cover three receptor targets and fixed target-specific conjugation + chemistries; performance outside this scope has not been established. +- The release contains the paper's PDC stack only. Its PROTAC experiments require separate code and + artifacts. +- Results can vary with hardware, CUDA/PyTorch versions, and revisions of models downloaded at + runtime. + +## Repository layout + +```text +checkpoints/ generator weights +configs/ paper settings and target sequences +docs/ model-artifact details and checksums +scripts/run_experiment.py unified experiment runner +scripts/verify_release.py release integrity checker +smiles/ + generation/ generation entry points + evaluation/ metrics and analyzers + models/ ReDi model and data code + conjugation/ PDC assembly builders + scoring/ property scorers + smiles_tokenizer/ tokenizer code and vocabulary +third_party/ peptide-to-SMILES conversion helper +``` + +The release currently covers the PDC implementation. The PROTAC experiments described in the paper +use a separate code and artifact stack that is not included here. + +## 1. Environment + +A CUDA GPU is strongly recommended. The tested environment used Python 3.9, PyTorch 2.5.1, and +CUDA 12.1. + +```bash +conda env create -f environment.yml +conda activate cupofmoca +``` + +Alternatively, install a PyTorch build appropriate for your CUDA driver and then install the pinned +packages: + +```bash +pip install -r requirements.txt +``` + +On first use, Transformers downloads `facebook/esm2_t33_650M_UR50D` and +`aaronfeller/PeptideCLM-23M-all` from Hugging Face. Set `HF_HOME` to a persistent cache if needed. + +Verify the bundled artifacts and source paths before running an experiment: + +```bash +python scripts/verify_release.py +``` + +## 2. Run PDC generation + +Run commands from the repository root. Preview a configured command without loading models: + +```bash +python scripts/run_experiment.py \ + --representation uaa \ + --variant cupofmoca \ + --method guided \ + --target NRP1 \ + --dry-run +``` + +Run the experiment: + +```bash +python scripts/run_experiment.py \ + --representation uaa \ + --variant cupofmoca \ + --method guided \ + --target NRP1 +``` + +Run a small smoke test: + +```bash +python scripts/run_experiment.py \ + --representation aa --variant baseline --method staged --target ERBB2 \ + --num-candidates 1 +``` + +Outputs are written under `outputs/` in separate run directories. Existing outputs are protected +unless `--force` is supplied. Arguments after `--` are passed to the underlying generator: + +```bash +python scripts/run_experiment.py \ + --representation smiles --variant cupofmoca --method guided --target GNRHR \ + -- --top_k 100 +``` + +### 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 | + +AA and UAA runs use length 10. Shared settings include 128 optimization steps, top-p 1.0, +objective weights `[1, 1]`, and acceptance sampling with beta 50 for CupOFMoCA. The machine-readable +configuration is in `configs/paper.json`; target sequences are in `configs/targets.fasta`. + +### Direct entry points + +The full argument surfaces remain available under `smiles/generation/`: + +```text +guided.py cupofmoca_guided.py +guided_aa.py cupofmoca_guided_aa.py +guided_uaa.py cupofmoca_guided_uaa.py +staged.py cupofmoca_staged.py +staged_aa.py cupofmoca_staged_aa.py +staged_uaa.py cupofmoca_staged_uaa.py +``` + +Run one directly as a module, for example: + +```bash +python -m smiles.generation.cupofmoca_guided_uaa --help +``` + +`smiles/evaluation/run_metrics.py` and `smiles/evaluation/run_metrics_uaa.py` contain the submitted evaluation routines. +Use `python --help` to inspect their arguments. + +## 3. Included checkpoints + +The release includes the SMILES, AA, and UAA generator weights together with the binding, +hemolysis, non-fouling, and solubility scorers needed by the PDC pipeline. Artifact roles, sizes, and +SHA-256 values are listed in [docs/ARTIFACTS.md](docs/ARTIFACTS.md). + +The AA-input affinity predictor is not included because the PDC generation configuration uses the +bundled SMILES-input scorer (`--affinity_type smiles`). + +Large `*.pt` and `*.ckpt` files are configured for Git LFS. The repository is approximately 1.9 GB +before environment and model-cache downloads. + +The checkpoint formats are loaded through PyTorch. As with any pickle-backed PyTorch artifact, +only load weights obtained from a source you trust. + +## 4. Notes + +- The paper reports NVIDIA RTX A6000 48 GB GPUs. Lower-memory devices may require smaller batches. +- Exact bitwise output can vary across CUDA, PyTorch, GPU, and downloaded model revisions. +- Generated structures are computational hypotheses that require experimental validation. Property + models are predictors, not clinical or safety guarantees. +- The peptide-to-SMILES helper used by the experiments is vendored under `third_party/` with its + upstream license notice. + +## 5. Citation and license + +Citation metadata is provided in `CITATION.cff`. The repository code is released under Apache-2.0; +see `LICENSE` and `NOTICE`. Third-party components and downloaded model artifacts retain their +respective terms. diff --git a/assets/CupOFMoCA.gif b/CupOFMoCA-PDC/assets/CupOFMoCA.gif similarity index 100% rename from assets/CupOFMoCA.gif rename to CupOFMoCA-PDC/assets/CupOFMoCA.gif diff --git a/checkpoints/PepReDi_base.pt b/CupOFMoCA-PDC/checkpoints/PepReDi_base.pt similarity index 100% rename from checkpoints/PepReDi_base.pt rename to CupOFMoCA-PDC/checkpoints/PepReDi_base.pt diff --git a/checkpoints/SMILESReDi_base.ckpt b/CupOFMoCA-PDC/checkpoints/SMILESReDi_base.ckpt similarity index 100% rename from checkpoints/SMILESReDi_base.ckpt rename to CupOFMoCA-PDC/checkpoints/SMILESReDi_base.ckpt diff --git a/checkpoints/UAAReDi_base.pt b/CupOFMoCA-PDC/checkpoints/UAAReDi_base.pt similarity index 100% rename from checkpoints/UAAReDi_base.pt rename to CupOFMoCA-PDC/checkpoints/UAAReDi_base.pt diff --git a/configs/paper.json b/CupOFMoCA-PDC/configs/paper.json similarity index 100% rename from configs/paper.json rename to CupOFMoCA-PDC/configs/paper.json diff --git a/configs/targets.fasta b/CupOFMoCA-PDC/configs/targets.fasta similarity index 100% rename from configs/targets.fasta rename to CupOFMoCA-PDC/configs/targets.fasta diff --git a/docs/ARTIFACTS.md b/CupOFMoCA-PDC/docs/ARTIFACTS.md similarity index 100% rename from docs/ARTIFACTS.md rename to CupOFMoCA-PDC/docs/ARTIFACTS.md diff --git a/docs/artifacts.json b/CupOFMoCA-PDC/docs/artifacts.json similarity index 100% rename from docs/artifacts.json rename to CupOFMoCA-PDC/docs/artifacts.json diff --git a/environment.yml b/CupOFMoCA-PDC/environment.yml similarity index 100% rename from environment.yml rename to CupOFMoCA-PDC/environment.yml diff --git a/requirements.txt b/CupOFMoCA-PDC/requirements.txt similarity index 100% rename from requirements.txt rename to CupOFMoCA-PDC/requirements.txt diff --git a/scripts/run_experiment.py b/CupOFMoCA-PDC/scripts/run_experiment.py similarity index 100% rename from scripts/run_experiment.py rename to CupOFMoCA-PDC/scripts/run_experiment.py diff --git a/scripts/verify_release.py b/CupOFMoCA-PDC/scripts/verify_release.py similarity index 100% rename from scripts/verify_release.py rename to CupOFMoCA-PDC/scripts/verify_release.py diff --git a/smiles/__init__.py b/CupOFMoCA-PDC/smiles/__init__.py similarity index 100% rename from smiles/__init__.py rename to CupOFMoCA-PDC/smiles/__init__.py diff --git a/smiles/conjugation/AoaDau.py b/CupOFMoCA-PDC/smiles/conjugation/AoaDau.py similarity index 100% rename from smiles/conjugation/AoaDau.py rename to CupOFMoCA-PDC/smiles/conjugation/AoaDau.py diff --git a/smiles/conjugation/CptFactory.py b/CupOFMoCA-PDC/smiles/conjugation/CptFactory.py similarity index 100% rename from smiles/conjugation/CptFactory.py rename to CupOFMoCA-PDC/smiles/conjugation/CptFactory.py diff --git a/smiles/conjugation/DSEBSN38.py b/CupOFMoCA-PDC/smiles/conjugation/DSEBSN38.py similarity index 100% rename from smiles/conjugation/DSEBSN38.py rename to CupOFMoCA-PDC/smiles/conjugation/DSEBSN38.py diff --git a/smiles/conjugation/DSECCpt.py b/CupOFMoCA-PDC/smiles/conjugation/DSECCpt.py similarity index 100% rename from smiles/conjugation/DSECCpt.py rename to CupOFMoCA-PDC/smiles/conjugation/DSECCpt.py diff --git a/smiles/conjugation/DSEPSN38.py b/CupOFMoCA-PDC/smiles/conjugation/DSEPSN38.py similarity index 100% rename from smiles/conjugation/DSEPSN38.py rename to CupOFMoCA-PDC/smiles/conjugation/DSEPSN38.py diff --git a/smiles/conjugation/DSPACpt.py b/CupOFMoCA-PDC/smiles/conjugation/DSPACpt.py similarity index 100% rename from smiles/conjugation/DSPACpt.py rename to CupOFMoCA-PDC/smiles/conjugation/DSPACpt.py diff --git a/smiles/conjugation/DSPASN38.py b/CupOFMoCA-PDC/smiles/conjugation/DSPASN38.py similarity index 100% rename from smiles/conjugation/DSPASN38.py rename to CupOFMoCA-PDC/smiles/conjugation/DSPASN38.py diff --git a/smiles/conjugation/DauFactory.py b/CupOFMoCA-PDC/smiles/conjugation/DauFactory.py similarity index 100% rename from smiles/conjugation/DauFactory.py rename to CupOFMoCA-PDC/smiles/conjugation/DauFactory.py diff --git a/smiles/conjugation/GlutarylDau.py b/CupOFMoCA-PDC/smiles/conjugation/GlutarylDau.py similarity index 100% rename from smiles/conjugation/GlutarylDau.py rename to CupOFMoCA-PDC/smiles/conjugation/GlutarylDau.py diff --git a/smiles/conjugation/MalHexCpt.py b/CupOFMoCA-PDC/smiles/conjugation/MalHexCpt.py similarity index 100% rename from smiles/conjugation/MalHexCpt.py rename to CupOFMoCA-PDC/smiles/conjugation/MalHexCpt.py diff --git a/smiles/conjugation/SN38Factory.py b/CupOFMoCA-PDC/smiles/conjugation/SN38Factory.py similarity index 100% rename from smiles/conjugation/SN38Factory.py rename to CupOFMoCA-PDC/smiles/conjugation/SN38Factory.py diff --git a/smiles/conjugation/SSCpt.py b/CupOFMoCA-PDC/smiles/conjugation/SSCpt.py similarity index 100% rename from smiles/conjugation/SSCpt.py rename to CupOFMoCA-PDC/smiles/conjugation/SSCpt.py diff --git a/smiles/conjugation/ValAlaDau.py b/CupOFMoCA-PDC/smiles/conjugation/ValAlaDau.py similarity index 100% rename from smiles/conjugation/ValAlaDau.py rename to CupOFMoCA-PDC/smiles/conjugation/ValAlaDau.py diff --git a/smiles/conjugation/ValCitDau.py b/CupOFMoCA-PDC/smiles/conjugation/ValCitDau.py similarity index 100% rename from smiles/conjugation/ValCitDau.py rename to CupOFMoCA-PDC/smiles/conjugation/ValCitDau.py diff --git a/smiles/conjugation/VcMMAE.py b/CupOFMoCA-PDC/smiles/conjugation/VcMMAE.py similarity index 100% rename from smiles/conjugation/VcMMAE.py rename to CupOFMoCA-PDC/smiles/conjugation/VcMMAE.py diff --git a/smiles/conjugation/__init__.py b/CupOFMoCA-PDC/smiles/conjugation/__init__.py similarity index 100% rename from smiles/conjugation/__init__.py rename to CupOFMoCA-PDC/smiles/conjugation/__init__.py diff --git a/smiles/conjugation/pdc_builder.py b/CupOFMoCA-PDC/smiles/conjugation/pdc_builder.py similarity index 100% rename from smiles/conjugation/pdc_builder.py rename to CupOFMoCA-PDC/smiles/conjugation/pdc_builder.py diff --git a/smiles/evaluation/__init__.py b/CupOFMoCA-PDC/smiles/evaluation/__init__.py similarity index 100% rename from smiles/evaluation/__init__.py rename to CupOFMoCA-PDC/smiles/evaluation/__init__.py diff --git a/smiles/evaluation/metrics.py b/CupOFMoCA-PDC/smiles/evaluation/metrics.py similarity index 100% rename from smiles/evaluation/metrics.py rename to CupOFMoCA-PDC/smiles/evaluation/metrics.py diff --git a/smiles/evaluation/pdc_analyzer.py b/CupOFMoCA-PDC/smiles/evaluation/pdc_analyzer.py similarity index 100% rename from smiles/evaluation/pdc_analyzer.py rename to CupOFMoCA-PDC/smiles/evaluation/pdc_analyzer.py diff --git a/smiles/evaluation/peptide_analyzer.py b/CupOFMoCA-PDC/smiles/evaluation/peptide_analyzer.py similarity index 100% rename from smiles/evaluation/peptide_analyzer.py rename to CupOFMoCA-PDC/smiles/evaluation/peptide_analyzer.py diff --git a/smiles/evaluation/run_metrics.py b/CupOFMoCA-PDC/smiles/evaluation/run_metrics.py similarity index 100% rename from smiles/evaluation/run_metrics.py rename to CupOFMoCA-PDC/smiles/evaluation/run_metrics.py diff --git a/smiles/evaluation/run_metrics_uaa.py b/CupOFMoCA-PDC/smiles/evaluation/run_metrics_uaa.py similarity index 100% rename from smiles/evaluation/run_metrics_uaa.py rename to CupOFMoCA-PDC/smiles/evaluation/run_metrics_uaa.py diff --git a/smiles/generation/__init__.py b/CupOFMoCA-PDC/smiles/generation/__init__.py similarity index 100% rename from smiles/generation/__init__.py rename to CupOFMoCA-PDC/smiles/generation/__init__.py diff --git a/smiles/generation/cupofmoca_guided.py b/CupOFMoCA-PDC/smiles/generation/cupofmoca_guided.py similarity index 100% rename from smiles/generation/cupofmoca_guided.py rename to CupOFMoCA-PDC/smiles/generation/cupofmoca_guided.py diff --git a/smiles/generation/cupofmoca_guided_aa.py b/CupOFMoCA-PDC/smiles/generation/cupofmoca_guided_aa.py similarity index 100% rename from smiles/generation/cupofmoca_guided_aa.py rename to CupOFMoCA-PDC/smiles/generation/cupofmoca_guided_aa.py diff --git a/smiles/generation/cupofmoca_guided_uaa.py b/CupOFMoCA-PDC/smiles/generation/cupofmoca_guided_uaa.py similarity index 100% rename from smiles/generation/cupofmoca_guided_uaa.py rename to CupOFMoCA-PDC/smiles/generation/cupofmoca_guided_uaa.py diff --git a/smiles/generation/cupofmoca_staged.py b/CupOFMoCA-PDC/smiles/generation/cupofmoca_staged.py similarity index 100% rename from smiles/generation/cupofmoca_staged.py rename to CupOFMoCA-PDC/smiles/generation/cupofmoca_staged.py diff --git a/smiles/generation/cupofmoca_staged_aa.py b/CupOFMoCA-PDC/smiles/generation/cupofmoca_staged_aa.py similarity index 100% rename from smiles/generation/cupofmoca_staged_aa.py rename to CupOFMoCA-PDC/smiles/generation/cupofmoca_staged_aa.py diff --git a/smiles/generation/cupofmoca_staged_uaa.py b/CupOFMoCA-PDC/smiles/generation/cupofmoca_staged_uaa.py similarity index 100% rename from smiles/generation/cupofmoca_staged_uaa.py rename to CupOFMoCA-PDC/smiles/generation/cupofmoca_staged_uaa.py diff --git a/smiles/generation/guided.py b/CupOFMoCA-PDC/smiles/generation/guided.py similarity index 100% rename from smiles/generation/guided.py rename to CupOFMoCA-PDC/smiles/generation/guided.py diff --git a/smiles/generation/guided_aa.py b/CupOFMoCA-PDC/smiles/generation/guided_aa.py similarity index 100% rename from smiles/generation/guided_aa.py rename to CupOFMoCA-PDC/smiles/generation/guided_aa.py diff --git a/smiles/generation/guided_uaa.py b/CupOFMoCA-PDC/smiles/generation/guided_uaa.py similarity index 100% rename from smiles/generation/guided_uaa.py rename to CupOFMoCA-PDC/smiles/generation/guided_uaa.py diff --git a/smiles/generation/staged.py b/CupOFMoCA-PDC/smiles/generation/staged.py similarity index 100% rename from smiles/generation/staged.py rename to CupOFMoCA-PDC/smiles/generation/staged.py diff --git a/smiles/generation/staged_aa.py b/CupOFMoCA-PDC/smiles/generation/staged_aa.py similarity index 100% rename from smiles/generation/staged_aa.py rename to CupOFMoCA-PDC/smiles/generation/staged_aa.py diff --git a/smiles/generation/staged_uaa.py b/CupOFMoCA-PDC/smiles/generation/staged_uaa.py similarity index 100% rename from smiles/generation/staged_uaa.py rename to CupOFMoCA-PDC/smiles/generation/staged_uaa.py diff --git a/smiles/generation/unconditional.py b/CupOFMoCA-PDC/smiles/generation/unconditional.py similarity index 100% rename from smiles/generation/unconditional.py rename to CupOFMoCA-PDC/smiles/generation/unconditional.py diff --git a/smiles/models/__init__.py b/CupOFMoCA-PDC/smiles/models/__init__.py similarity index 100% rename from smiles/models/__init__.py rename to CupOFMoCA-PDC/smiles/models/__init__.py diff --git a/smiles/models/aa_helpers.py b/CupOFMoCA-PDC/smiles/models/aa_helpers.py similarity index 100% rename from smiles/models/aa_helpers.py rename to CupOFMoCA-PDC/smiles/models/aa_helpers.py diff --git a/smiles/models/dataloading_for_dynamic_batching.py b/CupOFMoCA-PDC/smiles/models/dataloading_for_dynamic_batching.py similarity index 100% rename from smiles/models/dataloading_for_dynamic_batching.py rename to CupOFMoCA-PDC/smiles/models/dataloading_for_dynamic_batching.py diff --git a/smiles/models/train.py b/CupOFMoCA-PDC/smiles/models/train.py similarity index 100% rename from smiles/models/train.py rename to CupOFMoCA-PDC/smiles/models/train.py diff --git a/smiles/scoring/__init__.py b/CupOFMoCA-PDC/smiles/scoring/__init__.py similarity index 100% rename from smiles/scoring/__init__.py rename to CupOFMoCA-PDC/smiles/scoring/__init__.py diff --git a/smiles/scoring/checkpoints/binding-affinity.pt b/CupOFMoCA-PDC/smiles/scoring/checkpoints/binding-affinity.pt similarity index 100% rename from smiles/scoring/checkpoints/binding-affinity.pt rename to CupOFMoCA-PDC/smiles/scoring/checkpoints/binding-affinity.pt diff --git a/smiles/scoring/checkpoints/hemolysis-xgboost.json b/CupOFMoCA-PDC/smiles/scoring/checkpoints/hemolysis-xgboost.json similarity index 100% rename from smiles/scoring/checkpoints/hemolysis-xgboost.json rename to CupOFMoCA-PDC/smiles/scoring/checkpoints/hemolysis-xgboost.json diff --git a/smiles/scoring/checkpoints/nonfouling-xgboost.json b/CupOFMoCA-PDC/smiles/scoring/checkpoints/nonfouling-xgboost.json similarity index 100% rename from smiles/scoring/checkpoints/nonfouling-xgboost.json rename to CupOFMoCA-PDC/smiles/scoring/checkpoints/nonfouling-xgboost.json diff --git a/smiles/scoring/checkpoints/solubility-xgboost.json b/CupOFMoCA-PDC/smiles/scoring/checkpoints/solubility-xgboost.json similarity index 100% rename from smiles/scoring/checkpoints/solubility-xgboost.json rename to CupOFMoCA-PDC/smiles/scoring/checkpoints/solubility-xgboost.json diff --git a/smiles/scoring/classifiers.py b/CupOFMoCA-PDC/smiles/scoring/classifiers.py similarity index 100% rename from smiles/scoring/classifiers.py rename to CupOFMoCA-PDC/smiles/scoring/classifiers.py diff --git a/smiles/scoring/functions/__init__.py b/CupOFMoCA-PDC/smiles/scoring/functions/__init__.py similarity index 100% rename from smiles/scoring/functions/__init__.py rename to CupOFMoCA-PDC/smiles/scoring/functions/__init__.py diff --git a/smiles/scoring/functions/binding.py b/CupOFMoCA-PDC/smiles/scoring/functions/binding.py similarity index 100% rename from smiles/scoring/functions/binding.py rename to CupOFMoCA-PDC/smiles/scoring/functions/binding.py diff --git a/smiles/scoring/functions/binding_utils.py b/CupOFMoCA-PDC/smiles/scoring/functions/binding_utils.py similarity index 100% rename from smiles/scoring/functions/binding_utils.py rename to CupOFMoCA-PDC/smiles/scoring/functions/binding_utils.py diff --git a/smiles/scoring/functions/hemolysis.py b/CupOFMoCA-PDC/smiles/scoring/functions/hemolysis.py similarity index 100% rename from smiles/scoring/functions/hemolysis.py rename to CupOFMoCA-PDC/smiles/scoring/functions/hemolysis.py diff --git a/smiles/scoring/functions/nonfouling.py b/CupOFMoCA-PDC/smiles/scoring/functions/nonfouling.py similarity index 100% rename from smiles/scoring/functions/nonfouling.py rename to CupOFMoCA-PDC/smiles/scoring/functions/nonfouling.py diff --git a/smiles/scoring/functions/scoring_utils.py b/CupOFMoCA-PDC/smiles/scoring/functions/scoring_utils.py similarity index 100% rename from smiles/scoring/functions/scoring_utils.py rename to CupOFMoCA-PDC/smiles/scoring/functions/scoring_utils.py diff --git a/smiles/scoring/functions/solubility.py b/CupOFMoCA-PDC/smiles/scoring/functions/solubility.py similarity index 100% rename from smiles/scoring/functions/solubility.py rename to CupOFMoCA-PDC/smiles/scoring/functions/solubility.py diff --git a/smiles/smiles_tokenizer/__init__.py b/CupOFMoCA-PDC/smiles/smiles_tokenizer/__init__.py similarity index 100% rename from smiles/smiles_tokenizer/__init__.py rename to CupOFMoCA-PDC/smiles/smiles_tokenizer/__init__.py diff --git a/smiles/smiles_tokenizer/check_lys_tokens.py b/CupOFMoCA-PDC/smiles/smiles_tokenizer/check_lys_tokens.py similarity index 100% rename from smiles/smiles_tokenizer/check_lys_tokens.py rename to CupOFMoCA-PDC/smiles/smiles_tokenizer/check_lys_tokens.py diff --git a/smiles/smiles_tokenizer/my_tokenizers.py b/CupOFMoCA-PDC/smiles/smiles_tokenizer/my_tokenizers.py similarity index 100% rename from smiles/smiles_tokenizer/my_tokenizers.py rename to CupOFMoCA-PDC/smiles/smiles_tokenizer/my_tokenizers.py diff --git a/smiles/smiles_tokenizer/new_splits.txt b/CupOFMoCA-PDC/smiles/smiles_tokenizer/new_splits.txt similarity index 100% rename from smiles/smiles_tokenizer/new_splits.txt rename to CupOFMoCA-PDC/smiles/smiles_tokenizer/new_splits.txt diff --git a/smiles/smiles_tokenizer/new_vocab.txt b/CupOFMoCA-PDC/smiles/smiles_tokenizer/new_vocab.txt similarity index 100% rename from smiles/smiles_tokenizer/new_vocab.txt rename to CupOFMoCA-PDC/smiles/smiles_tokenizer/new_vocab.txt diff --git a/third_party/SMILESToPeptide/LICENSE-p2smi b/CupOFMoCA-PDC/third_party/SMILESToPeptide/LICENSE-p2smi similarity index 100% rename from third_party/SMILESToPeptide/LICENSE-p2smi rename to CupOFMoCA-PDC/third_party/SMILESToPeptide/LICENSE-p2smi diff --git a/third_party/SMILESToPeptide/__init__.py b/CupOFMoCA-PDC/third_party/SMILESToPeptide/__init__.py similarity index 100% rename from third_party/SMILESToPeptide/__init__.py rename to CupOFMoCA-PDC/third_party/SMILESToPeptide/__init__.py diff --git a/third_party/SMILESToPeptide/aminoacid_selective.py b/CupOFMoCA-PDC/third_party/SMILESToPeptide/aminoacid_selective.py similarity index 100% rename from third_party/SMILESToPeptide/aminoacid_selective.py rename to CupOFMoCA-PDC/third_party/SMILESToPeptide/aminoacid_selective.py diff --git a/third_party/SMILESToPeptide/peptide_to_smiles.py b/CupOFMoCA-PDC/third_party/SMILESToPeptide/peptide_to_smiles.py similarity index 100% rename from third_party/SMILESToPeptide/peptide_to_smiles.py rename to CupOFMoCA-PDC/third_party/SMILESToPeptide/peptide_to_smiles.py diff --git a/third_party/SMILESToPeptide/swisssidechain.py b/CupOFMoCA-PDC/third_party/SMILESToPeptide/swisssidechain.py similarity index 100% rename from third_party/SMILESToPeptide/swisssidechain.py rename to CupOFMoCA-PDC/third_party/SMILESToPeptide/swisssidechain.py diff --git a/third_party/__init__.py b/CupOFMoCA-PDC/third_party/__init__.py similarity index 100% rename from third_party/__init__.py rename to CupOFMoCA-PDC/third_party/__init__.py diff --git a/README.md b/README.md index 9a3f12d40cf1b390f88693d7ba52699525bb34e9..0f0bb860f404a2f861975f92a27e3619065d1b59 100644 --- a/README.md +++ b/README.md @@ -8,221 +8,52 @@ tags: - peptide - discrete-flow - peptide-drug-conjugate + - protac --- # CupOFMoCA -Code and PDC model artifacts for **CupOFMoCA: Coupled Objective-Guided Discrete Flows for +Code and model artifacts for **CupOFMoCA: Coupled Objective-Guided Discrete Flows for Molecular Conjugate Assembly** (NeurIPS 2026). -CupOFMoCA performs coupled, objective-guided discrete-flow generation while enforcing chemical -assembly constraints. This release supports the paper's peptide-drug conjugate (PDC) experiments -across SMILES, natural amino-acid (AA), and unnatural amino-acid (UAA) representations. +CupOFMoCA performs coupled, objective-guided discrete-flow generation while enforcing +cross-component chemical assembly constraints during sampling. The paper covers two +conjugate modalities, and this repository holds one self-contained release for each. -## Model overview - -![CupOFMoCA overview](assets/CupOFMoCA.gif) - -CupOFMoCA is a research pipeline for generating peptide-drug conjugate candidates. It couples a -pretrained discrete-flow generator with property guidance and conjugation-validity checks during -sampling. This repository contains three generator checkpoints and the property scorers used by the -released PDC pipeline: - -| Checkpoint | Representation | Role | +| Folder | Modality | Paper sections | |---|---|---| -| `SMILESReDi_base.ckpt` | peptide SMILES | pretrained SMILES discrete-flow generator | -| `PepReDi_base.pt` | canonical amino acids | pretrained AA discrete-flow generator | -| `UAAReDi_base.pt` | extended amino-acid vocabulary | pretrained UAA discrete-flow generator | - -The checkpoints are loaded by the repository's custom PyTorch code; this is not a Transformers -pipeline and does not provide a hosted-inference widget. - -### Intended uses - -- Reproduce and inspect the paper's PDC generation experiments. -- Generate computational PDC candidates for research and method development. -- Extend or compare constrained, multi-objective molecular-generation methods. - -The release is not intended for clinical decisions, direct therapeutic use, or as a substitute for -chemical synthesis, experimental validation, toxicology, or safety assessment. - -### Training data - -- **AA-PepReDi:** peptides from PepNN and BioLip2, together with 6--49-residue sequences from - PPIRef, using an 80:10:10 train/validation/test split. -- **UAA-PepReDi:** 150,000 synthetic sequences constructed with `p2smi` across combinations of - non-canonical and D-amino-acid composition, using an 80:10:10 split. -- **SMILESReDi:** the released pretrained SMILESReDi weights are used without additional - CupOFMoCA fine-tuning. - -Architecture, optimization, data construction, and scorer details are reported in Appendix E of -the paper. Training datasets are not redistributed in this repository. - -### Evaluation - -The paper evaluates generated PDCs for assembly validity and predicted functional properties across -ERBB2, GNRHR, and NRP1, using SMILES, AA, and UAA representations. The reported results and -experimental protocol are in the paper; the submitted evaluation routines are included under -`smiles/evaluation/`. - -### Limitations - -- Outputs and objective values are computational predictions, not experimentally validated - compounds or guarantees of efficacy, synthesizability, toxicity, or safety. -- The released configurations cover three receptor targets and fixed target-specific conjugation - chemistries; performance outside this scope has not been established. -- The release contains the paper's PDC stack only. Its PROTAC experiments require separate code and - artifacts. -- Results can vary with hardware, CUDA/PyTorch versions, and revisions of models downloaded at - runtime. +| [`CupOFMoCA-PDC/`](CupOFMoCA-PDC) | Peptide-drug conjugates, across SMILES, AA and UAA representations | Section 4, Appendices A, C, E, F, G | +| [`CupOFMoCA-PROTAC/`](CupOFMoCA-PROTAC) | PROTAC linker generation between fixed warhead and E3 anchors | Section 5, Appendices B, H, I, J | -## Repository layout +Each folder is independent: its own `README.md`, `checkpoints/`, `configs/paper.json` +with the settings used for the reported runs, `environment.yml`, and a +`docs/artifacts.json` manifest verified by `scripts/verify_release.py`. -```text -checkpoints/ generator weights -configs/ paper settings and target sequences -docs/ model-artifact details and checksums -scripts/run_experiment.py unified experiment runner -scripts/verify_release.py release integrity checker -smiles/ - generation/ generation entry points - evaluation/ metrics and analyzers - models/ ReDi model and data code - conjugation/ PDC assembly builders - scoring/ property scorers - smiles_tokenizer/ tokenizer code and vocabulary -third_party/ peptide-to-SMILES conversion helper -``` - -The release currently covers the PDC implementation. The PROTAC experiments described in the paper -use a separate code and artifact stack that is not included here. - -## 1. Environment - -A CUDA GPU is strongly recommended. The tested environment used Python 3.9, PyTorch 2.5.1, and -CUDA 12.1. +The checkpoints are loaded by this repository's own PyTorch code. This is not a +Transformers pipeline and provides no hosted-inference widget. -```bash -conda env create -f environment.yml -conda activate cupofmoca -``` - -Alternatively, install a PyTorch build appropriate for your CUDA driver and then install the pinned -packages: - -```bash -pip install -r requirements.txt -``` - -On first use, Transformers downloads `facebook/esm2_t33_650M_UR50D` and -`aaronfeller/PeptideCLM-23M-all` from Hugging Face. Set `HF_HOME` to a persistent cache if needed. - -Verify the bundled artifacts and source paths before running an experiment: +## Getting started ```bash +hf download ChatterjeeLab/CupOFMoCA --include "CupOFMoCA-PROTAC/*" --local-dir . +cd CupOFMoCA-PROTAC python scripts/verify_release.py ``` -## 2. Run PDC generation - -Run commands from the repository root. Preview a configured command without loading models: - -```bash -python scripts/run_experiment.py \ - --representation uaa \ - --variant cupofmoca \ - --method guided \ - --target NRP1 \ - --dry-run -``` - -Run the experiment: - -```bash -python scripts/run_experiment.py \ - --representation uaa \ - --variant cupofmoca \ - --method guided \ - --target NRP1 -``` - -Run a small smoke test: - -```bash -python scripts/run_experiment.py \ - --representation aa --variant baseline --method staged --target ERBB2 \ - --num-candidates 1 -``` - -Outputs are written under `outputs/` in separate run directories. Existing outputs are protected -unless `--force` is supplied. Arguments after `--` are passed to the underlying generator: - -```bash -python scripts/run_experiment.py \ - --representation smiles --variant cupofmoca --method guided --target GNRHR \ - -- --top_k 100 -``` - -### 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 | - -AA and UAA runs use length 10. Shared settings include 128 optimization steps, top-p 1.0, -objective weights `[1, 1]`, and acceptance sampling with beta 50 for CupOFMoCA. The machine-readable -configuration is in `configs/paper.json`; target sequences are in `configs/targets.fasta`. - -### Direct entry points - -The full argument surfaces remain available under `smiles/generation/`: - -```text -guided.py cupofmoca_guided.py -guided_aa.py cupofmoca_guided_aa.py -guided_uaa.py cupofmoca_guided_uaa.py -staged.py cupofmoca_staged.py -staged_aa.py cupofmoca_staged_aa.py -staged_uaa.py cupofmoca_staged_uaa.py -``` - -Run one directly as a module, for example: +Swap the prefix for `CupOFMoCA-PDC/*` to fetch the peptide-drug conjugate release +instead. Each folder's `README.md` carries its own setup and generation commands. -```bash -python -m smiles.generation.cupofmoca_guided_uaa --help -``` +## Intended uses -`smiles/evaluation/run_metrics.py` and `smiles/evaluation/run_metrics_uaa.py` contain the submitted evaluation routines. -Use `python --help` to inspect their arguments. - -## 3. Included checkpoints - -The release includes the SMILES, AA, and UAA generator weights together with the binding, -hemolysis, non-fouling, and solubility scorers needed by the PDC pipeline. Artifact roles, sizes, and -SHA-256 values are listed in [docs/ARTIFACTS.md](docs/ARTIFACTS.md). - -The AA-input affinity predictor is not included because the PDC generation configuration uses the -bundled SMILES-input scorer (`--affinity_type smiles`). - -Large `*.pt` and `*.ckpt` files are configured for Git LFS. The repository is approximately 1.9 GB -before environment and model-cache downloads. - -The checkpoint formats are loaded through PyTorch. As with any pickle-backed PyTorch artifact, -only load weights obtained from a source you trust. - -## 4. Notes +- Reproduce and inspect the paper's PDC and PROTAC generation experiments. +- Generate computational conjugate candidates for research and method development. +- Extend or compare constrained, multi-objective molecular-generation methods. -- The paper reports NVIDIA RTX A6000 48 GB GPUs. Lower-memory devices may require smaller batches. -- Exact bitwise output can vary across CUDA, PyTorch, GPU, and downloaded model revisions. -- Generated structures are computational hypotheses that require experimental validation. Property - models are predictors, not clinical or safety guarantees. -- The peptide-to-SMILES helper used by the experiments is vendored under `third_party/` with its - upstream license notice. +This release is not intended for clinical decisions, direct therapeutic use, or as a +substitute for chemical synthesis, experimental validation, toxicology, or safety +assessment. Outputs and objective values are computational predictions, not validated +compounds or guarantees of efficacy, synthesizability, toxicity or safety. -## 5. Citation and license +## Citation -Citation metadata is provided in `CITATION.cff`. The repository code is released under Apache-2.0; -see `LICENSE` and `NOTICE`. Third-party components and downloaded model artifacts retain their -respective terms. +See `CITATION.cff` in either release folder.