ComfyUI-ZImageTurbo-FlowSampler

Custom ComfyUI nodes for Z-Image-Turbo implementing verified rectified-flow samplers with clean interpolation formula, linear sigma schedulers, and higher-order variants.

The Discovery

Z-Image-Turbo was distilled using:

• Linear sigma schedule (1.0 → 0.0)
• Deterministic Euler steps via rectified-flow interpolation
• No intermediate noise injection
• Explicit final step handling when σ_next = 0

After extensive code analysis of ComfyUI's sampling implementation, a critical mismatch was identified between the built-in samplers and Z-Image-Turbo's distillation process.

Built-in Sampler Issues

sample_euler (default)

# Karras ODE formulation
d = (x - denoised) / sigma  # Division by sigma → unstable near σ≈0
x = x + d * dt              # Implicit final step

• Contains churn machinery (s_churn, s_tmin, s_tmax)
• Division by sigma causes numerical instability
• No explicit σ_next = 0 handling
• Designed for traditional diffusion, not rectified flow

sample_euler_ancestral

Contains a rectified-flow branch (sample_euler_ancestral_RF), but activation requires:

• Sampler must be euler_ancestral
• Model sampling type must be CONST
• eta > 0 (introduces ancestral noise)

For deterministic Z-Image-Turbo workflows (CFG=1.0, eta=0), this clean path is never reached.

Custom Implementation

# Core update from sample_euler_flow
if sigma_next == 0:
    x = denoised
else:
    ratio = sigma_next / sigma
    x = ratio * x + (1.0 - ratio) * denoised

Comparison

Feature	Built-in euler	Built-in euler_ancestral	Custom euler_flow
Update formula	Karras ODE derivative	RF interpolation (gated)	RF interpolation (always)
Division by sigma	Yes	No (when RF branch active)	No
Final step handling	Implicit	Explicit	Explicit
Churn machinery	Present	Present (outside RF branch)	Removed
Ancestral noise	Not required	Required (eta > 0) for RF	Optional (eta=0 default)
Z-Image turbo alignment	Partial	Conditional	Complete

Nodes Provided

Samplers

• euler_flow: 1st-order rectified-flow Euler (recommended)
• euler_flow_alt: Derivative formulation (for comparison)
• midpoint_flow: 2nd-order midpoint method
• heun_flow: 2nd-order Heun method
• euler_flow_verbose: Debug mode with step-by-step output

Schedulers

• ZImageTurbo Scheduler: Linear sigma schedule (1.0 → 0.0)
• ZImageTurbo Scheduler (Advanced): With denoise control for img2img
• FlowMatch Scheduler: Generic flow-matching with shift parameter
• FlowMatch Scheduler (Dynamic): Resolution-aware shift calculation
• ZImage Presets: One-click configurations for Z-Image-Turbo, Flux, SD3

Utilities

• Sigma Viewer: Debug node to visualize sigma schedules
• ZImage Sampler: Unified sampler node with type selection and eta control

Installation

Via ComfyUI Manager

1. Search for "ComfyUI-ZImageTurbo-FlowSampler"
2. Install and restart ComfyUI

Manual Installation

cd ComfyUI/custom_nodes
git clone https://github.com/capitan01R/ComfyUI-ZImageTurbo-FlowSampler.git

Restart ComfyUI.

Nodes

Recommended Settings for Z-Image-Turbo

• Steps: 8-9
• CFG: 1.0
• Sampler: euler_flow
• Scheduler: ZImageTurbo Scheduler (linear)
• eta: 0.0 (deterministic, sharpest)

eta Parameter Guide

• 0.0: Deterministic, sharpest results
• 0.1-0.2: Subtle variation, can reduce artifacts
• 0.3-0.5: Balanced diversity with slight softening
• 0.5-1.0: More creative variation, softer outputs

Example Workflow

1. Add ZImage Sampler node, select euler_flow, eta=0.0
2. Add ZImageTurbo Scheduler node, steps=8
3. Connect to SamplerCustomAdvanced
4. Set CFG=1.0

Testing

All nodes tested on Z-Image-Turbo at:

• 8-9 steps
• CFG 1.0
• Linear sigma schedule
• Various eta values (0.0-1.0)

Observations on bf16 generations:

• Sharper detail preservation
• Improved facial coherence
• Reduced numerical artifacts in final steps

Technical Details

Why Interpolation > Derivative

Both formulations are algebraically equivalent when σ ≠ 0:

Karras ODE:

d = (x - x̂) / σ
x' = x + d * (σ_next - σ)

RF Interpolation:

ratio = σ_next / σ  
x' = ratio * x + (1 - ratio) * x̂

The interpolation form provides:

• No division by potentially small sigma values
• Explicit final-step handling
• Cleaner code path without legacy diffusion machinery
• Direct alignment with Z-Image-Turbo distillation process

Compatibility

Primary target: Z-Image-Turbo

Also compatible with other flow-matching models via appropriate schedulers:

• Flux (use dynamic scheduler or presets)
• SD3/SD3.5 (use shifted scheduler with shift=3.0)

---

Author: Capitan01R
Version: 1.0.0

Based on analysis of:

• Tongyi-MAI/Z-Image official implementation
• ComfyUI k_diffusion sampling code
• Rectified flow mathematical framework

---

Note: Linear sigma schedule is critical for Z-Image-Turbo. Non-linear schedules break the distillation and produce degraded results.