Rewrite README

CupOFMoCA-PDC/README.md

@@ -1,129 +1,71 @@
----
-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 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.
+# CupOFMoCA for peptide-drug conjugates
 
-### Evaluation
+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 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/`.
+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.
 
-### Limitations
+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.
 
-- 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.
+## Representations and checkpoints
 
-## 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
-```
+| 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 currently covers the PDC implementation. The PROTAC experiments described in the paper
-use a separate code and artifact stack that is not included here.
+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.
 
-## 1. Environment
+## Installation
 
-A CUDA GPU is strongly recommended. The tested environment used Python 3.9, PyTorch 2.5.1, and
-CUDA 12.1.
+Run the following commands from this folder.
 
 ```bash
 conda env create -f environment.yml
 conda activate cupofmoca
+python scripts/verify_release.py
 ```
 
-Alternatively, install a PyTorch build appropriate for your CUDA driver and then install the pinned
-packages:
+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
 ```
 
-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.
+## Target configurations
 
-Verify the bundled artifacts and source paths before running an experiment:
+| 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 |
 
-```bash
-python scripts/verify_release.py
-```
+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.
 
-## 2. Run PDC generation
+## Run generation
 
-Run commands from the repository root. Preview a configured command without loading models:
+`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 \
@@ -134,7 +76,7 @@ python scripts/run_experiment.py \
   --dry-run
 ```
 
-Run the experiment:
+Remove `--dry-run` to launch the complete configured experiment.
 
 ```bash
 python scripts/run_experiment.py \
@@ -144,83 +86,150 @@ python scripts/run_experiment.py \
   --target NRP1
 ```
 
-Run a small smoke test:
+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 \
+  --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:
+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 \
+  --representation smiles \
+  --variant cupofmoca \
+  --method guided \
+  --target GNRHR \
   -- --top_k 100
 ```
 
-### Configurations
+Each seed receives a separate output directory with the following organization.
 
-| 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 |
+```text
+outputs/
+  <target>/
+    <representation>/
+      <variant>_<method>/
+        seed_<seed>/
+          molecules.txt
+          logs/
+```
 
-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 generation modules
 
-### Direct entry points
+The wrapper dispatches to the modules under `smiles/generation/`. Their complete argument
+surfaces remain available for method development and custom experiments.
 
-The full argument surfaces remain available under `smiles/generation/`:
+| 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` |
 
-```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
+Invoke a module with `--help` to inspect its parameters.
+
+```bash
+python -m smiles.generation.cupofmoca_guided_uaa --help
 ```
 
-Run one directly as a module, for example:
+## 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 -m smiles.generation.cupofmoca_guided_uaa --help
+python smiles/evaluation/run_metrics.py --help
+python smiles/evaluation/run_metrics_uaa.py --help
 ```
 
-`smiles/evaluation/run_metrics.py` and `smiles/evaluation/run_metrics_uaa.py` contain the submitted evaluation routines.
-Use `python <file> --help` to inspect their arguments.
+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.
 
-## 3. Included checkpoints
+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 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 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.
 
-The AA-input affinity predictor is not included because the PDC generation configuration uses the
-bundled SMILES-input scorer (`--affinity_type smiles`).
+## Artifact verification
 
-Large `*.pt` and `*.ckpt` files are configured for Git LFS. The repository is approximately 1.9 GB
-before environment and model-cache downloads.
+The integrity checker validates byte counts, SHA-256 hashes, and portability-sensitive
+source paths.
 
-The checkpoint formats are loaded through PyTorch. As with any pickle-backed PyTorch artifact,
-only load weights obtained from a source you trust.
+```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.
 
-## 4. Notes
+## Repository structure
 
-- 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.
+```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
+```
 
