ComfyUI Sampling Planner

Task-aware sampling controls for complex ComfyUI workflows.

The first release focuses on Wan 2.2 split-expert workflows. It converts a small set of user-facing choices into coordinated shift, step split, and sigma outputs.

The planner uses evidence-backed sampling profiles rather than treating one shift as universally optimal. See Wan 2.2 sigma and shift evidence for the source record and design rationale.

Wan 2.2 nodes

Scheduler Selector

This helper reads the live scheduler combo used by the installed core KSampler. Its output can fan out to:

• the Sampling Plan (Wan 2.2) scheduler input
• the high KSampler scheduler input
• the low KSampler scheduler input
• additional compatible KSampler branches

Scheduler names registered into the core KSampler list by installed extensions are included automatically when ComfyUI builds the node schema.

Custom scheduler nodes that directly output SIGMAS are a different ComfyUI interface and do not have names that can be passed into a KSampler scheduler combo. Use those through the Sigma Breakout/custom-sampling path instead.

Sampler Selector

Reads the live sampler combo used by the installed core KSampler. Its output can fan out to the high and low KSampler sampler_name inputs and other compatible core sampler controls.

Specialized sampler nodes such as Clownshark expose their own algorithm lists; those are separate registries and are not included in this combo.

Task Selector

Outputs a task combo compatible with Sampling Plan (Wan 2.2):

• T2V
• I2V

This is useful when the same workflow mode switch also controls latent/image inputs and other task-dependent branches.

Priority Selector

Outputs a priority combo compatible with Sampling Plan (Wan 2.2):

• Balanced
• 50/50 Split
• Motion / Structure
• Detail / Refinement

Step Budget

Defines two full-range-equivalent budgets:

• accelerated_steps: steps used if the entire denoising range were accelerated
• full_steps: steps used if the entire range were unaccelerated

The planner projects the appropriate budget onto each expert's share of the denoising range. With 10 accelerated steps, 30 full steps, and a 50/50 range split:

| Acceleration | High stage | Low stage | Effective total | |---|---:|---:|---:| | High + Low | 5 accelerated | 5 accelerated | 10 | | High only | 5 accelerated | 15 full | 20 | | Low only | 15 full | 5 accelerated | 20 | | None | 15 full | 15 full | 30 |

Acceleration Selector

Uses one compact mode:

• None
• High only
• Low only
• High + Low

It acts like the other compact selector helpers: one field and one combo output. Connect that output to the Sampling Plan acceleration input.

Acceleration Model Pair

This is the recommended replacement for manually bypassing acceleration groups. It accepts:

• base high model
• accelerated high model
• base low model
• accelerated low model
• base CFG
• accelerated CFG
• bundled acceleration state from Sampling Plan

It lazily requests only the selected model branches. With None, neither acceleration LoRA branch executes. With High only, only the accelerated high branch executes; the low branch remains base.

The same state routes CFG in lockstep with the models:

• unaccelerated stage → base_cfg
• accelerated stage → accelerated_cfg

The outputs are cfg_high and cfg_low, ready to connect to the corresponding samplers. This prevents a base expert from accidentally receiving accelerated CFG—or the reverse.

Recommended placement:

base high ───────────────┐
base high → accel LoRA ──┤
                         ├─ Acceleration Model Pair → selected high
base low ────────────────┤
base low → accel LoRA ───┘                         → selected low

Keep the acceleration groups enabled. Lazy routing prevents unused LoRA branches from running, so no group bypass synchronization is required.

Sampling Plan (Wan 2.2)

Managed controls:

• Task: T2V or I2V
• Acceleration: None, High only, Low only, or High + Low
• Step Budget: accelerated and full-range-equivalent steps
• Scheduler: ComfyUI sigma scheduler
• Priority: Balanced, 50/50, Motion / Structure, or Detail / Refinement

The connected MODEL is used to calculate the real ComfyUI sigma schedule. It can be either Wan expert model.

The planner outputs both the complete sampling plan and an acceleration_state breakout. Connect the latter to Acceleration Model Pair.

The planner uses the official Wan 2.2 boundaries:

• T2V: 0.875
• I2V: 0.900

Priority determines the high/low share of the denoising range. Acceleration determines which budget is projected onto each share. The resulting high and low step counts are added to produce the effective total schedule.

Auto selects an evidence-backed curve profile:

| Configuration | Profile | Shift anchor | Default split policy | |---|---|---:|---| | No acceleration, T2V | Wan Native | 12 | Scheduler boundary crossing | | No acceleration, I2V | Wan Native | 5 | Scheduler boundary crossing | | Acceleration active, accelerated budget ≤ 4 | LightX2V 4-Step | 5 | 50/50 | | Acceleration active, accelerated budget > 4 | ComfyUI / YAW | 8 | Scheduler boundary crossing |

