ComfyUI Sol-H3

ComfyUI-Sol-H3

v0.1.11 — coordinated release (17 October 2026)

Sol #41 fuses grouped VDN K/V preparation, preserves BF16 short-gather numerical semantics and bounds activation lifetimes. Pair it with VDN-H3-Plus v1.5.10, Flow-Aligned Regenerate v0.3.14, and H3 Continuum-Plus v3.4.9. The selected Sol path keeps the trained VDN linear complement active (550/550 in owner two-chunk traces) and logged 8,800 grouped K/V fusions. Owner SM120 producer-only medians improved ~24%; no matching overall-generation speedup or Sol-versus-Core same-work claim is implied. Windows native lacks these custom kernels. See grouped attention, memory policy and release notes.

Native MiniMax-H3 exact-runtime optimization and composable Sana Sol-Attn integration for ComfyUI.

Unreleased memory architecture: this branch adds bounded BF16 QKV production, bounded arithmetic qualification and deterministic temporary-callback cleanup. GPU memory, sampler timing and decoded-quality acceptance remain open. See BF16 memory architecture and acceptance procedure.

Sol-H3 packages the real Sol-Attn implementation from xmarre/Sana, branch sol-engine, pinned at revision 2936c47637380842aaa4a4488fac5006cc542b70. On supported SM120 and SM121 Linux/WSL2 systems it executes Sana's CuTe cute_sm120 backend; comfy_kitchen.sol_attn is not substituted for it.

The package has three parts:

• Exact Runtime — exact native H3 affine/runtime optimizations.
• Rectangular SOL — Sana/CuTe cute_sm120 attention on SM120/SM121 with independent query and K/V lengths.
• Composable interoperability — inherited dense providers, VDN grouped attention, Spectrum backend history, Untwist preprocessing, Diff-Aid and Flow mixed-grid routing can coexist when their ownership contracts are coherent.

Unvalidated combinations are experimental telemetry rather than blanket errors. Hard failures are reserved for broken contracts, unsafe geometry/indexing, failed arithmetic verification or real execution failures.

Native Windows: the current custom SOL and Exact Runtime kernel paths are not supported execution targets. SOL delegates to inherited dense attention and Exact Runtime delegates to native H3, so the nodes can remain in a workflow but no Sol-H3 custom kernel executes. Use Linux/WSL2 on supported hardware for custom-kernel acceleration. See Native Windows status.

SM121 / GB10 support

Since v0.1.7, Linux/WSL2 execution supports for compute capability (12, 1) devices such as NVIDIA GB10 / DGX Spark. SM121 is mapped to the existing packaged cute_sm120 CuTe backend; the reported CUDA capability is not rewritten or spoofed.

The SM121 admission is applied consistently across backend selection, the SOL loader, ordinary runtime shape checks, partitioned execution, and rectangular K/V token sizing. The vendored Sana patch stack and manifest/provenance hashes include the change, so source verification remains fail-closed.

PR #38 supplied real-GB10 execution evidence: a BF16 1×64×4×128 kernel call returned cute_sm120 with finite output, and a small Comfy prompt recorded sol_backend=cute_sm120 with sparse_calls=100. Hosted CI independently covers dispatch, provenance and interoperability contracts. This support does not claim an independent maintainer GB10 benchmark or SM120/SM121 performance equivalence.

Default: one dense trajectory evaluation

Sol-H3 SOL Attention (Experimental) now defaults to:

dense_evaluations = 1
dense_layers      = 2

dense_evaluations=1 keeps the first complete denoiser evaluation on inherited dense attention, then enables SOL. dense_layers=2 remains separate: the first two H3 blocks of each otherwise-SOL evaluation stay dense and do not add a transformer NFE.

v0.1.2 temporarily changed the default to dense_evaluations=0 because the initial dense -> sol numerical-backend transition invalidates Spectrum's dense forecasting anchor and can turn the first would-be forecast into an additional actual transformer NFE. Starting directly in phase=sol avoids that extra NFE.

That scheduling analysis remains correct, but a subsequent controlled same-seed video comparison exposed a concrete quality risk when SOL approximation acts from the first sigma-1.0 evaluation. With dense_evaluations=0, the opening motion showed an abrupt pose/orientation change with heavy early smearing before settling into the opposite heading. With dense_evaluations=1, the corresponding opening motion remained a continuous turn.

