Blame for README.md

---
title: Diffusion
emoji: 🌍
colorFrom: indigo
colorTo: purple
sdk: gradio
app_file: app.py
python_version: "3.10"
pinned: false
---

# Diffusion Lab

The Gradio app supports ZeroGPU and streams checkpoint images. The model selector offers `google/ddpm-celebahq-256` (256×256 faces, the default) and `google/ddpm-cifar10-32` (32×32 CIFAR-10 objects and animals) through Hugging Face Diffusers. Forward images and noise use the selected model’s resolution in Gradio. This is an unconditional CelebA-HQ face generator: reverse sampling normally starts with random Gaussian noise. You can also select the final forward-noise image as its input; this is a demonstration, not a guaranteed reconstruction of the uploaded image.

## Run

Use Python 3.10 or newer. Install a PyTorch build appropriate for your machine first if its default install needs a platform-specific wheel, then install the app dependencies and start the server:

```sh
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python app.py
```

Open <http://127.0.0.1:7860>. On first use, each selected model downloads its weights into `models/`; later runs use that cache. The backend prefers CUDA, then Apple Silicon MPS, then CPU. Model inference uses all 1,000 DDPM steps and sends the selected intermediate images to the browser as they are produced.

To generate and display one image without starting the server, run:

```sh
python generate.py
python generate.py --seed 1234
```

To download a particular zero-based row from the public CelebA-HQ dataset:

```sh
python download_celeba_hq.py 1374
python download_celeba_hq.py 42 --split train --output face-42.png
```

To download a 32×32 CIFAR-10 image (test split by default):

```sh
python download_cifar10.py 1374
python download_cifar10.py 42 --split train --output assets/cifar10-train-42.png
```

## ZeroGPU deployment

Push this repository to a Gradio Space and select ZeroGPU in the Space hardware settings. The Dockerfile and legacy server are not used by the Gradio deployment. Account eligibility and daily GPU quotas apply.

The app imports `spaces` before PyTorch and copies model tensors into owned CPU storage before placing both GPU models on CUDA at startup when `SPACES_ZERO_GPU` is enabled. Reverse sampling tries GPU first and automatically restarts on CPU if GPU allocation, quota, or supported CUDA availability errors prevent the run. Locally, the app prefers CUDA, then Apple Silicon MPS, then CPU. MPS availability failures also fall back to CPU. Separate pipelines are cached for each model and device; the CPU pipeline loads on first use. CPU sampling is substantially slower. GPU sampling runs inside a decorated function called by the Gradio handler. `GPU_DURATION_SECONDS` defaults to 120; benchmark a full 1,000-step run and adjust this Space variable if necessary. A timeout is reported by the Gradio queue; selecting fewer checkpoints does not reduce the sampling steps.

For persistent caching, attach a writable storage bucket and set the Space variable `MODEL_CACHE_DIR` to its mount path (for example `/data/models`). The old Docker path `/app/models` is also usable if explicitly configured with that variable.

For local use, install `gradio` and `spaces` alongside `requirements.txt` (these packages are provided by the Gradio Spaces runtime):

```sh
python -m pip install gradio spaces
python app.py
```

The original browser interface remains available with `python server.py` for local or dedicated-GPU use.