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