-## 5. Citation and license
+## 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.
+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/`.

CupOFMoCA-PROTAC/README.md

@@ -1,122 +1,247 @@
-# CupOFMoCA — PROTAC
+# CupOFMoCA for PROTACs
 
-Code and PROTAC model artifacts for **CupOFMoCA: Coupled Objective-Guided Discrete Flows for
-Molecular Conjugate Assembly** (NeurIPS 2026).
+This folder contains the PROTAC linker-generation code, model weights, validity
+classifiers, target builders, paper configurations, and reported outputs for
+**CupOFMoCA: Coupled Objective-Guided Discrete Flows for Molecular Conjugate Assembly**.
 
-This release supports the paper's PROTAC experiments: linker generation between a fixed
-warhead and a fixed E3 ligand, under hard assembly-validity constraints and objective
-guidance. For the peptide-drug conjugate half, see [`CupOFMoCA-PDC/`](../CupOFMoCA-PDC).
+The PROTAC workflow holds the warhead and E3-ligand subgraphs fixed and edits the linker
+subgraph with a DeFoG discrete flow-matching model. CupOFMoCA applies a hard assembly gate
+and three soft property objectives during sampling.
 
-## Model overview
+The [main README](../README.md) provides the shared project overview and a quickstart for
+both conjugate modalities. This guide covers the PROTAC targets, objective functions,
+commands, artifacts, evaluation programs, and molecular-dynamics workflow in greater
+detail.
 
-The generator is a DeFoG discrete flow-matching model over molecular graphs, fine-tuned on
-PROTAC-DB linkers. The warhead and E3-ligand subgraphs are held fixed throughout sampling;
-only the linker subgraph is edited.
+## Model and objectives
 
-| Checkpoint | Role |
+| Artifact | Role |
 |---|---|
-| `checkpoints/protac_linker_finetune/epoch=99-v1.ckpt` | DeFoG graph discrete-flow generator, fine-tuned for 100 epochs on 2,070 PROTAC-DB linker graphs |
-| `src/classifier/protac_linker_clf.pkl` | generic linker validity/quality classifier |
-| `src/classifier/protac_linker_clf_{ErlotinibVHL,BRD9VHL,CDK6CRBN}.pkl` | target-specific classifiers, auto-selected by `--protac_module` |
+| `checkpoints/protac_linker_finetune/epoch=99-v1.ckpt` | DeFoG graph generator fine-tuned for 100 epochs on 2,070 PROTAC-DB linker graphs |
+| `src/classifier/protac_linker_clf.pkl` | generic linker validity and quality classifier |
+| `src/classifier/protac_linker_clf_ErlotinibVHL.pkl` | EGFR-VHL target-specific classifier |
+| `src/classifier/protac_linker_clf_BRD9VHL.pkl` | BRD9-VHL target-specific classifier |
+| `src/classifier/protac_linker_clf_CDK6CRBN.pkl` | CDK6-CRBN target-specific classifier |
 
-The checkpoint is loaded by this repository's own PyTorch code. This is not a Transformers
-pipeline and provides no hosted-inference widget.
+The generator applies the validity classifier as a hard mask before exponential tilting.
+Three soft scores define the weighted objective used for the reported runs.
 
-## Quickstart
+| Position | Score | Paper weight |
+|---|---|---|
+| 1 | synthetic accessibility | 4.0 |
+| 2 | PROTAC-DB chemotype closeness across logP, molecular weight, rotatable bonds, and ether count | 2.0 |
+| 3 | linker connectivity | 4.0 |
+
+The `--weights` option accepts these values in the table order. The hard validity gate
+acts before weighted scoring and sits outside the three-value objective vector.
+
+## Installation
+
+Run the following commands from this folder.
 
 ```bash
