feat(timm_mobilenetv4): add the timm MobileNetV4 image-classification family (1276)

## Implementation

Almost the whole layout comes out of the checkpoint. The three block kinds
carry disjoint leaf names, so the kind is read rather than tabulated:

| block kind | identifying leaf |
| --- | --- |
| universal inverted bottleneck | `pw_exp` |
| edge residual | `conv_exp` |
| plain convolution | `conv` |

Kernel sizes, channel counts and which of the optional depthwise convolutions
are present all follow from weight shapes. A block carrying anything outside
the supported set - squeeze-excite or layer scale, which other MobileNetV4
variants use - is refused, so a silently partial build cannot look like a
working one.

Three things are not in a safetensors checkpoint and are stated explicitly.
Each was measured against the reference across all four widths:

| value | rule | measured over |
| --- | --- | --- |
| stride | 2 on the first block of stages 0-3, else 1 | 4 widths; stem 2 gives the factor of 32 the published input sizes divide by |
| activation | ReLU throughout, but not after `dw_start`, `pw_proj` or an edge residual's second norm | 4 widths |
| residual | plain convolutions never add their input back; the others do when stride is 1 and channels match | 6 widths, 136 blocks |

Author: zhenshanx-nv

apps/benchmark/performance/release.yaml

@@ -49,6 +49,15 @@ excluded_profiles:
       performance baseline runs Ultralytics, which cannot load a legacy YOLOv5
       archive: those archives pickle classes from the standalone yolov5
       repository, which is not a dependency here.
+  - model: mobilenetv4-conv-small
+    reason: &mobilenetv4_performance_exclusion >-
+      Functional and timm reference-parity qualification is present for every
+      claimed MobileNetV4 width, but the release-performance workload and
+      receipt were collected only for the 050 width.
+  - model: mobilenetv4-conv-medium
+    reason: *mobilenetv4_performance_exclusion
+  - model: mobilenetv4-conv-large
+    reason: *mobilenetv4_performance_exclusion
   - model: dpn92-mx-in1k
     reason: >-
       Functional and timm reference-parity qualification is present for every
@@ -1376,6 +1385,19 @@ entries:
       reference_backend: hf_transformers
       timing_scope: task-model-call-wall
       input_preparation_included: false
+  - id: timm_mobilenetv4.classify
+    family: timm_mobilenetv4
+    operation: classify
+    model: mobilenetv4-conv-small-050
+    workload:
+      testcase: mobilenetv4-conv-small-050
+    baseline:
+      runner: task-reference
+      adapter: hf-transformers-vision
+      mode: hf-eager
+      reference_backend: hf_transformers
+      timing_scope: task-model-call-wall
+      input_preparation_included: false
   - id: timm_mobilenetv3.classify
     family: timm_mobilenetv3
     operation: classify

families/timm_mobilenetv4/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""timm MobileNetV4 model family."""

families/timm_mobilenetv4/config.py

@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Read the timm MobileNetV4 fields used by this family."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class ModelConfig:
+    architecture: str
+    raw: dict
+
+    @staticmethod
+    def from_json(text: str) -> "ModelConfig":
+        raw = json.loads(text)
+        architecture = raw.get("architecture")
+        if not isinstance(architecture, str) or not architecture:
+            raise ValueError("timm MobileNetV4 config requires architecture")
+        return ModelConfig(architecture=architecture, raw=raw)
+
+    @classmethod
+    def from_dir(cls, model_dir: str | Path) -> "ModelConfig":
+        config_path = Path(model_dir) / "config.json"
+        if not config_path.is_file():
+            raise FileNotFoundError(f"missing model config: {config_path}")
+        return cls.from_json(config_path.read_text(encoding="utf-8"))

families/timm_mobilenetv4/graph/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Family-owned TensorRT model construction components."""

families/timm_mobilenetv4/graph/model.py

