ComfyUI-CFG-CTRL/README.md

Caution

NOT WORKING — Work in progress. The paper's algorithm was designed for DiffSynth-Studio and does not translate directly to ComfyUI's k-diffusion sampling framework. Images are corrupted or artifacted at high CFG scales (e.g. cfg=12 on SDXL). Do not use this node in production workflows until this notice is removed.

A ComfyUI node implementing SMC-CFG (Sliding Mode Control CFG) from the paper:

CFG-Ctrl: A Control-Theoretic Perspective on Classifier-Free Guidance Hang Yang, Shuwei Shi, Changhao Nan, Jingyi Yu, Lan Xu — CVPR 2026 [Paper] [Original Code]

Standard CFG uses a fixed linear gain that becomes unstable at high guidance scales — causing oversaturation, artifacts, and semantic drift. This node replaces that linear controller with a nonlinear sliding mode controller that keeps guidance stable at any CFG scale.

---

How It Works

The paper reframes CFG as a control problem. Standard CFG is P-control (proportional control with fixed gain). SMC-CFG adds a bounded nonlinear correction that enforces convergence along an exponential sliding surface.

The math in brief

At each denoising step t:

e_t  = noise_cond - noise_uncond          # guidance error signal
s_t  = (e_t - e_{t-1}) + λ · e_{t-1}     # sliding surface
u_sw = -K · sign(s_t)                     # switching control (bounded)
e_corrected = e_t + u_sw                  # corrected guidance
v_out = v_uncond + w · e_corrected        # final guided prediction

The correction u_sw is bounded to [-K, +K] per element — this is what prevents the unbounded growth that plagues standard CFG. The sliding surface combines the error derivative with a decayed previous error, creating a feedback loop with Lyapunov-stable convergence.

---

Installation

Manual

Clone into your ComfyUI custom_nodes directory:

cd ComfyUI/custom_nodes
git clone https://github.com/ethanfel/ComfyUI-CFG-CTRL.git

Restart ComfyUI. No additional dependencies required — the node only uses PyTorch (already in ComfyUI).

---

Usage

1. Add the SMC-CFG Ctrl node (found in sampling/custom_sampling)
2. Connect your model loader's MODEL output to the node's model input
3. Connect the node's MODEL output to your KSampler's model input
4. Set your KSampler's CFG scale — you can push it higher than usual thanks to the SMC stabilization

That's it. The node patches the model's internal CFG function. It works with KSampler, KSampler Advanced, and any sampler that respects the model's CFG configuration.

---

Parameters

smc_cfg_lambda — Sliding Surface Coefficient

Default: 5.0 | Range: 0.0 – 50.0

Controls the sliding surface equation s_t = (e_t - e_{t-1}) + λ · e_{t-1}. Higher values weight the previous error magnitude more heavily, making the controller more aggressive about correcting accumulated guidance drift.

Value	Behavior
0.0	Surface uses only error derivative — very gentle
1.0 – 5.0	Balanced correction (recommended range)
> 10.0	Aggressive — may over-constrain the generation

smc_cfg_K — Switching Gain

Default: 0.2 | Range: 0.0 – 5.0

Bounds the correction to [-K, +K] per tensor element. This is the "safety clamp" that prevents instability. Think of it as how hard the controller can push back.

Value	Behavior
0.0	No correction — equivalent to standard CFG
0.1 – 0.3	Subtle stabilization (recommended)
> 0.5	Strong correction — may introduce chattering artifacts

warmup_steps — No-Guidance Warmup

Default: 0 | Range: 0 – 100

Number of initial denoising steps where guidance is completely disabled (pure conditional prediction). The model establishes rough composition and structure before the SMC controller begins steering.

Value	Behavior
0	SMC-CFG active from the first step
2 – 5	Lets structure form first — can improve diversity
> 10	Long warmup — useful for experimentation

Quick Start Settings

For most models, start with the defaults and only adjust if needed:

smc_cfg_lambda = 5.0
smc_cfg_K      = 0.2
warmup_steps   = 0

These match the paper's recommended values and work well across SD 1.5, SDXL, SD3, FLUX, and Wan models.

---

Compatibility

• Works with any model that uses CFG (SD 1.5, SDXL, SD3, FLUX, Wan, etc.)
• Compatible with KSampler, KSampler Advanced, and custom sampling workflows
• Stacks with sampler_post_cfg_function nodes (e.g., RescaleCFG can be used alongside)
• Note: Replaces the model's CFG function — only one sampler_cfg_function node can be active at a time. If another node also sets a custom CFG function, the last one in the chain wins.

---

Technical Details

How it integrates with ComfyUI

The node uses model.clone() + set_model_sampler_cfg_function() — the standard model patching pattern. It intercepts the CFG combination step without modifying model weights, conditioning, or the sampling loop itself.

State management

The SMC algorithm requires memory of the previous step's guidance error (e_{t-1}). This state is held in a closure and automatically resets when a new generation starts (detected via sigma schedule discontinuity).

Performance

The correction adds only lightweight tensor operations (sign, multiply, add) per denoising step. The overhead is negligible compared to the model forward pass. However, disable_cfg1_optimization=True is set to ensure both conditional and unconditional predictions are always computed.

---

Citation

If you use this in your work, please cite the original paper:

@article{yang2025cfg,
  title={CFG-Ctrl: A Control-Theoretic Perspective on Classifier-Free Guidance},
  author={Yang, Hang and Shi, Shuwei and Nan, Changhao and Yu, Jingyi and Xu, Lan},
  journal={arXiv preprint arXiv:2505.18727},
  year={2025}
}

---

License

This ComfyUI node is released under the Apache 2.0 License, matching the original CFG-Ctrl repository.