-hf download ChatterjeeLab/CupOFMoCA --include "CupOFMoCA-PROTAC/*" --local-dir .
-cd CupOFMoCA-PROTAC
-conda env create -f environment.yml && conda activate defog
+conda env create -f environment.yml
+conda activate defog
 pip install -e src/defog
 python scripts/verify_release.py
 ```
 
-Generate 100 EGFR-VHL PROTACs with the reported configuration (one of three seeds):
+The tested environment uses Python 3.9, PyTorch 2.4.0, and CUDA 12.1. A CUDA GPU is
+recommended for full generation experiments.
+
+## Target systems
+
+| Reported system | `--protac_module` | Warhead | E3 ligand |
+|---|---|---|---|
+| EGFR-VHL | `ErlotinibVHL` | gefitinib-piperazine from MS39 | VH032 |
+| BRD9-VHL | `BRD9VHL` | BI-7273-piperazine | VH032 |
+| CDK6-CRBN | `CDK6CRBN` | palbociclib-piperazine | pomalidomide |
+
+Each module under `src/protac/` defines the fixed molecular fragments, reactive SMARTS,
+and assembly builder for its system.
+
+## Run generation
+
+The following command generates 100 EGFR-VHL candidates with seed 42 and the reported
+configuration. Run it from the `scripts/` directory.
 
 ```bash
 cd scripts
 python generate.py \
   --checkpoint ../checkpoints/protac_linker_finetune/epoch=99-v1.ckpt \