The pair establishes that SOL-first execution can destabilize the initial trajectory. It does not establish how frequently this occurs across seeds, prompts, references, resolutions or model variants. v0.1.3 therefore restores 1 as the quality-conservative default while keeping 0 available as an explicit maximum-speed mode.

Previous controlled no-VDN hot evidence remains the measured speed trade-off:

| Run | SOL | dense_evaluations | Logical | Actual | Forecast | H3 sampler | End-to-end | |---|---|---:|---:|---:|---:|---:|---:| | metrics_00321 | on | 1 | 40 | 26 | 14 | 353.36 s | 400.94 s | | metrics_00322 | off | — | 40 | 25 | 15 | 374.84 s | 420.81 s | | metrics_00323 | on | 0 | 40 | 25 | 15 | 332.56 s | 380.57 s |

dense_evaluations=0 restored exact NFE/forecast topology parity with the no-SOL control in that test and removed one actual NFE relative to dense_evaluations=1. The timing remains deployment-specific and is not a quality-equivalence result. Do not weaken Spectrum's history/receipt safety to recover that NFE while retaining a dense-to-SOL transition.

Existing saved workflows keep their serialized dense_evaluations value. Workflows created or saved under v0.1.2 can therefore remain at 0 after upgrading until changed explicitly. See SOL trajectory warmup for the speed/quality trade-off, migration behavior and telemetry guidance.

Production validation

The original full production stack was exercised on an NVIDIA RTX PRO 6000 Blackwell Workstation Edition (SM120) with PyTorch 2.10.0+cu130.

The v0.1.0 validation used the one-evaluation dense warmup and produced:

sampler_logical_calls       18
transformer_actual_nfe      14
spectrum_forecast_calls      4

low:    8 actual / 2 forecast
high:   4 actual / 2 forecast
probe:  2 actual / 0 forecast

The SOL-bypassed control executed 13 actual + 5 forecast; the additional SOL actual was the first low-stage dense -> sol numerical-backend transition. v0.1.2 removed that transition from the default for speed; v0.1.3 restores it as the default after the startup-quality regression described above. dense_evaluations=0 remains available when the speed trade-off is explicitly desired.

The real packaged kernel, VDN API-v3 rectangular route, Flow mixed-grid route, Spectrum receipts/history, Untwist preprocessing and zero-copy BTHD bridge all passed production execution. See Validation for the original evidence matrix and SOL trajectory warmup for the current default policy.

Nodes and composition

Apply MODEL patches and then apply Sol-H3 SOL Attention (Experimental) before sampling. exact_fusion=true also requests Exact Runtime. A later Sol-H3 Exact Runtime node merges with the same lifecycle rather than installing a second one.

The SOL node defaults to tau=1.0, dense_evaluations=1, and dense_layers=2. dense_evaluations is a trajectory-level dense warmup; dense_layers is a per-evaluation leading-layer dense policy. They are not interchangeable. Set dense_evaluations=0 only when explicitly choosing the faster SOL-first trajectory and accepting the documented startup-continuity risk.

The optional qkv_chunk_size defaults to 4096; 0 selects full native QKV production. Eligible native BF16 H3 calls above 32,768 rows retain full BF16 K/V and recompute Q in bounded projection chunks. With the compatible VDN-H3-Plus PR #42 overlay, eligible VDN native forwards instead project Q/K/V in bounded chunks into three independent full-length BF16 carriers, preserving VDN's learned linear branch and grouped softmax while avoiding its redundant full-V clone. The VDN path does not recompute Q. With the paired VDN partitioned wrapper (API 2), Flow's physical low/probe/high domains can use this bounded projection without changing any Flow attention or temporal/linear ownership. Unqualified runtime projection hooks retain their established owners. Native two-pass projection adds compute; sampler memory/time and GPU output parity remain unmeasured. Memory details.

On native Windows, the node can remain in the workflow but both custom-kernel paths fail closed: SOL delegates to inherited dense attention because CuTe is unavailable, and Exact Runtime records exact:native_windows_unvalidated then executes the untouched native H3 block. Linux/WSL2 supports the SM120 and SM121 targets described above.

