---
license: other
tags:
  - diffusers
  - controlnet
  - stable-diffusion
  - medical-imaging
  - retinal-imaging
  - diabetic-retinopathy
  - counterfactual
---

# ST — Weights & Training Logs

Companion Hugging Face repository for the audited GitHub handoff
[`KylianSu/reproduce_dr`](https://github.com/KylianSu/reproduce_dr).

This repo holds all weights, training logs, and reviewer-facing artifacts for
the NeurIPS 2026 submission on Bezier-conditioned ControlNet + parameter-level
counterfactual verification of vessel geometry → diabetic retinopathy (DR).

## Layout

```
weights/
  sd21_lora_fundus_v2/                      <-  Paper-final LoRA (noise_offset=0.1, rank=64)
    pytorch_lora_weights.safetensors        51 MB
  sd21_lora_fundus_v1/                      <-  Earlier LoRA, kept for comparison
    pytorch_lora_weights.safetensors        51 MB

  controlnet_g3_bezier_v3/                  <-  Paper-final G3 (Bezier-hint) ControlNet
    best_controlnet.pth                     78 MB
    train.log + hint_preview_epoch*.png
  controlnet_g2_encoder_v2/                 <-  Paper-final G2 (z_spatial-hint) ControlNet
    best_controlnet.pth                     78 MB
    train.log
  controlnet_g3_bezier_v1_legacy/           <-  Earlier G3 versions (logs + previews only;
  controlnet_g3_bezier_v2_legacy/               weights already pruned during 2026-04-23 cleanup)

  clip_finetune/                            <-  BiomedCLIP two-stage finetune (Stage 2 final)
    20260326_041223/best_model.pth          748 MB
    train.log + history.json + config.json
  vessel_encoder_v2/                        <-  VesselEncoderV2 (z_tok / z_spatial producer)
    20260407_201552/best_encoder_v2.pth     382 MB
    train.log + history.json + config.json

  cls_binary_leakfree/                      <-  Downstream DR classifiers (leak-free baselines)
    baseline/best_model.pth                 30 MB    (EfficientNet-B2 @ 384)
    baseline_resnet50/best_model.pth        90 MB    (ResNet-50 @ 384)
    baseline_vitb16/best_model.pth          329 MB   (ViT-B/16 @ 384, low DR sensitivity)
    augmented_g{2,3}_{400,4k}[_10pct]/      Prompt-bug-era synth augmentation (retained for comparison)
  cls_binary_leakfree_pfix/                 <-  Prompt-fixed augmentation (paper §5.3 main table)
    aug_g{2,3}_{400,4k}[_10pct]_pfix/       8 variants, 30 MB each

experiment_E/                               <-  Track 4 DR-prompt main experiment
  hints/ + gen/                             hints + generated images for every start x config
  stage{1,2,3}*.csv + stems.json + causal_curves*.png
experiment_E_uncond/                        <-  Track 4 Uncond (paper's strongest Delta = +0.781 cohort)
  hints/ + gen/ + CSV + top-5 champion visualization
```

## How to download

```bash
# Whole repo (~2.8 GB)
hf download KylianSu/vessel-bezier-retinal-weights --repo-type model --local-dir ./hf_weights

# Or a single subtree
hf download KylianSu/vessel-bezier-retinal-weights --include "weights/sd21_lora_fundus_v2/*" --local-dir ./hf_weights
```

## How the code expects the files

After download, copy (or symlink) the relevant folders back under the code
repo's `train_logs/`, `cls_binary_leakfree/`, `cls_binary_leakfree_pfix/`,
`experiment_E/`, `experiment_E_uncond/`:

```bash
rsync -a hf_weights/weights/sd21_lora_fundus_v2/  $ST_BASE/train_logs/sd21_lora_fundus_v2/
rsync -a hf_weights/weights/controlnet_g3_bezier_v3/  $ST_BASE/train_logs/diffusion_sd21/20260415_140655_group3_bezier_v3/
# ... etc, matching paths referenced in scripts/*.sh
```

The source repository now provides an exact restore script:

```bash
git clone https://github.com/KylianSu/reproduce_dr.git
cd reproduce_dr
bash scripts/00_setup_env.sh
bash scripts/01c_restore_paper_weights.sh
```

See
[`docs/13_remote_handoff.md`](https://github.com/KylianSu/reproduce_dr/blob/main/docs/13_remote_handoff.md)
for the complete clean-machine procedure. The script verifies the six
paper-final trainable checkpoints against
`data_manifests/PAPER_FINAL_MODEL_SHA256SUMS`.

## Derived-data handoff

The private dataset repository
[`KylianSu/btecf-dr-handoff`](https://huggingface.co/datasets/KylianSu/btecf-dr-handoff)
preserves the recomputed AutoMorph masks, Bézier/CLIP features, fixed splits,
Track 1/2 outputs, and both updated n=500 reruns. An authorized
researcher can restore and checksum all of them with:

```bash
hf auth login
bash scripts/15_download_handoff_assets.sh
```

The current n=500 files are a reproducible post-submission rerun using the
audited AutoMorph preprocessing. They preserve the fixed-start design and main
tortuosity conclusion, with small numerical variation from the updated masks.
They should be cited as the updated rerun rather than as a byte-identical copy
of the submission snapshot. The archived n=50 files remain the direct evidence
for the submitted Table 4/5 statistics.

## Other artifacts you still need (not in this repo)

- **Stable Diffusion 2.1 base** (24 GB): https://huggingface.co/stabilityai/stable-diffusion-2-1-base
- **BiomedCLIP pretrained** (753 MB): https://huggingface.co/microsoft/BiomedCLIP-PubMedBERT_256-vit_base_patch16_224
- **EyePACS + APTOS + Messidor images**: use the pinned upstream download
  scripts and manifests in the GitHub repository. These third-party images are
  intentionally not redistributed here.

## License

TBD — please contact the project owner (see GitHub repo) before any external
redistribution.