wgblas 1.2.1 → 2.1.0

package/src/saxpy/saxpy.mjs

@@ -11,6 +11,7 @@ import { extractTimestamp } from "../util/benchmark.mjs";
 import { getPipeline } from "../util/pipeline.mjs";
 import { calcWorkgroups } from "../util/workgroup.mjs";
 import { GpuVector } from "../classes/GpuVector.mjs";
+import { requireSameDevice } from "../util/device.mjs";
 
 export async function saxpy(device, n, alpha, x, incx, y, incy) {
   const xIsGpu = x instanceof GpuVector;
@@ -18,6 +19,7 @@ export async function saxpy(device, n, alpha, x, incx, y, incy) {
 
   if (!(device instanceof GPUDevice))
     throw new Error("device must be a GPUDevice.");
+  requireSameDevice(device, "saxpy", { x, y });
   if (
     !Number.isInteger(n) ||
     !Number.isInteger(incx) ||
@@ -56,9 +58,9 @@ export async function saxpy(device, n, alpha, x, incx, y, incy) {
   let readBuffer = null;
 
   try {
-    xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "saxpy-x", false);
-    yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "saxpy-y", true);
-    paramsBuffer = createParamsBuffer(
+    xBuffer = xIsGpu ? x._buf : uploadBuffer(device, x, "saxpy-x", false);
+    yBuffer = yIsGpu ? y._buf : uploadBuffer(device, y, "saxpy-y", true);
+    paramsBuffer = createParamsBuffer(device,
       [
         { value: n, type: "u32" },
         { value: alpha, type: "f32" },
@@ -68,19 +70,19 @@ export async function saxpy(device, n, alpha, x, incx, y, incy) {
       "saxpy-params",
     );
 
-    const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
       xBuffer,
       yBuffer,
       paramsBuffer,
     ]);
-    const { commandEncoder, ts } = runComputePass(
+    const { commandEncoder, ts } = runComputePass(device,
       pipeline,
       bindGroup,
-      calcWorkgroups(n),
+      calcWorkgroups(device, n),
     );
-    readBuffer = yIsGpu ? null : stageReadback(commandEncoder, yBuffer);
+    readBuffer = yIsGpu ? null : stageReadback(device, commandEncoder, yBuffer);
 
-    submit(commandEncoder);
+    submit(device, commandEncoder);
 
     const gpuTimeMs = await extractTimestamp(ts);
 

package/src/scopy/scopy.d.mts

@@ -1,7 +1,7 @@
 import { GpuVector } from "../classes/GpuVector.mjs";
 
 /**
- * Performs the operation y = x
+ * Performs the operation $$y \leftarrow x$$
  *
  * {@includeCode ../../examples/scopy/scopy.js}
  *
@@ -27,9 +27,9 @@ export declare function scopy(
 ): Promise<{ y: Float32Array } | { y: Float32Array; gpuTimeMs: number }>;
 
 /**
- * Performs the operation y = x
+ * Performs the operation $$y \leftarrow x$$
  *
- * {@includeCode ../../examples/scopy/gpuvec.scopy.js}
+ * {@includeCode ../../examples/scopy/gpu.scopy.js}
  *
  * @param device - GPUDevice from `init()`
  * @param n - number of elements (must be a positive integer)

package/src/scopy/scopy.mjs

@@ -11,6 +11,7 @@ import { extractTimestamp } from "../util/benchmark.mjs";
 import { getPipeline } from "../util/pipeline.mjs";
 import { calcWorkgroups } from "../util/workgroup.mjs";
 import { GpuVector } from "../classes/GpuVector.mjs";
+import { requireSameDevice } from "../util/device.mjs";
 
 export async function scopy(device, n, x, incx, y, incy) {
   const xIsGpu = x instanceof GpuVector;
@@ -18,6 +19,7 @@ export async function scopy(device, n, x, incx, y, incy) {
 
   if (!(device instanceof GPUDevice))
     throw new Error("device must be a GPUDevice.");
+  requireSameDevice(device, "scopy", { x, y });
   if (
     !Number.isInteger(n) ||
     !Number.isInteger(incx) ||
@@ -52,9 +54,9 @@ export async function scopy(device, n, x, incx, y, incy) {
   let readBuffer = null;
 
   try {
-    xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "scopy-x", false);
-    yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "scopy-y", true);
-    paramsBuffer = createParamsBuffer(
+    xBuffer = xIsGpu ? x._buf : uploadBuffer(device, x, "scopy-x", false);
+    yBuffer = yIsGpu ? y._buf : uploadBuffer(device, y, "scopy-y", true);
+    paramsBuffer = createParamsBuffer(device,
       [
         { value: n, type: "u32" },
         { value: incx, type: "u32" },
@@ -63,19 +65,19 @@ export async function scopy(device, n, x, incx, y, incy) {
       "scopy-params",
     );
 
-    const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
       xBuffer,
       yBuffer,
       paramsBuffer,
     ]);
-    const { commandEncoder, ts } = runComputePass(
+    const { commandEncoder, ts } = runComputePass(device,
       pipeline,
       bindGroup,
-      calcWorkgroups(n),
+      calcWorkgroups(device, n),
     );
-    readBuffer = yIsGpu ? null : stageReadback(commandEncoder, yBuffer);
+    readBuffer = yIsGpu ? null : stageReadback(device, commandEncoder, yBuffer);
 
-    submit(commandEncoder);
+    submit(device, commandEncoder);
 
     const gpuTimeMs = await extractTimestamp(ts);
 

package/src/sdot/sdot.d.mts

@@ -1,7 +1,7 @@
 import { GpuVector } from "../classes/GpuVector.mjs";
 
 /**
- * Computes the dot product of two vectors: result = sum(x[i] * y[i])
+ * Computes the dot product of two vectors: $$\text{result} = \sum_{i} x_i y_i$$
  *
  * {@includeCode ../../examples/sdot/sdot.js}
  *
@@ -28,9 +28,9 @@ export declare function sdot(
 ): Promise<{ dot: number } | { dot: number; gpuTimeMs: number }>;
 
 /**
- * Computes the dot product of two vectors: result = sum(x[i] * y[i])
+ * Computes the dot product of two vectors: $$\text{result} = \sum_{i} x_i y_i$$
  *
- * {@includeCode ../../examples/sdot/gpuvec.sdot.js}
+ * {@includeCode ../../examples/sdot/gpu.sdot.js}
  *
  * @param device - GPUDevice from `init()`
  * @param n - number of elements (must be a positive integer)

package/src/sdot/sdot.mjs

@@ -12,8 +12,9 @@ import { extractTimestamp } from "../util/benchmark.mjs";
 import { extractResult } from "../util/result.mjs";
 import { getPipeline } from "../util/pipeline.mjs";
 import { GpuVector } from "../classes/GpuVector.mjs";
+import { WGS } from "../util/constants.mjs";
+import { requireSameDevice } from "../util/device.mjs";
 
-const WGS = 64; //workgroup size
 
 export async function sdot(device, n, x, incx, y, incy) {
   const xIsGpu = x instanceof GpuVector;
@@ -21,6 +22,7 @@ export async function sdot(device, n, x, incx, y, incy) {
 
   if (!(device instanceof GPUDevice))
     throw new Error("device must be a GPUDevice.");
+  requireSameDevice(device, "sdot", { x, y });
   if (
     !Number.isInteger(n) ||
     !Number.isInteger(incx) ||
@@ -58,11 +60,11 @@ export async function sdot(device, n, x, incx, y, incy) {
   let readBuffer = null;
 
   try {
-    xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "sdot-x", false);
-    yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "sdot-y", false);
-    partialsBuffer = createStorageBuffer(2 * WGS * 4, "sdot-partials"); //to hold 2*WGS partial sums of f32
-    resultBuffer = createResultBuffer(4, "sdot-result"); //to hold the final float32 dot product
-    paramsBuffer = createParamsBuffer(
+    xBuffer = xIsGpu ? x._buf : uploadBuffer(device, x, "sdot-x", false);
+    yBuffer = yIsGpu ? y._buf : uploadBuffer(device, y, "sdot-y", false);
+    partialsBuffer = createStorageBuffer(device, 2 * WGS * 4, "sdot-partials"); //to hold 2*WGS partial sums of f32
+    resultBuffer = createResultBuffer(device, 4, "sdot-result"); //to hold the final float32 dot product
+    paramsBuffer = createParamsBuffer(device,
       [
         { value: n, type: "u32" },
         { value: incx, type: "u32" },
@@ -71,32 +73,32 @@ export async function sdot(device, n, x, incx, y, incy) {
       "sdot-params",
     );
 
-    const bgMain = createBindGroup(pipelineMain.getBindGroupLayout(0), [
+    const bgMain = createBindGroup(device, pipelineMain.getBindGroupLayout(0), [
       xBuffer,
       yBuffer,
       partialsBuffer,
       paramsBuffer,
     ]);
-    const { commandEncoder: enc1, ts: ts1 } = runComputePass(
+    const { commandEncoder: enc1, ts: ts1 } = runComputePass(device,
       pipelineMain,
       bgMain,
       2 * WGS,
     ); //dispatch 2*WGS workgroups
 
-    submit(enc1);
+    submit(device, enc1);
 
-    const bgReduce = createBindGroup(pipelineReduce.getBindGroupLayout(0), [
+    const bgReduce = createBindGroup(device, pipelineReduce.getBindGroupLayout(0), [
       partialsBuffer,
       resultBuffer,
     ]);
-    const { commandEncoder: enc2, ts: ts2 } = runComputePass(
+    const { commandEncoder: enc2, ts: ts2 } = runComputePass(device,
       pipelineReduce,
       bgReduce,
       1,
     ); // dispatch 1 workgroup to reduce the partial sums to a single result
-    readBuffer = stageReadback(enc2, resultBuffer);
+    readBuffer = stageReadback(device, enc2, resultBuffer);
 
-    submit(enc2);
+    submit(device, enc2);
 
     const resultPromise = extractResult(readBuffer, Float32Array);
     readBuffer = null; // ownership transferred — extractResult's own finally destroys it
@@ -117,7 +119,7 @@ export async function sdot(device, n, x, incx, y, incy) {
     if (partialsBuffer) destroyBuffers(partialsBuffer);
     if (resultBuffer) destroyBuffers(resultBuffer);
     if (paramsBuffer) destroyBuffers(paramsBuffer);
-    // Only reached if submit(enc2) threw before ownership was transferred above.
+    // Only reached if submit(device, enc2) threw before ownership was transferred above.
     if (readBuffer) destroyBuffers(readBuffer);
   }
 }

package/src/sgemm/sgemm.d.mts

@@ -0,0 +1,102 @@
+import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+
+/**
+ * Performs the matrix-matrix operation C = alpha * op(A) * op(B) + beta * C
+ *
+ * - `transA/transB='no-transpose'`: op(A) = A (m×k), op(B) = B (k×n)
+ * - `transA/transB='transpose'`:    op(A) = A^T,     op(B) = B^T
+ *
+ * A, B, C are row-major or column-major (see `layout`) — backed by one of
+ * two shared-memory-tiled, register-blocked kernels chosen by shape:
+ * `sgemm_small.wgsl` (BM=BN=32) below a 6x6 workgroup grid, `sgemm_large.wgsl`
+ * (BM=BN=64) above it.
+ *
+ * {@includeCode ../../examples/sgemm/sgemm.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/sgemm/web/sgemm.html}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param transA - `'no-transpose'` for A, `'transpose'` for A^T
+ * @param transB - `'no-transpose'` for B, `'transpose'` for B^T
+ * @param m      - rows of op(A) and C
+ * @param n      - columns of op(B) and C
+ * @param k      - columns of op(A), rows of op(B)
+ * @param alpha  - scalar multiplier for op(A)*op(B)
+ * @param A      - Float32Array, row-major or column-major (see `layout`)
+ * @param lda    - leading dimension of A as stored
+ * @param B      - Float32Array, row-major or column-major (see `layout`)
+ * @param ldb    - leading dimension of B as stored
+ * @param beta   - scalar multiplier for C
+ * @param C      - Float32Array input/output matrix, row-major or column-major
+ * @param ldc    - leading dimension of C as stored
+ * @param layout - storage layout shared by A/B/C when they're Float32Array
+ *   (default: `'row-major'`); column-major A/B flips the respective trans
+ *   flag internally, column-major C computes C^T = op(B)^T*op(A)^T instead
+ *   (same underlying bytes) — op(A)*op(B) stays what you asked for either way
+ * @returns updated C as a Float32Array
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/sgemm/sgemm.mjs#L17">Source code: sgemm.mjs (L17)</a>
+ * @category BLAS Level 3
+ */
+export declare function sgemm(
+  device: GPUDevice,
+  transA: 'no-transpose' | 'transpose',
+  transB: 'no-transpose' | 'transpose',
+  m: number,
+  n: number,
+  k: number,
+  alpha: number,
+  A: Float32Array,
+  lda: number,
+  B: Float32Array,
+  ldb: number,
+  beta: number,
+  C: Float32Array,
+  ldc: number,
+  layout?: 'row-major' | 'column-major',
+): Promise<{ C: Float32Array; gpuTimeMs?: number }>;
+
+/**
+ * Performs the matrix-matrix operation C = alpha * op(A) * op(B) + beta * C
+ *
+ * A, B, and C are all kept GPU-resident. Each matrix's own `layout` (set at
+ * `GpuMatrix.from` time) determines the operation — there is no separate
+ * `layout` argument here. A and B must be GpuMatrix whenever C is, and vice
+ * versa — mixing a GpuMatrix with a plain Float32Array is not supported.
+ *
+ * {@includeCode ../../examples/sgemm/gpu.sgemm.js}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param transA - `'no-transpose'` for A, `'transpose'` for A^T
+ * @param transB - `'no-transpose'` for B, `'transpose'` for B^T
+ * @param m      - rows of op(A) and C
+ * @param n      - columns of op(B) and C
+ * @param k      - columns of op(A), rows of op(B)
+ * @param alpha  - scalar multiplier for op(A)*op(B)
+ * @param A      - GpuMatrix
+ * @param lda    - leading dimension of A (must equal A.lda)
+ * @param B      - GpuMatrix
+ * @param ldb    - leading dimension of B (must equal B.lda)
+ * @param beta   - scalar multiplier for C
+ * @param C      - GpuMatrix (mutated in place)
+ * @param ldc    - leading dimension of C (must equal C.lda)
+ * @returns no C — it stays GPU-resident; call `C.read()` yourself for a CPU readback (see the example)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/sgemm/sgemm.mjs#L17">Source code: sgemm.mjs (L17)</a>
+ * @category BLAS Level 3
+ */
+export declare function sgemm(
+  device: GPUDevice,
+  transA: 'no-transpose' | 'transpose',
+  transB: 'no-transpose' | 'transpose',
+  m: number,
+  n: number,
+  k: number,
+  alpha: number,
+  A: GpuMatrix,
+  lda: number,
+  B: GpuMatrix,
+  ldb: number,
+  beta: number,
+  C: GpuMatrix,
+  ldc: number,
+): Promise<{ gpuTimeMs?: number }>;

package/src/sgemm/sgemm.mjs

@@ -0,0 +1,208 @@
+import {
+  uploadBuffer,
+  createParamsBuffer,
+  stageReadback,
+  destroyBuffers,
+  vec4ViewBinding,
+  vec4Usable,
+} from "../util/buffer.mjs";
+import { createBindGroup } from "../util/bindgroup.mjs";
+import { runComputePass, submit } from "../util/compute.mjs";
+import { extractResult } from "../util/result.mjs";
+import { extractTimestamp } from "../util/benchmark.mjs";
+import { getPipeline } from "../util/pipeline.mjs";
+import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+import { requireWorkgroupCount } from "../util/workgroup.mjs";
+import { BM_SMALL, BN_SMALL, BM_LARGE, BN_LARGE, LARGE_TILE_WORKGROUP_THRESHOLD } from "../util/constants.mjs";
+import { requireSameDevice } from "../util/device.mjs";
+
+
+export async function sgemm(
+  device, transA, transB, m, n, k, alpha, A, lda, B, ldb, beta, C, ldc, layout = "row-major",
+) {
+  let AIsGpu = A instanceof GpuMatrix;
+  let BIsGpu = B instanceof GpuMatrix;
+  const CIsGpu = C instanceof GpuMatrix;
+
+  if (!(device instanceof GPUDevice))
+    throw new Error("device must be a GPUDevice.");
+  requireSameDevice(device, "sgemm", { A, B, C });
+  if (transA !== "no-transpose" && transA !== "transpose")
+    throw new Error("transA must be 'no-transpose' or 'transpose'.");
+  if (transB !== "no-transpose" && transB !== "transpose")
+    throw new Error("transB must be 'no-transpose' or 'transpose'.");
+  if (layout !== "row-major" && layout !== "column-major")
+    throw new Error("layout must be 'row-major' or 'column-major'.");
+  if (typeof alpha !== "number")
+    throw new Error("alpha must be a number.");
+  if (Number.isNaN(alpha)) throw new Error("alpha must not be NaN.");
+  if (!Number.isFinite(alpha)) throw new Error("alpha must be finite.");
+  if (typeof beta !== "number")
+    throw new Error("beta must be a number.");
+  if (Number.isNaN(beta)) throw new Error("beta must not be NaN.");
+  if (!Number.isFinite(beta)) throw new Error("beta must be finite.");
+  if (
+    !Number.isInteger(m) ||
+    !Number.isInteger(n) ||
+    !Number.isInteger(k) ||
+    !Number.isInteger(lda) ||
+    !Number.isInteger(ldb) ||
+    !Number.isInteger(ldc)
+  )
+    throw new Error("m, n, k, lda, ldb, and ldc must be integers.");
+  if (!AIsGpu && !(A instanceof Float32Array))
+    throw new Error("A must be a Float32Array or GpuMatrix.");
+  if (!BIsGpu && !(B instanceof Float32Array))
+    throw new Error("B must be a Float32Array or GpuMatrix.");
+  if (!CIsGpu && !(C instanceof Float32Array))
+    throw new Error("C must be a Float32Array or GpuMatrix.");
+  if ((AIsGpu || BIsGpu) && !CIsGpu)
+    throw new Error("C must be a GpuMatrix when A or B is a GpuMatrix.");
+  if (CIsGpu && (!AIsGpu || !BIsGpu))
+    throw new Error("A and B must be GpuMatrix when C is a GpuMatrix.");
+  if (m < 0 || n < 0 || k < 0) throw new Error("m, n, and k must be non-negative.");
+  if (m === 0 || n === 0) return CIsGpu ? {} : { C };
+
+  // GpuMatrix's own .layout wins over the shared `layout` argument.
+  const effLayoutA = AIsGpu ? A.layout : layout;
+  const effLayoutB = BIsGpu ? B.layout : layout;
+  const effLayoutC = CIsGpu ? C.layout : layout;
+
+  // Shape validation, before any layout-driven swapping below.
+  // A: op(A) is m x k; A itself is m x k or k x m depending on transA.
+  const aRows = effLayoutA === "column-major" ? k : m;
+  const aCols = effLayoutA === "column-major" ? m : k;
+  const aOuter = transA === "no-transpose" ? aRows : aCols; // # of stored chunks
+  const aInner = transA === "no-transpose" ? aCols : aRows; // required chunk length
+  if (lda < aInner)
+    throw new Error(`lda must be >= ${effLayoutA === "column-major" ? "rows" : "cols"} of A as stored.`);
+  if (AIsGpu) {
+    if (lda !== A.lda) throw new Error("lda must match A.lda when A is a GpuMatrix.");
+    const [aLogRows, aLogCols] = transA === "no-transpose" ? [m, k] : [k, m];
+    if (A.rows < aLogRows || A.cols < aLogCols)
+      throw new Error("A is too small for the given m, k, and transA.");
+  } else if (A.length < (aOuter - 1) * lda + aInner) {
+    throw new Error("A does not have enough elements for the given dimensions and lda.");
+  }
+
+  // B: same reasoning as A, with op(B) = k x n.
+  const bRows = effLayoutB === "column-major" ? n : k;
+  const bCols = effLayoutB === "column-major" ? k : n;
+  const bOuter = transB === "no-transpose" ? bRows : bCols;
+  const bInner = transB === "no-transpose" ? bCols : bRows;
+  if (ldb < bInner)
+    throw new Error(`ldb must be >= ${effLayoutB === "column-major" ? "rows" : "cols"} of B as stored.`);
+  if (BIsGpu) {
+    if (ldb !== B.lda) throw new Error("ldb must match B.lda when B is a GpuMatrix.");
+    const [bLogRows, bLogCols] = transB === "no-transpose" ? [k, n] : [n, k];
+    if (B.rows < bLogRows || B.cols < bLogCols)
+      throw new Error("B is too small for the given n, k, and transB.");
+  } else if (B.length < (bOuter - 1) * ldb + bInner) {
+    throw new Error("B does not have enough elements for the given dimensions and ldb.");
+  }
+
+  // C: always m x n (no trans flag) — layout only affects lda/storage order.
+  const cOuter = effLayoutC === "column-major" ? n : m;
+  const cInner = effLayoutC === "column-major" ? m : n;
+  if (ldc < cInner)
+    throw new Error(`ldc must be >= ${effLayoutC === "column-major" ? "rows" : "cols"} of C as stored.`);
+  if (CIsGpu) {
+    if (ldc !== C.lda) throw new Error("ldc must match C.lda when C is a GpuMatrix.");
+    if (C.rows < m || C.cols < n) throw new Error("C is too small for the given m and n.");
+  } else if (C.length < (cOuter - 1) * ldc + cInner) {
+    throw new Error("C does not have enough elements for the given dimensions and ldc.");
+  }
+
+  // Column-major A/B reinterpreted row-major is A^T/B^T — flip the trans flag.
+  if (effLayoutA === "column-major")
+    transA = transA === "no-transpose" ? "transpose" : "no-transpose";
+  if (effLayoutB === "column-major")
+    transB = transB === "no-transpose" ? "transpose" : "no-transpose";
+
+  // Column-major C: compute C^T = op(B)^T * op(A)^T instead (swap A/B, flip trans, swap m<->n).
+  if (effLayoutC === "column-major") {
+    [A, B] = [B, A];
+    [AIsGpu, BIsGpu] = [BIsGpu, AIsGpu];
+    [lda, ldb] = [ldb, lda];
+    [transA, transB] = [
+      transB === "no-transpose" ? "transpose" : "no-transpose",
+      transA === "no-transpose" ? "transpose" : "no-transpose",
+    ];
+    [m, n] = [n, m];
+  }
+
+  // Shape-based auto-select — see sgemm_small.wgsl/sgemm_large.wgsl.
+  const largeWgX = Math.ceil(n / BN_LARGE);
+  const largeWgY = Math.ceil(m / BM_LARGE);
+  const useLargeTile = largeWgX * largeWgY >= LARGE_TILE_WORKGROUP_THRESHOLD;
+
+  const pipeline = await getPipeline(device, useLargeTile ? "sgemm_large" : "sgemm_small");
+
+  const ABuffer = AIsGpu ? A._buf : uploadBuffer(device, A, "sgemm-A", false);
+  const BBuffer = BIsGpu ? B._buf : uploadBuffer(device, B, "sgemm-B", false);
+  const CBuffer = CIsGpu ? C._buf : uploadBuffer(device, C, "sgemm-C", true);
+  // Vectorized-load enablement — kernel-side view after the column-major swap.
+  // op(A) is m×k (no-trans) or k×m (trans); op(B) is k×n or n×k.
+  const aNot = transA === "no-transpose";
+  const bNot = transB === "no-transpose";
+  const useVecA = aNot && vec4Usable(ABuffer, lda, m, k); // transposed-A vec stores bank-conflict smem — measured slower than scalar
+  const useVecB = vec4Usable(BBuffer, ldb, bNot ? k : n, bNot ? n : k);
+  const paramsBuffer = createParamsBuffer(device,
+    [
+      { value: m,   type: "u32" },
+      { value: n,   type: "u32" },
+      { value: k,   type: "u32" },
+      { value: alpha, type: "f32" },
+      { value: beta,  type: "f32" },
+      { value: lda, type: "u32" },
+      { value: ldb, type: "u32" },
+      { value: ldc, type: "u32" },
+      { value: transA === "transpose" ? 1 : 0, type: "u32" },
+      { value: transB === "transpose" ? 1 : 0, type: "u32" },
+      { value: useVecA ? 1 : 0, type: "u32" },
+      { value: useVecB ? 1 : 0, type: "u32" },
+    ],
+    "sgemm-params",
+  );
+
+  try {
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
+      ABuffer,
+      vec4ViewBinding(device, ABuffer),
+      BBuffer,
+      vec4ViewBinding(device, BBuffer),
+      CBuffer,
+      paramsBuffer,
+    ]);
+
+    const wgCount = useLargeTile
+      ? {
+        x: requireWorkgroupCount(device, largeWgX, "sgemm", "x"),
+        y: requireWorkgroupCount(device, largeWgY, "sgemm", "y"),
+      }
+      : {
+        x: requireWorkgroupCount(device, Math.ceil(n / BN_SMALL), "sgemm", "x"),
+        y: requireWorkgroupCount(device, Math.ceil(m / BM_SMALL), "sgemm", "y"),
+      };
+    const { commandEncoder, ts } = runComputePass(device, pipeline, bindGroup, wgCount);
+    const readBuffer = CIsGpu ? null : stageReadback(device, commandEncoder, CBuffer);
+
+    submit(device, commandEncoder);
+
+    const gpuTimeMs = await extractTimestamp(ts);
+
+    if (CIsGpu) {
+      if (gpuTimeMs !== undefined) return { gpuTimeMs };
+      return {};
+    }
+
+    const result = await extractResult(readBuffer, Float32Array);
+    if (gpuTimeMs !== undefined) return { C: result, gpuTimeMs };
+    return { C: result };
+  } finally {
+    if (!AIsGpu) destroyBuffers(ABuffer);
+    if (!BIsGpu) destroyBuffers(BBuffer);
+    if (!CIsGpu) destroyBuffers(CBuffer);
+    destroyBuffers(paramsBuffer);
+  }
+}

package/src/sgemmtr/sgemmtr.d.mts

@@ -0,0 +1,104 @@
+import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+
+/**
+ * Performs the matrix-matrix operation C := uplo(alpha * op(A) * op(B) + beta * C) —
+ * `sgemm`'s operation, but only the triangle of C named by `uplo` is read or
+ * written (`'lower'`: `col <= row`, `'upper'`: `col >= row`; C need not be
+ * square — the test applies over the full m×n grid).
+ *
+ * Same kernels as `sgemm` (`sgemmtr_small.wgsl`/`sgemmtr_large.wgsl`,
+ * identical tiling), with the final output write masked to one triangle.
+ *
+ * {@includeCode ../../examples/sgemmtr/sgemmtr.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/sgemmtr/web/sgemmtr.html}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param uplo   - `'lower'` to update only `col <= row`, `'upper'` for `col >= row`
+ * @param transA - `'no-transpose'` for A, `'transpose'` for A^T
+ * @param transB - `'no-transpose'` for B, `'transpose'` for B^T
+ * @param m      - rows of op(A) and C
+ * @param n      - columns of op(B) and C
+ * @param k      - columns of op(A), rows of op(B)
+ * @param alpha  - scalar multiplier for op(A)*op(B)
+ * @param A      - Float32Array, row-major or column-major (see `layout`)
+ * @param lda    - leading dimension of A as stored
+ * @param B      - Float32Array, row-major or column-major (see `layout`)
+ * @param ldb    - leading dimension of B as stored
+ * @param beta   - scalar multiplier for C
+ * @param C      - Float32Array input/output matrix, row-major or column-major
+ * @param ldc    - leading dimension of C as stored
+ * @param layout - storage layout shared by A/B/C when they're Float32Array
+ *   (default: `'row-major'`) — same handling as `sgemm`, plus `uplo` is
+ *   flipped internally for column-major C so it still names the triangle
+ *   you asked for
+ * @returns updated C as a Float32Array (only the requested triangle changed)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/sgemmtr/sgemmtr.mjs#L19">Source code: sgemmtr.mjs (L19)</a>
+ * @category BLAS Level 3
+ */
+export declare function sgemmtr(
+  device: GPUDevice,
+  uplo: 'lower' | 'upper',
+  transA: 'no-transpose' | 'transpose',
+  transB: 'no-transpose' | 'transpose',
+  m: number,
+  n: number,
+  k: number,
+  alpha: number,
+  A: Float32Array,
+  lda: number,
+  B: Float32Array,
+  ldb: number,
+  beta: number,
+  C: Float32Array,
+  ldc: number,
+  layout?: 'row-major' | 'column-major',
+): Promise<{ C: Float32Array; gpuTimeMs?: number }>;
+
+/**
+ * Performs the matrix-matrix operation C := uplo(alpha * op(A) * op(B) + beta * C)
+ *
+ * A, B, and C are all kept GPU-resident. Each matrix's own `layout` (set at
+ * `GpuMatrix.from` time) determines the operation — there is no separate
+ * `layout` argument here. A and B must be GpuMatrix whenever C is, and vice
+ * versa — mixing a GpuMatrix with a plain Float32Array is not supported.
+ *
+ * {@includeCode ../../examples/sgemmtr/gpu.sgemmtr.js}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param uplo   - `'lower'` to update only `col <= row`, `'upper'` for `col >= row`
+ * @param transA - `'no-transpose'` for A, `'transpose'` for A^T
+ * @param transB - `'no-transpose'` for B, `'transpose'` for B^T
+ * @param m      - rows of op(A) and C
+ * @param n      - columns of op(B) and C
+ * @param k      - columns of op(A), rows of op(B)
+ * @param alpha  - scalar multiplier for op(A)*op(B)
+ * @param A      - GpuMatrix
+ * @param lda    - leading dimension of A (must equal A.lda)
+ * @param B      - GpuMatrix
+ * @param ldb    - leading dimension of B (must equal B.lda)
+ * @param beta   - scalar multiplier for C
+ * @param C      - GpuMatrix (mutated in place; only the requested triangle changes)
+ * @param ldc    - leading dimension of C (must equal C.lda)
+ * @returns no C — it stays GPU-resident; call `C.read()` yourself for a CPU readback (see the example)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/sgemmtr/sgemmtr.mjs#L19">Source code: sgemmtr.mjs (L19)</a>
+ * @category BLAS Level 3
+ */
+export declare function sgemmtr(
+  device: GPUDevice,
+  uplo: 'lower' | 'upper',
+  transA: 'no-transpose' | 'transpose',
+  transB: 'no-transpose' | 'transpose',
+  m: number,
+  n: number,
+  k: number,
+  alpha: number,
+  A: GpuMatrix,
+  lda: number,
+  B: GpuMatrix,
+  ldb: number,
+  beta: number,
+  C: GpuMatrix,
+  ldc: number,
+): Promise<{ gpuTimeMs?: number }>;