Supported composition includes Exact -> SOL, SOL -> Exact and repeated identical applications. Different SOL policies on the same MODEL branch are ambiguous and require separate branches.

SOL wraps existing block replacements. Every attention call either executes SOL or delegates to the inherited owner with an explicit route/fallback receipt. A valid run may legitimately contain zero sparse calls.

Generic optimized_attention_override providers such as KJ Sage remain the dense owner for dense-evaluation warmup, dense leading layers and other dense-required rows when usable. Loader-level ImportError/OSError failures are request-locally demoted to original Comfy attention with telemetry; arbitrary CUDA/runtime compute failures are not swallowed.

Interoperability companions

The companion contracts are opt-in and are not automatically installed:

• VDN-H3-Plus #11 — grouped restricted-domain provider API v3 and lazy v2 square compatibility. It currently applies after the still-unreleased VDN audio-fidelity overlay #8, so it remains a pinned companion rather than a mainline release.
• Spectrum #104 — generic numerical-attention backend history and receipt coordination.
• Untwisting RoPE #9 — shape-preserving Q/K/V preprocessing contract.

Reviewed pins used by v0.1.0 validation:

Spectrum #104  9c682c07f4c5ea9de601cda234755a1561b59f59
Untwist #9     cf428e204f42354ce9a9582dd956906f75a52974
VDN #8         b6f0755c4172ec5c17386c56998f454e78b2a2d4
VDN #11        5b63dc670229d419a6350b64f7ceda609dbc8194
Flow v0.3.2    fe0ef8752b92081b5a85bc9b39ad8e2a7037d591
Diff-Aid       ba9d9efbcf7e64c755e068cb76547d8cc85481eb
Sana           2936c47637380842aaa4a4488fac5006cc542b70

VDN grouped attention

VDN retains ownership of its trained local-window geometry, global/anchor operations, learned softmax gate, learned linear complement and output projection.

Provider API v3 passes only:

requested local Q rows
VDN's unchanged restricted K rows
VDN's unchanged restricted V rows
leading global/prefix K/V sink count

to Sol-H3. No square query domain is constructed for a v3 provider. VDN's v2-only square_q / query_positions payload is created lazily only for a v2-only provider.

Production invariants:

vdn_requested_q_rows == vdn_kernel_q_rows
vdn_square_expanded_calls == 0

Representative native production stages:

| Stage | Rectangular SOL calls | Requested Q rows | Kernel Q rows | Square expansion | |---|---:|---:|---:|---:| | Native low | 1,584 | 3,744,000 | 3,744,000 | 0 | | Native high | 1,056 | 4,972,800 | 4,972,800 | 0 | | Later native high | 1,248 | 5,967,360 | 5,967,360 | 0 |

The historical v2 compatibility bridge expanded Q work by roughly 4.4–5.4x in the affected native stages. v3 removes that kernel-row expansion while leaving VDN's K/V domain semantics intact.

Global/anchor calls remain VDN-native. Masked Flex remains VDN-native; its existing grouped fallback can use v3.

Flow partitioned exact-prefix continuation

From Flow v0.3.11, partitioned continuation runs with the selected ComfyUI attention backend; Sol-H3 is an optional backend there, not a requirement. Flow's default progressive_uniform_source continuation evaluates reduced-grid low/probe and target-grid high stages as equal-grid partitions. With Sol selected, VDN-H3-Plus v1.5.9 routes their local query groups through Sol's own sparse selection, as in a non-partitioned call, and Sol records the stages in Spectrum history.

Flow mixed-grid external sequence

Flow's explicit API-2 contract:

api = 2
mode = dense_gate_no_linear
topology = mixed_grid_low_suffix

is validated against the current packed geometry rather than being forced dense by default. VDN retains the learned external-mode gate; its geometry-dependent linear complement remains disabled in this mode.

Representative final mixed-stage execution:

external_mixed_sol_calls           144
external_mixed_q_rows         6,270,480
external_mixed_kernel_q_rows  6,270,480
compatibility_fallbacks              {}

Unknown/stale/malformed external contracts delegate locally to inherited attention. Later target-grid stages resume native rectangular SOL.