The accelerated profile assumes that the selected high- and low-noise models form a compatible pair. LightX2V's official 4-step LoRA recipes use rank-64 LoRAs for both experts at strength 1.0. Do not send a full distilled-model checkpoint through a LoRA loader, and treat strengths above the vendor baseline as an independent quality variable. The planner can validate the denoising curve, but an opaque ComfyUI MODEL input does not expose enough provenance to prove that the selected acceleration files are compatible.

The shift anchor controls where the scheduler concentrates its evaluations; it does not replace or redefine the task's expert boundary. The planner accepts a discrete handoff that straddles the boundary and does not force one sigma to equal it. A bounded shift adjustment is used only when the anchored curve cannot represent a valid crossing. Otherwise the planner preserves the anchor and constructs a boundary-safe piecewise curve.

Step Split Override

Adds one managed field: steps_high.

Set steps_high to 0 to pass the plan through unchanged. This is the recommended way to leave the node visibly in-chain without applying a manual split.

Set steps_high to a positive value to replace Priority's calculated high-stage transition count. The complete curve and both sigma slices are rebuilt and validated.

How the remaining steps are handled depends on the acceleration mode:

• Uniform budgets (High + Low or None): both stages draw from one budget, so the forced value moves the split point while preserving the plan's effective total.
• Mixed acceleration (High only / Low only): the stages draw from different budgets, so the forced value overrides the high allocation only and the low stage keeps its own budget share. For example, Low only with budgets A10/F30 plans 14 high + 5 low; forcing steps_high = 5 yields 5 high + 5 low rather than redistributing the remainder into the accelerated CFG-1 low stage. The forced value may use up to the full high-stage budget.

Progressive 50/50 Sigma Control

No widgets. This is a branch-state signal for progressive transcode/upscale workflows. Put it inside the low-res → high-res group. When that group is active, the node tells Sampling Plan to use accelerated 50/50 sigmas; when the group is muted, the optional signal disappears and Sampling Plan falls back to normal Low-only accounting.

It connects to Sampling Plan's optional sigma_override input; it is not a pass-through node in the required plan chain. That means the progressive group can be muted without severing the WAN22_SAMPLING_PLAN wire.

Use it with Sampling Plan when:

• Acceleration is Low only
• you still want model/CFG routing to remain base high → accelerated low
• but you want the sigma curve to use the accelerated budget split 50/50

Example with accelerated/full budgets A10/F30:

| Plan | High steps | Low steps | Model routing | |---|---:|---:|---| | Low only + 50/50 priority | 15 | 5 | base high → accelerated low | | + Progressive 50/50 Sigma Control | 5 | 5 | base high → accelerated low |

Sampling Plan intentionally rejects this control for other acceleration modes. The control does not manage decode/upscale/re-encode routing or noise routing; keep those visible in the workflow where the progressive technique actually lives.

Shift Override

Adds one managed field: shift.

This replaces the Auto profile's shift anchor. It rebuilds the complete plan, including full sigmas and high/low sigma slices. Downstream Model Pair Breakout then applies the rebuilt plan's shift to both models, so model shift and sampling curve cannot diverge.

Step Split Override and Shift Override are order-independent. Each stores its requested override in the plan and rebuilds from the original planner controls. Progressive 50/50 Sigma Control is different: it should feed Sampling Plan's optional sigma_override input, before any downstream Step Split or Shift overrides.

For progressive-upscale style workflows, a clear ordering is:

Progressive 50/50 Sigma Control ─┐
                                  ├→ Sampling Plan → Step Split Override → Sigma Breakout
normal planner controls ──────────┘

With that order, steps_high = 0 keeps the accelerated 50/50 sigma plan, while any positive steps_high value manually overrides the split within that accelerated total.

Model Pair Breakout

Accepts the plan plus the selected high- and low-noise expert models. It clones and patches both models with the plan's exact shift, then outputs the synchronized model pair.

Use this after Acceleration Model Pair and before guiders or KSamplers:

Acceleration Model Pair → Model Pair Breakout → high/low samplers
Sampling Plan ────────────┘

Model Pair Breakout has no user-facing widgets. Shift is owned by the plan, including any Shift Override.

KSampler Breakout

Connect the plan, high/low expert models, and the sampler selected for the KSampler branch. The node exposes compatible KSampler Advanced controls:

• total steps
• high end_at_step
• low start_at_step
• high and low step counts
• shift

For a standard two-KSampler Advanced branch:

