README.md

---
license: mit
library_name: jax
tags:
- graph-generation
- discrete-diffusion
- classifier-free-guidance
- spectral-graph-theory
- absorbing-state-diffusion
datasets:
- synthetic
---

# Spectral Graph Diffusion (n=30)

Conditional discrete-diffusion denoiser for graphs targeting the algebraic
connectivity (Fiedler value, λ₂) of the graph Laplacian. Trained on 100K
stratified synthetic graphs at n=30 from six random-graph families.

- **Architecture**: graph transformer, ~25M parameters, three-FiLM conditioning
  (timestep, global features, λ\* target).
- **Training**: best loss 0.3601 nats at step 52,000 (vs marginal baseline 0.5669;
  36% below). ~7 hours on a single GCP T4 (~$4.50 USD).
- **Sampling**: discrete absorbing diffusion with classifier-free guidance.

[Code](https://github.com/cpennetier/spectral-graph-diffusion) ·
[Paper (arXiv: TBD)](https://arxiv.org/abs/XXXX.XXXXX) ·
[Companion search-based project](https://github.com/cpennetier/spectral-graph-patternboost)

## Intended use

Research and educational use. Generates undirected graphs at n=30 conditioned
on a target algebraic connectivity λ₂\*. Not intended for production decisions
or applications relying on graph robustness in real-world deployments.

## Headline empirical findings

- **Sample format validity**: 100% (architecturally enforced by upper-triangle
  sampling, mirror-to-lower, diagonal forced to zero; not learned).
- **Regime-flip critical value**: λ\*\_c ≈ 9.5. Classifier-free guidance with
  w > 0 helps tracking at λ\* ∈ [10, 14], collapses samples at λ\* ≤ 9, and
  over-amplifies toward K_30 at λ\* ≥ 16.
- **Bidirectional Pareto sweet-spot**: w=2 at λ\*=10. Both fidelity and
  diversity improve with guidance — contrary to the standard CFG framing.
- **Family attribution at high targets**: 32/32 samples classified as ER-like
  at λ\*=20, w=4.

See the paper for full empirical tables, sweep details, and mechanism analysis.

## Limitations

- Single graph size (n=30); does not generalize to other sizes.
- Single trained model, single seed, single hub layout — no variance estimates.
- The CFG-collapse regime at λ\* < λ\*_c is a measured limitation of the
  conditioning-corpus interaction, not a model bug.
- Hamming diversity is density-sensitive; reported with this caveat.

## Quick start (Python, JAX)

```python
from huggingface_hub import snapshot_download

# Download checkpoint
checkpoint_dir = snapshot_download(
    repo_id="cpennetier/spectral-graph-diffusion-n30",
    repo_type="model",
)

# Use with the spectral-graph-diffusion repo's sampler:
# https://github.com/cpennetier/spectral-graph-diffusion
# python -m model.sample --ckpt {checkpoint_dir} --target_lambda 12 --w 2.0
```

## Citation

```bibtex
@misc{pennetier2026diffusion,
  author = {Pennetier, Christophe},
  title = {Regime-Dependent Guidance in Spectral Graph Diffusion},
  year = {2026},
  url = {https://arxiv.org/abs/XXXX.XXXXX},
  note = {Code: https://github.com/cpennetier/spectral-graph-diffusion}
}
```

## License

MIT. See the [code repository](https://github.com/cpennetier/spectral-graph-diffusion)
for full license text.