Highlight scaffold decoration and add five-metric evaluation tables

Add separate collapsible tables for all 10 unconditional checkpoints and GEOM scaffold decoration. Report only novelty, PoseBusters validity, diversity, uniqueness, and connected-sanitization validity as mean +/- sample SD across seeds 42, 43, and 44. Document sample counts, metric populations, and the distinct scaffold PoseBusters protocol.

README.md

@@ -3,6 +3,7 @@ library_name: pytorch
 tags:
   - chemistry
   - molecular-generation
+  - scaffold-decoration
   - flow-matching
   - qm9
   - geom-drugs
@@ -11,16 +12,18 @@ tags:
   - arxiv:2606.07239
 ---
 
-# Morph: 3D molecular generation
+# Morph: 3D molecular generation and scaffold decoration
 
-Unconditional molecular generation checkpoints trained on **QM9**, **GEOM-Drugs**
-and **ChEMBL3D**, with the configurations, vocabularies and training distributions
-needed for inference. No training dataset is required to load a model or generate
-molecules.
+Checkpoints for **unconditional 3D molecular generation** on **QM9**,
+**GEOM-Drugs** and **ChEMBL3D**, plus **GEOM-Drugs scaffold decoration** with
+rank-16 LoRA after 25 fine-tuning epochs. The releases include the configurations,
+vocabularies and training distributions needed for their inference workflows.
+Unconditional generation requires no training dataset; scaffold decoration uses
+a supplied scaffold and the dedicated [scaffold bundle](#scaffold-decoration).
 
 See our [paper](https://arxiv.org/abs/2606.07239), *Generative Molecular Morphing for Flexible-Size Design via Unbalanced Optimal Transport*.
 
-## Available checkpoints
+## Unconditional checkpoints
 
 | Dataset | Model name | Hydrogen representation | Completed epochs | Files |
 | --- | --- | --- | --- | --- |
@@ -35,14 +38,105 @@ Checkpoints are original training files containing current weights, EMA weights
 and optimizer state.
 
 The [catalog](https://huggingface.co/maltefranke/morph/blob/main/catalog.json)
-is the source of truth for available model names and epochs. Each entry pins an
+is the source of truth for unconditional model names and epochs. Each entry pins an
 immutable release revision so its weights and supporting files stay together.
 New catalog entries are discovered without updating the Python package.
 
+## Scaffold decoration
+
+**GEOM-Drugs scaffold decoration is also available:** the
+[`geom-scaffold-murcko-substituent-lora-r16` bundle](https://huggingface.co/maltefranke/morph/tree/main/geom/scaffold_murcko_substituent_lora_r16)
+contains the checkpoint after **25 fine-tuning epochs**, initialized from the
+GEOM explicit-H epoch-100 EMA weights. It uses **rank-16 LoRA**, trainable output
+heads and substituent-constrained insertion supervision.
+
+| Model | Hydrogen representation | Completed fine-tuning epochs | Checkpoint |
+| --- | --- | ---: | --- |
+| `geom-scaffold-murcko-substituent-lora-r16` | Explicit H atoms | 25 | [epoch_025.ckpt](https://huggingface.co/maltefranke/morph/resolve/main/geom/scaffold_murcko_substituent_lora_r16/epoch_025.ckpt) |
+
+The model generates decorations conditioned on a Murcko scaffold. Scaffold atom
+identities, internal bonds and charges are preserved; scaffold positions can move.
+This conditional checkpoint requires the scaffold bundle's saved configuration and
+runtime. It is loaded through that workflow, outside the unconditional `morph generate`
+interface and catalog.
+
+The bundle includes the original checkpoint, training configuration and source,
+portable configuration, vocabularies, distributions, evaluation runtime and fixed
+validation/test scaffold panels. See its [usage and reproduction instructions](https://huggingface.co/maltefranke/morph/blob/main/geom/scaffold_murcko_substituent_lora_r16/README.md).
+
+## Evaluation results
+
+Values are **mean ± sample standard deviation** across seeds **42, 43 and 44**
+(`ddof=1`). Rates are percentages; diversity is on a 0–1 scale.
+Both evaluations use EMA weights and 100 integration steps.
+
+<details>
+<summary><strong>Unconditional generation — all 10 checkpoints</strong></summary>
+
+**10,000 generation attempts per seed and checkpoint** (30,000 per checkpoint).
+PoseBusters uses the full offline `mol` checks, including flatness and internal energy,
+on the generated structures.
+
+| Model | Completed epochs | Novelty (%) | PoseBusters validity (%) | Diversity (0–1) | Uniqueness (%) | Connected-sanitization validity (%) |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| QM9 · explicit H | 1,000 | 24.99 ± 0.50 | 93.19 ± 0.30 | 0.8969 ± 0.0003 | 94.77 ± 0.19 | 98.99 ± 0.14 |
+| QM9 · explicit H | 1,500 | 22.96 ± 0.23 | 93.53 ± 0.19 | 0.8966 ± 0.0001 | 94.91 ± 0.11 | 99.14 ± 0.08 |
+| GEOM-Drugs · explicit H | 50 | 99.77 ± 0.02 | 88.21 ± 0.39 | 0.8855 ± 0.0004 | 100.00 ± 0.00 | 95.22 ± 0.35 |
+| GEOM-Drugs · explicit H | 100 | 99.75 ± 0.07 | 88.30 ± 0.24 | 0.8848 ± 0.0001 | 100.00 ± 0.00 | 95.46 ± 0.31 |
+| ChEMBL3D · explicit H | 200 | 99.69 ± 0.05 | 91.46 ± 0.24 | 0.8953 ± 0.0002 | 99.99 ± 0.02 | 95.80 ± 0.17 |
+| ChEMBL3D · explicit H | 300 | 99.75 ± 0.05 | 91.38 ± 0.16 | 0.8956 ± 0.0005 | 100.00 ± 0.00 | 95.72 ± 0.15 |
+| ChEMBL3D · explicit H | 400 | 99.73 ± 0.02 | 91.21 ± 0.37 | 0.8953 ± 0.0001 | 100.00 ± 0.00 | 95.41 ± 0.16 |
+| ChEMBL3D · implicit H | 100 | 99.72 ± 0.04 | 94.61 ± 0.43 | 0.9141 ± 0.0002 | 100.00 ± 0.00 | 98.60 ± 0.08 |
+| ChEMBL3D · implicit H | 200 | 99.64 ± 0.10 | 95.27 ± 0.16 | 0.9140 ± 0.0002 | 100.00 ± 0.01 | 98.87 ± 0.18 |
+| ChEMBL3D · implicit H | 300 | 99.61 ± 0.04 | 95.32 ± 0.09 | 0.9142 ± 0.0001 | 100.00 ± 0.00 | 98.80 ± 0.07 |
+
+Novelty is measured against each checkpoint's training split. Novelty and uniqueness
+use canonical, H-stripped molecular identities with stereochemistry ignored.
+
+</details>
+
+<details>
+<summary><strong>Scaffold decoration — GEOM-Drugs, 25 fine-tuning epochs</strong></summary>
+
+**512 held-out test scaffolds × 8 generation attempts per scaffold per seed**
+(4,096 per seed; 12,288 total), using the fixed released Murcko scaffold panel.
+The generated coordinates are not relaxed.
+
+| Model | Completed epochs | Novelty (%) | PoseBusters validity (%) | Diversity (0–1) | Uniqueness (%) | Connected-sanitization validity (%) |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| GEOM-Drugs · scaffold decoration (LoRA r16) | 25 (fine-tuning) | 97.52 ± 0.10 | 94.10 ± 0.19 | 0.9076 ± 0.0004 | 63.54 ± 0.59 | 97.99 ± 0.20 |
+
+**PoseBusters protocol:** the native scaffold evaluation checks chemistry and distance
+geometry, excluding the full offline energy and flatness checks. The value above is
+`posebusters/validity`, the strict all-check pass rate for that configuration; it does
+not apply the scaffold-aware inherited-clash exemption. It is therefore **not directly
+comparable** to the full offline PoseBusters scores in the unconditional table.
+Novelty, diversity and uniqueness describe the pooled generated molecules within each
+seed, across all 512 scaffolds; uniqueness is not averaged per scaffold.
+
+See the [scaffold bundle documentation](https://huggingface.co/maltefranke/morph/blob/main/geom/scaffold_murcko_substituent_lora_r16/README.md)
+for the saved evaluation runtime and test panel.
+
+</details>
+
+Metric definitions:
+
+- **Novelty:** fraction of generated, SMILES-convertible molecules absent from the
+  corresponding training reference, retaining duplicates in the denominator.
+- **PoseBusters validity:** fraction of all generation attempts passing every enabled
+  PoseBusters check; missing checks and failed molecule conversions count as failures.
+- **Diversity:** mean pairwise Tanimoto distance between ECFP6 fingerprints (radius 3,
+  2,048 bits), retaining duplicates among fingerprintable molecules.
+- **Uniqueness:** distinct canonical molecular identities divided by all
+  SMILES-convertible molecules within a seed.
+- **Connected-sanitization validity:** fraction of all attempts producing connected,
+  RDKit-sanitizable molecules, with no additional charge or radical restriction
+  (`connected-sanitization-validity`).
+
 ## Install and authenticate
 
 The runtime bundled with GEOM includes the shared inference interface and catalog
-discovery for all models in the table. Install it in a Python environment:
+discovery for all models in the unconditional checkpoint table. Install it in a Python environment:
 
 ```bash
 python -m pip install 'huggingface_hub>=1.0,<2'
@@ -138,11 +232,11 @@ and `--offline`.
 
 The root `sample.py` remains available as the archived ChEMBL3D sampling entry
 point with its corresponding bundled runtimes. The shared interface above
-supports all four published model variants.
+supports all four published unconditional model variants.
 
 ## Reproducibility
 
-Each model has a **training bundle** with its original training configuration,
+Each unconditional model has a **training bundle** with its original training configuration,
 launch settings, frozen source, dependency versions and data references.
 The bundles live alongside the corresponding model files on Hugging Face:
 
@@ -184,8 +278,8 @@ started from scratch, validates every epoch and retains checkpoints every 25 epo
 
 The GEOM-Drugs epoch 50 and 100 checkpoints come from the run resumed from the
 best checkpoint after 48 completed epochs. The resumed run validates every epoch and retains
-checkpoints every fifth epoch. Only the epochs listed in the catalog have been
-published here.
+checkpoints every fifth epoch. The published unconditional epochs are listed in the catalog. The scaffold-decoration
+checkpoint adds 25 fine-tuning epochs on top of the epoch-100 model.
 
 Explicit-H models generate H atoms as graph vertices. Every model uses its own
 ordered vocabularies, distributions and saved configuration; keep those files
@@ -194,7 +288,7 @@ a hard atom-count limit during generation.
 
 ## Bundle contents and verification
 
-Each model directory contains:
+Each unconditional model directory contains:
 
 - `epoch_NNN.ckpt`: the published original training checkpoints.
 - `config.yaml`: portable inference configuration with dataset loading disabled.
@@ -210,8 +304,9 @@ Each model directory contains:
   portable training recipe; `training_bundle.json` records its checksum and provenance.
 - `validation.json`: results of checkpoint loading and sampling checks.
 
-The published bundles were checked for strict current/EMA weight loading and
-end-to-end sampling. These are functionality checks, not validity benchmarks.
+The published unconditional bundles were checked for strict current/EMA weight loading
+and end-to-end sampling. These functionality checks are separate from the
+[generation benchmarks above](#evaluation-results).
 The GEOM and QM9 releases also passed remote file-size and hash verification.
 
 The [ChEMBL3D release manifest](https://huggingface.co/maltefranke/morph/blob/main/manifest.json)