{"id":50563504,"url":"https://github.com/WASasquatch/RES4SHO","last_synced_at":"2026-06-21T08:00:53.431Z","repository":{"id":354226390,"uuid":"1222659097","full_name":"WASasquatch/RES4SHO","owner":"WASasquatch","description":"ComfyUI experimental Schedulers and Samplers. Create and save your own schedulers and sampler tunes.","archived":false,"fork":false,"pushed_at":"2026-05-08T03:47:36.000Z","size":159,"stargazers_count":20,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T21:36:27.887Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WASasquatch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-27T15:24:03.000Z","updated_at":"2026-06-11T22:08:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/WASasquatch/RES4SHO","commit_stats":null,"previous_names":["wasasquatch/res4sho"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/WASasquatch/RES4SHO","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WASasquatch%2FRES4SHO","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WASasquatch%2FRES4SHO/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WASasquatch%2FRES4SHO/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WASasquatch%2FRES4SHO/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WASasquatch","download_url":"https://codeload.github.com/WASasquatch/RES4SHO/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WASasquatch%2FRES4SHO/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34601662,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-04T13:00:25.186Z","updated_at":"2026-06-21T08:00:53.425Z","avatar_url":"https://github.com/WASasquatch.png","language":"Python","funding_links":[],"categories":["Workflows (5027) sorted by GitHub Stars"],"sub_categories":[],"readme":"# RES4SHO\n\nHigh-frequency detail sampling for ComfyUI: a family of exponential-integrator\nsamplers with spectral high-frequency emphasis (HFE), a set of detail-biased\nS-curve schedulers, and two custom-sampling nodes — **Sigma Curves** for\nper-step sigma editing and **Manual Sampler** for tunable, savable sampler\npresets.\n\n## Installation\n\nClone or copy this folder into your ComfyUI `custom_nodes` directory:\n\n```\nComfyUI/\n  custom_nodes/\n    RES4SHO/\n      __init__.py\n      sampling.py\n      nodes.py\n      manual_sampler.py\n      ...\n```\n\nRestart ComfyUI. The samplers and schedulers below will appear in every\n`KSampler` / `KSamplerAdvanced` / `SamplerCustom` dropdown. The two custom\nnodes appear under `sampling/custom_sampling/`.\n\n## What changed recently\n\nIf you're upgrading from an earlier version, note:\n\n- **`hfe3_*`, `hfe4_*`, `hfe5_*` (and their `_auto` siblings) are removed.**\n  Higher-stage integration is now reachable from any `hfe_*` sampler via the\n  **Manual Sampler** node by setting `stages=3..5`. One sampler entry in the\n  dropdown, your choice of stages.\n- **`karras_tan` is removed.** Use `atan_focused` or `atan_steep` for similar\n  shapes, or build a hybrid via the **Sigma Curves** node.\n- **Sigma Curves** and **Manual Sampler** are new — see their sections below.\n- New schedulers: `cosine`, `kumaraswamy`, `laplacian`, `linear`, plus asymmetric\n  `atan_structure` / `atan_detail` / `logistic_structure` / `logistic_detail`.\n  (ComfyUI's built-in `beta` is left alone — the Kumaraswamy curve we ship\n  is closed-form and a different shape, so it lives under its own name.)\n\nOld names are explicitly unregistered on load, so saved workflows that\nreference them will need to be repointed at the current equivalents.\n\n## Samplers\n\nAll samplers are exponential integrators with phi-function coefficients. The\nHFE enhancement extracts high-frequency detail from inter-stage correction\ndeltas via a 3×3 spatial high-pass filter and re-injects it with configurable\nstrength.\n\n### Fixed-strength HFE presets\n\nEight strength levels, two-stage integrator by default. Manual Sampler can\npromote any of them to 3–5 stages for higher integration accuracy.\n\n| Sampler | Description |\n|---------|-------------|\n| `hfe_s1` … `hfe_s8` | `s1` = no emphasis (clean res_2s), `s8` = maximum sharpness |\n\n### Adaptive HFE\n\n| Sampler | Description |\n|---------|-------------|\n| `hfe_auto` | Per-step adaptive `eta` driven by sigma envelope and content gating; defaults to 2 stages, `stages=3..5` via Manual Sampler |\n\nHow the adaptive gate works:\n\n- **Sigma envelope** (smoothstep) — suppresses emphasis at high noise (early\n  steps), full strength in the detail-forming range.\n- **Content gate** — reduces emphasis when the model correction is already\n  HF-rich; increases it when the correction is smooth and needs boosting.\n\n### Experimental modes (`hfx_*`)\n\nTen enhancement modes, each operating in a different mathematical domain. All\nuse a 2-stage exponential integrator base. Each has four graduated strength\npresets (`_s1` … `_s4`) on top of the bare entry, e.g. `hfx_sharp`,\n`hfx_sharp_s1` … `hfx_sharp_s4`.\n\n| Mode | Domain | Method |\n|------|--------|--------|\n| `hfx_sharp` | spatial | unsharp mask on `eps_2` via 3×3 box blur residual |\n| `hfx_detail` | spatial | post-step HF injection from `denoised_2` |\n| `hfx_boost` | value | uniform `eps_2` magnitude scaling (effective lying-sigma) |\n| `hfx_focus` | value | power-law contrast on `eps_2` magnitudes |\n| `hfx_spectral` | frequency | FFT distance-based power-law boost |\n| `hfx_coherence` | frequency | FFT phase gating between `eps_1` and `eps_2` |\n| `hfx_momentum` | temporal | EMA across steps on denoised differences |\n| `hfx_stochastic` | temporal | structure-aware SDE noise injection (non-deterministic) |\n| `hfx_orthogonal` | inter-stage | Gram-Schmidt projection of `eps_2` orthogonal to `eps_1` |\n| `hfx_refine` | inter-stage | curvature-adaptive emphasis using `|eps_2 − eps_1|` as a spatial mask |\n\nA per-step safety cap limits `eps_2` modifications to a fixed fraction of its\nRMS, preventing compounding artifacts at the higher strength levels.\n\n## Schedulers\n\nDetail-biased S-curve schedulers that concentrate step density in the\ndetail-forming sigma range. All print an ASCII sigma chart to the console\non first use.\n\n### Symmetric atan family\n\n| Scheduler | Concentration |\n|-----------|---------------|\n| `atan_gentle` | mild mid-sigma |\n| `atan_focused` | moderate detail-range |\n| `atan_steep` | aggressive detail-range |\n\n### Alternative curves\n\n| Scheduler | Character |\n|-----------|-----------|\n| `logistic` | sigmoid S-curve, sharper transition than `atan` |\n| `cosine` | smoothest, no inflection |\n| `kumaraswamy` | closed-form beta-like CDF, asymmetric tails (distinct from ComfyUI's `beta`) |\n| `laplacian` | exponential decay through mid sigmas |\n| `linear` | reference baseline |\n\n### Asymmetric two-stage curves\n\nIndependent slopes for the σ_max → σ_mid (structure) and σ_mid → σ_min\n(detail) halves of the schedule.\n\n| Scheduler | Bias |\n|-----------|------|\n| `atan_structure` | steep early stage, gentle late stage |\n| `atan_detail` | gentle early stage, steep late stage |\n| `logistic_structure` | logistic variant biased toward structure |\n| `logistic_detail` | logistic variant biased toward detail |\n\n## Sigma Curves node\n\n`Sigma Curves` (category `sampling/custom_sampling/schedulers`) is a\nper-step sigma editor with a canvas widget. It outputs a `SIGMAS` tensor\nready for `SamplerCustom` / `SamplerCustomAdvanced`.\n\n### What it does\n\n- Pick any registered scheduler as the **baseline** — the canvas seeds with\n  that scheduler's natural shape, computed against your *actual* connected\n  model (BasicScheduler is run on the loader at the other end of the model\n  socket, no need to run the workflow first).\n- Each sampling step is one draggable control point on the curve. Drag to\n  reshape; the y-axis is normalized to your model's `[σ_min, σ_max]`.\n- Right-drag the plot to select a step range; the toolbar's interpolation\n  picker (linear, sigmoid, cosine, smoothstep, ease, exp, …) reshapes the\n  selected range. Combine multiple curve archetypes in one schedule —\n  e.g. sigmoid head, bezier middle, step tail.\n- Header tag tells you whether the displayed shape came from your real\n  model (`✓ from your model`) or a synthetic fallback (`≈ approximate`).\n\n### Toolbar controls\n\nAll controls live in a two-row in-canvas toolbar above the plot:\n\n- Row 1: `[interp ▾]` `[k tension]` `[apply curve]` ‧ `[select all]` `[clear]` `[flatten]`\n- Row 2: `[reset to default]` ‧ `[save…]` `[load…]` `[delete…]`\n\nHover any button for a one-line description in the header strip.\n\n### Saving and loading sigma curves\n\nSaved curves are stored at `presets/sigma_curves.json` and **registered as\nComfyUI schedulers** under the prefix `sigma_curve_\u003cname\u003e`. After saving,\nthe new entry appears in every scheduler dropdown (KSampler, KSamplerAdvanced,\nBasicScheduler, …) once the frontend refreshes node defs — Sigma Curves\ntriggers that refresh automatically.\n\nAt runtime, a saved curve resamples to whatever step count the consuming\nnode requests and denormalizes against the active model's `σ_min` / `σ_max`,\nso a curve authored at 20 steps still works correctly at 8 or 60.\n\n## Manual Sampler node\n\n`Manual Sampler` (category `sampling/custom_sampling/samplers`) wraps any\nregistered k-diffusion sampler — the built-in ones, this repo's `hfe_*` /\n`hfx_*` variants, and any third-party samplers — with adjustable\n`eta` / `s_noise` / `stages` overrides. It outputs a `SAMPLER` ready for\n`SamplerCustom`.\n\n### Inputs\n\n| Input | Effect |\n|-------|--------|\n| `base_sampler` | Any sampler in the global registry |\n| `stages` | Integrator stages (2–5). Honored by `hfe_*` and `hfe_auto`; silently dropped for samplers that don't accept it |\n| `eta_override` | `-1.0` = use the base sampler's default; `0` = deterministic; `\u003e0` = noisier / sharper. Hidden if the base sampler doesn't accept `eta` |\n| `s_noise` | Noise scale for stochastic samplers; hidden if not accepted |\n\nThe frontend probes the chosen base sampler's signature on each change and\nhides the widgets it doesn't accept, so the UI honestly reflects what's\nactually tunable.\n\n### Saving and loading samplers\n\nSaved presets are stored at `presets/manual_samplers.json` and **registered\nas ComfyUI samplers** under the prefix `manual_sampler_\u003cname\u003e`. After saving,\nthe new sampler appears in every sampler dropdown once the frontend refreshes\nnode defs.\n\nThis is the supported path for *creating new samplers* in this repo: pick a\nknown-good integrator, dial in `eta` / `s_noise` / `stages`, save with a\nname. There's no facility for hand-writing integrator code from a node —\nthat's deliberate: every saved preset is guaranteed to be a sensible\nintegrator that won't NaN.\n\n## Recommended combinations\n\n### Getting started\n\n| Goal | Sampler | Scheduler | Notes |\n|------|---------|-----------|-------|\n| General use | `hfe_auto` | `atan_focused` | Best all-rounder; adaptive emphasis handles most content |\n| Subtle enhancement | `hfe_s3` | `atan_gentle` | Light touch, minimal artifact risk |\n| Strong detail | `hfe_s6` | `atan_steep` | Noticeably sharper textures and edges |\n| Maximum sharpness | `hfe_s7` / `hfe_s8` | `atan_steep` | Aggressive — inspect for over-sharpening |\n\n### By content type\n\n| Content | Sampler | Scheduler | Why |\n|---------|---------|-----------|-----|\n| Portraits / faces | `hfe_auto` | `atan_focused` | Auto gate protects skin while sharpening eyes / hair / pores |\n| Landscapes / nature | `hfe_s5` | `atan_gentle` | Mid-strength avoids over-enhancing skies |\n| Architecture / hard surfaces | `hfe_s7` | `atan_steep` | Strong emphasis on edges and geometric detail |\n| Text / UI renders | `hfx_sharp` | `atan_steep` | Spatial high-pass targets glyph edges |\n| Fabric / organic texture | `hfx_spectral` | `atan_focused` | Frequency-domain emphasis across texture scales |\n| Illustrations / anime | `hfe_s4` | `atan_gentle` | Light emphasis preserves flat shading |\n\n### Higher integration accuracy\n\nWrap any `hfe_*` sampler in **Manual Sampler** with `stages=3..5` for better\nODE accuracy at low step counts or with difficult models:\n\n| Wrapped sampler | `stages` | Use case |\n|-----------------|----------|----------|\n| `hfe_auto` | 3 | Solid balance of accuracy and speed |\n| `hfe_auto` | 4 | High accuracy for complex prompts |\n| `hfe_auto` | 5 | Maximum integration accuracy |\n| `hfe_s5` | 4 | Fixed-strength detail + 4-stage accuracy |\n\nSave the configured Manual Sampler as a preset (e.g. `hfe_auto_5stage`) so\nit appears as `manual_sampler_hfe_auto_5stage` in every sampler dropdown\nwithout the wrapper node in your graph.\n\n### Experimental combinations\n\n| Sampler | Scheduler | Character |\n|---------|-----------|-----------|\n| `hfx_sharp` | `atan_focused` | Spatial high-pass, good default experimental choice |\n| `hfx_spectral` | `atan_steep` | Frequency-domain power-law sharpening |\n| `hfx_refine` | `atan_focused` | Curvature-adaptive — sharpens where the model is least certain |\n| `hfx_coherence` | `atan_focused` | Phase-coherence gating — amplifies structurally confident frequencies |\n| `hfx_orthogonal` | `atan_focused` | Novel-information extraction via Gram-Schmidt |\n| `hfx_momentum` | `atan_gentle` | Temporal accumulation — builds detail across steps |\n| `hfx_focus` | `atan_focused` | Value-domain contrast — amplifies dominant correction directions |\n| `hfx_stochastic` | `atan_gentle` | Stochastic texture injection — adds micro-variation |\n| `hfx_boost` | `atan_gentle` | Uniform eps amplification — simple signal boost |\n| `hfx_detail` | `atan_focused` | Post-step HF injection from denoised output |\n\n### Scheduler pairings\n\n| Scheduler | Best with | Character |\n|-----------|-----------|-----------|\n| `atan_gentle` | low-strength samplers (`s1`–`s4`), stochastic modes | mild concentration, safe for any content |\n| `atan_focused` | auto samplers, mid-strength presets (`s4`–`s6`) | balanced step density in detail range |\n| `atan_steep` | high-strength samplers (`s6`–`s8`), architecture | aggressive detail-range concentration |\n| `logistic` | any | sharper transition through detail range, flatter extremes |\n| `atan_structure` / `logistic_structure` | high stage counts via Manual Sampler | bias toward composition / form |\n| `atan_detail` / `logistic_detail` | high-strength HFE / HFX modes | bias toward texture / micro-detail |\n| `cosine` | low-step counts | smoothest transition, no inflection |\n\n## How it works\n\n**Base integrator.** Multi-stage singlestep exponential integrator (res_Ns)\nwith phi-function coefficients, giving exact treatment of exponential decay\nand higher-order corrections from intermediate evaluations. `stages=2` is the\ndefault; `3..5` are reachable via Manual Sampler.\n\n**HFE enhancement (`hfe_*`).** The inter-stage correction delta captures\nwhat the model reveals at lower noise — texture, edges, micro-structure. A\nspatial high-pass (residual after a 3×3 box blur in latent space) extracts\nthe fine-detail component, which is re-injected with extra weight `eta`.\nThis compounds across every step, with `eta` scheduled by sigma envelope\n(suppress at high noise) and content gate (boost smooth corrections,\nrestrain HF-rich ones) for the `_auto` variant.\n\n**HFX modes (`hfx_*`).** Each mode modifies the second-stage prediction\n(`eps_2`) using a different mathematical operation before the integrator\nupdate step. The 10 modes span 5 domains:\n\n- **Spatial** — high-pass filtering (`sharp`), post-step HF injection (`detail`).\n- **Value** — uniform scaling (`boost`), nonlinear power-law contrast (`focus`).\n- **Frequency** — FFT power-law reshaping (`spectral`), inter-stage phase\n  coherence gating (`coherence`).\n- **Temporal** — EMA across steps (`momentum`), stochastic noise injection\n  (`stochastic`).\n- **Inter-stage** — Gram-Schmidt novel-component extraction (`orthogonal`),\n  ODE curvature-adaptive gain (`refine`).\n\n**Schedulers.** `atan_*` and `logistic_*` apply a curve function in two\nstages (σ_max → σ_mid for structure, σ_mid → σ_min for detail), each with\nits own slope normalized by step count. `cosine` / `kumaraswamy` / `laplacian` /\n`linear` apply a single curve across the whole range. The `_structure` /\n`_detail` variants make the two stages asymmetric.\n\n**Sigma Curves.** Stores a normalized `[0, 1]` y-array per step alongside\nthe originally chosen baseline scheduler. At runtime the values are\nresampled to the consumer's step count and denormalized against the active\nmodel's `σ_min` / `σ_max`. Workflows persist the curve in the node's\n`curve_data` widget; saved presets live at `presets/sigma_curves.json`.\n\n**Manual Sampler.** Builds a thin wrapper around the chosen base sampler's\nfunction in `comfy.samplers.k_diffusion_sampling`, injecting `eta` /\n`s_noise` / `stages` only when the base sampler accepts them. Saved\npresets live at `presets/manual_samplers.json` and re-register as samplers\non every ComfyUI startup.\n\n**Safety.** A per-step cap limits `eps_2` modifications to a small fraction\nof the original RMS, preventing compounding artifacts. A sigma warmup gate\nsuppresses enhancement at high noise levels (early steps). An img2img\ndenoise gate scales down enhancement for partial-denoise schedules.\n\n**Cost.** One 3×3 `avg_pool` per step for spatial variants; one FFT pair for\nspectral / coherence modes. All negligible vs. model evaluation. Auto\nsamplers add a few scalar ops on top.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWASasquatch%2FRES4SHO","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FWASasquatch%2FRES4SHO","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FWASasquatch%2FRES4SHO/lists"}