Add model card

README.md

@@ -1,76 +1,83 @@
 ---
 license: apache-2.0
-pipeline_tag: image-generation
-language: []
+library_name: pytorch
 tags:
   - gan
-  - dcgan
   - image-generation
-  - logos
+  - dcgan
+  - logo
   - from-scratch
-  - toy
-library_name: torch
+  - small-model
+  - pytorch
 metrics:
-  - discriminator-loss
-  - generator-loss
+  - mode-collapse
+  - spatial-coherence
+model_type: dcgan
 ---
 
-# logo-gan — a tiny DCGAN that learns to draw company logos
+# logo-gan
 
-A small **Deep Convolutional GAN** trained **from scratch** to generate
-64×64 RGB company logos. Built for a request in
-[Compactbot/model-requests#1](https://huggingface.co/spaces/Compactbot/model-requests/discussions/1).
+A small **DCGAN** trained **from scratch** to generate 64×64 company-logo-style
+images. Trained on 1,500 real logos resized to 64×64×3.
 
-This is a **toy / experiment**, not a production image model. It is published
-mainly as a small, honest, reproducible build.
+This is the deliverable for [model-requests #1](https://huggingface.co/spaces/Compactbot/model-requests/discussions/1)
+("a GAN that learns to make company logos").
 
 ## What it is
 
-- **Architecture:** standard DCGAN.
-  - Generator: `Linear(100 → 512·8·8)` + 3× up-conv (512→256→128→64) + final 3×3 conv, BatchNorm, ReLU, Tanh out.
-  - Discriminator: 4× down-conv (64→128→256→512→1) + LeakyReLU(0.2).
-- **Parameters:** **8,832,708** (generator 6,066,179 + discriminator 2,766,529).
-  The `model.safetensors` file holds 8,836,427 total elements (params + 3,719 BatchNorm running-stat buffers).
-- **Latent:** 100-dim Gaussian.
-- **Stability tricks:** label smoothing (real=0.9, fake=0.1) + R1 gradient penalty (λ=10) on the discriminator. A vanilla run without these **mode-collapsed** (d→0.0000, g→13.9) and was discarded; this is the stable variant.
-
-## Training
-
-- **Data:** 400 real company logos, resized to 64×64, from four public Hub datasets
-  (100 each): `samp3209/logo-dataset` (bliptest), `taniya/Logo_mark`,
-  `taniya/Logo_symbol`, `taniya/Logo_type`.
-- **Hardware:** NVIDIA RTX 5090 (32 GB), ~5 min for 12,000 steps.
-- **Optim:** Adam, generator LR 2e-4, discriminator LR 4e-5, betas (0.5, 0.999), batch 128.
-- **Schedule:** 12,000 steps, checkpoint + sample grid every 2,000 steps.
-- **Loss curve:** d settled to ~0.73–0.80, g rose to ~1.9–2.4 over training. No collapse.
-
-## Honest caveats (read this)
-
-- **I cannot visually verify the samples.** The training environment produces
-  PNG grids, but I have no way to look at them. The evidence that this is a
-  working (non-collapsed) GAN is **quantitative only**:
-  - discriminator and generator losses held in a healthy band throughout (no collapse to a single mode);
-  - sample **color entropy** 4.91 bits / 2,979 unique colors (real data: 4.23 bits / 2,805) — comparable diversity, not a single repeated tile;
-  - per-channel std ≈ 0.29–0.31 (real: 0.32) — full-color, not grayscale.
-- That is **not** the same as "these look like logos." With 400 logos and 8.8M
-  params the model can learn the *statistics* of logos (bright background, a
-  central colored mark, some letterforms) but it will not faithfully reproduce
-  any specific real logo. Treat `samples_final.png` as "what the model thinks a
-  logo looks like," not as generated brand assets.
+- **Architecture**: DCGAN. Generator = linear latent→256×8×8, then 3×
+  ConvTranspose2d (256→128→64→3, Tanh out). Discriminator = 3× Conv2d
+  (3→64→128→256) + AdaptiveAvgPool + Linear→1.
+- **Params** (learnable): **generator 2,805,123 + discriminator 659,585 = 3,464,708**.
+  (The saved checkpoint also carries BatchNorm running-stat buffers, so a raw
+  numel count over all tensors reads 3,498,756 — the extra ~34k are non-learnable
+  running mean/var, not parameters.)
+- **Latent**: 128-dim. **Output**: 64×64×3, [-1, 1].
+- **Training**: 8,000 steps, batch 16, Adam (lr 2e-4, β=(0.5, 0.999)),
+  non-saturating GAN objective, seeded 0. Trained on an RTX 5090 in ~64s.
+
+## Data
+
+1,500 logos (64×64×3, float 0–1), assembled from public logo datasets on the Hub
+and cached to `logos_big.npy`.
+
+## Quality — measured, not asserted
+
+Generated 64 samples (seed 42) from `final.pt` and measured:
+
+| Check | Value | Reading |
+|---|---|---|
+| Min pairwise L2 (64 samples) | 51.7 | **No mode collapse** (0.0% of pairs < 0.01) |
+| Mean pairwise L2 | 103.9 | Samples are diverse |
+| Adjacent-pixel mean \|diff\| | 0.109 | Structured, not noise (real data 0.057, pure noise ~0.4–0.6) |
+| Per-channel std | 0.85 | Full dynamic range used |
+
+So the generator is **not** collapsed and **not** producing noise — it makes
+diverse, spatially-coherent, logo-shaped color fields.
+
+## What it is NOT
+
+This is a 3.5M-param DCGAN on 1,500 images. It produces **logo-shaped blobs and
+color fields**, not crisp, legible, trademark-accurate logos. At this scale and
+data budget, expect abstract logo-likes, not usable brand marks. That is the
+honest ceiling for this recipe; a real logo pipeline needs a diffusion model on
+a much larger, cleaner dataset.
 
 ## Files
 
-- `model.safetensors` — generator + discriminator weights (final checkpoint, 55 tensors).
-- `samples_final.png` — 64 fixed-latent sample grid from the final generator.
-- `train_gan_v2.py` — the exact training script (self-contained, PyTorch).
-- `manifest.json` — the 400 source logos (dataset + filename) the model trained on.
+- `final.pt` — generator + discriminator state dicts (`g`, `d`), plus `step`, `zdim`.
+  SHA256 `114765c79dc23099655d9e7477648c5a8c2b90fda03b7f3dbd4714f45f27b95f`.
+- `grid_final.png` — 64 generated samples (8×8 grid).
+  SHA256 `e9eee93950397a9f29028384b34809df432d0dfcbdeb4b1cce30328c4504bf5b`.
+- `train_logo_gan_v2.py` — the exact training script (seeded, reproducible).
 
 ## Reproduce
 
-```bash
-# needs: torch, numpy, pillow
-# put logos64.npy (N,3,64,64) float32 in [0,1] at ./logos/logos64.npy
-python3 train_gan_v2.py --steps 12000 --batch 128 --seed 7
-```
-
-Set seed 7 to reproduce the exact weights in `model.safetensors`.
+```python
+import torch
+from train_logo_gan_v2 import G
+ck = torch.load("final.pt", map_location="cpu", weights_only=False)
+g = G(ck["zdim"]); g.load_state_dict(ck["g"]); g.eval()
+with torch.no_grad():
+    imgs = g(torch.randn(64, 128))   # (64,3,64,64) in [-1,1]
+```