@@ -0,0 +1,179 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""TensorRT graph builders for timm MobileNetV4 classifiers.
+
+MobileNetV4 adds three things to the plain convolutional op set: the hard
+activations (hard-swish and hard-sigmoid), depthwise separable convolutions,
+and a squeeze-and-excite gate.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import tensorrt as trt
+
+
+def add_conv2d(
+    network,
+    inp,
+    weight: np.ndarray,
+    bias: np.ndarray | None,
+    out_channels: int,
+    kernel_size: tuple[int, int],
+    stride: tuple[int, int] = (1, 1),
+    padding: tuple[int, int] = (0, 0),
+    groups: int = 1,
+    *,
+    dtype: np.dtype,
+):
+    """2D convolution wrapper.
+
+    Input: [N, C_in, H, W]
+    Weight: [C_out, C_in/groups, kH, kW]
+    Output: [N, C_out, H', W']
+
+    Convolution bias is present only in the squeeze-excite and classifier heads.
+    """
+    conv_w = trt.Weights(np.ascontiguousarray(weight, dtype=dtype))
+    conv_b = trt.Weights()
+    if bias is not None:
+        conv_b = trt.Weights(np.ascontiguousarray(bias, dtype=dtype))
+
+    conv = network.add_convolution_nd(
+        inp,
+        num_output_maps=out_channels,
+        kernel_shape=kernel_size,
+        kernel=conv_w,
+        bias=conv_b,
+    )
+    conv.stride_nd = stride
+    conv.padding_nd = padding
+    conv.num_groups = groups
+    return conv.get_output(0)
+
+
+def add_batch_norm(
+    network,
+    x,
+    gamma: np.ndarray,
+    beta: np.ndarray,
+    running_mean: np.ndarray,
+    running_var: np.ndarray,
+    eps: float,
+    *,
+    dtype: np.dtype,
+):
+    """Fold inference-time batch norm into a single per-channel scale+shift.
+
+    y = (x - mean) / sqrt(var + eps) * gamma + beta
+      = x * scale + shift
+    Folding avoids emitting a normalization layer whose statistics are
+    constant at inference time.
+    """
+    scale = (gamma / np.sqrt(running_var + eps)).astype(np.float32)
+    shift = (beta - running_mean * scale).astype(np.float32)
+    layer = network.add_scale(
+        x,
+        trt.ScaleMode.CHANNEL,
+        shift=trt.Weights(np.ascontiguousarray(shift, dtype=dtype)),
+        scale=trt.Weights(np.ascontiguousarray(scale, dtype=dtype)),
+    )
+    return layer.get_output(0)
+
+
+def add_relu(network, x):
+    return network.add_activation(x, trt.ActivationType.RELU).get_output(0)
+
+
+def add_global_avg_pool(network, x, spatial: tuple[int, int]):
+    pool = network.add_pooling_nd(x, trt.PoolingType.AVERAGE, spatial)
+    pool.stride_nd = (1, 1)
+    return pool.get_output(0)
+
+
+def add_sum(network, a, b):
+    return network.add_elementwise(a, b, trt.ElementWiseOperation.SUM).get_output(0)
+
+
+def add_fc(
+    network,
+    x,
+    in_features: int,
+    out_features: int,
+    weight: np.ndarray,
+    bias: np.ndarray,
+    *,
+    dtype: np.dtype,
+):
+    """Final classifier: flatten the pooled feature map, then y = x @ W^T + b."""
+    flat = network.add_shuffle(x)
+    flat.reshape_dims = (1, in_features)
+    flat_out = flat.get_output(0)
+
+    # timm stores fc.weight as (out, in); TensorRT wants the (in, out) operand.
+    w = np.ascontiguousarray(weight.T, dtype=dtype)
+    w_const = network.add_constant((in_features, out_features), trt.Weights(w)).get_output(0)
+    mm = network.add_matrix_multiply(
+        flat_out,
+        trt.MatrixOperation.NONE,
+        w_const,
+        trt.MatrixOperation.NONE,
+    ).get_output(0)
+
+    b = np.ascontiguousarray(bias.reshape(1, out_features), dtype=dtype)
+    b_const = network.add_constant((1, out_features), trt.Weights(b)).get_output(0)
+    return network.add_elementwise(mm, b_const, trt.ElementWiseOperation.SUM).get_output(0)
+
+
+def add_hard_sigmoid(network, x, *, dtype: np.dtype):
+    """hard-sigmoid: clamp(x / 6 + 0.5, 0, 1), the timm/PyTorch definition."""
+    scaled = network.add_scale(
+        x,
+        trt.ScaleMode.UNIFORM,
+        shift=trt.Weights(np.array([0.5], dtype=dtype)),
+        scale=trt.Weights(np.array([1.0 / 6.0], dtype=dtype)),
+    ).get_output(0)
+    clipped = network.add_activation(scaled, trt.ActivationType.CLIP)
+    clipped.alpha = 0.0
+    clipped.beta = 1.0
+    return clipped.get_output(0)
+
+
+def add_hard_swish(network, x, *, dtype: np.dtype):
+    """hard-swish: x * hard_sigmoid(x)."""
+    gate = add_hard_sigmoid(network, x, dtype=dtype)
+    return network.add_elementwise(x, gate, trt.ElementWiseOperation.PROD).get_output(0)
+
+
+def add_squeeze_excite(
+    network,
+    x,
+    spatial: tuple[int, int],
+    reduce_w: np.ndarray,
+    reduce_b: np.ndarray,
+    expand_w: np.ndarray,
+    expand_b: np.ndarray,
+    *,
+    dtype: np.dtype,
+):
+    """Squeeze-and-excite gate.
+
+    Mean over the spatial dims, a 1x1 reduce convolution with ReLU, a 1x1
+    expand convolution, then a hard-sigmoid gate multiplied back into x.
+    timm applies the gate to the full-resolution tensor, so the pooled branch
+    broadcasts over height and width.
+    """
+    pooled = network.add_pooling_nd(x, trt.PoolingType.AVERAGE, spatial)
+    pooled.stride_nd = (1, 1)
+    squeezed = pooled.get_output(0)
+
+    reduced = add_conv2d(
+        network, squeezed, reduce_w, reduce_b, int(reduce_w.shape[0]), (1, 1), dtype=dtype
+    )
+    reduced = add_relu(network, reduced)
+    expanded = add_conv2d(
+        network, reduced, expand_w, expand_b, int(expand_w.shape[0]), (1, 1), dtype=dtype
+    )
+    gate = add_hard_sigmoid(network, expanded, dtype=dtype)
+    return network.add_elementwise(x, gate, trt.ElementWiseOperation.PROD).get_output(0)