-  --protac_module ErlotinibVHL --fix_termini cooh --fast_scoring \
-  --num_samples 100 --num_batches 1 --num_steps 1500 --warmup_steps 100 \
-  --weights 4.0 2.0 4.0 --seed 42 \
-  --output_file ./protac_linkers_egfrvhl.smi --output_dir ../generation_logs
+  --protac_module ErlotinibVHL \
+  --fix_termini cooh \
+  --fast_scoring \
+  --num_samples 100 \
+  --num_batches 1 \
+  --num_steps 1500 \
+  --warmup_steps 100 \
+  --weights 4.0 2.0 4.0 \
+  --seed 42 \
+  --output_file ./protac_linkers_egfrvhl.smi \
+  --output_dir ../generation_logs
 ```
 
-Swap `--protac_module` for `BRD9VHL` or `CDK6CRBN` for the other two systems. Every
-setting above is recorded in `configs/paper.json`.
+Use `BRD9VHL` or `CDK6CRBN` as the module name for the other reported target systems.
+Seeds 42, 123, and 456 reproduce the paper's three generation batches. The complete
+configuration in `configs/paper.json` records 100 candidates per seed, 1,500 sampling
+steps, 100 warmup steps, guidance strength 5.0, top-k 50, weighted position sampling,
+and the objective weights shown above.
+
+The generator writes assembled PROTAC SMILES to the selected `--output_file` and detailed
+sampling records under `--output_dir`. Run the help command for the full set of graph,
+guidance, scoring, and output controls.
+
+```bash
+python generate.py --help
+```
+
+## Evaluate generated candidates
+
+`evaluate_linkers.py` assembles each candidate with the selected anchors and computes
+structural validity, linker properties, assembled-PROTAC properties, and available
+degradation scores.
+
+```bash
+python evaluate_linkers.py protac_linkers_egfrvhl.smi \
+  --protac-module ErlotinibVHL \
+  --out protac_linkers_egfrvhl_scored.csv
+```
+
+`batch_report.py` compares one or more generation-summary files and can save a figure.
+
+```bash
+python batch_report.py ../generation_logs/*_summary.csv \
+  --protac-module ErlotinibVHL \
+  --out batch_report.png
+```
 
-`--weights` is positional over the three soft scorers: synthetic accessibility,
-PROTAC-DB chemotype closeness, connectivity. The validity classifier is applied as a hard
-mask and takes no weight.
+The paper evaluates assembly validity, predicted degradation, molecular diversity,
+training-set similarity, and physicochemical properties for EGFR-VHL, BRD9-VHL, and
+CDK6-CRBN. [`results/README.md`](results/README.md) maps the archived outputs to the paper
+tables and records the aggregation conventions.
 
-### Intended uses
+The archived weight-ablation outputs preserve an earlier five-slot representation of the
+objective. The active terms correspond to synthetic accessibility, chemotype closeness,
+and connectivity with weights 4, 2, and 4. The current generator accepts those three live
+weights directly.
 
-- Reproduce and inspect the paper's PROTAC generation experiments.
-- Generate computational PROTAC linker candidates for research and method development.
-- Extend or compare constrained, multi-objective molecular-generation methods.
+## Optional evaluation components
 
-The release is not intended for clinical decisions, direct therapeutic use, or as a
-substitute for chemical synthesis, experimental validation, toxicology, or safety
-assessment.
+DegradeMaster supplies predicted degradation scores, and EGFR-PROPK supplies the EGFR
+pharmacokinetic columns. The fetch program retrieves both components at the commits used
+for the paper.
 
-### Training data
+```bash
+cd ..
+python scripts/fetch_third_party.py
+```
 
-The generator is the released DeFoG GuacaMol checkpoint fine-tuned on 2,070 PROTAC-DB
-linker graphs (258 validation, 260 test). `data/linker.csv` is the derived linker table.
-Architecture, optimization and scorer details are in Appendix H of the paper. Training
-datasets are not redistributed beyond that derived table.
+Generation uses the bundled checkpoint, builders, and classifiers. The optional
+components extend evaluation after generation. Their upstream licensing and pinned
+revisions are recorded in `NOTICE` and `scripts/fetch_third_party.py`.
 
-### Evaluation
+DegradeMaster uses data derived from overlapping PROTAC databases, which makes its
+reported degradation analysis an in-domain model evaluation. Interpret these scores as
+computational prioritization measurements within that setting.
 
-The paper evaluates generated PROTACs on EGFR-VHL, BRD9-VHL and CDK6-CRBN for standard
-and assembly validity, predicted degradation, diversity and training-set similarity. The
-runs behind those tables are in `results/`, documented in `results/README.md`. Predicted
-degradation requires DegradeMaster, which is fetched rather than redistributed — see below.
+## Training data
 
-### Limitations
+The generator starts from the released DeFoG GuacaMol checkpoint and was fine-tuned on
+2,070 PROTAC-DB linker graphs. The validation and test partitions contain 258 and 260
+graphs, respectively. `data/linker.csv` provides the derived linker table used by this
+release. Appendix H describes the architecture, optimization procedure, data processing,
+and scorers.
 
-- Outputs and objective values are computational predictions, not experimentally validated
-  compounds or guarantees of efficacy, synthesizability, toxicity or safety.
-- The released configurations cover three target/E3 systems with fixed anchor chemistry;
-  performance outside this scope has not been established.
-- Predicted degradation comes from a model trained on overlapping PROTAC databases, so it
-  is an in-domain evaluation rather than an independent one.
-- `scripts/runs/ablation_egfr.py` sweeps five weight slots, but the current `generate.py`
-  exposes three; the Morgan-fingerprint row of the weight ablation is documented by the
-  archived outputs in `results/` rather than re-runnable as-is.
-- Results can vary with hardware and CUDA/PyTorch versions.
+## Reported outputs
 
-## Repository layout
+The `results/` directory contains the generation outputs and scored summaries used in the
+paper's PROTAC tables.
 
 ```text
-checkpoints/              generator weights
-configs/paper.json        the settings used for the reported runs
-data/linker.csv           PROTAC-DB derived linker table
-docs/                     artifact manifest (ARTIFACTS.md, artifacts.json)
-md/                       explicit-solvent molecular dynamics pipeline
-results/                  generation outputs behind the reported tables
-scripts/                  generate.py, batch_report.py, evaluate_linkers.py,
-                          fetch_third_party.py, verify_release.py, runs/
-src/protac/               per-target warhead + E3 builders
-src/classifier/           validity gate, analyzer, classifiers
-src/defog/                DeFoG discrete flow model (MIT, see src/defog/LICENSE)
+results/
+  ablation_all/             EGFR-VHL constraint, guidance, and fine-tuning studies
+  ablation_targets/         BRD9-VHL and CDK6-CRBN target studies
+  README.md                 table mapping and aggregation details
 ```
 
-## Third-party components
+The reported runs use seeds 42, 123, and 456 with 100 candidates per seed. The archived
+files contain the per-seed results, pooled summaries, and scored per-molecule tables
+described in `results/README.md`.
 
-DeFoG is redistributed here under MIT. Two optional components — DegradeMaster
-(degradation scoring) and EGFR-PROPK (EGFR-only PK columns) — are published upstream
-without a license and so are **not** redistributed. Fetch them at the pinned commits used
-for the paper:
+## Molecular dynamics
+
+The `md/` folder contains the explicit-solvent workflow used to analyze generated PROTAC
+conformations in water and chloroform. The analyses cover radius of gyration, three-
+dimensional polar surface area, intramolecular hydrogen bonds, ternary span, and
+conformational-state populations.
+
+Create the dedicated environment and inspect the MD guide before launching trajectories.
 
 ```bash
-python scripts/fetch_third_party.py
+conda env create -f md/environment_md.yml
+conda activate protacmd
+cd md
+python protac_md.py --solvent chloroform --replicas 3 --prod-ns 50 --gpu 0
+python analyze_conformations.py \
+  --dir egfrvhl_rank4/chloroform \
+  --name egfrvhl_rank4
 ```
 
-Linker generation does not require either. See `NOTICE` for the full statement.
+[`md/README.md`](md/README.md) documents the complete workflow, and
+[`md/reference_protocol.md`](md/reference_protocol.md) records the simulation protocol.
+
+## 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 checker also reports the availability of the optional evaluation components.
+
+PyTorch loads the bundled generator checkpoint through its serialized checkpoint
+interface. Use weights from a trusted release location and verify their hashes before
+loading.
+
+## Research scope
+
+The released paper configurations cover three target and E3-ligase systems with fixed
+anchor chemistry. All generated structures and objective values are computational
+predictions. Synthesis, biochemical and cellular testing, toxicology, and safety
+assessment establish the experimental properties of candidates selected for further
+study.
+
+Hardware, CUDA, and PyTorch revisions can introduce numerical variation across repeated
+runs.
+
+## Repository structure
+
+```text
+checkpoints/              fine-tuned DeFoG generator weights
+configs/paper.json        settings used for the reported runs
+data/linker.csv           PROTAC-DB-derived linker table
+docs/                     artifact documentation and checksums
+md/                       explicit-solvent molecular-dynamics workflow
+results/                  generation outputs used in the paper tables
+scripts/
+  generate.py             guided linker generation
+  evaluate_linkers.py     candidate assembly and scoring
+  batch_report.py         multi-run summaries and plots
+  fetch_third_party.py    pinned optional evaluation components
+  verify_release.py       release integrity checker
+src/classifier/           validity gate, analyzers, and classifiers
+src/defog/                DeFoG discrete flow model
+src/protac/               target-specific warhead and E3 builders
+```
 
-## Citation
+## Citation and license
 
-See `CITATION.cff`.
+Citation metadata is available in [`CITATION.cff`](CITATION.cff). The CupOFMoCA code is
+released under Apache-2.0 through `LICENSE` and `NOTICE`. The bundled DeFoG code retains
+its MIT license under `src/defog/LICENSE`. Optional upstream components retain their own
+terms.

README.md

@@ -13,49 +13,201 @@ tags:
 
 # CupOFMoCA
 
-Code and model artifacts for **CupOFMoCA: Coupled Objective-Guided Discrete Flows for
-Molecular Conjugate Assembly** (NeurIPS 2026).
+Code, model weights, configurations, and reported outputs for **CupOFMoCA: Coupled
+Objective-Guided Discrete Flows for Molecular Conjugate Assembly** (NeurIPS 2026).
 
 ![CupOFMoCA overview](assets/CupOFMoCA.gif)
 
-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.
+Molecular conjugates derive their function from interactions among multiple chemical
+components. CupOFMoCA uses discrete flows to generate coupled components, enforce
+assembly-validity constraints throughout sampling, and guide local transitions with
+property objectives. This release supports the two conjugate modalities studied in the
+paper.
 
-| Folder | Modality | Paper sections |
+| Folder | Generated component | Representations or systems |
 |---|---|---|
-| [`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 |
+| [`CupOFMoCA-PDC/`](CupOFMoCA-PDC) | peptide carrier assembled with a fixed payload and linker chemistry | SMILES, natural amino acids, and unnatural amino acids for ERBB2, GNRHR, and NRP1 |
+| [`CupOFMoCA-PROTAC/`](CupOFMoCA-PROTAC) | linker connecting fixed target-binding and E3-ligase anchors | EGFR-VHL, BRD9-VHL, and CDK6-CRBN |
 
-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`.
+Each modality folder provides its own environment, paper configuration, model artifacts,
+generation programs, integrity checker, and detailed README. The sections below contain
+the shared setup, representative commands, and the information needed to choose and run
+either modality.
 
-The checkpoints are loaded by this repository's own PyTorch code. This is not a
-Transformers pipeline and provides no hosted-inference widget.
+## Download
 
-## Getting started
+Install the [Hugging Face CLI](https://huggingface.co/docs/huggingface_hub/guides/cli)
+and download the complete release with the following commands.
+
+```bash
+hf download ChatterjeeLab/CupOFMoCA --local-dir CupOFMoCA
+cd CupOFMoCA
+```
+
+A modality-specific download reduces local storage use.
+
+```bash
+hf download ChatterjeeLab/CupOFMoCA \
+  --include "CupOFMoCA-PDC/*" \
+  --local-dir CupOFMoCA
+```
+
+Replace `CupOFMoCA-PDC/*` with `CupOFMoCA-PROTAC/*` for the PROTAC release.
+
+## Choose a workflow
+
+Use the PDC workflow to generate peptide carriers in one of three molecular
+representations and assemble them with the target-specific payload chemistry. Use the
+PROTAC workflow to generate a molecular-graph linker between a fixed warhead and a fixed
+E3 ligand.
+
+| Capability | PDC | PROTAC |
+|---|---|---|
+| Base generator | SMILESReDi, PepReDi, or UAAReDi | DeFoG fine-tuned on PROTAC-DB linkers |
+| Generated object | peptide carrier | linker subgraph |
+| Fixed context | payload and conjugation chemistry | warhead and E3-ligand subgraphs |
+| Released systems | ERBB2, GNRHR, NRP1 | EGFR-VHL, BRD9-VHL, CDK6-CRBN |
+| Paper settings | `CupOFMoCA-PDC/configs/paper.json` | `CupOFMoCA-PROTAC/configs/paper.json` |
+| Detailed guide | [`CupOFMoCA-PDC/README.md`](CupOFMoCA-PDC/README.md) | [`CupOFMoCA-PROTAC/README.md`](CupOFMoCA-PROTAC/README.md) |
+
+Both workflows use custom PyTorch generation code and local checkpoints. A CUDA GPU is
+recommended for generation. The released environments use Python 3.9 and CUDA 12.1.
+
+## PDC quickstart
+
+From the release root, create the PDC environment and verify the bundled artifacts.
+
+```bash
+cd CupOFMoCA-PDC
+conda env create -f environment.yml
+conda activate cupofmoca
+python scripts/verify_release.py
+```
+
+Preview the configured NRP1 UAA experiment, then run it from the PDC folder.
+
+```bash
+python scripts/run_experiment.py \
+  --representation uaa \
+  --variant cupofmoca \
+  --method guided \
+  --target NRP1 \
+  --dry-run
+
+python scripts/run_experiment.py \
+  --representation uaa \
+  --variant cupofmoca \
+  --method guided \
+  --target NRP1
+```
+
+The runner supports `smiles`, `aa`, and `uaa` representations; `guided` and `staged`
+sampling methods; and `ERBB2`, `GNRHR`, and `NRP1` targets. It writes each seed to a
+separate directory under `outputs/`. The PDC guide documents the complete command
+surface, checkpoints, target chemistries, and evaluation programs.
+
+## PROTAC quickstart
+
+From the release root, create the PROTAC environment, install the bundled DeFoG package,
+and verify the release.
 
 ```bash
-hf download ChatterjeeLab/CupOFMoCA --include "CupOFMoCA-PROTAC/*" --local-dir .
 cd CupOFMoCA-PROTAC
+conda env create -f environment.yml
+conda activate defog
+pip install -e src/defog
 python scripts/verify_release.py
 ```
 
-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.
+Generate 100 EGFR-VHL candidates with one reported seed.
+
+```bash
+cd scripts
+python generate.py \
+  --checkpoint ../checkpoints/protac_linker_finetune/epoch=99-v1.ckpt \
+  --protac_module ErlotinibVHL \
+  --fix_termini cooh \
+  --fast_scoring \
+  --num_samples 100 \
+  --num_batches 1 \
+  --num_steps 1500 \
+  --warmup_steps 100 \
+  --weights 4.0 2.0 4.0 \
+  --seed 42 \
+  --output_file ./protac_linkers_egfrvhl.smi \
+  --output_dir ../generation_logs
+```
+
+Set `--protac_module` to `BRD9VHL` or `CDK6CRBN` for the other reported systems.
+The PROTAC guide explains the three objective weights, target builders, evaluation
+programs, archived paper outputs, and molecular-dynamics workflow.
+
+## Paper configurations
+
+The machine-readable configuration files record the settings used for the reported
+experiments. Both modalities use seeds 42, 123, and 456 with 100 candidates per seed.
+
+The PDC configuration uses 128 optimization steps, equal objective weights, and a
+target-specific conjugation builder. SMILES sequence lengths are 80 for ERBB2 and GNRHR
+and 100 for NRP1. AA and UAA experiments use length 10.
+
+The PROTAC configuration uses 1,500 sampling steps, 100 warmup steps, a hard validity
+gate, and soft-objective weights of 4.0 for synthetic accessibility, 2.0 for PROTAC-DB
+chemotype closeness, and 4.0 for connectivity.
 
-## Intended uses
+## Artifacts and reproducibility
 
-- 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.
+Run the integrity checker inside a modality folder before generation.
 
-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.
+```bash
+python scripts/verify_release.py
+```
+
+Each checker validates file sizes, SHA-256 hashes, and portability-sensitive source
+paths against `docs/artifacts.json`. Human-readable artifact inventories appear in
+`docs/ARTIFACTS.md`. The PDC inventory covers the three generators and the property
+scorers. The PROTAC inventory covers the fine-tuned DeFoG checkpoint and the generic and
+target-specific validity classifiers.
+
+The paper settings remain in `configs/paper.json`, and detailed PROTAC outputs behind the
+reported tables remain under `CupOFMoCA-PROTAC/results/`. Hardware, CUDA, PyTorch, and
+runtime model revisions can introduce numerical variation across repeated runs.
+
+## Data and evaluation scope
+
+The PDC release supports the paper experiments across ERBB2, GNRHR, and NRP1 with the
+released target sequences and conjugation chemistries. The PROTAC release supports the
+paper experiments across EGFR-VHL, BRD9-VHL, and CDK6-CRBN with fixed anchor chemistry.
+The detailed modality guides describe the training sources and evaluation measurements.
+
+All generated candidates and objective values are computational predictions. Use
+chemical synthesis, experimental validation, toxicology, and safety assessment to
+establish the properties of candidates selected for further study. DegradeMaster results
+use an in-domain predictor trained with overlapping PROTAC databases and should be
+interpreted within that evaluation setting.
+
+## Repository structure
+
+```text
+CupOFMoCA/
+  assets/                    overview media
+  CupOFMoCA-PDC/             PDC generation and evaluation release
+    checkpoints/             SMILES, AA, and UAA generator weights
+    configs/                 paper settings and target sequences
+    scripts/                 experiment runner and integrity checker
+    smiles/                  generation, assembly, scoring, and evaluation code
+  CupOFMoCA-PROTAC/          PROTAC linker generation and evaluation release
+    checkpoints/             fine-tuned DeFoG weights
+    configs/                 paper settings
+    data/                    derived linker table
+    md/                      explicit-solvent molecular-dynamics workflow
+    results/                 outputs and summaries used in paper tables
+    scripts/                 generation, evaluation, and verification programs
+    src/                     DeFoG, target builders, and classifiers
+```
 
-## Citation
+## Citation and license
 
-See `CITATION.cff` in either release folder.
+Citation metadata is available in [`CITATION.cff`](CITATION.cff). The CupOFMoCA code is
+released under Apache-2.0. Third-party code and downloaded model artifacts retain their
+respective terms, which are recorded in the modality-specific `NOTICE` files.