File size: 6,504 Bytes
3935449 8a270f7 3935449 8a270f7 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 | ---
license: apache-2.0
language:
- en
library_name: snowgan
pipeline_tag: image-generation
tags:
- gan
- wgan-gp
- image-generation
- snowpack
- transfer-learning
- modality-core
datasets:
- rmdig/rocky_mountain_snowpack
---
# snowGAN β core backbone (v0.1.0)
WGAN-GP trained on the
[Rocky Mountain Snowpack dataset](https://huggingface.co/datasets/rmdig/rocky_mountain_snowpack),
single-modality (`core`), depth=1, 1024x1024 resolution.
Published from the [snowGAN](https://github.com/dennys246/snowGAN) project for
downstream transfer-learning consumers.
## How to use
The canonical consumer-side path uses [`snowgan.weights.fetch`](https://github.com/dennys246/snowGAN/blob/main/src/snowgan/weights.py)
to download + cache, then `snowgan.models.Discriminator` to rebuild and load:
```python
from snowgan.weights import fetch
from snowgan.config import build
from snowgan.models.discriminator import Discriminator
# Fetch the release (cached locally after first call).
path = fetch("RMDig/snowGAN-core", "v0.1.0")
# Reconstruct the model from its sidecar config, then load weights.
cfg = build(str(path / "discriminator_config.json"))
disc = Discriminator(cfg)
disc.model.build((None, cfg.depth, cfg.resolution[0], cfg.resolution[1], cfg.channels))
disc.model.load_weights(str(path / "discriminator.weights.h5"))
# Tap the named features layer β the cross-repo contract with downstream consumers.
features = disc.model.get_layer("features")
print("backbone features:", features.output.shape) # (None, 1048576)
```
Requires `pip install snowgan[hub]` (pulls in `huggingface_hub`). Without the
`[hub]` extra, `fetch()` raises a clean ImportError naming the missing dep.
## Intended use
Primary use case is **transfer learning** β downstream classifiers (e.g. [AvAI](https://github.com/dennys246/AvAI)) attach task heads to the discriminator's Conv3D backbone via `model.get_layer("features").output`. Secondary use is generating synthetic core samples via the generator.
## Architecture
| Field | Value |
| --- | --- |
| Modality | `core` (depth=1) |
| Resolution | 1024x1024 |
| Channels | 3 |
| Latent dim | 100 |
| Generator filter counts | `[1024, 512, 256, 128, 64]` |
| Discriminator filter counts | `[64, 128, 256, 512, 1024]` |
| Conv kernel / stride | `[3, 3]` / `[2, 2]` |
| Backbone (Flatten "features") dim | 1048576 |
| Final activation | `tanh` |
The discriminator's `Conv3D` layers use `ksize=(1, kH, kW)`, so the depth axis is
broadcast β kernels themselves are depth-agnostic. This is the contract that lets
downstream consumers compose multiple single-modality backbones into a depth=N model
(e.g. profile + core stacked at depth=2 for paired-modality transfer).
## Training
Trained with WGAN-GP loss (Wasserstein + gradient penalty, Ξ»_gp=10.0)
on the core samples of [`rmdig/rocky_mountain_snowpack`](https://huggingface.co/datasets/rmdig/rocky_mountain_snowpack).
At release: `fade_step=130000`.
| Stabilizer | Setting |
| --- | --- |
| Spectral norm | `False` |
| Differentiable augmentation | `True` |
| Adaptive augmentation (ADA) target | `0.6` |
| Adaptive disc/gen step ratio | `False` |
| EMA decay (generator shadow) | `0.999` |
| Multi-scale discriminator | `True` |
| Gradient clip (global norm) | `1.0` |
| LR decay schedule | `cosine` (lr_min=`1e-07`) |
| FID eval interval | `5000` steps |
### Dataset splits
Splits are deterministic at the `(site, column, core)` group level (seed=42),
persisted in both sidecar configs so downstream consumers (e.g. AvAI) evaluate
on the same held-out cores the GAN never saw:
- `trained_pool`: 10 groups
- `validation_pool`: 1 groups
- `test_pool`: 2 groups
## Limitations
- Trained on the core modality of rmdig/rocky_mountain_snowpack; generalization untested.
- Late-training discriminator divergence: disc loss plateaued at large magnitudes (~28k abs-mean) from step ~80k onward. The Conv3D backbone features are still informative (the generator learns structured outputs) but the final Dense head is noisy. AvAI only taps the named features layer (before the final Dense) so the noisy Dense is harmless for transfer.
- Single-modality backbone (depth=1); paired-modality features must be composed on the consumer side. See AvAIs load_backbones for the canonical two-backbone composition pattern.
- Small held-out test_pool (2 groups) due to the underlying datasets ~13 unique cores. Downstream evaluation metrics will be noisy.
- Trained without spectral_norm; planned for v0.2 retrain.
## Files in this release
- `discriminator.weights.h5` β main discriminator weights (the transfer backbone).
- `discriminator_config.json` β architecture sidecar; pass to `snowgan.models.Discriminator(cfg)`.
- `generator.weights.h5` + `generator_config.json` β generator weights and sidecar.
- `generator_ema.weights.h5` β EMA shadow weights (only if EMA was enabled during training).
- `generator_fade_endpoints.weights.h5` β progressive-fade toRGB endpoints (only if fade was used).
- `discriminator_lowres.weights.h5` β multi-scale 256Γ256 critic (only if multiscale_disc was on).
- `MANIFEST.md` β full provenance dump (git SHA, every training flag, every artifact). Read this for debugging.
- `README.md` β this file.
## License
Apache 2.0 β see the [snowGAN repository](https://github.com/dennys246/snowGAN) for the full license text.
## Cross-references
- **Source code**: [github.com/dennys246/snowGAN](https://github.com/dennys246/snowGAN)
- **Downstream transfer-learning project**: [github.com/dennys246/AvAI](https://github.com/dennys246/AvAI)
- **Companion modality backbones**:
[`RMDig/snowGAN-magnified-profile`](https://huggingface.co/RMDig/snowGAN-magnified-profile),
[`RMDig/snowGAN-core`](https://huggingface.co/RMDig/snowGAN-core)
- **Training dataset**: [`rmdig/rocky_mountain_snowpack`](https://huggingface.co/datasets/rmdig/rocky_mountain_snowpack)
## Release notes
First core release. Trained ~127k steps without spectral_norm (the v0.1.0 ms2 fade-step counter shows higher numbers but real training is ~127k). Disc loss diverged post-step-80k due to small dataset (~13 unique cores) + no Lipschitz constraint + unconstrained multiscale_disc lowres critic. Generator produces structured outputs (vertical snow-like patterns, blue/white palette) so the Conv3D backbone has learned meaningful features even if the final Dense head is noisy. Backbone usable for transfer learning; v0.2 planned with spectral_norm enabled for a stable retrain.
|