onebelowall/ddpm-cifar10-v66

Class-Conditional DDPM from Scratch in PyTorch

This package provides the v66 best checkpoint's EMA weights for a custom PyTorch denoising diffusion probabilistic model (DDPM). The 6,767,683-parameter U-Net generates 32×32 CIFAR-10 class-conditioned images. Its implementation includes residual blocks, single-head self-attention at 32×32, 16×16, and 8×8, sinusoidal timestep embeddings, 11-dimensional one-hot conditioning (10 classes plus a null class), EMA, and classifier-free guidance (CFG). The full documented experiment is in the GitHub repository.

This is not a Transformers or Diffusers model. modeling_ddpm.py is a small inference-only implementation of the v66 architecture and reverse sampler; config.json records the settings needed to reconstruct it. model.safetensors contains only model tensors, without optimizer state, pickle, training data, or the notebook's fixed evaluation-noise tensors.

Training and checkpoint lineage

Run	Run-local steps	Best 500-step average noise-prediction loss	Best run-local step	Logged run time
v65	15,000	0.03161	14,000	6,169 s
v66	15,000	0.03054	14,500	6,055 s

Training used CIFAR-10 at 32×32, batch size 256, Adam with learning rate 1e-4, a 1,000-step linear beta schedule, EMA decay 0.999, 10% null-class dropout for CFG, and random horizontal flips. v66 resumed from v65's best checkpoint at cumulative step 14,000. The runs contain 30,000 optimizer steps in total, while the v66 best and latest checkpoint metadata records 28,500 and 29,000 cumulative steps on the resumed lineage. The published weights come from the v66 best checkpoint. The saved counters and logs have not been changed.

The v66 run processed 3,826,624 images in 6,055 seconds, approximately 632 images/sec run-local throughput. The notebook's printed images/sec value combines a cumulative image count with v66-only time and is not used as a performance figure.

Inference

Install Python 3.12 and the inference dependencies:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install torch safetensors huggingface_hub matplotlib

Replace <HUGGING_FACE_MODEL_URL> with this model's published URL, then run:

import sys
from huggingface_hub import snapshot_download
import matplotlib.pyplot as plt

model_url = "<HUGGING_FACE_MODEL_URL>"
repo_id = model_url.removeprefix("https://huggingface.co/").rstrip("/")
package_dir = snapshot_download(
    repo_id=repo_id,
    allow_patterns=["config.json", "model.safetensors", "modeling_ddpm.py"],
)
sys.path.insert(0, package_dir)
from modeling_ddpm import load_pipeline

pipeline = load_pipeline(package_dir)
image = pipeline.sample("cat", seed=42, guidance_scale=3.0)
rgb = image.permute(1, 2, 0).numpy()
plt.imshow(rgb)
plt.axis("off")
plt.show()
plt.imsave("cat.png", rgb)

Available classes: airplane, automobile, bird, cat, deer, dog, frog, horse, ship, and truck. sample returns a CPU RGB tensor scaled to [0, 1]. Sampling runs all 1,000 reverse steps and can be slow on CPU. The seed controls the public package's random noise, but its outputs are not pixel-identical to the notebook's fixed-input comparisons because those saved reverse-process noise tensors are not distributed here.

Intended use and evaluation

This release supports education, inspection of a compact diffusion implementation, and experiments with CIFAR-10 class conditioning and CFG. The ddpm-documented-v66.ipynb notebook in the GitHub repository contains loss plots, checkpoint evidence, class-conditioned samples, CFG comparisons, and six mixed-conditioning examples. Those are the observed qualitative results. No FID, Inception Score, precision/recall, or systematic human evaluation was performed. The generated 32×32 images are an engineering demonstration rather than a state-of-the-art image-quality claim.

Limitations and license

The small CIFAR-10 resolution limits visual complexity, and this 6.77M-parameter model favors a tractable implementation over state-of-the-art scale. Class labels can guide generation but do not guarantee a recognizable instance in every sample. Quantitative evaluation, multi-seed assessment, longer training, and higher-resolution datasets remain future work.

The helper and released weights are offered under MIT, Copyright (c) 2026 Anjum Ulazim. CIFAR-10 is a separate third-party dataset; see its source and citation information. The MIT license for this project does not grant rights to the dataset.