bridge.utils.gdn_utils#

Checks for running GatedDeltaNet (GDN) layers on cuDNN’s kernels.

model.gdn_kernel_backend="transformer_engine" runs GatedDeltaNet through Transformer Engine’s GatedDeltaNetAttention on the cuDNN frontend kernels in cudnn.linear_attention.

Module Contents#

Functions#

_release_tuple

Parse version the way cuDNN frontend 1.29 compares CuTe DSL versions.

_version_str

Render a release tuple such as (4, 7, 0) as "4.7.0".

cudnn_gdn_stack_issues

List why gdn_kernel_backend="transformer_engine" would not run on cuDNN’s fast GatedDeltaNet kernels.

te_gdn_fp8_issues

List why Transformer Engine’s GatedDeltaNetAttention would fail under the model’s FP8 or FP4 autocast.

is_te_gdn_available

Return Megatron-Core’s own check that Transformer Engine provides GatedDeltaNetAttention.

probe_cudnn_gdn_stack_issues

Run cudnn_gdn_stack_issues against this environment without importing cudnn or cutlass.

validate_cudnn_gdn_stack

Warn when gdn_kernel_backend="transformer_engine" cannot reach cuDNN’s fast GatedDeltaNet kernels.

Data#

TRANSFORMER_ENGINE_GDN_MIN_VERSION

_TRANSFORMER_ENGINE_GDN_FP8_RAISING_RELEASE

TRANSFORMER_ENGINE_GDN_FP8_VERSION

CUDNN_FRONTEND_GDN_MIN_VERSION

CUDNN_FRONTEND_GDN_NAN_FREE_VERSION

CUTLASS_DSL_GDN_MIN_VERSION

_LEADING_INTEGER

API#

bridge.utils.gdn_utils.TRANSFORMER_ENGINE_GDN_MIN_VERSION#

(2, 19)

bridge.utils.gdn_utils._TRANSFORMER_ENGINE_GDN_FP8_RAISING_RELEASE#

(2, 19)

bridge.utils.gdn_utils.TRANSFORMER_ENGINE_GDN_FP8_VERSION#

(2, 20, 2)

bridge.utils.gdn_utils.CUDNN_FRONTEND_GDN_MIN_VERSION#

(1, 27, 0)

bridge.utils.gdn_utils.CUDNN_FRONTEND_GDN_NAN_FREE_VERSION#

(1, 29, 0)

bridge.utils.gdn_utils.CUTLASS_DSL_GDN_MIN_VERSION#

(4, 7, 0)

bridge.utils.gdn_utils._LEADING_INTEGER#

‘compile(…)’

bridge.utils.gdn_utils._release_tuple(version: str) → tuple[int, ...]#

Parse version the way cuDNN frontend 1.29 compares CuTe DSL versions.

Keeps the leading integer of each of the first three dot components, drops a local label and zero-pads short versions (“4.6” -> (4, 6, 0)). Returns () when nothing parses.

bridge.utils.gdn_utils._version_str(version: tuple[int, ...]) → str#

Render a release tuple such as (4, 7, 0) as "4.7.0".

bridge.utils.gdn_utils.cudnn_gdn_stack_issues(
*,
have_te_gdn: bool,
cudnn_frontend_version: str | None,
cutlass_importable: bool,
cutlass_dsl: tuple[str, str] | None,
) → list[str]#

List why gdn_kernel_backend="transformer_engine" would not run on cuDNN’s fast GatedDeltaNet kernels.

Parameters:

  • have_te_gdn – Megatron-Core’s HAVE_TE_GDN: Transformer Engine provides GatedDeltaNetAttention.

  • cudnn_frontend_version – Installed nvidia-cudnn-frontend version, or None.

  • cutlass_importable – Whether the CuTe DSL cutlass package resolves.

  • cutlass_dsl – (distribution, version) of the first installed of nvidia-cutlass-dsl and nvidia-cutlass-dsl-internal (what cuDNN frontend’s cutedsl_state() reads), or None.

Returns:

One message per gap; empty when the installed packages pass cuDNN frontend 1.29’s FROST support gate (cutedsl_state / cutedsl_too_old). Two cases still fall back to the slower cuTile engine without a message: a GPU outside SM100-SM103 and SM107 (checking it would initialize CUDA), and a cutlass package that does not match the nvidia-cutlass-dsl metadata, such as a PYTHONPATH copy of the wheel without its dsl_packages directory.

bridge.utils.gdn_utils.te_gdn_fp8_issues(
*,
transformer_engine_version: str | None,
fp8: bool,
fp4: bool,
) → list[str]#

List why Transformer Engine’s GatedDeltaNetAttention would fail under the model’s FP8 or FP4 autocast.

Transformer Engine 2.19 raises “GatedDeltaNetAttention does not support FP8 autocast or FP8 calibration.” whenever GatedDeltaNet runs under Transformer Engine’s FP8 autocast, which NVFP4 also uses. With model.fp8 Megatron-Core runs the layers under it, so training fails in the first forward pass. With only model.fp4 it fails where Megatron-Core’s own transformer and hybrid blocks, CUDA-graph capture or EP-overlap schedule enter that autocast; Bridge’s Qwen3-VL block does not. Transformer Engine 2.20.2 and later ignore FP8 autocast in GatedDeltaNet. Only the 2.19 family is flagged; releases without GatedDeltaNetAttention are reported by cudnn_gdn_stack_issues.

Parameters:

  • transformer_engine_version – Installed transformer-engine version, or None.

  • fp8 – Whether the model config sets fp8.

  • fp4 – Whether the model config sets fp4.

Returns:

One message for Transformer Engine 2.19 with FP8 or FP4; empty otherwise, including unparsable versions.

bridge.utils.gdn_utils.is_te_gdn_available() → bool#

Return Megatron-Core’s own check that Transformer Engine provides GatedDeltaNetAttention.

Returns:

megatron.core.extensions.transformer_engine.HAVE_TE_GDN, or False when Megatron-Core does not define it.

bridge.utils.gdn_utils.probe_cudnn_gdn_stack_issues() → list[str]#

Run cudnn_gdn_stack_issues against this environment without importing cudnn or cutlass.

Returns:

The issues cudnn_gdn_stack_issues reports for the installed packages; empty when the stack is complete.

bridge.utils.gdn_utils.validate_cudnn_gdn_stack(model_config: object) → None#

Warn when gdn_kernel_backend="transformer_engine" cannot reach cuDNN’s fast GatedDeltaNet kernels.

ConfigContainer.validate() calls this on the final model config, after every override. Warn-only: the backend is never changed, so a recipe builds the same config in every environment, and the message names the fix and the FLA override. Setups that cannot run at all also fail later in Megatron-Core or Transformer Engine; the silent cases are the cuTile fallback (slower than FLA) and cuDNN frontend releases before 1.29.0 (GatedDeltaNet NaN). With fp8 or fp4 set it also flags Transformer Engine 2.19, whose GatedDeltaNetAttention raises under FP8 autocast (te_gdn_fp8_issues), and the install hint then asks for Transformer Engine 2.20.2. The check reads installed package metadata only; cudnn_gdn_stack_issues lists what it cannot see.

Parameters:

model_config – The model provider or config; read for gdn_kernel_backend, fp8 and fp4.