Upload semdisdiffae_p32_v2 private export

README.md

@@ -0,0 +1,124 @@
+---
+license: apache-2.0
+tags:
+  - diffusion
+  - autoencoder
+  - image-reconstruction
+  - latent-space
+  - pytorch
+  - fcdm
+library_name: fcdm_diffae
+---
+
+# data-archetype/semdisdiffae_p32_v2
+
+**semdisdiffae_p32_v2** is a native patch-32 SemDisDiffAE diffusion autoencoder. It
+keeps the same FCDM decoder family as
+[SemDisDiffAE](https://huggingface.co/data-archetype/semdisdiffae), with an
+8-block encoder, an 8-block decoder, and a 384-channel spatial latent at
+`H/32 x W/32`.
+
+Relative to the original
+[SemDisDiffAE](https://huggingface.co/data-archetype/semdisdiffae), this model
+is optimized for a lower-resolution latent grid and downstream latent diffusion:
+patch size `32` instead of `16`, `384` latent channels instead of `128`, an
+8-block encoder instead of a 4-block encoder, and DINOv3 ConvNeXt-B semantic
+alignment instead of the original DINO semantic alignment setup.
+
+See the original
+[SemDisDiffAE technical report](https://huggingface.co/data-archetype/semdisdiffae/blob/main/technical_report_semantic.md)
+for the shared architecture background.
+
+The p32 checkpoint was trained at `384` resolution rather than the original
+`256`-scale recipe. With patch size `32`, this gives a `12x12` latent grid
+instead of `8x8`, reducing the impact of 7x7-convolution border effects during
+training.
+
+## 2k PSNR Benchmark
+
+Evaluated on `2000` images, split as `1333` Pexels images and `667` Amazon book
+covers. Reconstruction uses the default 1-step VP/DDIM path in `bfloat16`.
+
+| Model | Mean PSNR (dB) | Std (dB) | Median (dB) | P5 (dB) | P95 (dB) |
+|---|---:|---:|---:|---:|---:|
+| semdisdiffae_p32_v2 | `36.06` | `5.47` | `35.80` | `27.63` | `45.02` |
+
+## Throughput
+
+Measured on an `NVIDIA GeForce RTX 5090` in `bfloat16`, with `5` warmup batches
+and `20` timed batches. Decode uses the default 1-step sampler with PDG
+disabled.
+
+| Operation | Resolution | Batch Size | Mean (ms/batch) | Images/s | Peak Allocated VRAM |
+|---|---:|---:|---:|---:|---:|
+| Encode | `256x256` | `128` | `12.57` | `10186.8` | `574 MiB` |
+| Decode | `256x256` | `128` | `98.93` | `1293.9` | `1042 MiB` |
+| Encode | `512x512` | `32` | `12.08` | `2649.9` | `579 MiB` |
+| Decode | `512x512` | `32` | `100.36` | `318.8` | `1042 MiB` |
+
+## Results Viewer
+
+The 39-image visual viewer shows originals, FLUX.2 reconstructions,
+semdisdiffae_p32_v2 reconstructions, deltas, and latent PCA side by side:
+[semdisdiffae_p32_v2 results](https://huggingface.co/spaces/data-archetype/semdisdiffae_p32_v2-results).
+
+## Latent Interface
+
+- `encode()` returns whitened latents using the model's saved running statistics.
+- `decode()` expects those whitened latents and dewhitens internally.
+- `whiten()` and `dewhiten()` expose the transform explicitly.
+- `encode_posterior()` returns the raw exported posterior before whitening.
+
+Weights are stored in `float32`. The recommended runtime path is `bfloat16` for
+the encoder and decoder, while whitening, dewhitening, posterior moment math,
+VP schedule math, and sampler state updates are kept in `float32`.
+
+## Usage
+
+```python
+import torch
+
+from fcdm_diffae import FCDMDiffAE, FCDMDiffAEInferenceConfig
+
+
+device = "cuda"
+model = FCDMDiffAE.from_pretrained(
+    "data-archetype/semdisdiffae_p32_v2",
+    device=device,
+    dtype=torch.bfloat16,
+)
+
+image = ...  # [B, 3, H, W] in [-1, 1], H and W divisible by 32
+
+with torch.inference_mode():
+    latents = model.encode(image.to(device=device, dtype=torch.bfloat16))
+    recon = model.decode(
+        latents,
+        height=int(image.shape[-2]),
+        width=int(image.shape[-1]),
+        inference_config=FCDMDiffAEInferenceConfig(num_steps=1),
+    )
+```
+
+## Details
+
+- Architecture: patch-32 FCDM DiffAE, `156.6M` parameters, `384` latent channels.
+- Encoder / decoder depth: `8` blocks each.
+- Training resolution: `384` AR buckets and `384x384` square crops.
+- Semantic alignment: DINOv3 ConvNeXt-B/LVD1689M, 50/50 MSE plus negative cosine.
+- Posterior: diagonal Gaussian with VP log-SNR parameterization.
+- Export variant: EMA weights.
+- [Technical report](https://huggingface.co/data-archetype/semdisdiffae_p32_v2/blob/main/technical_report_fcdm_diffae.md)
+
+## Citation
+
+```bibtex
+@misc{semdisdiffae_p32_v2,
+  title   = {SemDisDiffAE p32 v2: a patch-32 FCDM diffusion autoencoder},
+  author  = {data-archetype},
+  email   = {data-archetype@proton.me},
+  year    = {2026},
+  month   = apr,
+  url     = {https://huggingface.co/data-archetype/semdisdiffae_p32_v2},
+}
+```

config.json

@@ -0,0 +1,19 @@
+{
+  "in_channels": 3,
+  "patch_size": 32,
+  "model_dim": 1024,
+  "encoder_depth": 8,
+  "decoder_depth": 8,
+  "decoder_start_blocks": 2,
+  "decoder_end_blocks": 2,
+  "bottleneck_dim": 384,
+  "mlp_ratio": 4.0,
+  "depthwise_kernel_size": 7,
+  "adaln_low_rank_rank": 128,
+  "bottleneck_posterior_kind": "diagonal_gaussian",
+  "bottleneck_norm_mode": "disabled",
+  "logsnr_min": -10.0,
+  "logsnr_max": 10.0,
+  "pixel_noise_std": 0.558,
+  "latent_running_stats_eps": 0.0001
+}

fcdm_diffae/__init__.py

@@ -0,0 +1,33 @@
+"""FCDMDiffAE: Standalone diffusion autoencoder with FCDM blocks.
+
+FCDM DiffAE — a fast diffusion autoencoder with a 128-channel spatial
+bottleneck and a VP-parameterized diagonal Gaussian posterior. Built on FCDM
+(Fully Convolutional Diffusion Model) blocks with GRN and scale+gate AdaLN.
+
+Usage::
+
+    from fcdm_diffae import FCDMDiffAE, FCDMDiffAEInferenceConfig
+
+    model = FCDMDiffAE.from_pretrained("path/to/weights", device="cuda")
+
+    # Encode (returns posterior mode by default)
+    latents = model.encode(images)  # images: [B,3,H,W] in [-1,1]
+
+    # Decode — PSNR-optimal (1 step, default)
+    recon = model.decode(latents, height=H, width=W)
+
+    # Decode — perceptual sharpness (10 steps + path-drop PDG)
+    cfg = FCDMDiffAEInferenceConfig(num_steps=10, pdg=True, pdg_strength=2.0)
+    recon = model.decode(latents, height=H, width=W, inference_config=cfg)
+"""
+
+from .config import FCDMDiffAEConfig, FCDMDiffAEInferenceConfig
+from .encoder import EncoderPosterior
+from .model import FCDMDiffAE
+
+__all__ = [
+    "EncoderPosterior",
+    "FCDMDiffAE",
+    "FCDMDiffAEConfig",
+    "FCDMDiffAEInferenceConfig",
+]

fcdm_diffae/adaln.py

@@ -0,0 +1,50 @@
+"""Scale+Gate AdaLN (2-way) for FCDM decoder blocks."""
+
+from __future__ import annotations
+
+from torch import Tensor, nn
+
+
+class AdaLNScaleGateZeroProjector(nn.Module):
+    """Packed 2-way AdaLN projection (SiLU -> Linear), zero-initialized.
+
+    Outputs [B, 2*d_model] packed as (scale, gate).
+    """
+
+    def __init__(self, d_model: int, d_cond: int) -> None:
+        super().__init__()
+        self.d_model: int = int(d_model)
+        self.d_cond: int = int(d_cond)
+        self.act: nn.SiLU = nn.SiLU()
+        self.proj: nn.Linear = nn.Linear(self.d_cond, 2 * self.d_model)
+        nn.init.zeros_(self.proj.weight)
+        nn.init.zeros_(self.proj.bias)
+
+    def forward_activated(self, act_cond: Tensor) -> Tensor:
+        """Return packed modulation for a pre-activated conditioning vector."""
+        return self.proj(act_cond)
+
+    def forward(self, cond: Tensor) -> Tensor:
+        """Return packed modulation [B, 2*d_model]."""
+        return self.forward_activated(self.act(cond))
+
+
+class AdaLNScaleGateZeroLowRankDelta(nn.Module):
+    """Low-rank delta for 2-way AdaLN: down(d_cond -> rank) -> up(rank -> 2*d_model).
+
+    Zero-initialized up projection preserves zero-output semantics at init.
+    """
+
+    def __init__(self, *, d_model: int, d_cond: int, rank: int) -> None:
+        super().__init__()
+        self.d_model: int = int(d_model)
+        self.d_cond: int = int(d_cond)
+        self.rank: int = int(rank)
+        self.down: nn.Linear = nn.Linear(self.d_cond, self.rank, bias=False)
+        self.up: nn.Linear = nn.Linear(self.rank, 2 * self.d_model, bias=False)
+        nn.init.normal_(self.down.weight, mean=0.0, std=0.02)
+        nn.init.zeros_(self.up.weight)
+
+    def forward(self, act_cond: Tensor) -> Tensor:
+        """Return packed delta modulation [B, 2*d_model]."""
+        return self.up(self.down(act_cond))

fcdm_diffae/config.py

@@ -0,0 +1,74 @@
+"""Frozen model architecture and user-tunable inference configuration."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class FCDMDiffAEConfig:
+    """Frozen model architecture config stored alongside exported weights."""
+
+    in_channels: int = 3
+    patch_size: int = 16
+    model_dim: int = 896
+    encoder_depth: int = 8
+    decoder_depth: int = 8
+    decoder_start_blocks: int = 2
+    decoder_end_blocks: int = 2
+    bottleneck_dim: int = 128
+    mlp_ratio: float = 4.0
+    depthwise_kernel_size: int = 7
+    adaln_low_rank_rank: int = 128
+    # Encoder posterior kind: "diagonal_gaussian" or "deterministic"
+    bottleneck_posterior_kind: str = "diagonal_gaussian"
+    # Post-bottleneck normalization: "channel_wise" or "disabled"
+    bottleneck_norm_mode: str = "disabled"
+    # VP diffusion schedule endpoints
+    logsnr_min: float = -10.0
+    logsnr_max: float = 10.0
+    # Pixel-space noise std for VP diffusion initialization
+    pixel_noise_std: float = 0.558
+    # Per-channel latent whitening epsilon used with running stats
+    latent_running_stats_eps: float = 1e-4
+
+    @property
+    def latent_channels(self) -> int:
+        """Channel width of the exported latent space."""
+        return self.bottleneck_dim
+
+    @property
+    def effective_patch_size(self) -> int:
+        """Effective spatial stride from image to latent grid."""
+        return self.patch_size
+
+    def save(self, path: str | Path) -> None:
+        """Save config as JSON."""
+        p = Path(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(json.dumps(asdict(self), indent=2) + "\n")
+
+    @classmethod
+    def load(cls, path: str | Path) -> FCDMDiffAEConfig:
+        """Load config from JSON."""
+        data = json.loads(Path(path).read_text())
+        return cls(**data)
+
+
+@dataclass
+class FCDMDiffAEInferenceConfig:
+    """User-tunable inference parameters with sensible defaults.
+
+    PDG (Path-Drop Guidance) sharpens reconstructions by degrading conditioning
+    in one pass and amplifying the difference. When enabled, uses 2 NFE per step.
+    Recommended: ``pdg=True, pdg_strength=2.0, num_steps=10``.
+    """
+
+    num_steps: int = 1  # number of denoising steps (NFE)
+    sampler: str = "ddim"  # "ddim" or "dpmpp_2m"
+    schedule: str = "linear"  # "linear" or "cosine"
+    pdg: bool = False  # enable PDG for perceptual sharpening
+    pdg_strength: float = 2.0  # CFG-like strength when pdg=True
+    seed: int | None = None

fcdm_diffae/decoder.py

@@ -0,0 +1,168 @@
+"""FCDM DiffAE decoder: skip-concat topology with FCDM blocks and path-drop PDG.
+
+No outer RMSNorms (use_other_outer_rms_norms=False during training):
+norm_in, latent_norm, and norm_out are all absent.
+"""
+
+from __future__ import annotations
+
+import torch
+from torch import Tensor, nn
+
+from .adaln import AdaLNScaleGateZeroLowRankDelta, AdaLNScaleGateZeroProjector
+from .fcdm_block import FCDMBlock
+from .straight_through_encoder import Patchify
+from .time_embed import SinusoidalTimeEmbeddingMLP
+
+
+class Decoder(nn.Module):
+    """VP diffusion decoder conditioned on encoder latents and timestep.
+
+    Architecture (skip-concat, 2+4+2 default):
+        Patchify x_t -> Fuse with upsampled z
+        -> Start blocks (2) -> Middle blocks (4) -> Skip fuse -> End blocks (2)
+        -> Conv1x1 -> PixelShuffle
+
+    Path-Drop Guidance (PDG) at inference:
+    - Replace middle block output with ``path_drop_mask_feature`` to create
+      an unconditional prediction, then extrapolate.
+    """
+
+    def __init__(
+        self,
+        in_channels: int,
+        patch_size: int,
+        model_dim: int,
+        depth: int,
+        start_block_count: int,
+        end_block_count: int,
+        bottleneck_dim: int,
+        mlp_ratio: float,
+        depthwise_kernel_size: int,
+        adaln_low_rank_rank: int,
+    ) -> None:
+        super().__init__()
+        self.patch_size = int(patch_size)
+        self.model_dim = int(model_dim)
+
+        # Input processing (no norm_in)
+        self.patchify = Patchify(in_channels, patch_size, model_dim)
+
+        # Latent conditioning path (no latent_norm)
+        self.latent_up = nn.Conv2d(bottleneck_dim, model_dim, kernel_size=1, bias=True)
+        self.fuse_in = nn.Conv2d(2 * model_dim, model_dim, kernel_size=1, bias=True)
+
+        # Time embedding
+        self.time_embed = SinusoidalTimeEmbeddingMLP(model_dim)
+
+        # 2-way AdaLN: shared base projector + per-block low-rank deltas
+        self.adaln_base = AdaLNScaleGateZeroProjector(
+            d_model=model_dim, d_cond=model_dim
+        )
+        self.adaln_deltas = nn.ModuleList(
+            [
+                AdaLNScaleGateZeroLowRankDelta(
+                    d_model=model_dim, d_cond=model_dim, rank=adaln_low_rank_rank
+                )
+                for _ in range(depth)
+            ]
+        )
+
+        # Block layout: start + middle + end
+        middle_count = depth - start_block_count - end_block_count
+        self._middle_start_idx = start_block_count
+        self._end_start_idx = start_block_count + middle_count
+
+        def _make_blocks(count: int) -> nn.ModuleList:
+            return nn.ModuleList(
+                [
+                    FCDMBlock(
+                        model_dim,
+                        mlp_ratio,
+                        depthwise_kernel_size=depthwise_kernel_size,
+                        use_external_adaln=True,
+                    )
+                    for _ in range(count)
+                ]
+            )
+
+        self.start_blocks = _make_blocks(start_block_count)
+        self.middle_blocks = _make_blocks(middle_count)
+        self.fuse_skip = nn.Conv2d(2 * model_dim, model_dim, kernel_size=1, bias=True)
+        self.end_blocks = _make_blocks(end_block_count)
+
+        # Learned mask feature for path-drop PDG
+        self.path_drop_mask_feature = nn.Parameter(torch.zeros((1, model_dim, 1, 1)))
+
+        # Output head (no norm_out)
+        self.out_proj = nn.Conv2d(
+            model_dim, in_channels * (patch_size**2), kernel_size=1, bias=True
+        )
+        self.unpatchify = nn.PixelShuffle(patch_size)
+
+    def _adaln_m_for_layer(self, cond: Tensor, layer_idx: int) -> Tensor:
+        """Compute packed AdaLN modulation = shared_base + per-layer delta."""
+        act = self.adaln_base.act(cond)
+        base_m = self.adaln_base.forward_activated(act)
+        delta_m = self.adaln_deltas[layer_idx](act)
+        return base_m + delta_m
+
+    def _run_blocks(
+        self, blocks: nn.ModuleList, x: Tensor, cond: Tensor, start_index: int
+    ) -> Tensor:
+        """Run a group of decoder blocks with per-block AdaLN modulation."""
+        for local_idx, block in enumerate(blocks):
+            adaln_m = self._adaln_m_for_layer(cond, layer_idx=start_index + local_idx)
+            x = block(x, adaln_m=adaln_m)
+        return x
+
+    def forward(
+        self,
+        x_t: Tensor,
+        t: Tensor,
+        latents: Tensor,
+        *,
+        drop_middle_blocks: bool = False,
+    ) -> Tensor:
+        """Single decoder forward pass.
+
+        Args:
+            x_t: Noised image [B, C, H, W].
+            t: Timestep [B] in [0, 1].
+            latents: Encoder latents [B, bottleneck_dim, h, w].
+            drop_middle_blocks: Replace middle block output with mask feature (PDG).
+
+        Returns:
+            x0 prediction [B, C, H, W].
+        """
+        x_feat = self.patchify(x_t)
+        z_up = self.latent_up(latents)
+
+        fused = torch.cat([x_feat, z_up], dim=1)
+        fused = self.fuse_in(fused)
+
+        cond = self.time_embed(t.to(torch.float32).to(device=x_t.device))
+
+        start_out = self._run_blocks(self.start_blocks, fused, cond, start_index=0)
+
+        if drop_middle_blocks:
+            middle_out = self.path_drop_mask_feature.to(
+                device=x_t.device, dtype=x_t.dtype
+            ).expand_as(start_out)
+        else:
+            middle_out = self._run_blocks(
+                self.middle_blocks,
+                start_out,
+                cond,
+                start_index=self._middle_start_idx,
+            )
+
+        skip_fused = torch.cat([start_out, middle_out], dim=1)
+        skip_fused = self.fuse_skip(skip_fused)
+
+        end_out = self._run_blocks(
+            self.end_blocks, skip_fused, cond, start_index=self._end_start_idx
+        )
+
+        patches = self.out_proj(end_out)
+        return self.unpatchify(patches)

fcdm_diffae/encoder.py

@@ -0,0 +1,137 @@
+"""FCDM DiffAE encoder: patchify -> FCDMBlocks -> diagonal Gaussian posterior.
+
+No input RMSNorm (use_other_outer_rms_norms=False during training).
+Post-bottleneck RMSNorm (affine=False) on the mean branch.
+Encoder outputs posterior mode by default: alpha * RMSNorm(mean).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import torch
+import torch.nn.functional as F
+from torch import Tensor, nn
+
+from .fcdm_block import FCDMBlock
+from .norms import ChannelWiseRMSNorm
+from .straight_through_encoder import Patchify
+
+
+@dataclass(frozen=True)
+class EncoderPosterior:
+    """VP-parameterized diagonal Gaussian posterior.
+
+    mean: Clean signal branch mu [B, bottleneck_dim, h, w]
+    logsnr: Per-element log signal-to-noise ratio [B, bottleneck_dim, h, w]
+    """
+
+    mean: Tensor
+    logsnr: Tensor
+
+    @property
+    def alpha(self) -> Tensor:
+        """VP signal coefficient computed stably in float32."""
+        logsnr_fp32 = self.logsnr.to(torch.float32)
+        return torch.exp(0.5 * F.logsigmoid(logsnr_fp32))
+
+    @property
+    def sigma(self) -> Tensor:
+        """VP noise coefficient computed stably in float32."""
+        logsnr_fp32 = self.logsnr.to(torch.float32)
+        return torch.exp(0.5 * F.logsigmoid(-logsnr_fp32))
+
+    def mode(self) -> Tensor:
+        """Posterior mode in token space: alpha * mean, computed in float32."""
+        return (self.alpha * self.mean.to(torch.float32)).to(dtype=self.mean.dtype)
+
+    def sample(self, *, generator: torch.Generator | None = None) -> Tensor:
+        """Sample from posterior: alpha * mean + sigma * eps, computed in float32."""
+        mean_fp32 = self.mean.to(torch.float32)
+        eps = torch.randn(
+            mean_fp32.shape,
+            device=mean_fp32.device,
+            dtype=torch.float32,
+            generator=generator,
+        )
+        return (self.alpha * mean_fp32 + self.sigma * eps).to(dtype=self.mean.dtype)
+
+
+class Encoder(nn.Module):
+    """Encoder: Image [B,3,H,W] -> latents [B,bottleneck_dim,h,w].
+
+    With diagonal_gaussian posterior, the to_bottleneck projection outputs
+    2 * bottleneck_dim channels, split into mean and logsnr. The default
+    encode() returns the posterior mode: alpha * RMSNorm(mean).
+    """
+
+    def __init__(
+        self,
+        in_channels: int,
+        patch_size: int,
+        model_dim: int,
+        depth: int,
+        bottleneck_dim: int,
+        mlp_ratio: float,
+        depthwise_kernel_size: int,
+        bottleneck_posterior_kind: str = "diagonal_gaussian",
+        bottleneck_norm_mode: str = "disabled",
+    ) -> None:
+        super().__init__()
+        self.bottleneck_dim = int(bottleneck_dim)
+        self.bottleneck_posterior_kind = bottleneck_posterior_kind
+        self.bottleneck_norm_mode = bottleneck_norm_mode
+        self.patchify = Patchify(in_channels, patch_size, model_dim)
+        self.blocks = nn.ModuleList(
+            [
+                FCDMBlock(
+                    model_dim,
+                    mlp_ratio,
+                    depthwise_kernel_size=depthwise_kernel_size,
+                    use_external_adaln=False,
+                )
+                for _ in range(depth)
+            ]
+        )
+        out_dim = (
+            2 * bottleneck_dim
+            if bottleneck_posterior_kind == "diagonal_gaussian"
+            else bottleneck_dim
+        )
+        self.to_bottleneck = nn.Conv2d(model_dim, out_dim, kernel_size=1, bias=True)
+        if bottleneck_norm_mode == "channel_wise":
+            self.norm_out = ChannelWiseRMSNorm(bottleneck_dim, eps=1e-6, affine=False)
+        else:
+            self.norm_out = nn.Identity()
+
+    def encode_posterior(self, images: Tensor) -> EncoderPosterior:
+        """Encode images and return the full posterior (mean + logsnr).
+
+        Only valid when bottleneck_posterior_kind == "diagonal_gaussian".
+        """
+        z = self.patchify(images)
+        for block in self.blocks:
+            z = block(z)
+        projection = self.to_bottleneck(z)
+        mean, logsnr = projection.chunk(2, dim=1)
+        mean = self.norm_out(mean)
+        return EncoderPosterior(mean=mean, logsnr=logsnr)
+
+    def forward(self, images: Tensor) -> Tensor:
+        """Encode images [B,3,H,W] in [-1,1] to latents [B,bottleneck_dim,h,w].
+
+        Returns posterior mode (alpha * mean) for diagonal_gaussian,
+        or deterministic latents otherwise.
+        """
+        z = self.patchify(images)
+        for block in self.blocks:
+            z = block(z)
+        projection = self.to_bottleneck(z)
+        if self.bottleneck_posterior_kind == "diagonal_gaussian":
+            mean, logsnr = projection.chunk(2, dim=1)
+            mean = self.norm_out(mean)
+            logsnr_fp32 = logsnr.to(torch.float32)
+            alpha = torch.exp(0.5 * F.logsigmoid(logsnr_fp32))
+            return (alpha * mean.to(torch.float32)).to(dtype=mean.dtype)
+        z = self.norm_out(projection)
+        return z

fcdm_diffae/fcdm_block.py

@@ -0,0 +1,103 @@
+"""FCDM block: ConvNeXt-style conv block with GRN and scale+gate AdaLN."""
+
+from __future__ import annotations
+
+import torch
+import torch.nn.functional as F
+from torch import Tensor, nn
+
+from .norms import ChannelWiseRMSNorm
+
+
+class GRN(nn.Module):
+    """Global Response Normalization for NCHW tensors."""
+
+    def __init__(self, channels: int, *, eps: float = 1e-6) -> None:
+        super().__init__()
+        self.eps: float = float(eps)
+        c = int(channels)
+        self.gamma = nn.Parameter(torch.zeros((1, c, 1, 1), dtype=torch.float32))
+        self.beta = nn.Parameter(torch.zeros((1, c, 1, 1), dtype=torch.float32))
+
+    def forward(self, x: Tensor) -> Tensor:
+        g = torch.linalg.vector_norm(x, ord=2, dim=(2, 3), keepdim=True)
+        g_fp32 = g.to(dtype=torch.float32)
+        n = (g_fp32 / (g_fp32.mean(dim=1, keepdim=True) + self.eps)).to(dtype=x.dtype)
+        gamma = self.gamma.to(device=x.device, dtype=x.dtype)
+        beta = self.beta.to(device=x.device, dtype=x.dtype)
+        return gamma * (x * n) + beta + x
+
+
+class FCDMBlock(nn.Module):
+    """ConvNeXt-style block with scale+gate AdaLN and GRN.
+
+    Two modes:
+    - Unconditioned (encoder): uses learned layer-scale for near-identity init.
+    - External AdaLN (decoder): receives packed [B, 2*C] modulation (scale, gate).
+      The gate is applied raw (no tanh).
+    """
+
+    def __init__(
+        self,
+        channels: int,
+        mlp_ratio: float,
+        *,
+        depthwise_kernel_size: int = 7,
+        use_external_adaln: bool = False,
+        norm_eps: float = 1e-6,
+        layer_scale_init: float = 1e-3,
+    ) -> None:
+        super().__init__()
+        self.channels: int = int(channels)
+        self.mlp_ratio: float = float(mlp_ratio)
+
+        self.dwconv = nn.Conv2d(
+            channels,
+            channels,
+            kernel_size=depthwise_kernel_size,
+            padding=depthwise_kernel_size // 2,
+            stride=1,
+            groups=channels,
+            bias=True,
+        )
+        self.norm = ChannelWiseRMSNorm(channels, eps=float(norm_eps), affine=False)
+        hidden = max(int(float(channels) * float(mlp_ratio)), 1)
+        self.pwconv1 = nn.Conv2d(channels, hidden, kernel_size=1, bias=True)
+        self.grn = GRN(hidden, eps=1e-6)
+        self.pwconv2 = nn.Conv2d(hidden, channels, kernel_size=1, bias=True)
+
+        if not use_external_adaln:
+            self.layer_scale = nn.Parameter(
+                torch.full((channels,), float(layer_scale_init))
+            )
+        else:
+            self.register_parameter("layer_scale", None)
+
+    def forward(self, x: Tensor, *, adaln_m: Tensor | None = None) -> Tensor:
+        b, c, _, _ = x.shape
+
+        if adaln_m is not None:
+            m = adaln_m.to(device=x.device, dtype=x.dtype)
+            scale, gate = m.chunk(2, dim=-1)
+        else:
+            scale = gate = None
+
+        h = self.dwconv(x)
+        h = self.norm(h)
+
+        if scale is not None:
+            h = h * (1.0 + scale.view(b, c, 1, 1))
+
+        h = self.pwconv1(h)
+        h = F.gelu(h)
+        h = self.grn(h)
+        h = self.pwconv2(h)
+
+        if gate is not None:
+            gate_view = gate.view(b, c, 1, 1)
+        else:
+            gate_view = self.layer_scale.view(1, c, 1, 1).to(  # type: ignore[union-attr]
+                device=h.device, dtype=h.dtype
+            )
+
+        return x + gate_view * h

fcdm_diffae/model.py

@@ -0,0 +1,420 @@
+"""FCDMDiffAE: standalone HuggingFace-compatible diffusion autoencoder."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+import torch
+from torch import Tensor, nn
+
+from .config import FCDMDiffAEConfig, FCDMDiffAEInferenceConfig
+from .decoder import Decoder
+from .encoder import Encoder, EncoderPosterior
+from .samplers import run_ddim, run_dpmpp_2m
+from .vp_diffusion import get_schedule, make_initial_state, sample_noise
+
+
+def _resolve_model_dir(
+    path_or_repo_id: str | Path,
+    *,
+    revision: str | None,
+    cache_dir: str | Path | None,
+) -> Path:
+    """Resolve a local path or HuggingFace Hub repo ID to a local directory."""
+    local = Path(path_or_repo_id)
+    if local.is_dir():
+        return local
+    repo_id = str(path_or_repo_id)
+    try:
+        from huggingface_hub import snapshot_download
+    except ImportError:
+        raise ImportError(
+            f"'{repo_id}' is not an existing local directory. "
+            "To download from HuggingFace Hub, install huggingface_hub: "
+            "pip install huggingface_hub"
+        )
+    cache_dir_str = str(cache_dir) if cache_dir is not None else None
+    local_dir = snapshot_download(
+        repo_id,
+        revision=revision,
+        cache_dir=cache_dir_str,
+    )
+    return Path(local_dir)
+
+
+class FCDMDiffAE(nn.Module):
+    """Standalone FCDM DiffAE model for HuggingFace distribution.
+
+    A diffusion autoencoder built on FCDM (Fully Convolutional Diffusion Model)
+    blocks. Encodes images to compact 128-channel spatial latents via a
+    VP-parameterized diagonal Gaussian posterior, and decodes them back via
+    iterative VP diffusion with a skip-concat decoder.
+
+    Usage::
+
+        model = FCDMDiffAE.from_pretrained("path/to/weights")
+        model = model.to("cuda", dtype=torch.bfloat16)
+
+        # Encode (returns posterior mode by default)
+        latents = model.encode(images)  # images: [B,3,H,W] in [-1,1]
+
+        # Decode (1 step by default — PSNR-optimal)
+        recon = model.decode(latents, height=H, width=W)
+
+        # Reconstruct (encode + 1-step decode)
+        recon = model.reconstruct(images)
+    """
+
+    def __init__(self, config: FCDMDiffAEConfig) -> None:
+        super().__init__()
+        self.config = config
+
+        # Latent running stats for whitening/dewhitening (at exported latent channels)
+        self.register_buffer(
+            "latent_norm_running_mean",
+            torch.zeros((config.latent_channels,), dtype=torch.float32),
+        )
+        self.register_buffer(
+            "latent_norm_running_var",
+            torch.ones((config.latent_channels,), dtype=torch.float32),
+        )
+
+        self.encoder = Encoder(
+            in_channels=config.in_channels,
+            patch_size=config.patch_size,
+            model_dim=config.model_dim,
+            depth=config.encoder_depth,
+            bottleneck_dim=config.bottleneck_dim,
+            mlp_ratio=config.mlp_ratio,
+            depthwise_kernel_size=config.depthwise_kernel_size,
+            bottleneck_posterior_kind=config.bottleneck_posterior_kind,
+            bottleneck_norm_mode=config.bottleneck_norm_mode,
+        )
+
+        self.decoder = Decoder(
+            in_channels=config.in_channels,
+            patch_size=config.patch_size,
+            model_dim=config.model_dim,
+            depth=config.decoder_depth,
+            start_block_count=config.decoder_start_blocks,
+            end_block_count=config.decoder_end_blocks,
+            bottleneck_dim=config.bottleneck_dim,
+            mlp_ratio=config.mlp_ratio,
+            depthwise_kernel_size=config.depthwise_kernel_size,
+            adaln_low_rank_rank=config.adaln_low_rank_rank,
+        )
+
+    def _restore_float32_norm_buffers(self) -> None:
+        """Keep latent whitening statistics in float32 after dtype/device moves."""
+
+        self.latent_norm_running_mean = self.latent_norm_running_mean.to(
+            dtype=torch.float32
+        )
+        self.latent_norm_running_var = self.latent_norm_running_var.to(
+            dtype=torch.float32
+        )
+
+    def _apply(
+        self,
+        fn: Callable[[Tensor], Tensor],
+        recurse: bool = True,
+    ) -> FCDMDiffAE:
+        """Apply module tensor transforms while preserving float32 latent stats."""
+
+        applied = super()._apply(fn, recurse=recurse)
+        if not isinstance(applied, FCDMDiffAE):
+            raise RuntimeError(
+                f"Expected FCDMDiffAE after nn.Module._apply(), got {type(applied).__name__}"
+            )
+        applied._restore_float32_norm_buffers()
+        return applied
+
+    def to(self, *args: object, **kwargs: object) -> FCDMDiffAE:
+        """Move the module while preserving latent whitening stats in float32."""
+
+        moved = super().to(*args, **kwargs)
+        if not isinstance(moved, FCDMDiffAE):
+            raise RuntimeError(
+                f"Expected FCDMDiffAE after nn.Module.to(), got {type(moved).__name__}"
+            )
+        moved._restore_float32_norm_buffers()
+        return moved
+
+    @classmethod
+    def from_pretrained(
+        cls,
+        path_or_repo_id: str | Path,
+        *,
+        dtype: torch.dtype = torch.bfloat16,
+        device: str | torch.device = "cpu",
+        revision: str | None = None,
+        cache_dir: str | Path | None = None,
+    ) -> FCDMDiffAE:
+        """Load a pretrained model from a local directory or HuggingFace Hub.
+
+        The directory (or repo) should contain:
+        - config.json: Model architecture config.
+        - model.safetensors (preferred) or model.pt: Model weights.
+
+        Args:
+            path_or_repo_id: Local directory path or HuggingFace Hub repo ID.
+            dtype: Load weights in this dtype (float32 or bfloat16).
+            device: Target device.
+            revision: Git revision for Hub downloads.
+            cache_dir: Where to cache Hub downloads.
+
+        Returns:
+            Loaded model in eval mode.
+        """
+        model_dir = _resolve_model_dir(
+            path_or_repo_id, revision=revision, cache_dir=cache_dir
+        )
+        config = FCDMDiffAEConfig.load(model_dir / "config.json")
+        model = cls(config)
+
+        safetensors_path = model_dir / "model.safetensors"
+        pt_path = model_dir / "model.pt"
+
+        if safetensors_path.exists():
+            try:
+                from safetensors.torch import load_file
+
+                state_dict = load_file(str(safetensors_path), device=str(device))
+            except ImportError:
+                raise ImportError(
+                    "safetensors package required to load .safetensors files. "
+                    "Install with: pip install safetensors"
+                )
+        elif pt_path.exists():
+            state_dict = torch.load(
+                str(pt_path), map_location=device, weights_only=True
+            )
+        else:
+            raise FileNotFoundError(
+                f"No model weights found in {model_dir}. "
+                "Expected model.safetensors or model.pt."
+            )
+
+        model.load_state_dict(state_dict)
+        model = model.to(dtype=dtype, device=torch.device(device))
+        model.eval()
+        return model
+
+    def _latent_norm_stats(self) -> tuple[Tensor, Tensor]:
+        """Return (mean, std) tensors for latent whitening, shaped [1,C,1,1]."""
+        mean = self.latent_norm_running_mean.view(1, -1, 1, 1)
+        var = self.latent_norm_running_var.view(1, -1, 1, 1)
+        std = torch.sqrt(
+            var.to(torch.float32) + float(self.config.latent_running_stats_eps)
+        )
+        return mean.to(torch.float32), std
+
+    def whiten(self, latents: Tensor) -> Tensor:
+        """Whiten encoder latents using per-channel running stats.
+
+        Use this before passing latents to a downstream latent-space
+        diffusion model. The whitened latents have approximately zero mean
+        and unit variance per channel.
+
+        Args:
+            latents: [B, bottleneck_dim, h, w] raw encoder output.
+
+        Returns:
+            Whitened latents [B, bottleneck_dim, h, w] in float32.
+        """
+        z = latents.to(torch.float32)
+        mean, std = self._latent_norm_stats()
+        return (z - mean.to(device=z.device)) / std.to(device=z.device)
+
+    def dewhiten(self, latents: Tensor) -> Tensor:
+        """Undo whitening to recover raw encoder latent scale.
+
+        Use this before passing whitened latents back to ``decode()``.
+
+        Args:
+            latents: [B, bottleneck_dim, h, w] whitened latents.
+
+        Returns:
+            Dewhitened latents [B, bottleneck_dim, h, w] in float32.
+        """
+        z = latents.to(torch.float32)
+        mean, std = self._latent_norm_stats()
+        return z * std.to(device=z.device) + mean.to(device=z.device)
+
+    def encode(self, images: Tensor) -> Tensor:
+        """Encode images to whitened latents (posterior mode).
+
+        Returns latents whitened using per-channel running stats, ready for
+        use by downstream latent-space diffusion models.
+
+        Args:
+            images: [B, 3, H, W] in [-1, 1], H and W divisible by
+                effective_patch_size.
+
+        Returns:
+            Whitened latents [B, latent_channels, H/effective_patch, W/effective_patch].
+        """
+        eff_patch = self.config.effective_patch_size
+        h, w = int(images.shape[2]), int(images.shape[3])
+        if h % eff_patch != 0 or w % eff_patch != 0:
+            raise ValueError(
+                f"Image height={h} and width={w} must be divisible by "
+                f"effective_patch_size={eff_patch}"
+            )
+        try:
+            model_dtype = next(self.parameters()).dtype
+        except StopIteration:
+            model_dtype = torch.float32
+        z = self.encoder(images.to(dtype=model_dtype))
+        return self.whiten(z).to(dtype=model_dtype)
+
+    def encode_posterior(self, images: Tensor) -> EncoderPosterior:
+        """Encode images and return the full posterior (mean + logsnr).
+
+        Args:
+            images: [B, 3, H, W] in [-1, 1], H and W divisible by
+                effective_patch_size.
+
+        Returns:
+            EncoderPosterior with mean and logsnr tensors in the exported
+            latent space.
+        """
+        eff_patch = self.config.effective_patch_size
+        h, w = int(images.shape[2]), int(images.shape[3])
+        if h % eff_patch != 0 or w % eff_patch != 0:
+            raise ValueError(
+                f"Image height={h} and width={w} must be divisible by "
+                f"effective_patch_size={eff_patch}"
+            )
+        try:
+            model_dtype = next(self.parameters()).dtype
+        except StopIteration:
+            model_dtype = torch.float32
+        posterior = self.encoder.encode_posterior(images.to(dtype=model_dtype))
+        return posterior
+
+    @torch.no_grad()
+    def decode(
+        self,
+        latents: Tensor,
+        height: int,
+        width: int,
+        *,
+        inference_config: FCDMDiffAEInferenceConfig | None = None,
+    ) -> Tensor:
+        """Decode whitened latents to images via VP diffusion.
+
+        Latents are dewhitened before being passed to the decoder.
+
+        Args:
+            latents: [B, latent_channels, h, w] whitened encoder latents.
+            height: Output image height (divisible by effective_patch_size).
+            width: Output image width (divisible by effective_patch_size).
+            inference_config: Optional inference parameters.
+
+        Returns:
+            Reconstructed images [B, 3, H, W] in float32.
+        """
+        cfg = inference_config or FCDMDiffAEInferenceConfig()
+        config = self.config
+        batch = int(latents.shape[0])
+        device = latents.device
+
+        try:
+            model_dtype = next(self.parameters()).dtype
+        except StopIteration:
+            model_dtype = torch.float32
+
+        eff_patch = config.effective_patch_size
+        if height % eff_patch != 0 or width % eff_patch != 0:
+            raise ValueError(
+                f"height={height} and width={width} must be divisible by "
+                f"effective_patch_size={eff_patch}"
+            )
+
+        latents = self.dewhiten(latents)
+        latents = latents.to(dtype=model_dtype)
+
+        shape = (batch, config.in_channels, height, width)
+        noise = sample_noise(
+            shape,
+            noise_std=config.pixel_noise_std,
+            seed=cfg.seed,
+            device=torch.device("cpu"),
+            dtype=torch.float32,
+        )
+
+        schedule = get_schedule(cfg.schedule, cfg.num_steps).to(device=device)
+        initial_state = make_initial_state(
+            noise=noise.to(device=device),
+            t_start=schedule[0:1],
+            logsnr_min=config.logsnr_min,
+            logsnr_max=config.logsnr_max,
+        )
+
+        device_type = "cuda" if device.type == "cuda" else "cpu"
+        with torch.autocast(device_type=device_type, enabled=False):
+            latents_in = latents.to(device=device)
+
+            def _forward_fn(
+                x_t: Tensor,
+                t: Tensor,
+                latents: Tensor,
+                *,
+                drop_middle_blocks: bool = False,
+                mask_latent_tokens: bool = False,
+            ) -> Tensor:
+                return self.decoder(
+                    x_t.to(dtype=model_dtype),
+                    t,
+                    latents.to(dtype=model_dtype),
+                    drop_middle_blocks=drop_middle_blocks,
+                )
+
+            pdg_mode = "path_drop" if cfg.pdg else "disabled"
+
+            if cfg.sampler == "ddim":
+                sampler_fn = run_ddim
+            elif cfg.sampler == "dpmpp_2m":
+                sampler_fn = run_dpmpp_2m
+            else:
+                raise ValueError(
+                    f"Unsupported sampler: {cfg.sampler!r}. Use 'ddim' or 'dpmpp_2m'."
+                )
+
+            result = sampler_fn(
+                forward_fn=_forward_fn,
+                initial_state=initial_state,
+                schedule=schedule,
+                latents=latents_in,
+                logsnr_min=config.logsnr_min,
+                logsnr_max=config.logsnr_max,
+                pdg_mode=pdg_mode,
+                pdg_strength=cfg.pdg_strength,
+                device=device,
+            )
+
+        return result
+
+    @torch.no_grad()
+    def reconstruct(
+        self,
+        images: Tensor,
+        *,
+        inference_config: FCDMDiffAEInferenceConfig | None = None,
+    ) -> Tensor:
+        """Encode then decode. Convenience wrapper.
+
+        Args:
+            images: [B, 3, H, W] in [-1, 1].
+            inference_config: Optional inference parameters.
+
+        Returns:
+            Reconstructed images [B, 3, H, W] in float32.
+        """
+        latents = self.encode(images)
+        _, _, h, w = images.shape
+        return self.decode(
+            latents, height=h, width=w, inference_config=inference_config
+        )

fcdm_diffae/norms.py

@@ -0,0 +1,39 @@
+"""Channel-wise RMSNorm for NCHW tensors."""
+
+from __future__ import annotations
+
+import torch
+from torch import Tensor, nn
+
+
+class ChannelWiseRMSNorm(nn.Module):
+    """Channel-wise RMSNorm with float32 reduction for numerical stability.
+
+    Normalizes across channels per spatial position. Supports optional
+    per-channel affine weight and bias.
+    """
+
+    def __init__(self, channels: int, eps: float = 1e-6, affine: bool = True) -> None:
+        super().__init__()
+        self.channels: int = int(channels)
+        self._eps: float = float(eps)
+        if affine:
+            self.weight = nn.Parameter(torch.ones(self.channels))
+            self.bias = nn.Parameter(torch.zeros(self.channels))
+        else:
+            self.register_parameter("weight", None)
+            self.register_parameter("bias", None)
+
+    def forward(self, x: Tensor) -> Tensor:
+        if x.dim() < 2:
+            return x
+        # Float32 accumulation for stability
+        ms = torch.mean(torch.square(x), dim=1, keepdim=True, dtype=torch.float32)
+        inv_rms = torch.rsqrt(ms + self._eps)
+        y = x * inv_rms.to(dtype=x.dtype)
+        if self.weight is not None:
+            shape = (1, -1) + (1,) * (x.dim() - 2)
+            y = y * self.weight.view(shape).to(dtype=x.dtype)
+            if self.bias is not None:
+                y = y + self.bias.view(shape).to(dtype=x.dtype)
+        return y

fcdm_diffae/samplers.py

@@ -0,0 +1,255 @@
+"""DDIM and DPM++2M samplers for VP diffusion with path-drop PDG support."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+import torch
+from torch import Tensor
+
+from .vp_diffusion import (
+    alpha_sigma_from_logsnr,
+    broadcast_time_like,
+    shifted_cosine_interpolated_logsnr_from_t,
+)
+
+
+class DecoderForwardFn(Protocol):
+    """Callable that predicts x0 from (x_t, t, latents) with path-drop PDG flag."""
+
+    def __call__(
+        self,
+        x_t: Tensor,
+        t: Tensor,
+        latents: Tensor,
+        *,
+        drop_middle_blocks: bool = False,
+        mask_latent_tokens: bool = False,
+    ) -> Tensor: ...
+
+
+def _reconstruct_eps_from_x0(
+    *, x_t: Tensor, x0_hat: Tensor, alpha: Tensor, sigma: Tensor
+) -> Tensor:
+    """Reconstruct eps_hat from (x_t, x0_hat) under VP parameterization.
+
+    eps_hat = (x_t - alpha * x0_hat) / sigma. All float32.
+    """
+    alpha_view = broadcast_time_like(alpha, x_t).to(dtype=torch.float32)
+    sigma_view = broadcast_time_like(sigma, x_t).to(dtype=torch.float32)
+    x_t_f32 = x_t.to(torch.float32)
+    x0_f32 = x0_hat.to(torch.float32)
+    return (x_t_f32 - alpha_view * x0_f32) / sigma_view
+
+
+def _ddim_step(
+    *,
+    x0_hat: Tensor,
+    eps_hat: Tensor,
+    alpha_next: Tensor,
+    sigma_next: Tensor,
+    ref: Tensor,
+) -> Tensor:
+    """DDIM step: x_next = alpha_next * x0_hat + sigma_next * eps_hat."""
+    a = broadcast_time_like(alpha_next, ref).to(dtype=torch.float32)
+    s = broadcast_time_like(sigma_next, ref).to(dtype=torch.float32)
+    return a * x0_hat + s * eps_hat
+
+
+def _predict_with_pdg(
+    forward_fn: DecoderForwardFn,
+    state: Tensor,
+    t_vec: Tensor,
+    latents: Tensor,
+    *,
+    pdg_mode: str,
+    pdg_strength: float,
+) -> Tensor:
+    """Run decoder forward with optional PDG guidance.
+
+    Args:
+        forward_fn: Decoder forward function.
+        state: Current noised state [B, C, H, W].
+        t_vec: Timestep vector [B].
+        latents: Encoder latents.
+        pdg_mode: "disabled" or "path_drop".
+        pdg_strength: CFG-like strength for PDG.
+
+    Returns:
+        x0_hat prediction in float32.
+    """
+    if pdg_mode == "path_drop":
+        x0_uncond = forward_fn(state, t_vec, latents, drop_middle_blocks=True).to(
+            torch.float32
+        )
+        x0_cond = forward_fn(state, t_vec, latents, drop_middle_blocks=False).to(
+            torch.float32
+        )
+        return x0_uncond + pdg_strength * (x0_cond - x0_uncond)
+    else:
+        return forward_fn(state, t_vec, latents, drop_middle_blocks=False).to(
+            torch.float32
+        )
+
+
+def run_ddim(
+    *,
+    forward_fn: DecoderForwardFn,
+    initial_state: Tensor,
+    schedule: Tensor,
+    latents: Tensor,
+    logsnr_min: float,
+    logsnr_max: float,
+    log_change_high: float = 0.0,
+    log_change_low: float = 0.0,
+    pdg_mode: str = "disabled",
+    pdg_strength: float = 1.5,
+    device: torch.device | None = None,
+) -> Tensor:
+    """Run DDIM sampling loop with path-drop PDG support.
+
+    Args:
+        forward_fn: Decoder forward function (x_t, t, latents) -> x0_hat.
+        initial_state: Starting noised state [B, C, H, W] in float32.
+        schedule: Descending t-schedule [num_steps] in [0, 1].
+        latents: Encoder latents [B, bottleneck_dim, h, w].
+        logsnr_min, logsnr_max: VP schedule endpoints.
+        log_change_high, log_change_low: Shifted-cosine schedule parameters.
+        pdg_mode: "disabled" or "path_drop".
+        pdg_strength: CFG-like strength for PDG.
+        device: Target device.
+
+    Returns:
+        Denoised samples [B, C, H, W] in float32.
+    """
+    run_device = device or initial_state.device
+    batch_size = int(initial_state.shape[0])
+    state = initial_state.to(device=run_device, dtype=torch.float32)
+
+    # Precompute logSNR, alpha, sigma for all schedule points
+    lmb = shifted_cosine_interpolated_logsnr_from_t(
+        schedule.to(device=run_device),
+        logsnr_min=logsnr_min,
+        logsnr_max=logsnr_max,
+        log_change_high=log_change_high,
+        log_change_low=log_change_low,
+    )
+    alpha_sched, sigma_sched = alpha_sigma_from_logsnr(lmb)
+
+    for i in range(int(schedule.numel()) - 1):
+        t_i = schedule[i]
+        a_t = alpha_sched[i].expand(batch_size)
+        s_t = sigma_sched[i].expand(batch_size)
+        a_next = alpha_sched[i + 1].expand(batch_size)
+        s_next = sigma_sched[i + 1].expand(batch_size)
+
+        # Model prediction with optional PDG
+        t_vec = t_i.expand(batch_size).to(device=run_device, dtype=torch.float32)
+        x0_hat = _predict_with_pdg(
+            forward_fn,
+            state,
+            t_vec,
+            latents,
+            pdg_mode=pdg_mode,
+            pdg_strength=pdg_strength,
+        )
+
+        eps_hat = _reconstruct_eps_from_x0(
+            x_t=state, x0_hat=x0_hat, alpha=a_t, sigma=s_t
+        )
+        state = _ddim_step(
+            x0_hat=x0_hat,
+            eps_hat=eps_hat,
+            alpha_next=a_next,
+            sigma_next=s_next,
+            ref=state,
+        )
+
+    return state
+
+
+def run_dpmpp_2m(
+    *,
+    forward_fn: DecoderForwardFn,
+    initial_state: Tensor,
+    schedule: Tensor,
+    latents: Tensor,
+    logsnr_min: float,
+    logsnr_max: float,
+    log_change_high: float = 0.0,
+    log_change_low: float = 0.0,
+    pdg_mode: str = "disabled",
+    pdg_strength: float = 1.5,
+    device: torch.device | None = None,
+) -> Tensor:
+    """Run DPM++2M sampling loop with path-drop PDG support.
+
+    Multi-step solver using exponential integrator formulation in half-lambda space.
+    """
+    run_device = device or initial_state.device
+    batch_size = int(initial_state.shape[0])
+    state = initial_state.to(device=run_device, dtype=torch.float32)
+
+    # Precompute logSNR, alpha, sigma, half-lambda for all schedule points
+    lmb = shifted_cosine_interpolated_logsnr_from_t(
+        schedule.to(device=run_device),
+        logsnr_min=logsnr_min,
+        logsnr_max=logsnr_max,
+        log_change_high=log_change_high,
+        log_change_low=log_change_low,
+    )
+    alpha_sched, sigma_sched = alpha_sigma_from_logsnr(lmb)
+    half_lambda = 0.5 * lmb.to(torch.float32)
+
+    x0_prev: Tensor | None = None
+
+    for i in range(int(schedule.numel()) - 1):
+        t_i = schedule[i]
+        s_t = sigma_sched[i].expand(batch_size)
+        a_next = alpha_sched[i + 1].expand(batch_size)
+        s_next = sigma_sched[i + 1].expand(batch_size)
+
+        # Model prediction with optional PDG
+        t_vec = t_i.expand(batch_size).to(device=run_device, dtype=torch.float32)
+        x0_hat = _predict_with_pdg(
+            forward_fn,
+            state,
+            t_vec,
+            latents,
+            pdg_mode=pdg_mode,
+            pdg_strength=pdg_strength,
+        )
+
+        lam_t = half_lambda[i].expand(batch_size)
+        lam_next = half_lambda[i + 1].expand(batch_size)
+        h = (lam_next - lam_t).to(torch.float32)
+        phi_1 = torch.expm1(-h)
+
+        sigma_ratio = (s_next / s_t).to(torch.float32)
+
+        if i == 0 or x0_prev is None:
+            # First-order step
+            state = (
+                sigma_ratio.view(-1, *([1] * (state.dim() - 1))) * state
+                - broadcast_time_like(a_next, state).to(torch.float32)
+                * broadcast_time_like(phi_1, state).to(torch.float32)
+                * x0_hat
+            )
+        else:
+            # Second-order step
+            lam_prev = half_lambda[i - 1].expand(batch_size)
+            h_0 = (lam_t - lam_prev).to(torch.float32)
+            r0 = h_0 / h
+            d1_0 = (x0_hat - x0_prev) / broadcast_time_like(r0, x0_hat)
+            common = broadcast_time_like(a_next, state).to(
+                torch.float32
+            ) * broadcast_time_like(phi_1, state).to(torch.float32)
+            state = (
+                sigma_ratio.view(-1, *([1] * (state.dim() - 1))) * state
+                - common * x0_hat
+                - 0.5 * common * d1_0
+            )
+
+        x0_prev = x0_hat
+
+    return state

fcdm_diffae/straight_through_encoder.py

@@ -0,0 +1,27 @@
+"""PixelUnshuffle-based patchifier (no residual conv path)."""
+
+from __future__ import annotations
+
+from torch import Tensor, nn
+
+
+class Patchify(nn.Module):
+    """PixelUnshuffle(patch) -> Conv2d 1x1 projection.
+
+    Converts [B, C, H, W] images into [B, out_channels, H/patch, W/patch] features.
+    """
+
+    def __init__(self, in_channels: int, patch: int, out_channels: int) -> None:
+        super().__init__()
+        self.patch = int(patch)
+        self.unshuffle = nn.PixelUnshuffle(self.patch)
+        in_after = in_channels * (self.patch * self.patch)
+        self.proj = nn.Conv2d(in_after, out_channels, kernel_size=1, bias=True)
+
+    def forward(self, x: Tensor) -> Tensor:
+        if x.shape[2] % self.patch != 0 or x.shape[3] % self.patch != 0:
+            raise ValueError(
+                f"Input H={x.shape[2]} and W={x.shape[3]} must be divisible by patch={self.patch}"
+            )
+        y = self.unshuffle(x)
+        return self.proj(y)

fcdm_diffae/time_embed.py

@@ -0,0 +1,83 @@
+"""Sinusoidal timestep embedding with MLP projection."""
+
+from __future__ import annotations
+
+import math
+
+import torch
+from torch import Tensor, nn
+
+
+def _log_spaced_frequencies(
+    half: int, max_period: float, *, device: torch.device | None = None
+) -> Tensor:
+    """Log-spaced frequencies for sinusoidal embedding."""
+    return torch.exp(
+        -math.log(max_period)
+        * torch.arange(half, device=device, dtype=torch.float32)
+        / max(float(half - 1), 1.0)
+    )
+
+
+def sinusoidal_time_embedding(
+    t: Tensor,
+    dim: int,
+    *,
+    max_period: float = 10000.0,
+    scale: float | None = None,
+    freqs: Tensor | None = None,
+) -> Tensor:
+    """Sinusoidal timestep embedding (DDPM/DiT-style). Always float32."""
+    t32 = t.to(torch.float32)
+    if scale is not None:
+        t32 = t32 * float(scale)
+    half = dim // 2
+    if freqs is not None:
+        freqs = freqs.to(device=t32.device, dtype=torch.float32)
+    else:
+        freqs = _log_spaced_frequencies(half, max_period, device=t32.device)
+    angles = t32[:, None] * freqs[None, :]
+    return torch.cat([torch.sin(angles), torch.cos(angles)], dim=-1)
+
+
+class SinusoidalTimeEmbeddingMLP(nn.Module):
+    """Sinusoidal time embedding followed by Linear -> SiLU -> Linear."""
+
+    def __init__(
+        self,
+        dim: int,
+        *,
+        freq_dim: int = 256,
+        hidden_mult: float = 1.0,
+        time_scale: float = 1000.0,
+        max_period: float = 10000.0,
+    ) -> None:
+        super().__init__()
+        self.dim = int(dim)
+        self.freq_dim = int(freq_dim)
+        self.time_scale = float(time_scale)
+        self.max_period = float(max_period)
+        hidden_dim = max(int(round(int(dim) * float(hidden_mult))), 1)
+
+        freqs = _log_spaced_frequencies(self.freq_dim // 2, self.max_period)
+        self.register_buffer("freqs", freqs, persistent=True)
+
+        self.proj_in = nn.Linear(self.freq_dim, hidden_dim)
+        self.act = nn.SiLU()
+        self.proj_out = nn.Linear(hidden_dim, self.dim)
+
+    def forward(self, t: Tensor) -> Tensor:
+        freqs: Tensor = self.freqs  # type: ignore[assignment]
+        emb_freq = sinusoidal_time_embedding(
+            t.to(torch.float32),
+            self.freq_dim,
+            max_period=self.max_period,
+            scale=self.time_scale,
+            freqs=freqs,
+        )
+        dtype_in = self.proj_in.weight.dtype
+        hidden = self.proj_in(emb_freq.to(dtype_in))
+        hidden = self.act(hidden)
+        if hidden.dtype != self.proj_out.weight.dtype:
+            hidden = hidden.to(self.proj_out.weight.dtype)
+        return self.proj_out(hidden)

fcdm_diffae/vp_diffusion.py

@@ -0,0 +1,150 @@
+"""VP diffusion math: logSNR schedules, alpha/sigma computation, noise construction."""
+
+from __future__ import annotations
+
+import math
+
+import torch
+import torch.nn.functional as F
+from torch import Tensor
+
+
+def alpha_sigma_from_logsnr(lmb: Tensor) -> tuple[Tensor, Tensor]:
+    """Compute (alpha, sigma) from logSNR in float32.
+
+    VP constraint: alpha^2 + sigma^2 = 1.
+    """
+    lmb32 = lmb.to(dtype=torch.float32)
+    alpha = torch.exp(0.5 * F.logsigmoid(lmb32))
+    sigma = torch.exp(0.5 * F.logsigmoid(-lmb32))
+    return alpha, sigma
+
+
+def broadcast_time_like(coeff: Tensor, x: Tensor) -> Tensor:
+    """Broadcast [B] coefficient to match x for per-sample scaling."""
+    view_shape = (int(x.shape[0]),) + (1,) * (x.dim() - 1)
+    return coeff.view(view_shape)
+
+
+def _cosine_interpolated_params(
+    logsnr_min: float, logsnr_max: float
+) -> tuple[float, float]:
+    """Compute (a, b) for cosine-interpolated logSNR schedule.
+
+    logsnr(t) = -2 * log(tan(a*t + b))
+    logsnr(0) = logsnr_max, logsnr(1) = logsnr_min
+    """
+    b = math.atan(math.exp(-0.5 * logsnr_max))
+    a = math.atan(math.exp(-0.5 * logsnr_min)) - b
+    return a, b
+
+
+def cosine_interpolated_logsnr_from_t(
+    t: Tensor, *, logsnr_min: float, logsnr_max: float
+) -> Tensor:
+    """Map t in [0,1] to logSNR via cosine-interpolated schedule. Always float32."""
+    a, b = _cosine_interpolated_params(logsnr_min, logsnr_max)
+    t32 = t.to(dtype=torch.float32)
+    a_t = torch.tensor(a, device=t32.device, dtype=torch.float32)
+    b_t = torch.tensor(b, device=t32.device, dtype=torch.float32)
+    u = a_t * t32 + b_t
+    return -2.0 * torch.log(torch.tan(u))
+
+
+def shifted_cosine_interpolated_logsnr_from_t(
+    t: Tensor,
+    *,
+    logsnr_min: float,
+    logsnr_max: float,
+    log_change_high: float = 0.0,
+    log_change_low: float = 0.0,
+) -> Tensor:
+    """SiD2 "shifted cosine" schedule: logSNR with resolution-dependent shifts.
+
+    lambda(t) = (1-t) * (base(t) + log_change_high) + t * (base(t) + log_change_low)
+    """
+    base = cosine_interpolated_logsnr_from_t(
+        t, logsnr_min=logsnr_min, logsnr_max=logsnr_max
+    )
+    t32 = t.to(dtype=torch.float32)
+    high = base + float(log_change_high)
+    low = base + float(log_change_low)
+    return (1.0 - t32) * high + t32 * low
+
+
+def get_schedule(schedule_type: str, num_steps: int) -> Tensor:
+    """Generate a descending t-schedule in [0, 1] for VP diffusion sampling.
+
+    ``num_steps`` is the number of function evaluations (NFE = decoder forward
+    passes).  Internally the schedule has ``num_steps + 1`` time points
+    (including both endpoints).
+
+    Args:
+        schedule_type: "linear" or "cosine".
+        num_steps: Number of decoder forward passes (NFE), >= 1.
+
+    Returns:
+        Descending 1D tensor with ``num_steps + 1`` elements from ~1.0 to ~0.0.
+    """
+    # num_steps is the number of decoder evaluations exposed to users.
+    # The schedule therefore needs one additional endpoint.
+    n = max(int(num_steps) + 1, 2)
+    if schedule_type == "linear":
+        base = torch.linspace(0.0, 1.0, n)
+    elif schedule_type == "cosine":
+        i = torch.arange(n, dtype=torch.float32)
+        base = 0.5 * (1.0 - torch.cos(math.pi * (i / (n - 1))))
+    else:
+        raise ValueError(
+            f"Unsupported schedule type: {schedule_type!r}. Use 'linear' or 'cosine'."
+        )
+    # Descending: high t (noisy) -> low t (clean)
+    return torch.flip(base, dims=[0])
+
+
+def make_initial_state(
+    *,
+    noise: Tensor,
+    t_start: Tensor,
+    logsnr_min: float,
+    logsnr_max: float,
+    log_change_high: float = 0.0,
+    log_change_low: float = 0.0,
+) -> Tensor:
+    """Construct VP initial state x_t0 = sigma_start * noise (since x0=0).
+
+    All math in float32.
+    """
+    batch = int(noise.shape[0])
+    lmb_start = shifted_cosine_interpolated_logsnr_from_t(
+        t_start.expand(batch).to(dtype=torch.float32),
+        logsnr_min=logsnr_min,
+        logsnr_max=logsnr_max,
+        log_change_high=log_change_high,
+        log_change_low=log_change_low,
+    )
+    _alpha_start, sigma_start = alpha_sigma_from_logsnr(lmb_start)
+    sigma_view = broadcast_time_like(sigma_start, noise)
+    return sigma_view * noise.to(dtype=torch.float32)
+
+
+def sample_noise(
+    shape: tuple[int, ...],
+    *,
+    noise_std: float = 1.0,
+    seed: int | None = None,
+    device: torch.device | None = None,
+    dtype: torch.dtype = torch.float32,
+) -> Tensor:
+    """Sample Gaussian noise with optional seeding. CPU-seeded for reproducibility."""
+    if seed is None:
+        noise = torch.randn(
+            shape, device=device or torch.device("cpu"), dtype=torch.float32
+        )
+    else:
+        gen = torch.Generator(device="cpu")
+        gen.manual_seed(int(seed))
+        noise = torch.randn(shape, generator=gen, device="cpu", dtype=torch.float32)
+    noise = noise.mul(float(noise_std))
+    target_device = device if device is not None else torch.device("cpu")
+    return noise.to(device=target_device, dtype=dtype)

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:566aaf108b41ceb4a55fa2c3e4f42321e2962fafba56d5fccd16670383df20b7
+size 626569856

technical_report_fcdm_diffae.md

@@ -0,0 +1,196 @@
+# semdisdiffae_p32_v2 Technical Report
+
+`semdisdiffae_p32_v2` is a native patch-32 SemDisDiffAE diffusion autoencoder. It
+uses the same FCDM block family as
+[SemDisDiffAE](https://huggingface.co/data-archetype/semdisdiffae), but with a
+native `32x32` pixel token grid, an 8-block encoder, and an 8-block decoder. The
+model is intended as a compact latent autoencoder for downstream latent
+diffusion work.
+
+This report focuses on the differences from the original SemDisDiffAE release.
+For the shared FCDM block, VP decoder, stochastic posterior, and general design
+background, see the original
+[SemDisDiffAE technical report](https://huggingface.co/data-archetype/semdisdiffae/blob/main/technical_report_semantic.md).
+
+## Compared With SemDisDiffAE
+
+| Component | SemDisDiffAE | semdisdiffae_p32_v2 |
+|---|---:|---:|
+| HF repo | [`data-archetype/semdisdiffae`](https://huggingface.co/data-archetype/semdisdiffae) | [`data-archetype/semdisdiffae_p32_v2`](https://huggingface.co/data-archetype/semdisdiffae_p32_v2) |
+| Patch size | `16` | `32` |
+| Latent grid | `H/16 x W/16` | `H/32 x W/32` |
+| Latent channels | `128` | `384` |
+| Model dim | `896` | `1024` |
+| Encoder blocks | `4` | `8` |
+| Decoder blocks | `8` | `8` |
+| Parameters | `88.8M` | `156.6M` |
+| Semantic teacher | DINOv3 ViT-S/16 LVD1689M, `vit_small_patch16_dinov3.lvd_1689m` | DINOv3 ConvNeXt-B/LVD1689M, `convnext_base.dinov3_lvd1689m` |
+| Semantic loss | negative cosine | 50/50 MSE plus negative cosine |
+
+The main change is the native patch-32 latent interface. It reduces the spatial
+token count by `4x` relative to patch-16 while increasing channel width and
+encoder depth. The result is a lower-resolution latent grid intended to be
+easier and cheaper for downstream diffusion models, while still preserving the
+SemDisDiffAE-style VP diffusion decoder and stochastic posterior.
+
+## Architecture
+
+| Component | Value |
+|---|---:|
+| Parameters | `156.6M` |
+| Encoder blocks | `8` |
+| Decoder blocks | `8` |
+| Patch size | `32` |
+| Model dim | `1024` |
+| Bottleneck dim | `384` |
+| Spatial compression | `32x` |
+| Posterior | `diagonal_gaussian` |
+| Bottleneck norm | `disabled` |
+
+The decoder uses the start / middle / end skip-concat layout with `2` start
+blocks and `2` end blocks. The encoder and decoder both operate natively at
+patch size `32`; this is not a patch-16 model with an additional latent
+downsampling step. The posterior is VP-parameterized as mean plus log-SNR, with
+the exported `encode()` path returning the whitened posterior mode.
+
+## Training
+
+The checkpoint exported here is the EMA model at step `400107`. The training
+recipe follows the original SemDisDiffAE objective, with changes for the native
+patch-32 latent grid.
+
+### Data And Resolution
+
+Training uses the same bucketed image mixture style as the original
+SemDisDiffAE recipe: photographs and aesthetic web images, posters/stills, and
+book-cover/document-like images. Images are loaded without captions.
+
+Unlike the original `256`-scale SemDisDiffAE recipe, p32 was trained with `384`
+aspect-ratio buckets and `384x384` square crops, batch size `128`; validation
+used `384` AR buckets with patch samples disabled. At patch size `32`, `256x256`
+images give only an `8x8` latent grid, so 7x7 depthwise convolutions are
+dominated by border padding. `384x384` gives a `12x12` grid and a better-trained
+center region.
+
+### Losses
+
+The active losses are:
+
+| Loss | Weight | Description |
+|---|---:|---|
+| Reconstruction | `1.0` | VP `x_pred` reconstruction objective with SiD2-style sigmoid weighting. |
+| Semantic alignment | `0.01` | DINOv3 ConvNeXt-B/LVD1689M alignment on noisy latent tokens. |
+| Latent scale penalty | `1e-4` | Per-channel latent variance regularization toward unit variance. |
+| Posterior variance expansion | `1e-5` | Encourages a non-collapsed stochastic posterior variance. |
+
+The auxiliary weights are intentionally small. The native SiD2-style VP
+`x_pred` reconstruction loss has a small effective scale after the log-SNR
+Jacobian and sigmoid weighting are applied; larger auxiliary weights would
+dwarf the reconstruction objective rather than act as regularizers.
+
+Semantic alignment uses the DINOv3 ConvNeXt-B/LVD1689M teacher at token stride
+`32`, matching the model's native latent grid. The training-only projection head
+maps noisy student latents to `1024`-dimensional teacher tokens. It is a compact
+DiT-style head: `1x1` input projection from `384` latent channels to model dim
+`1024`, one DiT block with `16` attention heads of head dim `64`, axial RoPE over
+patch-index coordinates, sinusoidal timestep embedding fed through AdaLN-Zero,
+RMSNorm, and a final `1x1` projection to the teacher token width.
+
+As in the original SemDisDiffAE alignment setup, alignment is performed on
+noisy latents rather than only on clean latents. The clean latent `z` is linearly
+interpolated with Gaussian noise:
+
+```text
+z_noisy = (1 - tau) * z + tau * eps,   eps ~ N(0, I),   tau ~ Beta(2, 2)
+```
+
+The p32 semantic loss is exactly the 50/50 mix configured in the checkpoint:
+
+```text
+semantic_loss = 0.5 * (MSE(student_tokens, teacher_tokens)
+                     + negative_cosine(student_tokens, teacher_tokens))
+```
+
+This differs from the original SemDisDiffAE report, which used the DINOv3
+ViT-S/16 LVD1689M teacher and negative-cosine-only alignment. The projection
+head is training-only and is not included in the exported inference package.
+
+### Optimizer And Schedule
+
+| Parameter | Value |
+|---|---:|
+| Optimizer | AdamW |
+| Learning rate | `1e-4` |
+| Betas | `(0.9, 0.99)` |
+| Epsilon | `1e-8` |
+| Weight decay | `0.0` |
+| LR schedule | constant after warmup |
+| Warmup steps | `10000` |
+| Gradient clip | `1.0` |
+| Precision | AMP `bfloat16`, TF32 matmul |
+| EMA decay | `0.9995` |
+| EMA update | every step |
+| Compile | enabled |
+
+Latent running statistics are tracked during training with momentum `0.0001`
+and epsilon `0.0001`; those statistics are stored in the export and used for
+the `whiten()` / `dewhiten()` interface.
+
+## Export Contract
+
+- `encode()` returns whitened latents using the model's saved running statistics.
+- `decode()` expects those whitened latents and dewhitens internally.
+- `whiten()` and `dewhiten()` expose the transform explicitly.
+- `encode_posterior()` returns the raw exported posterior before whitening.
+
+Weights are stored in `float32`. The recommended runtime path is `bfloat16` for
+the encoder and decoder. Whitening, dewhitening, posterior alpha/sigma
+computation, diffusion schedule computation, and sampler state updates are kept
+in `float32`.
+
+## Export Verification
+
+The exported EMA checkpoint was checked against the source training checkpoint
+on the same input image. In `float32`, reconstruction mean absolute error was
+`8.95e-5` with max absolute error `7.86e-4`; whitened latent mean absolute
+error was `1.84e-4` with max absolute error `2.91e-3`. In the recommended
+`bfloat16` runtime path, reconstruction mean absolute error was `0.0012`.
+
+## Reconstruction Quality
+
+The `2k` benchmark uses a fixed validation list with `1333` Pexels images and
+`667` Amazon book covers. The export uses `bfloat16` inference and the default
+1-step reconstruction path.
+
+| Model | Mean PSNR (dB) | Std (dB) | Median (dB) | P5 (dB) | P95 (dB) |
+|---|---:|---:|---:|---:|---:|
+| semdisdiffae_p32_v2 | `36.06` | `5.47` | `35.80` | `27.63` | `45.02` |
+
+The fixed 39-image visual set is exported separately as a results viewer with
+side-by-side originals, FLUX.2 reconstructions, semdisdiffae_p32_v2
+reconstructions, error deltas, and PCA visualizations.
+
+## Throughput
+
+Measured on an `NVIDIA GeForce RTX 5090` in `bfloat16`, with `5` warmup batches
+and `20` timed batches. Decode uses the default 1-step sampler with PDG
+disabled.
+
+| Operation | Resolution | Batch Size | Mean (ms/batch) | Median (ms/batch) | P95 (ms/batch) | ms/image | Images/s | Peak Allocated VRAM |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|
+| Encode | `256x256` | `128` | `12.57` | `12.41` | `13.27` | `0.098` | `10186.8` | `574 MiB` |
+| Decode | `256x256` | `128` | `98.93` | `99.22` | `100.16` | `0.773` | `1293.9` | `1042 MiB` |
+| Encode | `512x512` | `32` | `12.08` | `11.98` | `12.46` | `0.377` | `2649.9` | `579 MiB` |
+| Decode | `512x512` | `32` | `100.36` | `99.39` | `105.84` | `3.136` | `318.8` | `1042 MiB` |
+
+## VP Stability
+
+The VP posterior and diffusion schedule compute alpha/sigma with a stable
+`logsigmoid` formulation:
+
+```text
+alpha = exp(0.5 * logsigmoid(logsnr))
+sigma = exp(0.5 * logsigmoid(-logsnr))
+```
+
+This avoids unstable `sqrt(sigmoid(...))` behavior at extreme log-SNR values.