Initial release

ggml/docs/metal-conv-transpose-2d.md

@@ -0,0 +1,62 @@
+# ggml `CONV_TRANSPOSE_2D` semantics
+
+Source of truth: [`ggml_compute_forward_conv_transpose_2d()`](../src/ggml-cpu/ops.cpp).
+
+This note documents the exact contract the Metal kernel mirrors.
+
+## Tensor layouts
+
+- `src0` weights: `(KW, KH, Cout, Cin)`, contiguous, `F16` in the CPU implementation used by SAM.
+- `src1` input: `(IW, IH, Cin, N)`, contiguous, `F32`.
+- `dst` output: `(OW, OH, Cout, N)`, `F32`.
+
+For `ggml_conv_transpose_2d_p0()` the output size is:
+
+- `OW = (IW - 1) * stride + KW`
+- `OH = (IH - 1) * stride + KH`
+
+The `p0` variant used here has:
+
+- zero padding only
+- one shared spatial stride `s0`
+- no dilation
+- no output padding
+- no bias term
+
+## CPU computation
+
+The CPU implementation permutes weights and inputs into temporary buffers, zeros `dst`,
+then performs a scatter-add over output channel, input spatial position, and kernel tap:
+
+```text
+for out_c in [0, Cout):
+  for in_y in [0, IH):
+    for in_x in [0, IW):
+      for kh in [0, KH):
+        for kw in [0, KW):
+          dst[in_x * stride + kw, in_y * stride + kh, out_c] +=
+            dot(input[in_x, in_y, :, 0], weight[kw, kh, out_c, :, 0])
+```
+
+The Metal reference kernel uses the equivalent gather form for one output element:
+
+```text
+dst[ow, oh, out_c] =
+  sum over kh, kw, in_c where
+    ow = in_x * stride + kw
+    oh = in_y * stride + kh
+  of weight[kw, kh, out_c, in_c] * input[in_x, in_y, in_c]
+```
+
+## Numeric behavior
+
+- input source type: `F32`, but the CPU implementation first packs it to `F16`
+- weight type: `F16` or `F32` on Metal, `F16` in the CPU path used here
+- multiply inputs: `F16 x F16` in the reference CPU path
+- accumulation type: `float`
+- output type: `F32`
+
+## Scope
+
+The current CPU implementation only uses batch `N = 1` in practice for this path, and
+the Metal implementation matches that contract explicitly.