Spectrum history and receipts

Spectrum preflights numerical backend policy and observes actual route receipts before retaining forecasting history. Sol-H3 provides a stable identity for the actual attention ownership chain; Spectrum remains provider-generic.

Production-only history issues found during validation were fixed narrowly:

• audited Diff-Aid activation wrappers are transparent only when Diff-Aid publishes its runtime declaration;
• Flow's marked layout wrapper and mixed-grid wrapper are recognized only when exact marker/closure/geometry invariants agree;
• progressive high stages consume Flow's explicit continuation contract so the one-evaluation trajectory warmup is not spuriously restarted;
• Flow's partitioned exact-prefix replacement is recognized for both the reduced-grid native carrier and the target-grid native carrier declared by target-band continuation (native_carrier_grid="target" with matching rows per frame);
• Flow's domain-uniform target-band streams are recognized per stream when each carries a canonical equal-grid contract and matching stream leaf;
• unknown/malformed wrappers remain opaque and force an actual call rather than weakening the gate.

Untwist preprocessing remains exactly once. Receipt/provider transitions still reset incompatible history. With the v0.1.3 default dense_evaluations=1, backend history begins dense and the later dense -> sol route change is intentionally treated as a real history boundary. With the explicit dense_evaluations=0 speed mode, history starts directly in phase=sol and that initial transition is absent.

SOL kernel contract

The packaged cute_sm120 implementation is the supported SM120/SM121 path and supports rectangular BTHD attention:

Q:   [B, Tq,  H, 128]
K/V: [B, Tkv, H, 128]

Q owns query launch geometry, Q pooling/tails, output and LSE. K/V own centroids, route groups, exact sink blocks and approximate masses. CuTe compile descriptors and arithmetic-cache keys include Q/K/V geometry and layout.

The bridge preserves BF16 and native H3 scaling. sink_start=0 keeps the leading prefix/global K/V exact with Sana's outward 64-row block rounding. An all-selected call is checked against independent BF16 SDPA; failed arithmetic calibration is fatal.

Kernel contract identity:

sana-sol-engine-sol-attn-64-rect-sm120-query-origin-v5

Zero-copy BTHD bridge

Pinned Comfy MiniMax-H3 produces BTHD views from [T,3*H*D] -> split -> view[T,H,D] -> transpose(0,1).unsqueeze(0). v0.1.0 preserves suitable innermost-contiguous strided views instead of forcing transpose(...).contiguous() copies.

The arithmetic gate is stride-sensitive, so different Q/K/V layouts cannot reuse a calibration result accidentally.

The isolated real-SM120 A/B used identical Q/K/V values and the exact mixed production stride:

Q/V stride [7168, 21504, 128, 1]
K stride   [7168,  7168, 128, 1]
shape      [1, 43545, 56, 128]

Seven-run medians:

| Path | CUDA median | Host-wall median | |---|---:|---:| | strided zero-copy | 46.768 ms | 42.338 ms | | pre-contiguous kernel | 46.941 ms | 42.376 ms | | old copy + kernel | 47.727 ms | 43.136 ms |

Interpretation:

• strided CuTe execution is effectively parity with pre-contiguous CuTe (-0.37% CUDA / -0.09% wall);
• the old copies add about 0.786 ms CUDA / 0.761 ms host wall per representative mixed call;
• the zero-copy path is about 2.01% faster than old copy+kernel in CUDA timing and 1.85% faster than old copy+kernel in host-wall timing for this isolated call;
• the old bridge materialized 1,248,522,240 bytes per mixed call. Across 144 representative mixed calls, zero-copy avoids about 167.44 GiB of redundant Q/V materialization and about 0.11 s of direct copy overhead.

This is intentionally a micro-optimization claim. It does not explain multi-second whole-workflow variance.

Performance evidence

Exact Runtime

Historical matched production A/B:

| Exact Runtime | Sampler | End-to-end | Peak VRAM | |---|---:|---:|---:| | off | 263.56 s | 312.57 s | 17.18 GB | | on | 247.30 s | 298.69 s | 17.18 GB |

This is Exact-only evidence, not a SOL speed claim.

Historical v0.1.2 SOL-first A/B

