# ChebyFlow for ComfyUI

**ChebyFlow** is an adaptive two-stage Chebyshev flow sampler for ComfyUI, developed and tuned around MiniMax H3 / `CONST` rectified-flow sampling.

The core idea is to use the second model evaluation not at a fixed midpoint, but at an **adaptive internal stage** whose position is driven by the locally observed flow behavior. The sampler also adapts correction strength and can do so per latent channel.

## Nodes

### ChebyFlow Auto Sampler

Recommended default. It self-calibrates online during the current generation using the two model evaluations it already performs per interval. No prior runs, logs, or extra NFEs are required.

Controls:

```text
coordinate
base_stage_position
min_stage_position
max_stage_position
adaptivity
quality_bias
turbo_mode
correction_granularity
```

Presets:

```text
balanced
detail
smooth
stable
dynamic
```

`turbo_mode` is an orthogonal low-step operating mode intended for distilled / Turbo-LoRA workflows around roughly 6–10 steps. It shortens warm-up, accelerates the online observer, biases the internal stage later, and narrows the final correction range for stability on large intervals.

Recommended normal default:

```text
coordinate              = flow_lambda
base_stage_position     = 0.72
min_stage_position      = 0.58
max_stage_position      = 0.96
adaptivity              = 1.00
quality_bias            = balanced
turbo_mode              = false
correction_granularity  = per_channel
```

Recommended low-step / Turbo default:

```text
coordinate              = flow_lambda
base_stage_position     = 0.72
min_stage_position      = 0.58
max_stage_position      = 0.96
adaptivity              = 1.00
quality_bias            = balanced
turbo_mode              = true
correction_granularity  = per_channel
```

### ChebyFlow Advanced Sampler

Manually tunable version. Defaults keep the strongest combined configuration found during development:

```text
coordinate                  = flow_lambda
base_stage_position         = 0.70
min_stage_position          = 0.55
max_stage_position          = 0.95
adapt_strength              = 1.00
curvature_smoothing         = 0.50
stage_curvature_scale       = 0.12

curvature_metric            = combined
residual_weight             = 1.00
angle_weight                = 1.00
magnitude_weight            = 0.50

correction_mode             = curvature_down
correction_granularity      = per_channel
correction_min              = 0.88
correction_max              = 1.08
correction_curvature_scale  = 0.12
```

## How ChebyFlow works

For each non-terminal outer interval, ChebyFlow:

1. evaluates the model at the current state;
2. predicts an internal Chebyshev stage;
3. evaluates the model again at that stage;
4. measures local flow behavior using residual change, angular turning, and magnitude change;
5. adapts the next internal-stage position;
6. adapts the current correction strength, optionally per latent channel;
7. applies the two-stage corrected update.

The Auto sampler additionally maintains fast and slow online statistics so it responds to **relative difficulty within the current generation**, rather than requiring hand-tuned absolute curvature scales.

Approximate cost: **~2 model evaluations per non-terminal interval**.

## Installation

Copy the folder to:

```text
ComfyUI/custom_nodes/ComfyUI-ChebyFlow/
```

Then restart ComfyUI completely.

Both nodes output `SAMPLER` and connect directly to the `sampler` input of `SamplerCustomAdvanced`.

## Compatibility

ChebyFlow currently validates that the active ComfyUI model sampling object is `CONST` / rectified-flow. It was developed specifically around MiniMax H3 and should be considered experimental outside that setting.

## Backward compatibility

The internal ComfyUI node class IDs remain compatible with the previous `H3 Adaptive Chebyshev` development builds, while the user-visible node names are now **ChebyFlow Auto Sampler** and **ChebyFlow Advanced Sampler**.