netcl 0.3.0__tar.gz → 0.3.2__tar.gz

{netcl-0.3.0/netcl.egg-info → netcl-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: netcl
-Version: 0.3.0
+Version: 0.3.2
 Summary: PyOpenCL-based deep learning playground with autograd, kernels, and high-level APIs.
 Author: netcl contributors
 License: MIT
@@ -148,3 +148,4 @@ model2 = load_model("model_artifact")
 ## Notes
 - Mixed precision is experimental; it is disabled on the CPU backend.
 - Conv2d algorithms can be tuned via env flags like `NETCL_CONV_AUTOTUNE=1`.
+- 1x1 convolutions (stride 1, no padding) are timed once per shape class against the general conv path and run as batched GEMMs where that is faster (`NETCL_CONV_POINTWISE=auto|1|0`); the decision is cached per device in the autotune cache. Depthwise convolutions with filters up to 7x7 and stride 1/2 use local-memory tiled kernels (`NETCL_DWCONV_ALGO=local|naive|tile`). `NETCL_AUTOTUNE=0` disables all measurements and keeps the previous conv paths.

{netcl-0.3.0 → netcl-0.3.2}/README.md

@@ -49,4 +49,4 @@ trainer.fit(loader, epochs=1, loss_fn=functional.cross_entropy)
 
 ## Docs
 - `README_PACKAGE.md` for the package summary used on PyPI.
-- `wiki/README.md` for a compact API index and examples.
+- `web-wiki/content/` for the documentation (API reference, concepts, tutorials); serve it with `pip install -r web-wiki/requirements.txt && python web-wiki/app.py`.

{netcl-0.3.0 → netcl-0.3.2}/README_PACKAGE.md

@@ -134,3 +134,4 @@ model2 = load_model("model_artifact")
 ## Notes
 - Mixed precision is experimental; it is disabled on the CPU backend.
 - Conv2d algorithms can be tuned via env flags like `NETCL_CONV_AUTOTUNE=1`.
+- 1x1 convolutions (stride 1, no padding) are timed once per shape class against the general conv path and run as batched GEMMs where that is faster (`NETCL_CONV_POINTWISE=auto|1|0`); the decision is cached per device in the autotune cache. Depthwise convolutions with filters up to 7x7 and stride 1/2 use local-memory tiled kernels (`NETCL_DWCONV_ALGO=local|naive|tile`). `NETCL_AUTOTUNE=0` disables all measurements and keeps the previous conv paths.

{netcl-0.3.0 → netcl-0.3.2}/netcl/autograd/ops.py

@@ -138,6 +138,47 @@ def _strides_for_dims(dims):
     return strides_for_dims(dims)
 
 
+_REDUCE_TO_SHAPE_WG_SRC = r"""
+// One work-group (256) per output element o of the target shape t0..t3; it sums the gradient over the
+// broadcast axes (extents r0..r3, 1 for kept axes). The reduced index runs fastest along the last axis, so
+// neighbouring work-items read neighbouring memory.
+__kernel __attribute__((reqd_work_group_size(256, 1, 1)))
+void reduce_to_shape_wg(__global const float* grad, __global float* out,
+                        const int t0, const int t1, const int t2, const int t3,
+                        const int r0, const int r1, const int r2, const int r3,
+                        const int s0, const int s1, const int s2, const int s3,
+                        const int R)
+{
+    const int o = get_group_id(0);
+    const int lid = get_local_id(0);
+    int tmp = o;
+    const int c3 = tmp % t3; tmp /= t3;
+    const int c2 = tmp % t2; tmp /= t2;
+    const int c1 = tmp % t1; tmp /= t1;
+    const int c0 = tmp;
+    const size_t base = (size_t)(r0 == 1 ? c0 : 0) * s0 + (size_t)(r1 == 1 ? c1 : 0) * s1
+                      + (size_t)(r2 == 1 ? c2 : 0) * s2 + (size_t)(r3 == 1 ? c3 : 0) * s3;
+    float acc = 0.0f;
+    for (int r = lid; r < R; r += 256) {
+        int q = r;
+        const int d3 = q % r3; q /= r3;
+        const int d2 = q % r2; q /= r2;
+        const int d1 = q % r1; q /= r1;
+        const int d0 = q;
+        acc += grad[base + (size_t)d0 * s0 + (size_t)d1 * s1 + (size_t)d2 * s2 + (size_t)d3 * s3];
+    }
+    __local float red[256];
+    red[lid] = acc;
+    barrier(CLK_LOCAL_MEM_FENCE);
+    for (int s = 128; s > 0; s >>= 1) {
+        if (lid < s) red[lid] += red[lid + s];
+        barrier(CLK_LOCAL_MEM_FENCE);
+    }
+    if (lid == 0) out[o] = red[0];
+}
+"""
+
+
 def _reduce_to_shape(grad: Tensor, target_shape: Tuple[int, ...]) -> Tensor:
     target_shape = tuple(target_shape)
     if grad.shape == target_shape:
@@ -214,6 +255,22 @@ def _reduce_to_shape(grad: Tensor, target_shape: Tuple[int, ...]) -> Tensor:
         _REDUCE_TO_SHAPE_CACHE[cache_key] = cl.Program(ctx, src).build().reduce_to_shape
 
     total_out = int(np.prod(target_shape))
+    reduced = 1
+    for gd, td in zip(gdims, tdims):
+        if td == 1:
+            reduced *= gd
+    if reduced >= 256:
+        # many elements per output (e.g. a broadcast scalar or bias): one work-group per output element with a
+        # parallel tree reduction instead of one thread summing everything serially
+        wg_key = (ctx.int_ptr, "reduce_to_shape_wg", grad.dtype)
+        kern = _REDUCE_TO_SHAPE_CACHE.get(wg_key)
+        if kern is None:
+            kern = _REDUCE_TO_SHAPE_CACHE[wg_key] = cl.Program(ctx, _REDUCE_TO_SHAPE_WG_SRC).build().reduce_to_shape_wg
+        rd = [gd if td == 1 else 1 for gd, td in zip(gdims, tdims)]
+        kern(grad.queue, (total_out * 256,), (256,), grad.buffer, out.buffer,
+             *[np.int32(v) for v in tdims], *[np.int32(v) for v in rd], *[np.int32(v) for v in gstrides],
+             np.int32(reduced))
+        return out
     gsize = (int(np.ceil(total_out / 256.0)) * 256,)
     mf = cl.mem_flags
     gdims_buf = cl.Buffer(ctx, mf.READ_ONLY | mf.COPY_HOST_PTR, hostbuf=np.int32(gdims))
@@ -649,15 +706,14 @@ def hard_sigmoid(x: Node, tape=None) -> Node:
 def hard_swish(x: Node, tape=None) -> Node:
     def grad_fn(grad_out: Tensor):
         # forward is x * hard_sigmoid(x) with hard_sigmoid(x) = clip(0.2x + 0.5, 0, 1)
-        # d/dx = hard_sigmoid(x) + 0.2 * x * [-2.5 < x < 2.5]
-        gate = elementwise_binary(x.value, x.value, expression="fmax(0.0f, fmin(1.0f, 0.2f * v0 + 0.5f))")
-        mask = elementwise_binary(x.value, x.value, expression="(v0 > -2.5f && v0 < 2.5f ? 0.2f : 0.0f)")
-        x_in = elementwise_binary(x.value, mask, expression="MUL(v0, v1)")
-        deriv = elementwise_binary(gate, x_in, expression="ADD(v0, v1)")
-        grad = elementwise_binary(grad_out, deriv, expression="MUL(v0, v1)")
+        # d/dx = hard_sigmoid(x) + 0.2 * x * [-2.5 < x < 2.5]; one fused kernel (v0 = grad_out, v1 = x)
+        grad = elementwise_binary(
+            grad_out, x.value,
+            expression="v0 * (fmax(0.0f, fmin(1.0f, 0.2f * v1 + 0.5f)) + ((v1 > -2.5f && v1 < 2.5f) ? 0.2f * v1 : 0.0f))",
+        )
         return [grad]
 
-    return apply_op(lambda t: hard_swish_op(t), grad_fn, x, tape=tape)
+    return apply_op(lambda t: hard_swish_op(t), grad_fn, x, tape=tape, op_name="hard_swish")
 
 
 def clamp(x: Node, min_val: float, max_val: float, tape=None) -> Node:

{netcl-0.3.0 → netcl-0.3.2}/netcl/ops/conv2d.py

@@ -850,6 +850,17 @@ def conv2d(
         from netcl.ops.conv2d_dilated import conv2d_dilated
 
         return conv2d_dilated(x, w, bias=bias, stride=stride, pad=pad, dilation=dilation, out=out, pool=pool)
+    # 1x1 / stride 1 convolutions are GEMMs: measured choice between the dedicated pointwise kernels and the
+    # path below (see netcl.ops.conv2d_pointwise). An explicitly requested algorithm is always honoured.
+    if not use_im2col and algo in (None, "auto", "optimized") and strategy is None:
+        from netcl.ops.conv2d_pointwise import pointwise_eligible, dispatch_forward
+
+        if pointwise_eligible(x, w, stride=stride, pad=pad, dilation=dilation, groups=groups):
+            return dispatch_forward(
+                x, w, bias, out, pool, _ENV_CONV_FUSE_RELU if fuse_relu is None else bool(fuse_relu),
+                legacy=lambda: conv2d(x, w, bias=bias, out=out, pool=pool, stride=stride, pad=pad,
+                                      use_im2col=use_im2col, algo=algo, strategy=strategy, fuse_relu=fuse_relu),
+            )
     if backend == "cpu":
         return conv2d_cpu(x, w, bias=bias, stride=stride, pad=pad)
     if cl is None or np is None:
@@ -1538,6 +1549,15 @@ def conv2d_backward(
             x, w, grad_out, bias=bias, stride=stride, pad=pad, dilation=dilation,
             pool=pool, need_grad_x=need_grad_x,
         )
+    if not use_im2col and algo in (None, "auto", "optimized"):
+        from netcl.ops.conv2d_pointwise import pointwise_eligible, dispatch_backward
+
+        if pointwise_eligible(x, w, stride=stride, pad=pad, dilation=dilation, groups=groups):
+            return dispatch_backward(
+                x, w, grad_out, bias, pool, need_grad_x,
+                legacy=lambda: conv2d_backward(x, w, grad_out, bias=bias, pool=pool, stride=stride, pad=pad,
+                                               use_im2col=use_im2col, algo=algo, need_grad_x=need_grad_x),
+            )
     if backend == "cpu":
         return conv2d_backward_cpu(x, w, grad_out, stride=stride, pad=pad, bias=bias)
     if cl is None or np is None:

netcl-0.3.2/netcl/ops/conv2d_pointwise.py

@@ -0,0 +1,520 @@
+"""
+Pointwise (1x1, stride 1, no padding, no groups/dilation) convolution as batched GEMM.
+
+A 1x1 convolution on NCHW data is a matrix product per sample,
+
+    out[n] (F x P) = W (F x C) @ x[n] (C x P),        P = H * W,
+
+so the dense conv kernels (tuned for 3x3 filters with many channels at small
+resolution) are a poor fit for it: MobileNet-style networks run their 1x1
+layers with few channels at high resolution, where those kernels reach only a
+few percent of the device's throughput. This module computes the three passes
+directly as register-tiled GEMMs on the NCHW buffers, without im2col or
+layout copies:
+
+    forward   out[n]  = W   @ x[n]        (+ bias, optional ReLU)
+    grad_x    gx[n]   = W^T @ go[n]
+    grad_w    gw      = sum_n go[n] @ x[n]^T     (split-K over N * P, then reduced)
+    grad_b    gb      = sum_{n,p} go[n, :, p]
+
+Selection is measured, not guessed: for every new shape the pointwise kernels
+(several tile configurations) and the existing ("legacy") conv path are timed
+once with the real buffers via netcl.core.autotune; the winner is cached per
+device (memory + JSON file). Shapes where the legacy path is faster keep using
+it, so the change can only make a given shape faster.
+
+Environment:
+    NETCL_CONV_POINTWISE=auto  (default) measured choice per shape
+    NETCL_CONV_POINTWISE=1     always use the pointwise kernels when eligible
+    NETCL_CONV_POINTWISE=0     never use them (previous behaviour)
+With NETCL_AUTOTUNE=0 no measurement happens and the legacy path is used,
+i.e. behaviour is exactly that of earlier releases.
+"""
+from __future__ import annotations
+
+import os
+import threading
+import time
+from contextlib import contextmanager
+from typing import Optional, Tuple
+
+from netcl.core.memory import BufferPool
+from netcl.core.tensor import Tensor
+
+try:
+    import numpy as np
+except ImportError:  # pragma: no cover
+    np = None
+
+try:
+    import pyopencl as cl
+except ImportError:  # pragma: no cover
+    cl = None
+
+__all__ = [
+    "pointwise_eligible",
+    "conv2d_pointwise",
+    "conv2d_pointwise_backward",
+    "GEMM_CONFIGS",
+    "GW_CONFIGS",
+]
+
+_MODE = os.environ.get("NETCL_CONV_POINTWISE", "auto").strip().lower()
+
+# (TM, TN, TK, RM, RN): output tile M x N per work-group, K step, register block per thread
+GEMM_CONFIGS: Tuple[Tuple[int, int, int, int, int], ...] = (
+    (32, 64, 16, 4, 4),
+    (64, 64, 16, 4, 4),
+    (32, 128, 16, 4, 8),
+    (64, 128, 16, 8, 8),
+)
+# (TF, TC, TK, RF, RC): grad_w tile F x C per work-group, reduction step, register block per thread
+GW_CONFIGS: Tuple[Tuple[int, int, int, int, int], ...] = (
+    (32, 32, 32, 4, 4),
+    (64, 32, 32, 4, 4),
+    (64, 64, 16, 4, 4),
+)
+
+_KERNEL_CACHE: dict = {}
+_state = threading.local()
+
+
+# --------------------------------------------------------------------------- eligibility / bypass
+
+@contextmanager
+def _bypass():
+    """While active, conv2d / conv2d_backward take their previous (legacy) path for pointwise shapes."""
+    prev = getattr(_state, "bypass", False)
+    _state.bypass = True
+    try:
+        yield
+    finally:
+        _state.bypass = prev
+
+
+def pointwise_eligible(x: Tensor, w: Tensor, stride: int = 1, pad: int = 0, dilation: int = 1, groups: int = 1) -> bool:
+    """True when the convolution is a plain 1x1 GEMM this module can compute (OpenCL, float32)."""
+    if cl is None or np is None or _MODE in ("0", "off", "false", "no"):
+        return False
+    if getattr(_state, "bypass", False):
+        return False
+    if getattr(x, "backend", "cl") == "cpu" or getattr(w, "backend", "cl") == "cpu":
+        return False
+    if groups != 1 or dilation != 1 or stride != 1 or pad != 0:
+        return False
+    if len(x.shape) != 4 or len(w.shape) != 4 or w.shape[2] != 1 or w.shape[3] != 1:
+        return False
+    if x.dtype not in ("float32", "float") or w.dtype != x.dtype or w.shape[1] != x.shape[1]:
+        return False
+    return True
+
+
+def _forced() -> bool:
+    return _MODE in ("1", "on", "true", "yes", "force")
+
+
+# --------------------------------------------------------------------------- kernels
+
+_GEMM_SRC = r"""
+// C[b] (M x P) = op(A) (M x K) @ B[b] (K x P)   (+ bias[m], optional ReLU)
+// op(A)[m][k] = TRANS_A ? A[k * M + m] : A[m * K + k]
+__kernel __attribute__((reqd_work_group_size(TN / RN, TM / RM, 1)))
+void pw_gemm(__global const float* restrict A,
+             __global const float* restrict B,
+             __global float* restrict Cout,
+             __global const float* restrict bias,
+             const int M, const int K, const int P,
+             const int has_bias, const int relu)
+{
+    const int tx = get_local_id(0);
+    const int ty = get_local_id(1);
+    const int bn = get_group_id(0) * TN;
+    const int bm = get_group_id(1) * TM;
+    const int b = get_group_id(2);
+    const int NTX = TN / RN, NTY = TM / RM, NT = NTX * NTY;
+    const int tid = ty * NTX + tx;
+    __global const float* Bb = B + (size_t)b * K * P;
+    __global float* Cb = Cout + (size_t)b * M * P;
+
+    __local float As[TK][TM];
+    __local float Bs[TK][TN];
+    float acc[RM][RN];
+    for (int i = 0; i < RM; ++i)
+        for (int j = 0; j < RN; ++j)
+            acc[i][j] = 0.0f;
+
+    for (int k0 = 0; k0 < K; k0 += TK) {
+        for (int i = tid; i < TK * TM; i += NT) {
+#if TRANS_A
+            const int kk = i / TM, mm = i % TM;           // consecutive threads -> consecutive m (contiguous)
+            const int m = bm + mm, k = k0 + kk;
+            As[kk][mm] = (m < M && k < K) ? A[(size_t)k * M + m] : 0.0f;
+#else
+            const int mm = i / TK, kk = i % TK;           // consecutive threads -> consecutive k (contiguous)
+            const int m = bm + mm, k = k0 + kk;
+            As[kk][mm] = (m < M && k < K) ? A[(size_t)m * K + k] : 0.0f;
+#endif
+        }
+        for (int i = tid; i < TK * TN; i += NT) {
+            const int kk = i / TN, nn = i % TN;
+            const int k = k0 + kk, n = bn + nn;
+            Bs[kk][nn] = (k < K && n < P) ? Bb[(size_t)k * P + n] : 0.0f;
+        }
+        barrier(CLK_LOCAL_MEM_FENCE);
+        for (int kk = 0; kk < TK; ++kk) {
+            float a[RM], bv[RN];
+            for (int i = 0; i < RM; ++i) a[i] = As[kk][ty + i * NTY];
+            for (int j = 0; j < RN; ++j) bv[j] = Bs[kk][tx + j * NTX];
+            for (int i = 0; i < RM; ++i)
+                for (int j = 0; j < RN; ++j)
+                    acc[i][j] = mad(a[i], bv[j], acc[i][j]);
+        }
+        barrier(CLK_LOCAL_MEM_FENCE);
+    }
+    for (int i = 0; i < RM; ++i) {
+        const int m = bm + ty + i * NTY;
+        if (m >= M) continue;
+        const float bb = has_bias ? bias[m] : 0.0f;
+        for (int j = 0; j < RN; ++j) {
+            const int n = bn + tx + j * NTX;
+            if (n < P) {
+                float v = acc[i][j] + bb;
+                if (relu) v = fmax(v, 0.0f);
+                Cb[(size_t)m * P + n] = v;
+            }
+        }
+    }
+}
+"""
+
+_GW_SRC = r"""
+// partial[s] (F x C) = sum_{p in chunk} go[n][f][p] * x[n][c][p],  s = n * chunks + chunk
+__kernel __attribute__((reqd_work_group_size(TC / RC, TF / RF, 1)))
+void pw_grad_w_partial(__global const float* restrict go,
+                       __global const float* restrict x,
+                       __global float* restrict partial,
+                       const int F, const int C, const int P,
+                       const int chunks, const int L)
+{
+    const int tx = get_local_id(0);
+    const int ty = get_local_id(1);
+    const int bc = get_group_id(0) * TC;
+    const int bf = get_group_id(1) * TF;
+    const int s = get_group_id(2);
+    const int n = s / chunks;
+    const int p_begin = (s % chunks) * L;
+    const int p_end = min(P, p_begin + L);
+    const int NTX = TC / RC, NTY = TF / RF, NT = NTX * NTY;
+    const int tid = ty * NTX + tx;
+    __global const float* gon = go + (size_t)n * F * P;
+    __global const float* xn = x + (size_t)n * C * P;
+
+    __local float Gs[TK][TF + 1];
+    __local float Xs[TK][TC + 1];
+    float acc[RF][RC];
+    for (int i = 0; i < RF; ++i)
+        for (int j = 0; j < RC; ++j)
+            acc[i][j] = 0.0f;
+
+    for (int p0 = p_begin; p0 < p_end; p0 += TK) {
+        for (int i = tid; i < TK * TF; i += NT) {
+            const int ff = i / TK, kk = i % TK;          // consecutive threads -> consecutive p (contiguous)
+            const int f = bf + ff, p = p0 + kk;
+            Gs[kk][ff] = (f < F && p < p_end) ? gon[(size_t)f * P + p] : 0.0f;
+        }
+        for (int i = tid; i < TK * TC; i += NT) {
+            const int cc = i / TK, kk = i % TK;
+            const int c = bc + cc, p = p0 + kk;
+            Xs[kk][cc] = (c < C && p < p_end) ? xn[(size_t)c * P + p] : 0.0f;
+        }
+        barrier(CLK_LOCAL_MEM_FENCE);
+        for (int kk = 0; kk < TK; ++kk) {
+            float g[RF], xv[RC];
+            for (int i = 0; i < RF; ++i) g[i] = Gs[kk][ty + i * NTY];
+            for (int j = 0; j < RC; ++j) xv[j] = Xs[kk][tx + j * NTX];
+            for (int i = 0; i < RF; ++i)
+                for (int j = 0; j < RC; ++j)
+                    acc[i][j] = mad(g[i], xv[j], acc[i][j]);
+        }
+        barrier(CLK_LOCAL_MEM_FENCE);
+    }
+    __global float* out = partial + (size_t)s * F * C;
+    for (int i = 0; i < RF; ++i) {
+        const int f = bf + ty + i * NTY;
+        if (f >= F) continue;
+        for (int j = 0; j < RC; ++j) {
+            const int c = bc + tx + j * NTX;
+            if (c < C) out[(size_t)f * C + c] = acc[i][j];
+        }
+    }
+}
+"""
+
+_REDUCE_SRC = r"""
+// out[i] = sum_s partial[s * n + i]
+__kernel void pw_reduce_partials(__global const float* restrict partial, __global float* restrict out,
+                                 const int n, const int S)
+{
+    const int i = get_global_id(0);
+    if (i >= n) return;
+    float acc = 0.0f;
+    for (int s = 0; s < S; ++s) acc += partial[(size_t)s * n + i];
+    out[i] = acc;
+}
+
+// gb[f] = sum_{n, p} go[n][f][p]; one work-group of 256 per f
+__kernel __attribute__((reqd_work_group_size(256, 1, 1)))
+void pw_grad_bias(__global const float* restrict go, __global float* restrict gb,
+                  const int N, const int F, const int P)
+{
+    const int f = get_group_id(0);
+    const int t = get_local_id(0);
+    __local float red[256];
+    float acc = 0.0f;
+    for (int n = 0; n < N; ++n) {
+        __global const float* row = go + ((size_t)n * F + f) * P;
+        for (int p = t; p < P; p += 256) acc += row[p];
+    }
+    red[t] = acc;
+    barrier(CLK_LOCAL_MEM_FENCE);
+    for (int s = 128; s > 0; s >>= 1) {
+        if (t < s) red[t] += red[t + s];
+        barrier(CLK_LOCAL_MEM_FENCE);
+    }
+    if (t == 0) gb[f] = red[0];
+}
+"""
+
+
+def _kernel(ctx: "cl.Context", key: tuple, src: str, defines: dict, name: str) -> "cl.Kernel":
+    """Build each (source, defines) once per context and keep the kernel object (retrieving a kernel from a
+    program on every launch is slow in pyopencl)."""
+    k = (ctx.int_ptr, name) + key
+    kern = _KERNEL_CACHE.get(k)
+    if kern is None:
+        opts = [f"-D{d}={v}" for d, v in defines.items()]
+        kern = _KERNEL_CACHE[k] = getattr(cl.Program(ctx, src).build(options=opts), name)
+    return kern
+
+
+def _gemm_kernel(ctx, cfg, trans_a: bool):
+    TM, TN, TK, RM, RN = cfg
+    return _kernel(ctx, (cfg, trans_a), _GEMM_SRC, dict(TM=TM, TN=TN, TK=TK, RM=RM, RN=RN, TRANS_A=int(trans_a)), "pw_gemm")
+
+
+def _gw_kernel(ctx, cfg):
+    TF, TC, TK, RF, RC = cfg
+    return _kernel(ctx, (cfg,), _GW_SRC, dict(TF=TF, TC=TC, TK=TK, RF=RF, RC=RC), "pw_grad_w_partial")
+
+
+def _aux_kernel(ctx, name: str):
+    return _kernel(ctx, (), _REDUCE_SRC, {}, name)
+
+
+def _ceil(a: int, b: int) -> int:
+    return -(-a // b)
+
+
+def _bucket(v: int) -> int:
+    """Next power of two: tuning keys group similar batch sizes / resolutions, so inputs of varying size
+    (inference on arbitrary images, a smaller last batch) reuse one measurement instead of re-measuring and
+    growing the cache with every new shape."""
+    return 1 << max(0, int(v) - 1).bit_length()
+
+
+def _check_config(cfg, dev_max_wg: int) -> bool:
+    t1, t2, _, r1, r2 = cfg
+    return t1 % r1 == 0 and t2 % r2 == 0 and (t1 // r1) * (t2 // r2) <= dev_max_wg
+
+
+# --------------------------------------------------------------------------- launches
+
+def _gemm(q, A_buf, B: Tensor, out: Tensor, M: int, K: int, P: int, batch: int, cfg, trans_a: bool,
+          bias: Optional[Tensor] = None, relu: bool = False) -> None:
+    TM, TN, TK, RM, RN = cfg
+    kernel = _gemm_kernel(q.context, cfg, trans_a)
+    lsize = (TN // RN, TM // RM, 1)
+    gsize = (_ceil(P, TN) * lsize[0], _ceil(M, TM) * lsize[1], batch)
+    kernel(q, gsize, lsize, A_buf, B.buffer, out.buffer, bias.buffer if bias is not None else A_buf,
+           np.int32(M), np.int32(K), np.int32(P), np.int32(bias is not None), np.int32(bool(relu)))
+
+
+def _gw_split(F: int, C: int, N: int, P: int, cfg) -> Tuple[int, int]:
+    """Chunk length L along P and chunks per sample: enough work-groups to fill the device, without
+    growing the partial buffer beyond what the reduction needs."""
+    TF, TC, TK, _, _ = cfg
+    tiles = _ceil(F, TF) * _ceil(C, TC)
+    target_groups = 1024
+    splits = max(N, _ceil(target_groups, tiles))
+    L = max(TK * 8, _ceil(_ceil(N * P, splits), TK) * TK)
+    L = min(L, _ceil(P, TK) * TK)
+    return L, _ceil(P, L)
+
+
+def _grad_w(q, x: Tensor, go: Tensor, gw: Tensor, N: int, C: int, F: int, P: int, cfg, pool) -> None:
+    L, chunks = _gw_split(F, C, N, P, cfg)
+    S = N * chunks
+    TF, TC, TK, RF, RC = cfg
+    partial = Tensor.from_shape(q, (S, F, C), dtype="float32", pool=pool)
+    lsize = (TC // RC, TF // RF, 1)
+    gsize = (_ceil(C, TC) * lsize[0], _ceil(F, TF) * lsize[1], S)
+    _gw_kernel(q.context, cfg)(q, gsize, lsize, go.buffer, x.buffer, partial.buffer,
+                               np.int32(F), np.int32(C), np.int32(P), np.int32(chunks), np.int32(L))
+    n = F * C
+    _aux_kernel(q.context, "pw_reduce_partials")(q, (_ceil(n, 256) * 256,), (256,), partial.buffer, gw.buffer,
+                                               np.int32(n), np.int32(S))
+
+
+def _grad_bias(q, go: Tensor, gb: Tensor, N: int, F: int, P: int) -> None:
+    _aux_kernel(q.context, "pw_grad_bias")(q, (F * 256,), (256,), go.buffer, gb.buffer,
+                                         np.int32(N), np.int32(F), np.int32(P))
+
+
+# --------------------------------------------------------------------------- tuning helpers
+
+def _timed(q, fn) -> float:
+    q.finish()
+    t0 = time.perf_counter()
+    fn()
+    q.finish()
+    return time.perf_counter() - t0
+
+
+def _valid_configs(q, configs):
+    max_wg = int(getattr(q.device, "max_work_group_size", 256))
+    return [c for c in configs if _check_config(c, max_wg)]
+
+
+def _tuned_gemm_config(q, M: int, K: int, P: int, batch: int, trans_a: bool, A_buf, B: Tensor, out: Tensor):
+    from netcl.core.autotune import autotune
+
+    cands = _valid_configs(q, GEMM_CONFIGS)
+    return tuple(autotune(
+        q, "conv2d_pointwise_gemm", (M, K, _bucket(P), _bucket(batch), int(trans_a)), [list(c) for c in cands],
+        bench=lambda c: _timed(q, lambda: _gemm(q, A_buf, B, out, M, K, P, batch, tuple(c), trans_a)),
+        default=list(cands[0]), reps=3,
+    ))
+
+
+def _tuned_gw_config(q, x: Tensor, go: Tensor, gw: Tensor, N: int, C: int, F: int, P: int, pool):
+    from netcl.core.autotune import autotune
+
+    cands = _valid_configs(q, GW_CONFIGS)
+    return tuple(autotune(
+        q, "conv2d_pointwise_grad_w", (F, C, _bucket(N), _bucket(P)), [list(c) for c in cands],
+        bench=lambda c: _timed(q, lambda: _grad_w(q, x, go, gw, N, C, F, P, tuple(c), pool)),
+        default=list(cands[0]), reps=3,
+    ))
+
+
+# --------------------------------------------------------------------------- public ops
+
+def conv2d_pointwise(
+    x: Tensor,
+    w: Tensor,
+    bias: Optional[Tensor] = None,
+    out: Optional[Tensor] = None,
+    pool: Optional[BufferPool] = None,
+    fuse_relu: bool = False,
+    config: Optional[Tuple[int, int, int, int, int]] = None,
+) -> Tensor:
+    """1x1 convolution x (N, C, H, W) * w (F, C, 1, 1) -> (N, F, H, W) as one batched GEMM launch.
+    `config` forces a tile configuration (GEMM_CONFIGS entry); default: autotuned per shape."""
+    N, C, H, W = x.shape
+    F = w.shape[0]
+    P = H * W
+    q = x.queue
+    if out is None:
+        out = Tensor.from_shape(q, (N, F, H, W), dtype=x.dtype, pool=pool)
+    if N == 0 or F == 0 or P == 0:
+        return out
+    if C == 0:
+        raise ValueError("conv2d_pointwise: zero input channels")
+    if config is None:
+        config = _tuned_gemm_config(q, F, C, P, N, False, w.buffer, x, out)
+    _gemm(q, w.buffer, x, out, F, C, P, N, config, False, bias=bias, relu=bool(fuse_relu))
+    return out
+
+
+def conv2d_pointwise_backward(
+    x: Tensor,
+    w: Tensor,
+    grad_out: Tensor,
+    bias: Optional[Tensor] = None,
+    pool: Optional[BufferPool] = None,
+    need_grad_x: bool = True,
+    gemm_config: Optional[Tuple[int, int, int, int, int]] = None,
+    gw_config: Optional[Tuple[int, int, int, int, int]] = None,
+) -> Tuple[Optional[Tensor], Tensor, Optional[Tensor]]:
+    """Gradients of conv2d_pointwise: (grad_x or None, grad_w (F, C, 1, 1), grad_b or None)."""
+    N, C, H, W = x.shape
+    F = w.shape[0]
+    P = H * W
+    q = x.queue
+    grad_w = Tensor.from_shape(q, (F, C, 1, 1), dtype=x.dtype, pool=pool)
+    grad_b = Tensor.from_shape(q, (F,), dtype=x.dtype, pool=pool) if bias is not None else None
+    grad_x = Tensor.from_shape(q, (N, C, H, W), dtype=x.dtype, pool=pool) if need_grad_x else None
+    if N * P == 0:
+        for t in (grad_w, grad_b):
+            if t is not None and t.shape[0] > 0:
+                cl.enqueue_fill_buffer(q, t.buffer, np.float32(0), 0, int(np.prod(t.shape)) * 4)
+        return grad_x, grad_w, grad_b
+    if need_grad_x:
+        cfg = gemm_config or _tuned_gemm_config(q, C, F, P, N, True, w.buffer, grad_out, grad_x)
+        _gemm(q, w.buffer, grad_out, grad_x, C, F, P, N, cfg, True)
+    cfg = gw_config or _tuned_gw_config(q, x, grad_out, grad_w, N, C, F, P, pool)
+    _grad_w(q, x, grad_out, grad_w, N, C, F, P, cfg, pool)
+    if grad_b is not None:
+        _grad_bias(q, grad_out, grad_b, N, F, P)
+    return grad_x, grad_w, grad_b
+
+
+# --------------------------------------------------------------------------- measured dispatch
+
+def _shape_key(x: Tensor, w: Tensor, bias, extra) -> tuple:
+    N, C, H, W = (int(d) for d in x.shape)
+    return (_bucket(N), C, _bucket(H * W), int(w.shape[0]), int(bias is not None)) + tuple(extra)
+
+
+def dispatch_forward(x: Tensor, w: Tensor, bias: Optional[Tensor], out: Optional[Tensor], pool, fuse_relu,
+                     legacy) -> Tensor:
+    """Called by conv2d for eligible shapes. `legacy()` runs the previous conv path (pointwise bypassed)."""
+    if not _forced():
+        from netcl.core.autotune import autotune
+
+        q = x.queue
+        scratch = Tensor.from_shape(q, (x.shape[0], w.shape[0], x.shape[2], x.shape[3]), dtype=x.dtype, pool=pool)
+
+        def bench(cand):
+            if cand == "legacy":
+                with _bypass():
+                    return _timed(q, legacy)
+            return _timed(q, lambda: conv2d_pointwise(x, w, bias, out=scratch, pool=pool, fuse_relu=fuse_relu))
+
+        choice = autotune(q, "conv2d_pointwise_fwd_select", _shape_key(x, w, bias, (int(bool(fuse_relu)),)),
+                          ["legacy", "pointwise"], bench=bench, default="legacy", reps=3)
+        if choice == "legacy":
+            with _bypass():
+                return legacy()
+    return conv2d_pointwise(x, w, bias, out=out, pool=pool, fuse_relu=fuse_relu)
+
+
+def dispatch_backward(x: Tensor, w: Tensor, grad_out: Tensor, bias: Optional[Tensor], pool, need_grad_x, legacy):
+    """Called by conv2d_backward for eligible shapes; same measured choice as dispatch_forward."""
+    if not _forced():
+        from netcl.core.autotune import autotune
+
+        q = x.queue
+
+        def bench(cand):
+            if cand == "legacy":
+                with _bypass():
+                    return _timed(q, legacy)
+            return _timed(q, lambda: conv2d_pointwise_backward(x, w, grad_out, bias, pool=pool, need_grad_x=need_grad_x))
+
+        choice = autotune(q, "conv2d_pointwise_bwd_select", _shape_key(x, w, bias, (int(bool(need_grad_x)),)),
+                          ["legacy", "pointwise"], bench=bench, default="legacy", reps=3)
+        if choice == "legacy":
+            with _bypass():
+                return legacy()
+    return conv2d_pointwise_backward(x, w, grad_out, bias, pool=pool, need_grad_x=need_grad_x)