Skip to content

dew.sampling.guidance

Guidance as a wrapper around a denoiser.

Every guidance computes a second prediction next to the conditional one and combines the two. CFG and APG evaluate the same model without its condition, CFGPlusPlus also renoises with that unconditional prediction, and Autoguidance evaluates a weaker model under the same condition.

A walk is one pass of the sampler over its N steps. guidance.walk(denoise, N) applies a guidance to a denoiser over such a walk and returns a Walk. The Walk gives each step’s guided prediction (x_t, t) -> (x_0, epsilon) and holds whatever the guidance keeps from one step to the next. Only APG with momentum keeps anything: the walk’s state holds its running average of the guidance direction.

Each guidance is a pytree: its scale (and APG’s eta) a leaf, so a compiled walk takes another value as data; its interval and the switches that shape the program (CFG’s rescale, APG’s clipping and momentum, a guide’s module) are static.

Every guidance’s interval is the part of the walk it guides, as fractions of the walk. The interval is closed at both ends, so step i of N is guided when start <= i / N <= stop, and the closing denoise counts as step N. Each step decides once whether it is guided, and every evaluation within the step (a corrector, a midpoint, a stage) uses that decision. Kynkaanniemi et al.’s own sampler and Diffusers’ guiders decide the same way.

The paper’s guidance_interval=[a, b] over N steps converts to interval=(a / N, b / N). A Diffusers guider’s start and stop guide its steps [int(start N), int(stop N)), which converts to interval=(int(start N) / N, (int(stop N) - 1) / N).

NameSummary
APGAdaptive projected guidance, combining raw outputs as Diffusers’ AdaptiveProjectedGuidance does.
CFGInterval-limited classifier-free guidance.
AutoguidanceGuides a model with a weaker version of itself (autoguidance).
CFGPlusPlusGuides the clean prediction and renoises with the unconditional noise (CFG++).
GuidanceWhat sample guides with: a walk over the steps for one denoiser.
WalkA guided denoiser for one walk, with the state the guidance keeps between steps.

dataclass source

class APG(
eta: float = 1.0,
norm_threshold: float = struct.field(pytree_node=False, default=15.0),
momentum: float = struct.field(pytree_node=False, default=0.0),
interval: tuple[float, float] = struct.field(pytree_node=False, default=(0.0, 1.0)),
)

Adaptive projected guidance, combining raw outputs as Diffusers’ AdaptiveProjectedGuidance does.

The method is from Sadat et al. 2025, “Eliminating Oversaturation and Artifacts of High Guidance Scales in Diffusion Models”. The guided output is uncond + scale (orthogonal + eta parallel), where the guidance direction cond - uncond goes through three changes:

  • momentum (the paper’s beta) keeps a running average of the direction over the walk. A negative value pushes away from earlier steps’ updates, and 0 keeps no average.
  • The direction’s norm, taken over every axis but the batch axis, is clipped at norm_threshold. 0 clips nothing.
  • The direction’s component parallel to the conditional output is scaled by eta.

With eta 1, no clipping and no momentum, this is CFG. Where guidance is off (outside interval, or at scale 1), the running average stays as it is, like Diffusers’ buffer.

def walk(denoise: Denoiser, steps: int | jax.Array) -> Walk

dataclass source

class CFG(
interval: tuple[float, float] = struct.field(pytree_node=False, default=(0.0, 1.0)),
rescale: float = struct.field(pytree_node=False, default=0.0),
)

Interval-limited classifier-free guidance.

The guided prediction is uncond + scale (cond - uncond). Kynkaanniemi et al. 2024 found that guidance hurts at high noise and does not help at low noise, so outside interval the scale is 1, which gives exactly the plain conditional prediction. The interval is measured in progress along the trajectory, from 0 at pure noise to 1 at the clean sample, and the default covers all of it.

