Community Pipeline: Add HRDiT (training-free high-resolution FLUX.1-dev)

[smellslikeml]

Staged on this fork for review; targets huggingface/diffusers → examples/community.

What

Adds examples/community/pipeline_flux_hrdit.py — training-free high-resolution image generation for off-the-shelf diffusion transformers, implementing HRDiT (arXiv:2608.07003, official repo).

It generates natively at high resolution (up to 4096×4096) straight from a text prompt on stock FLUX.1-dev — no fine-tuning, no new weights, no separate upscaler model, and no src/diffusers changes. Users of the base checkpoint get 4K generation directly, instead of the usual generate-at-1K-then-upscale (or train-a-high-res-model) workaround.

This is high-resolution generation, not super-resolution of an existing image — it complements, rather than replaces, image upscalers.

Validation (FLUX.1-dev · A100-80GB · torch 2.11)

Both 2048² and 4096² are coherent — no tiling, no washout. A 4096² generation runs in ~2 min at ~26 GB peak.

Runnable notebook: https://colab.research.google.com/drive/1AU6QNOGDMCPpGdocVyIyKpXXGt3hoWdo?usp=sharing

Method (on top of the stock FluxPipeline denoise loop)

• NTK-aware RoPE scaling — the primary high-res mechanism; per-stage scaling of the RoPE base brings out-of-range positions back into the trained band, applied on every upscale step.
• Spatial Position Alignment (SPA) — leading-steps-only nudge; a monotonic bundle coarsening of position ids (no wrapping → no periodic tiling), averaged over sliding variants inside attention.
• Structure-guided progressive ladder (1024 → 2048 → 4096) — each stage decodes / upscales / re-encodes the previous latent as a structural prior, then injects its low-frequency band every step (Butterworth FFT split, weight alpha) with a velocity-momentum term (beta) to hold the coarse structure stable at the highest stage.

Out of scope (not needed for the results above; noted in the pipeline docstring): HAP attention pruning, swin_pachify, and DWT guidance.

Scope & generality

HRDiT is a DiT-general technique, not FLUX-specific. SPA operates on the token indices (i, j) fed to the model's positional function — which, per the paper, "though different mainstream DiT models may differ in their specific implementations… all share a common structure: f_pe takes token indices as inputs." So the architecture-agnostic parts of this pipeline — build_bundle_id_variants (SPA on token indices) and the structure-guided progressive ladder — carry over unchanged to other DiTs; only the per-model position scaling differs.

• Applies to diffusion transformers. The paper's two evaluation targets are FLUX (this PR) and SD3; an SD3 instantiation would reuse this same SPA + structure-guidance core, swapping RoPE-base scaling for SD3's positional-embedding interpolation.
• Not for U-Net Stable Diffusion (1.5 / 2.x / SDXL) — that space is already served by the DemoFusion / FreeScale community pipelines.
• Prior-art note. The structure-guidance ladder follows a DemoFusion-style skip-residual; the DiT-specific contributions here are the NTK-aware position scaling and SPA.

Files

• examples/community/pipeline_flux_hrdit.py — the pipeline
• examples/community/README.md — usage entry
• tests/others/test_community_pipeline_flux_hrdit.py — CPU-only unit tests (SPA variants, NTK RoPE, structure-guidance helpers; 13 passing)
• benchmarks/benchmarking_flux_hrdit.py — naive FluxPipeline vs HRDiT timing / peak memory

Disclosure

Training-free / adds no weights. Initially drafted by Outrider (remyx) and then corrected and completed with AI assistance (Claude) against the reference implementation, with each iteration validated on GPU before merge.