The v0.1.2 dense_evaluations=0 run (metrics_00323) and the no-SOL control (metrics_00322) both executed 40 logical / 25 actual / 15 forecast calls. That removes the old NFE-topology confound:

SOL, dense_evaluations=0:  332.56 s sampler / 380.57 s end-to-end
SOL disabled:              374.84 s sampler / 420.81 s end-to-end

In this controlled hot pair, SOL reduced H3 sampler wall by 42.28 s (11.3%) and end-to-end wall by 40.24 s (9.6%). Arithmetic-gate and general hot-run variance still exist, so this remains deployment-specific evidence rather than a universal percentage. It is also not evidence that dense_evaluations=0 is quality-equivalent: the later controlled startup comparison is why v0.1.3 restores the conservative default.

Historical SOL whole-workflow timing

A pre-zero-copy same-process hot SOL run with the old 14/4 Spectrum schedule measured:

end-to-end prompt       274.87 s
H3ContinuumSamplerV34   229.13 s

That run was faster than the SOL-bypassed control (287.51 s end-to-end / 240.55 s sampler) despite executing one extra actual transformer NFE, but this is not a clean SOL speed percentage because routing/content/cache state and NFE topology differed.

Subsequent zero-copy workflow runs varied materially (287.29/239.10 s and 298.59/247.63 s end-to-end/sampler) while preserving the old 14/4 schedule. Arithmetic-gate/caching cost also varied. Therefore the isolated kernel/layout A/B remains the authoritative zero-copy result.

Installation

Set your ComfyUI root once and install in the same Python environment as ComfyUI:

export COMFYUI_ROOT=/path/to/ComfyUI
cd "$COMFYUI_ROOT/custom_nodes"
git clone https://github.com/xmarre/ComfyUI-Sol-H3.git
cd ComfyUI-Sol-H3
python -m pip install -r requirements.txt

For an existing checkout:

export COMFYUI_ROOT=/path/to/ComfyUI
cd "$COMFYUI_ROOT/custom_nodes/ComfyUI-Sol-H3"
git pull
python -m pip install -r requirements.txt

On Linux/WSL2, dependencies include PyTorch, Triton >=3.6,<4, NVIDIA CUTLASS DSL with the CUDA 13 extra, CUDA Python and Apache TVM FFI. No Sana checkout, SOL_ROOT, special PYTHONPATH, runtime source download or linker override is required. The custom-kernel runtime dependencies are intentionally not installed on native Windows.

The validated and supported SOL/Exact custom-kernel target is Linux/WSL2 on SM120 and SM121 (SM121 selects the cute_sm120 kernel). Native Windows cannot currently execute the required NVIDIA CuTe DSL backend; SOL falls back locally to inherited dense attention and Exact Runtime delegates to native H3. See Native Windows status.

SageAttention on Blackwell

SageAttention is optional and is not installed by Sol-H3. On SM120 use KJNodes auto, not sageattn_qk_int8_pv_fp16_triton; upstream SageAttention 2 dispatches SM120 away from the unusable Triton path.

If Sage fails with a binary ABI error such as GLIBCXX_3.4.32 not found, rebuild the official package against the same ComfyUI Python/compiler/CUDA toolkit. Do not repair it with LD_LIBRARY_PATH, LD_PRELOAD or runtime preloading. See SageAttention installation and repair.

Validation and diagnostics

From the node checkout:

python -m pip install -e '.[test]'
python -m pip check
python -m ruff check .
python -m pytest -q

GPU validation and production telemetry are documented in VALIDATION. The v0.1.3 trajectory-warmup decision, historical timing evidence and startup-quality boundary are documented in DENSE_EVALUATIONS. Rectangular ownership, zero-copy layout behavior and approximation boundaries are documented in RECTANGULAR. Source/interoperability provenance is in AUDIT. Native-Windows support, fallback behavior and troubleshooting are in WINDOWS.

Useful counters include:

