CupOFMoCA-PROTAC/README.md

# CupOFMoCA for PROTACs

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**.

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.

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.

## Model and objectives

| Artifact | Role |
|---|---|
| `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 generator applies the validity classifier as a hard mask before exponential tilting.
Three soft scores define the weighted objective used for the reported runs.

| 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
conda env create -f environment.yml
conda activate defog
pip install -e src/defog
python scripts/verify_release.py
```

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
```

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
```

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.

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.

## Optional evaluation components

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.

```bash
cd ..
python scripts/fetch_third_party.py
```

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

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.

## Training data

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.

## Reported outputs

The `results/` directory contains the generation outputs and scored summaries used in the
paper's PROTAC tables.

```text
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
```

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

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

[`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 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 bundled DeFoG code retains
its MIT license under `src/defog/LICENSE`. Optional upstream components retain their own
terms.