[perf]: batched classifier-free guidance for Wan/Cosmos

Run cond + uncond as a single batch=2 DiT forward per denoise step
instead of two sequential batch=1 forwards. Composable with Adaptive
Guidance (hao-ai-lab#1372).

Mechanism is bit-equivalent to sequential CFG on H100 FA3 eager
(SSIM=1.000000, 5 prompts, Wan 14B 720x1280x49f/30steps). See PR
body for full validation matrix across L40S/H100 and eager/compile.

Changes:
- fastvideo_args.py: new use_batched_cfg: bool = True field +
  --use-batched-cfg CLI. Auto-fallback to sequential when V2V/I2V/
  TI2V/action/camera conditioning is present (those carry batch=1
  conditioning tensors out of scope for this PR).
- entrypoints/video_generator.py: add use_batched_cfg to
  _FROM_PRETRAINED_CONVENIENCE_KWARGS so users don't see the
  DeprecationWarning from the legacy kwarg path.
- pipelines/stages/denoising.py: gated batched branch in main
  DenoisingStage.forward. Cats [neg, pos] along batch dim with
  shape-match defensive fallback, single forward, chunk(2),
  existing CFG-combine + guidance_rescale math reused. Other
  DenoisingStage subclasses (Cosmos25, Dmd, ...) unchanged.

Sequential CFG path preserved bit-for-bit for non-batched callers.
Other DiTs (HunyuanVideo, LongCat, ...) unaffected.

Author: Mister-Raggs

docs/design/inference_schema_parity_inventory.yaml

@@ -39,6 +39,7 @@ surfaces:
       torch_compile_kwargs_audio_vae: generator.engine.compile.audio_vae_kwargs
       transformer_quant: generator.engine.quantization.transformer_quant
       disable_autocast: generator.engine.disable_autocast
+      use_batched_cfg: generator.engine.use_batched_cfg
       enable_stage_verification: generator.engine.enable_stage_verification
       prompt_txt: request.inputs.prompt_path
       override_text_encoder_safetensors: generator.pipeline.components.text_encoder_weights

fastvideo/api/compat.py

@@ -157,7 +157,7 @@ def legacy_from_pretrained_to_config(
             preset_refine["num_inference_steps"] = value
         elif key == "ltx2_refine_guidance_scale":
             preset_refine["guidance_scale"] = value
-        elif key in {"enable_stage_verification", "use_fsdp_inference", "disable_autocast"}:
+        elif key in {"enable_stage_verification", "use_fsdp_inference", "disable_autocast", "use_batched_cfg"}:
             engine[key] = value
         elif key == "override_text_encoder_quant":
             quantization["text_encoder_quant"] = value
@@ -244,6 +244,7 @@ def generator_config_to_fastvideo_args(config: GeneratorConfig | Mapping[str, An
         "enable_stage_verification": engine.enable_stage_verification,
         "use_fsdp_inference": engine.use_fsdp_inference,
         "disable_autocast": engine.disable_autocast,
+        "use_batched_cfg": engine.use_batched_cfg,
     }
     if normalized.pipeline.workload_type is not None:
         kwargs["workload_type"] = normalized.pipeline.workload_type

fastvideo/api/schema.py

@@ -81,6 +81,7 @@ class EngineConfig:
     enable_stage_verification: bool = True
     use_fsdp_inference: bool = False
     disable_autocast: bool = False
+    use_batched_cfg: bool = True
     quantization: QuantizationConfig | None = None
 
 

fastvideo/entrypoints/video_generator.py

@@ -94,6 +94,7 @@
     "pin_cpu_memory",
     "enable_torch_compile",
     "torch_compile_kwargs",
+    "use_batched_cfg",
     "output_type",
     "nvfp4_fa4",
 })

fastvideo/fastvideo_args.py

@@ -153,6 +153,14 @@ class FastVideoArgs:
 
     disable_autocast: bool = False
 
+    # Batched classifier-free guidance: run cond + uncond as a single
+    # batch=2 DiT forward per denoise step instead of two sequential
+    # batch=1 forwards. Output-identical (SSIM=1.0); reduces per-step
+    # launch + memory-traffic overhead. Disable to fall back to the
+    # legacy sequential path (e.g. for debugging or for entry points
+    # that aren't covered by the batched path yet).
+    use_batched_cfg: bool = True
+
     # VSA parameters
     VSA_sparsity: float = 0.0  # inference/validation sparsity
 
@@ -538,6 +546,17 @@ def add_cli_args(parser: FlexibleArgumentParser) -> FlexibleArgumentParser:
             help="Use torch.compile to speed up DiT inference." +
             "However, will likely cause precision drifts. See (https://github.com/pytorch/pytorch/issues/145213)",
         )
+        parser.add_argument(
+            "--use-batched-cfg",
+            action=StoreBoolean,
+            default=FastVideoArgs.use_batched_cfg,
+            help="Run classifier-free guidance as a single batch=2 DiT "
+            "forward per step (cond+uncond stacked) instead of two "
+            "sequential batch=1 forwards. Output-identical at SSIM=1.0; "
+            "reduces per-step launch + memory overhead. Falls back to "
+            "the sequential path when V2V/I2V/TI2V/action/camera "
+            "conditioning is present.",
+        )
         parser.add_argument(
             "--torch-compile-kwargs",
             type=str,