https://github.com/WASasquatch/RES4SHO

ComfyUI experimental Schedulers and Samplers. Create and save your own schedulers and sampler tunes.
https://github.com/WASasquatch/RES4SHO

Last synced: about 2 months ago
JSON representation

ComfyUI experimental Schedulers and Samplers. Create and save your own schedulers and sampler tunes.

• Host: GitHub
• URL: https://github.com/WASasquatch/RES4SHO
• Owner: WASasquatch
• License: mit
• Created: 2026-04-27T15:24:03.000Z (3 months ago)
• Default Branch: main
• Last Pushed: 2026-05-08T03:47:36.000Z (3 months ago)
• Last Synced: 2026-06-13T21:36:27.887Z (about 2 months ago)
• Language: Python
• Homepage:
• Size: 155 KB
• Stars: 20
• Watchers: 0
• Forks: 3
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-comfyui - **RES4SHO** - Frequency Detail Sampling based on Res Sampling for ComfyUI (Workflows (5027) sorted by GitHub Stars)

README

          
# RES4SHO

High-frequency detail sampling for ComfyUI: a family of exponential-integrator

samplers with spectral high-frequency emphasis (HFE), a set of detail-biased

S-curve schedulers, and two custom-sampling nodes — **Sigma Curves** for

per-step sigma editing and **Manual Sampler** for tunable, savable sampler

presets.

## Installation

Clone or copy this folder into your ComfyUI `custom_nodes` directory:

```

ComfyUI/

  custom_nodes/

    RES4SHO/

      __init__.py

      sampling.py

      nodes.py

      manual_sampler.py

      ...

```

Restart ComfyUI. The samplers and schedulers below will appear in every

`KSampler` / `KSamplerAdvanced` / `SamplerCustom` dropdown. The two custom

nodes appear under `sampling/custom_sampling/`.

## What changed recently

If you're upgrading from an earlier version, note:

- **`hfe3_*`, `hfe4_*`, `hfe5_*` (and their `_auto` siblings) are removed.**

  Higher-stage integration is now reachable from any `hfe_*` sampler via the

  **Manual Sampler** node by setting `stages=3..5`. One sampler entry in the

  dropdown, your choice of stages.

- **`karras_tan` is removed.** Use `atan_focused` or `atan_steep` for similar

  shapes, or build a hybrid via the **Sigma Curves** node.

- **Sigma Curves** and **Manual Sampler** are new — see their sections below.

- New schedulers: `cosine`, `kumaraswamy`, `laplacian`, `linear`, plus asymmetric

  `atan_structure` / `atan_detail` / `logistic_structure` / `logistic_detail`.

  (ComfyUI's built-in `beta` is left alone — the Kumaraswamy curve we ship

  is closed-form and a different shape, so it lives under its own name.)

Old names are explicitly unregistered on load, so saved workflows that

reference them will need to be repointed at the current equivalents.

## Samplers

All samplers are exponential integrators with phi-function coefficients. The

HFE enhancement extracts high-frequency detail from inter-stage correction

deltas via a 3×3 spatial high-pass filter and re-injects it with configurable

strength.

### Fixed-strength HFE presets

Eight strength levels, two-stage integrator by default. Manual Sampler can

promote any of them to 3–5 stages for higher integration accuracy.

| Sampler | Description |

|---------|-------------|

| `hfe_s1` … `hfe_s8` | `s1` = no emphasis (clean res_2s), `s8` = maximum sharpness |

### Adaptive HFE

| Sampler | Description |

|---------|-------------|

| `hfe_auto` | Per-step adaptive `eta` driven by sigma envelope and content gating; defaults to 2 stages, `stages=3..5` via Manual Sampler |

How the adaptive gate works:

- **Sigma envelope** (smoothstep) — suppresses emphasis at high noise (early

  steps), full strength in the detail-forming range.

- **Content gate** — reduces emphasis when the model correction is already

  HF-rich; increases it when the correction is smooth and needs boosting.

### Experimental modes (`hfx_*`)

Ten enhancement modes, each operating in a different mathematical domain. All

use a 2-stage exponential integrator base. Each has four graduated strength

presets (`_s1` … `_s4`) on top of the bare entry, e.g. `hfx_sharp`,

`hfx_sharp_s1` … `hfx_sharp_s4`.

