Upload README.md with huggingface_hub

README.md

@@ -8,39 +8,88 @@ For the Diffusers-format release with bundled inference code, see
 
 | File | Description |
 | --- | --- |
-| `stage1_vqgan.ckpt` | Stage 1 VQGAN checkpoint (first stage autoencoder). |
-| `stage2_ldm.ckpt` | Stage 2 latent diffusion / CLDM checkpoint (original A101 run, epoch 212 / step 13,991). |
-| `stage2_ldm_config.yaml` | Exact Stage 2 training config used for `stage2_ldm.ckpt`, with env-based paths. |
-| `ldm_backend_vqgan_marmousi.yaml` | Stage 1 training config. |
+| `stage1_vqgan.ckpt` | Stage 1 VQGAN checkpoint (first stage autoencoder), 721 MB. |
+| `stage2_ldm.ckpt` | Stage 2 latent diffusion / CLDM checkpoint (original A101 run, epoch 212 / step 13,991), 4.3 GB. |
+| `stage2_ldm_config.yaml` | Exact Stage 2 training config used for `stage2_ldm.ckpt`, with env-based relative paths. |
+| `ldm_backend_vqgan_marmousi.yaml` | Stage 1 training config from the refactored repo. |
 | `ldm_backend_a101_train_hwd.yaml` | Stage 2 training config from the refactored repo. |
 | `ldm_backend_lightning.yaml` | Lightning trainer, logger, and Overthrust eval callback config. |
 
-## Usage
+## Download the checkpoints
 
-Clone the training code repository and copy these checkpoints/configs into it
-(or set the corresponding `.env` paths):
+With [huggingface_hub](https://huggingface.co/docs/huggingface_hub):
 
 ```bash
-cp stage1_vqgan.ckpt stage2_ldm.ckpt <your_repo>/models/
-cp stage2_ldm_config.yaml <your_repo>/configs/
+pip install huggingface_hub
+huggingface-cli download \
+  --repo-type model \
+  --local-dir ./saii-cldm-ldm-checkpoints \
+  mally-2000/saii-cldm-ldm-checkpoints
 ```
 
-Then set in `.env`:
+Or in Python:
+
+```python
+from huggingface_hub import snapshot_download
+snapshot_download(
+    "mally-2000/saii-cldm-ldm-checkpoints",
+    repo_type="model",
+    local_dir="./saii-cldm-ldm-checkpoints",
+)
+```
+
+## Run inference on Overthrust
+
+Clone the training code repository and copy the checkpoints/configs into it:
+
+```bash
+git clone <SAII-CLDM-training-repo>
+cd SAII-CLDM
+mkdir -p models
+cp saii-cldm-ldm-checkpoints/stage1_vqgan.ckpt models/
+cp saii-cldm-ldm-checkpoints/stage2_ldm.ckpt models/
+cp saii-cldm-ldm-checkpoints/stage2_ldm_config.yaml configs/
+```
+
+Set the required paths in `.env` (copy from `.env.example`):
 
 ```bash
 FIRST_STAGE_CKPT=./models/stage1_vqgan.ckpt
+OVERTHRUST_DATA_DIR=./data/overthrust
 ```
 
-And run the Stage 2 training resuming from `stage2_ldm.ckpt`, or evaluate it
-with:
+Then run CLDM inference on the Overthrust benchmark:
 
 ```bash
-python eval_overthrust.py CLDM \
+CUDA_VISIBLE_DEVICES=0 python eval_overthrust.py CLDM \
   --ckpt ./models/stage2_ldm.ckpt \
+  --config ./configs/stage2_ldm_config.yaml \
   --output runs/eval_cldm \
   --device cuda --steps 30
 ```
 
+If GPU 0 is occupied or you hit OOM, switch to another GPU:
+
+```bash
+CUDA_VISIBLE_DEVICES=1 python eval_overthrust.py CLDM \
+  --ckpt ./models/stage2_ldm.ckpt \
+  --config ./configs/stage2_ldm_config.yaml \
+  --output runs/eval_cldm \
+  --device cuda --steps 30
+```
+
+The script will save `metrics_summary.json`, numpy arrays, and a comparison figure under `runs/eval_cldm`.
+
+## Resume training
+
+To resume Stage 2 training from this checkpoint:
+
+```bash
+CUDA_VISIBLE_DEVICES=0 python train_ldm_backend.py -t \
+  --resume ./models/stage2_ldm.ckpt \
+  --base ./configs/stage2_ldm_config.yaml ./configs/ldm_backend_lightning.yaml
+```
+
 ## Paper
 
 SAII-CLDM: Seismic Acoustic Impedance Inversion through Conditional Latent Diffusion Model.