rescale applies the guidance rescaling of Lin et al. 2023 (“Common Diffusion Noise Schedules and Sample Steps are Flawed”, section 3.4), which Diffusers calls guidance_rescale. The guided output is rescaled to the per-sample standard deviation of the conditional output, then mixed with the unrescaled guided output at weight rescale. So 0 leaves the guided output alone and 1 uses the rescaled one. The standard deviation is taken over every axis but the batch axis, with the unbiased correction that the reference’s Tensor.std applies.

The guidance combines the model’s raw outputs, and the denoiser then converts the combined output once. So a source’s clipping, dynamic thresholding or consistency boundary is applied once, to the guided output, and never to the conditional or unconditional output alone.

def walk(denoise: Denoiser, steps: int | jax.Array) -> Walk

dataclass source

class Autoguidance(
model: nn.Module = struct.field(pytree_node=False),
interval: tuple[float, float] = struct.field(pytree_node=False, default=(0.0, 1.0)),
)

Guides a model with a weaker version of itself (autoguidance).

The method is from Karras et al. 2024, “Guiding a diffusion model with a bad version of itself”, and NVlabs/edm2’s edm_sampler(gnet=...) is the reference. The guided output is guide + scale (main - guide), where main is the output of the denoiser’s own model. The guide is a weaker model for the same task, smaller or less trained, and it is evaluated under the same condition as the main model.

model is the guide’s module. Its variables go in the denoiser’s variables under guide, so a compiled walk receives them as arguments together with the main model’s; walk raises ValueError when they are missing. Both models use the same process, and their raw outputs are combined before the single conversion, as in CFG.

def walk(denoise: Denoiser, steps: int | jax.Array) -> Walk

dataclass source

class CFGPlusPlus(
interval: tuple[float, float] = struct.field(pytree_node=False, default=(0.0, 1.0)),
)

Guides the clean prediction and renoises with the unconditional noise (CFG++).

This is Algorithm 1 of Chung et al. 2025, “CFG++: Manifold-constrained Classifier Free Guidance for Diffusion Models”. The clean prediction is uncond + scale (cond - uncond) with scale in [0, 1], and the noise a step renoises with is the unconditional prediction’s noise. A scale outside [0, 1] raises ValueError.

The guided pair (x_0, epsilon) is what DDIM’s update, alpha x_0 + sigma epsilon, reads. A solver that integrates from x_t alone, without that pair, follows plain CFG’s trajectory.

def walk(denoise: Denoiser, steps: int | jax.Array) -> Walk

class source

class Guidance(Protocol)

What sample guides with: a walk over the steps for one denoiser. CFG, CFG++, APG and autoguidance are four; a run records any by class.

A walk’s prediction over an opened denoiser (Denoiser.opened, a watched training step’s) reads its model through raw_observed or raw_both_observed and returns denoise.observed(pair, sown): the pair and what its policy’s call opened, carried out of any transform the guidance runs its call in (a lax.cond, a jit) by its own outputs. A prediction that returns a bare pair over an opened denoiser is refused by name where it is read.

def walk(denoise: Denoiser, steps: int | jax.Array) -> Walk

dataclass source

class Walk(
init: Callable[[jax.Array], Any],
step: Callable[[jax.Array, jax.Array, Index, Any], tuple[Prediction, Any]],
at: Callable[[Any, Index], Predict],
)

A guided denoiser for one walk, with the state the guidance keeps between steps.

init(x_T) returns the state before the first step. step(x, t, index, state) returns the guided prediction at the start of step index and the state after that step. at(state, index) returns step index’s guided prediction function under a given state, without advancing the state. The solver calls it for its own evaluations within a step (a corrector, a midpoint) and for the closing denoise.

def stateless(predict: Callable[[Index], Predict]) -> Walk

Return a walk that keeps no state between steps.

predict maps a step’s index to that step’s guided prediction.

def over(denoise: Predict, guidance: Guidance | None, steps: int | jax.Array) -> Walk

Return guidance’s walk of denoise over steps steps.

When guidance is None, the walk is unguided. Raises TypeError when guidance is given and denoise is not a continuous Denoiser, as with the masked diffusion LM.