sampler_logical_calls
transformer_actual_nfe
spectrum_forecast_calls
sol_backend
sol_source_tree_verified
sol_eligible_calls
sparse_calls
external_mixed_sol_calls
external_mixed_q_rows
external_mixed_kernel_q_rows
vdn_local_sol_calls
vdn_rectangular_sol_calls
vdn_requested_q_rows
vdn_kernel_q_rows
vdn_square_expanded_calls
materialized_qkv_bytes
bthd_strides
dense_provider_failures
numerical_backend_transitions
compatibility_fallbacks
streamed_blocks
streamed_q_rows
streamed_vdn_projection_calls
streamed_vdn_projection_rows
streamed_skips
qkv_storage_bytes

Set SOL_H3_MEMORY_PROFILE=1 when launching ComfyUI for opt-in allocated/reserved memory attribution on real sampler requests. The memory procedure explains baseline matching, first-use/warmed measurements and remaining acceptance.

The legacy dense_warmup telemetry value counts attention calls kept dense by either dense_evaluations or dense_layers; it is not a count of full dense denoiser evaluations. Diagnose trajectory warmup with the configured dense_evaluations, backend-history phase, numerical_backend_transitions, and actual/forecast topology.

A successful run with zero sparse calls is valid execution telemetry but is not evidence of SOL acceleration.

Partitioned conditioning-key measure

PARTITIONED_SINK_MEASURE_API = 1 permits dense partitioned requests to use a key-measure range (0, end) that covers the global conditioning sink and extends into video keys. Partial sink overlap and sink-covering sparse requests are rejected. Range and measure are included in weighted-dense validation and completion identity; receipt acceptance remains request/evaluation owned.

Paired Flow/VDN can use this for the experimental target_query_sink_measure selector. This capability does not change ordinary Sol weighting or establish that a rendered continuation boundary improves. Existing requests retain their range and numerical policy.

Release notes and coordinated release set

See CHANGELOG.md and RELEASE_NOTES.md for per-version scope, validation evidence and historical release notes.

Sol-H3 is released together with the other H3 components:

| Component | Release | Included PRs | | --- | --- | --- | | Flow-Aligned Regenerate | v0.3.11 | #97 | | Sol-H3 | v0.1.10 | #40 | | VDN-H3-Plus | v1.5.9 | #39, #40 | | H3 Continuum-Plus | v3.4.6 | unchanged | | Latent Upscaler-Plus | v0.2.2 | unchanged |

Spectrum MiniMax H3 v0.2.28 is the unchanged companion. Separate Keyless, audio-training and rejected decoded-geometry experiments are outside this release set.

The tested Core adapter repair is ComfyUI #16783. For INT8 fused MLP runtime adapters, retain that ComfyUI Patcher PR overlay until the repair is available upstream. The independent Core #16720 optimization is not included in this release set.

sol_h3/sol_manifest.json records original upstream hashes and packaged hashes. tools/rectangular_sm120.patch records the functional rectangular changes after import adaptation.

GPL-3.0-or-later; see LICENSE and NOTICE.

Arithmetic-gate reduction acceleration (experimental)

On CUDA with Triton available, Sol now computes its full-query, full-key arithmetic-qualification statistics with a fused, tiled reduction and a small FP64 partial buffer. This does not skip kernel numerical qualification, change Sol's sparse attention output or change VDN/Flow projection arithmetic. It replaces thousands of individual PyTorch metric-reduction launches when an eligible BF16 3-D/4-D result is checked; other inputs keep the reference implementation. Only metric aggregation order may differ at floating-point roundoff levels. First-use kernel compilation and actual GPU throughput must be measured on SM120; no speedup has been established by CPU CI alone. A standalone, model-free GPU acceptance benchmark is available via python tools/benchmark_gate_metrics.py; it compares exact statistics and time against the preserved PyTorch reference at production-like query/head shapes without starting a video generation. ComfyUI Patcher installation needs no additional environment variables or node setting.

VDN zero-copy grouped Q ownership (draft)

Sol's native v4 and physical partitioned attention providers advertise a read-only-Q marker to VDN. VDN may therefore pass slices for grouped contiguous query intervals instead of materializing extra index_select copies and indexed output scatters. Provider behavior, Q/K/V numerical values, query position maps, key/value gather, and dense fallback remain unchanged. Unknown third-party providers are not trusted and retain the old isolated Q-gather behavior. CPU CI checks the marker, while real RTX PRO 6000 peak-memory and sampling latency acceptance remains required before release.