| Mode | Domain | Method |

|------|--------|--------|

| `hfx_sharp` | spatial | unsharp mask on `eps_2` via 3×3 box blur residual |

| `hfx_detail` | spatial | post-step HF injection from `denoised_2` |

| `hfx_boost` | value | uniform `eps_2` magnitude scaling (effective lying-sigma) |

| `hfx_focus` | value | power-law contrast on `eps_2` magnitudes |

| `hfx_spectral` | frequency | FFT distance-based power-law boost |

| `hfx_coherence` | frequency | FFT phase gating between `eps_1` and `eps_2` |

| `hfx_momentum` | temporal | EMA across steps on denoised differences |

| `hfx_stochastic` | temporal | structure-aware SDE noise injection (non-deterministic) |

| `hfx_orthogonal` | inter-stage | Gram-Schmidt projection of `eps_2` orthogonal to `eps_1` |

| `hfx_refine` | inter-stage | curvature-adaptive emphasis using `|eps_2 − eps_1|` as a spatial mask |

A per-step safety cap limits `eps_2` modifications to a fixed fraction of its

RMS, preventing compounding artifacts at the higher strength levels.

## Schedulers

Detail-biased S-curve schedulers that concentrate step density in the

detail-forming sigma range. All print an ASCII sigma chart to the console

on first use.

### Symmetric atan family

| Scheduler | Concentration |

|-----------|---------------|

| `atan_gentle` | mild mid-sigma |

| `atan_focused` | moderate detail-range |

| `atan_steep` | aggressive detail-range |

### Alternative curves

| Scheduler | Character |

|-----------|-----------|

| `logistic` | sigmoid S-curve, sharper transition than `atan` |

| `cosine` | smoothest, no inflection |