model_high      -> High KSampler model
model_low       -> Low KSampler model
steps           -> both KSampler steps
high_end_step   -> High KSampler end_at_step
low_start_step  -> Low KSampler start_at_step

Keep the scheduler selected in both KSamplers the same as the Sampling Plan. The Scheduler Selector is intended to drive all three scheduler inputs, and the Sampler Selector should drive the KSamplers and KSampler Breakout.

KSampler Breakout is available only when core KSampler can reproduce the exact planned curve from the selected sampler, scheduler, step count, and shift. Plans using piecewise-resampled sigmas are not KSampler-representable; the node reports that incompatibility and directs the workflow to Sigma Breakout instead of silently approximating the curve.

For parity testing against older Wan 2.2 workflows, prefer this KSampler Breakout path whenever the plan reports curve_mode: exact. It lets ComfyUI's native KSampler Advanced implementation own start_at_step, end_at_step, and return_with_leftover_noise, which is the closest match to legacy two-KSampler branches.

MoE Sampler Breakout

Adapts the plan for single-node MoE samplers such as WanMoeKSampler (stduhpf/ComfyUI-WanMoeKSampler). Connect the plan and the high/low expert models (typically from Acceleration Model Pair):

model_high -> MoE sampler model_high_noise (patched with the plan's shift)
model_low  -> MoE sampler model_low_noise  (patched with the plan's shift)
steps      -> MoE sampler steps
shift      -> MoE sampler sigma_shift
boundary   -> MoE sampler boundary (the plan's task boundary: T2V 0.875 / I2V 0.900)

Drive the MoE sampler's sampler_name and scheduler inputs from the same Sampler Selector and Scheduler Selector that feed the Sampling Plan so the sampler's internally generated curve matches the planned curve.

Unlike KSampler Breakout, this node never rejects a plan: the MoE sampler rebuilds a native scheduler curve from steps and shift and hands off experts where that curve crosses the boundary sigma, so exact representability is not required. Because the planner solves shift against the same task boundary, an exact plan's handoff lands on the planned split step; for piecewise plans the curve is approximated best-effort at the planned shift (the split may land a step away from the plan's allocation) and the node's summary notes the approximation. Step Split Override and priority choices influence this path only through the solved shift.

Sigma Breakout

Exposes:

• high sigmas
• low sigmas
• complete sigmas
• total/high/low step counts
• shift

The high schedule ends at the same sigma where the low schedule begins.

Sigma Breakout is the authoritative sigma-output path for every plan. It preserves the exact validated curve, including mixed-budget and priority-adjusted piecewise curves that ordinary KSampler controls cannot express. Use it when KSampler Breakout reports that the plan cannot be represented by native KSampler Advanced controls.

For SamplerCustomAdvanced, continue the two expert stages as follows:

RandomNoise → high SamplerCustomAdvanced → output → low SamplerCustomAdvanced → output
                                                   ↑
                                              DisableNoise

Use the high sampler's output, not denoised_output, as the low-stage latent. denoised_output is an x0 prediction intended for preview or inspection, not the partially sampled latent at the shared handoff sigma.

For KSampler parity, use CFGGuider for each custom-sampler stage, feed the same positive/negative conditioning and CFG values that the KSampler Advanced nodes used, use the same KSamplerSelect sampler, and do not insert a separate BasicScheduler/scheduler node between the plan and the samplers. Sigma Breakout already emits the high and low sigma slices.

See Comfy sampler parity notes for the source comparison between KSampler Advanced and SamplerCustomAdvanced.

Priority behaviour

• Balanced: profile allocation.
• 50/50 Split: equal high/low range allocation. Executed step counts may differ when the stages use different budgets.
• Motion / Structure: moves roughly 10% of the range to the high-noise expert.
• Detail / Refinement: moves roughly 10% of the range to low-noise refinement.

At least one step is preserved for each expert.

Scheduler notes

Some ComfyUI schedulers respond very little to ModelSamplingSD3 shift. The plan validates each generated curve for finite, nonnegative, descending sigmas, a terminal zero, usable stage lengths, and a shared handoff. Requested scheduler steps and actual sigma transitions are tracked separately for schedulers whose output cardinality differs from steps + 1.

When an installed scheduler cannot produce a safe anchored crossing, the planner uses a validated piecewise curve or reports a descriptive error. It does not emit an extreme shift or a malformed schedule.

Installation

Place this directory under ComfyUI/custom_nodes and restart ComfyUI.

The nodes appear under:

sampling / Sampling Planner / Wan 2.2

Development tests

The planner tests do not require ComfyUI or PyTorch:

python3 -m unittest discover -s tests -v