| `kumaraswamy` | closed-form beta-like CDF, asymmetric tails (distinct from ComfyUI's `beta`) |

| `laplacian` | exponential decay through mid sigmas |

| `linear` | reference baseline |

### Asymmetric two-stage curves

Independent slopes for the σ_max → σ_mid (structure) and σ_mid → σ_min

(detail) halves of the schedule.

| Scheduler | Bias |

|-----------|------|

| `atan_structure` | steep early stage, gentle late stage |

| `atan_detail` | gentle early stage, steep late stage |

| `logistic_structure` | logistic variant biased toward structure |

| `logistic_detail` | logistic variant biased toward detail |

## Sigma Curves node

`Sigma Curves` (category `sampling/custom_sampling/schedulers`) is a

per-step sigma editor with a canvas widget. It outputs a `SIGMAS` tensor

ready for `SamplerCustom` / `SamplerCustomAdvanced`.

### What it does

- Pick any registered scheduler as the **baseline** — the canvas seeds with

  that scheduler's natural shape, computed against your *actual* connected

  model (BasicScheduler is run on the loader at the other end of the model

  socket, no need to run the workflow first).

- Each sampling step is one draggable control point on the curve. Drag to

  reshape; the y-axis is normalized to your model's `[σ_min, σ_max]`.

- Right-drag the plot to select a step range; the toolbar's interpolation

  picker (linear, sigmoid, cosine, smoothstep, ease, exp, …) reshapes the

  selected range. Combine multiple curve archetypes in one schedule —

  e.g. sigmoid head, bezier middle, step tail.

- Header tag tells you whether the displayed shape came from your real

  model (`✓ from your model`) or a synthetic fallback (`≈ approximate`).

### Toolbar controls

All controls live in a two-row in-canvas toolbar above the plot:

- Row 1: `[interp ▾]` `[k tension]` `[apply curve]` ‧ `[select all]` `[clear]` `[flatten]`

- Row 2: `[reset to default]` ‧ `[save…]` `[load…]` `[delete…]`

Hover any button for a one-line description in the header strip.

### Saving and loading sigma curves

Saved curves are stored at `presets/sigma_curves.json` and **registered as

ComfyUI schedulers** under the prefix `sigma_curve_`. After saving,

the new entry appears in every scheduler dropdown (KSampler, KSamplerAdvanced,

BasicScheduler, …) once the frontend refreshes node defs — Sigma Curves

triggers that refresh automatically.

At runtime, a saved curve resamples to whatever step count the consuming

node requests and denormalizes against the active model's `σ_min` / `σ_max`,

so a curve authored at 20 steps still works correctly at 8 or 60.

## Manual Sampler node

`Manual Sampler` (category `sampling/custom_sampling/samplers`) wraps any

registered k-diffusion sampler — the built-in ones, this repo's `hfe_*` /

`hfx_*` variants, and any third-party samplers — with adjustable

`eta` / `s_noise` / `stages` overrides. It outputs a `SAMPLER` ready for

`SamplerCustom`.

### Inputs

| Input | Effect |

|-------|--------|

| `base_sampler` | Any sampler in the global registry |

| `stages` | Integrator stages (2–5). Honored by `hfe_*` and `hfe_auto`; silently dropped for samplers that don't accept it |

| `eta_override` | `-1.0` = use the base sampler's default; `0` = deterministic; `>0` = noisier / sharper. Hidden if the base sampler doesn't accept `eta` |

| `s_noise` | Noise scale for stochastic samplers; hidden if not accepted |

The frontend probes the chosen base sampler's signature on each change and

hides the widgets it doesn't accept, so the UI honestly reflects what's

actually tunable.

### Saving and loading samplers

Saved presets are stored at `presets/manual_samplers.json` and **registered

as ComfyUI samplers** under the prefix `manual_sampler_`. After saving,

the new sampler appears in every sampler dropdown once the frontend refreshes

node defs.

This is the supported path for *creating new samplers* in this repo: pick a

known-good integrator, dial in `eta` / `s_noise` / `stages`, save with a

name. There's no facility for hand-writing integrator code from a node —

that's deliberate: every saved preset is guaranteed to be a sensible

integrator that won't NaN.

## Recommended combinations

### Getting started

| Goal | Sampler | Scheduler | Notes |

|------|---------|-----------|-------|

| General use | `hfe_auto` | `atan_focused` | Best all-rounder; adaptive emphasis handles most content |

| Subtle enhancement | `hfe_s3` | `atan_gentle` | Light touch, minimal artifact risk |

| Strong detail | `hfe_s6` | `atan_steep` | Noticeably sharper textures and edges |

| Maximum sharpness | `hfe_s7` / `hfe_s8` | `atan_steep` | Aggressive — inspect for over-sharpening |

### By content type

| Content | Sampler | Scheduler | Why |

|---------|---------|-----------|-----|

| Portraits / faces | `hfe_auto` | `atan_focused` | Auto gate protects skin while sharpening eyes / hair / pores |

| Landscapes / nature | `hfe_s5` | `atan_gentle` | Mid-strength avoids over-enhancing skies |

| Architecture / hard surfaces | `hfe_s7` | `atan_steep` | Strong emphasis on edges and geometric detail |

| Text / UI renders | `hfx_sharp` | `atan_steep` | Spatial high-pass targets glyph edges |

| Fabric / organic texture | `hfx_spectral` | `atan_focused` | Frequency-domain emphasis across texture scales |

| Illustrations / anime | `hfe_s4` | `atan_gentle` | Light emphasis preserves flat shading |

### Higher integration accuracy

Wrap any `hfe_*` sampler in **Manual Sampler** with `stages=3..5` for better

ODE accuracy at low step counts or with difficult models:

| Wrapped sampler | `stages` | Use case |

|-----------------|----------|----------|

| `hfe_auto` | 3 | Solid balance of accuracy and speed |

| `hfe_auto` | 4 | High accuracy for complex prompts |

| `hfe_auto` | 5 | Maximum integration accuracy |

| `hfe_s5` | 4 | Fixed-strength detail + 4-stage accuracy |

Save the configured Manual Sampler as a preset (e.g. `hfe_auto_5stage`) so

it appears as `manual_sampler_hfe_auto_5stage` in every sampler dropdown

without the wrapper node in your graph.

### Experimental combinations

| Sampler | Scheduler | Character |

|---------|-----------|-----------|

| `hfx_sharp` | `atan_focused` | Spatial high-pass, good default experimental choice |

| `hfx_spectral` | `atan_steep` | Frequency-domain power-law sharpening |

| `hfx_refine` | `atan_focused` | Curvature-adaptive — sharpens where the model is least certain |

| `hfx_coherence` | `atan_focused` | Phase-coherence gating — amplifies structurally confident frequencies |

| `hfx_orthogonal` | `atan_focused` | Novel-information extraction via Gram-Schmidt |

| `hfx_momentum` | `atan_gentle` | Temporal accumulation — builds detail across steps |

| `hfx_focus` | `atan_focused` | Value-domain contrast — amplifies dominant correction directions |

| `hfx_stochastic` | `atan_gentle` | Stochastic texture injection — adds micro-variation |

| `hfx_boost` | `atan_gentle` | Uniform eps amplification — simple signal boost |

| `hfx_detail` | `atan_focused` | Post-step HF injection from denoised output |

### Scheduler pairings

| Scheduler | Best with | Character |

|-----------|-----------|-----------|

| `atan_gentle` | low-strength samplers (`s1`–`s4`), stochastic modes | mild concentration, safe for any content |

| `atan_focused` | auto samplers, mid-strength presets (`s4`–`s6`) | balanced step density in detail range |

| `atan_steep` | high-strength samplers (`s6`–`s8`), architecture | aggressive detail-range concentration |

| `logistic` | any | sharper transition through detail range, flatter extremes |

| `atan_structure` / `logistic_structure` | high stage counts via Manual Sampler | bias toward composition / form |

| `atan_detail` / `logistic_detail` | high-strength HFE / HFX modes | bias toward texture / micro-detail |

| `cosine` | low-step counts | smoothest transition, no inflection |

## How it works

**Base integrator.** Multi-stage singlestep exponential integrator (res_Ns)

with phi-function coefficients, giving exact treatment of exponential decay

and higher-order corrections from intermediate evaluations. `stages=2` is the

default; `3..5` are reachable via Manual Sampler.

**HFE enhancement (`hfe_*`).** The inter-stage correction delta captures

what the model reveals at lower noise — texture, edges, micro-structure. A

spatial high-pass (residual after a 3×3 box blur in latent space) extracts

the fine-detail component, which is re-injected with extra weight `eta`.

This compounds across every step, with `eta` scheduled by sigma envelope

(suppress at high noise) and content gate (boost smooth corrections,

restrain HF-rich ones) for the `_auto` variant.

**HFX modes (`hfx_*`).** Each mode modifies the second-stage prediction

(`eps_2`) using a different mathematical operation before the integrator

update step. The 10 modes span 5 domains:

- **Spatial** — high-pass filtering (`sharp`), post-step HF injection (`detail`).

- **Value** — uniform scaling (`boost`), nonlinear power-law contrast (`focus`).

- **Frequency** — FFT power-law reshaping (`spectral`), inter-stage phase

  coherence gating (`coherence`).

- **Temporal** — EMA across steps (`momentum`), stochastic noise injection

  (`stochastic`).

- **Inter-stage** — Gram-Schmidt novel-component extraction (`orthogonal`),

  ODE curvature-adaptive gain (`refine`).

**Schedulers.** `atan_*` and `logistic_*` apply a curve function in two

stages (σ_max → σ_mid for structure, σ_mid → σ_min for detail), each with

its own slope normalized by step count. `cosine` / `kumaraswamy` / `laplacian` /

`linear` apply a single curve across the whole range. The `_structure` /

`_detail` variants make the two stages asymmetric.

**Sigma Curves.** Stores a normalized `[0, 1]` y-array per step alongside

the originally chosen baseline scheduler. At runtime the values are

resampled to the consumer's step count and denormalized against the active

model's `σ_min` / `σ_max`. Workflows persist the curve in the node's

`curve_data` widget; saved presets live at `presets/sigma_curves.json`.

**Manual Sampler.** Builds a thin wrapper around the chosen base sampler's

function in `comfy.samplers.k_diffusion_sampling`, injecting `eta` /

`s_noise` / `stages` only when the base sampler accepts them. Saved

presets live at `presets/manual_samplers.json` and re-register as samplers

on every ComfyUI startup.

**Safety.** A per-step cap limits `eps_2` modifications to a small fraction

of the original RMS, preventing compounding artifacts. A sigma warmup gate

suppresses enhancement at high noise levels (early steps). An img2img

denoise gate scales down enhancement for partial-denoise schedules.

**Cost.** One 3×3 `avg_pool` per step for spatial variants; one FFT pair for

spectral / coherence modes. All negligible vs. model evaluation. Auto

samplers add a few scalar ops on top.

## License

MIT