wgblas 1.2.1 → 2.1.0

package/src/ssyr2/ssyr2.mjs

@@ -11,6 +11,7 @@ import { extractTimestamp } from "../util/benchmark.mjs";
 import { getPipeline } from "../util/pipeline.mjs";
 import { GpuVector } from "../classes/GpuVector.mjs";
 import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+import { requireSameDevice } from "../util/device.mjs";
 
 export async function ssyr2(device, uplo, n, alpha, x, incx, y, incy, A, lda, layout = "row-major") {
   const xIsGpu = x instanceof GpuVector;
@@ -19,6 +20,7 @@ export async function ssyr2(device, uplo, n, alpha, x, incx, y, incy, A, lda, la
 
   if (!(device instanceof GPUDevice))
     throw new Error("device must be a GPUDevice.");
+  requireSameDevice(device, "ssyr2", { A, x, y });
   if (uplo !== "lower" && uplo !== "upper")
     throw new Error("uplo must be 'lower' or 'upper'.");
   if (layout !== "row-major" && layout !== "column-major")
@@ -49,6 +51,8 @@ export async function ssyr2(device, uplo, n, alpha, x, incx, y, incy, A, lda, la
     );
   if (xIsGpu && !AIsGpu)
     throw new Error("A must be a GpuMatrix when x and y are GpuVectors.");
+  if (AIsGpu && !xIsGpu)
+    throw new Error("x and y must be GpuVectors when A is a GpuMatrix.");
   if (AIsGpu && xIsGpu && A._buf === x._buf)
     throw new Error("A and x must not reference the same GPU buffer.");
   if (AIsGpu && yIsGpu && A._buf === y._buf)
@@ -81,10 +85,10 @@ export async function ssyr2(device, uplo, n, alpha, x, incx, y, incy, A, lda, la
   let paramsBuffer = null;
 
   try {
-    xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "ssyr2-x", false);
-    yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "ssyr2-y", false);
-    ABuffer = AIsGpu ? A._buf : uploadBuffer(A, "ssyr2-A", true);
-    paramsBuffer = createParamsBuffer(
+    xBuffer = xIsGpu ? x._buf : uploadBuffer(device, x, "ssyr2-x", false);
+    yBuffer = yIsGpu ? y._buf : uploadBuffer(device, y, "ssyr2-y", false);
+    ABuffer = AIsGpu ? A._buf : uploadBuffer(device, A, "ssyr2-A", true);
+    paramsBuffer = createParamsBuffer(device,
       [
         { value: n,               type: "u32" },
         { value: alpha,           type: "f32" },
@@ -96,7 +100,7 @@ export async function ssyr2(device, uplo, n, alpha, x, incx, y, incy, A, lda, la
       "ssyr2-params",
     );
 
-    const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
       xBuffer,
       yBuffer,
       ABuffer,
@@ -106,10 +110,10 @@ export async function ssyr2(device, uplo, n, alpha, x, incx, y, incy, A, lda, la
     // One workgroup per row of A; clamped to device limit — the shader's
     // grid-stride loop handles remaining rows when n > dispatch count.
     const wgCount = Math.min(n, device.limits.maxComputeWorkgroupsPerDimension);
-    const { commandEncoder, ts } = runComputePass(pipeline, bindGroup, wgCount);
-    const readBuffer = AIsGpu ? null : stageReadback(commandEncoder, ABuffer);
+    const { commandEncoder, ts } = runComputePass(device, pipeline, bindGroup, wgCount);
+    const readBuffer = AIsGpu ? null : stageReadback(device, commandEncoder, ABuffer);
 
-    submit(commandEncoder);
+    submit(device, commandEncoder);
 
     const gpuTimeMs = await extractTimestamp(ts);
 

package/src/ssyr2k/ssyr2k.d.mts

@@ -0,0 +1,100 @@
+import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+
+/**
+ * Performs the symmetric rank-2k update
+ * C := uplo(alpha * op(A) * op(B)^T + alpha * op(B) * op(A)^T + beta * C) —
+ * only the triangle of C named by `uplo` is read or written (`'lower'`:
+ * `col <= row`, `'upper'`: `col >= row`). C is always n×n.
+ *
+ * - `trans='no-transpose'`: op(A) = A, op(B) = B (both n×k)
+ * - `trans='transpose'`:    op(A) = A^T, op(B) = B^T (A, B stored k×n)
+ *
+ * No dedicated kernel — two passes of `sgemmtr`'s kernel
+ * (`sgemmtr_small.wgsl`/`sgemmtr_large.wgsl`) on one command encoder, the
+ * second accumulating with `beta=1` so C never leaves the GPU between them.
+ *
+ * {@includeCode ../../examples/ssyr2k/ssyr2k.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/ssyr2k/web/ssyr2k.html}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param uplo   - `'lower'` to update only `col <= row`, `'upper'` for `col >= row`
+ * @param trans  - `'no-transpose'` for A*B^T + B*A^T, `'transpose'` for A^T*B + B^T*A
+ * @param n      - order of C (C is n×n); rows of op(A) and op(B)
+ * @param k      - columns of op(A) and op(B) — the shared/contracted dimension
+ * @param alpha  - scalar multiplier for both rank-k terms
+ * @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 `sgemmtr`; column-major C
+ *   flips `uplo` internally 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/ssyr2k/ssyr2k.mjs#L20">Source code: ssyr2k.mjs (L20)</a>
+ * @category BLAS Level 3
+ */
+export declare function ssyr2k(
+  device: GPUDevice,
+  uplo: 'lower' | 'upper',
+  trans: 'no-transpose' | 'transpose',
+  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 symmetric rank-2k update
+ * C := uplo(alpha * op(A) * op(B)^T + alpha * op(B) * op(A)^T + 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/ssyr2k/gpu.ssyr2k.js}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param uplo   - `'lower'` to update only `col <= row`, `'upper'` for `col >= row`
+ * @param trans  - `'no-transpose'` for A*B^T + B*A^T, `'transpose'` for A^T*B + B^T*A
+ * @param n      - order of C (C is n×n); rows of op(A) and op(B)
+ * @param k      - columns of op(A) and op(B) — the shared/contracted dimension
+ * @param alpha  - scalar multiplier for both rank-k terms
+ * @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/ssyr2k/ssyr2k.mjs#L20">Source code: ssyr2k.mjs (L20)</a>
+ * @category BLAS Level 3
+ */
+export declare function ssyr2k(
+  device: GPUDevice,
+  uplo: 'lower' | 'upper',
+  trans: 'no-transpose' | 'transpose',
+  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/ssyr2k/ssyr2k.mjs

@@ -0,0 +1,202 @@
+import {
+  uploadBuffer,
+  createParamsBuffer,
+  stageReadback,
+  destroyBuffers,
+} from "../util/buffer.mjs";
+import { createBindGroup } from "../util/bindgroup.mjs";
+import { beginTimedEncoder, encodePass, submit } from "../util/compute.mjs";
+import { extractResult } from "../util/result.mjs";
+import { resolveTimestamp, 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";
+
+
+// ssyr2k: C := uplo(alpha*op(A)*op(B)^T + alpha*op(B)*op(A)^T + beta*C). No
+// dedicated shader — two sgemmtr passes on one encoder, second with beta=1.
+export async function ssyr2k(
+  device, uplo, trans, n, k, alpha, A, lda, B, ldb, beta, C, ldc, layout = "row-major",
+) {
+  const AIsGpu = A instanceof GpuMatrix;
+  const BIsGpu = B instanceof GpuMatrix;
+  const CIsGpu = C instanceof GpuMatrix;
+
+  if (!(device instanceof GPUDevice))
+    throw new Error("device must be a GPUDevice.");
+  requireSameDevice(device, "ssyr2k", { A, B, C });
+  if (uplo !== "lower" && uplo !== "upper")
+    throw new Error("uplo must be 'lower' or 'upper'.");
+  if (trans !== "no-transpose" && trans !== "transpose")
+    throw new Error("trans 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(n) || !Number.isInteger(k) ||
+    !Number.isInteger(lda) || !Number.isInteger(ldb) || !Number.isInteger(ldc)
+  )
+    throw new Error("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 (n < 0 || k < 0) throw new Error("n and k must be non-negative.");
+  if (n === 0) return CIsGpu ? {} : { C };
+
+  const effLayoutA = AIsGpu ? A.layout : layout;
+  const effLayoutB = BIsGpu ? B.layout : layout;
+  const effLayoutC = CIsGpu ? C.layout : layout;
+
+  // A: op(A) is n x k; A itself is n x k or k x n depending on trans.
+  const aRows = effLayoutA === "column-major" ? k : n;
+  const aCols = effLayoutA === "column-major" ? n : k;
+  const aOuter = trans === "no-transpose" ? aRows : aCols;
+  const aInner = trans === "no-transpose" ? aCols : aRows;
+  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] = trans === "no-transpose" ? [n, k] : [k, n];
+    if (A.rows < aLogRows || A.cols < aLogCols)
+      throw new Error("A is too small for the given n, k, and trans.");
+  } 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 shape rule as A — netlib's syr2k shares one trans across both operands.
+  const bRows = effLayoutB === "column-major" ? k : n;
+  const bCols = effLayoutB === "column-major" ? n : k;
+  const bOuter = trans === "no-transpose" ? bRows : bCols;
+  const bInner = trans === "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] = trans === "no-transpose" ? [n, k] : [k, n];
+    if (B.rows < bLogRows || B.cols < bLogCols)
+      throw new Error("B is too small for the given n, k, and trans.");
+  } 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 n x n symmetric — layout only affects storage order, not size.
+  if (ldc < n) throw new Error("ldc must be >= n.");
+  if (CIsGpu) {
+    if (ldc !== C.lda) throw new Error("ldc must match C.lda when C is a GpuMatrix.");
+    if (C.rows < n || C.cols < n) throw new Error("C is too small for the given n.");
+  } else if (C.length < (n - 1) * ldc + n) {
+    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 trans per operand.
+  let effTransA = trans;
+  if (effLayoutA === "column-major")
+    effTransA = effTransA === "no-transpose" ? "transpose" : "no-transpose";
+  let effTransB = trans;
+  if (effLayoutB === "column-major")
+    effTransB = effTransB === "no-transpose" ? "transpose" : "no-transpose";
+
+  const uploEff = effLayoutC === "column-major"
+    ? (uplo === "lower" ? "upper" : "lower")
+    : uplo;
+  const flip = (t) => (t === "no-transpose" ? "transpose" : "no-transpose");
+
+  // One pass: op(X) as-is, op(Y) transposed. transOwnY is explicit, not inferred.
+  function passShape(transOwnX, X, ldX, transOwnY, Y, ldY) {
+    const transX = transOwnX;
+    const transY = flip(transOwnY);
+    if (effLayoutC !== "column-major") return { transX, X, ldX, transY, Y, ldY };
+    return { transX: flip(transY), X: Y, ldX: ldY, transY: flip(transX), Y: X, ldY: ldX };
+  }
+
+  // Shape-based auto-select — see sgemmtr_small.wgsl/sgemmtr_large.wgsl. m=n=n here (square C).
+  const largeWgX = Math.ceil(n / BN_LARGE);
+  const largeWgY = Math.ceil(n / BM_LARGE);
+  const useLargeTile = largeWgX * largeWgY >= LARGE_TILE_WORKGROUP_THRESHOLD;
+  const pipeline = await getPipeline(device, useLargeTile ? "sgemmtr_large" : "sgemmtr_small");
+  const wgCount = useLargeTile
+    ? {
+      x: requireWorkgroupCount(device, largeWgX, "ssyr2k", "x"),
+      y: requireWorkgroupCount(device, largeWgY, "ssyr2k", "y"),
+    }
+    : {
+      x: requireWorkgroupCount(device, Math.ceil(n / BN_SMALL), "ssyr2k", "x"),
+      y: requireWorkgroupCount(device, Math.ceil(n / BM_SMALL), "ssyr2k", "y"),
+    };
+
+  const ABuffer = AIsGpu ? A._buf : uploadBuffer(device, A, "ssyr2k-A", false);
+  const BBuffer = BIsGpu ? B._buf : uploadBuffer(device, B, "ssyr2k-B", false);
+  const CBuffer = CIsGpu ? C._buf : uploadBuffer(device, C, "ssyr2k-C", true);
+  let paramsBuffer1 = null, paramsBuffer2 = null;
+
+  try {
+    const pass1 = passShape(effTransA, ABuffer, lda, effTransB, BBuffer, ldb);
+    const pass2 = passShape(effTransB, BBuffer, ldb, effTransA, ABuffer, lda);
+
+    const makeParams = (p, betaVal) => createParamsBuffer(device,
+      [
+        { value: n,   type: "u32" },
+        { value: n,   type: "u32" },
+        { value: k,   type: "u32" },
+        { value: alpha, type: "f32" },
+        { value: betaVal, type: "f32" },
+        { value: p.ldX, type: "u32" },
+        { value: p.ldY, type: "u32" },
+        { value: ldc, type: "u32" },
+        { value: p.transX === "transpose" ? 1 : 0, type: "u32" },
+        { value: p.transY === "transpose" ? 1 : 0, type: "u32" },
+        { value: uploEff === "upper" ? 1 : 0, type: "u32" },
+      ],
+      "ssyr2k-params",
+    );
+    paramsBuffer1 = makeParams(pass1, beta);
+    paramsBuffer2 = makeParams(pass2, 1.0);
+
+    const bindGroup1 = createBindGroup(device, pipeline.getBindGroupLayout(0), [pass1.X, pass1.Y, CBuffer, paramsBuffer1]);
+    const bindGroup2 = createBindGroup(device, pipeline.getBindGroupLayout(0), [pass2.X, pass2.Y, CBuffer, paramsBuffer2]);
+
+    const { commandEncoder, querySet } = beginTimedEncoder(device);
+    const desc1 = querySet ? { timestampWrites: { querySet, beginningOfPassWriteIndex: 0 } } : undefined;
+    const desc2 = querySet ? { timestampWrites: { querySet, endOfPassWriteIndex: 1 } } : undefined;
+    encodePass(commandEncoder, pipeline, bindGroup1, wgCount, desc1);
+    encodePass(commandEncoder, pipeline, bindGroup2, wgCount, desc2);
+
+    const ts = resolveTimestamp(device, commandEncoder, querySet);
+    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);
+    if (paramsBuffer1) destroyBuffers(paramsBuffer1);
+    if (paramsBuffer2) destroyBuffers(paramsBuffer2);
+  }
+}

package/src/ssyrk/ssyrk.d.mts

@@ -0,0 +1,90 @@
+import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+
+/**
+ * Performs the symmetric rank-k update C := uplo(alpha * op(A) * op(A)^T + beta * C) —
+ * only the triangle of C named by `uplo` is read or written (`'lower'`: `col <= row`,
+ * `'upper'`: `col >= row`). C is always n×n.
+ *
+ * - `trans='no-transpose'`: op(A) = A (n×k), computes alpha*A*A^T + beta*C
+ * - `trans='transpose'`:    op(A) = A^T (A stored k×n), computes alpha*A^T*A + beta*C
+ *
+ * No dedicated kernel — this is `sgemmtr`'s exact kernel
+ * (`sgemmtr_small.wgsl`/`sgemmtr_large.wgsl`) with `A` aliased into both
+ * operand slots (`B := A`).
+ *
+ * {@includeCode ../../examples/ssyrk/ssyrk.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/ssyrk/web/ssyrk.html}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param uplo   - `'lower'` to update only `col <= row`, `'upper'` for `col >= row`
+ * @param trans  - `'no-transpose'` for A*A^T, `'transpose'` for A^T*A
+ * @param n      - order of C (C is n×n); rows of op(A)
+ * @param k      - columns of op(A) — the shared/contracted dimension
+ * @param alpha  - scalar multiplier for op(A)*op(A)^T
+ * @param A      - Float32Array, row-major or column-major (see `layout`)
+ * @param lda    - leading dimension of A 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/C when they're Float32Array
+ *   (default: `'row-major'`) — same handling as `sgemmtr`; column-major C
+ *   flips `uplo` internally 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/ssyrk/ssyrk.mjs#L21">Source code: ssyrk.mjs (L21)</a>
+ * @category BLAS Level 3
+ */
+export declare function ssyrk(
+  device: GPUDevice,
+  uplo: 'lower' | 'upper',
+  trans: 'no-transpose' | 'transpose',
+  n: number,
+  k: number,
+  alpha: number,
+  A: Float32Array,
+  lda: number,
+  beta: number,
+  C: Float32Array,
+  ldc: number,
+  layout?: 'row-major' | 'column-major',
+): Promise<{ C: Float32Array; gpuTimeMs?: number }>;
+
+/**
+ * Performs the symmetric rank-k update C := uplo(alpha * op(A) * op(A)^T + beta * C)
+ *
+ * A and C are both kept GPU-resident. Each matrix's own `layout` (set at
+ * `GpuMatrix.from` time) determines the operation — there is no separate
+ * `layout` argument here. A must be a GpuMatrix whenever C is, and vice
+ * versa — mixing a GpuMatrix with a plain Float32Array is not supported.
+ *
+ * {@includeCode ../../examples/ssyrk/gpu.ssyrk.js}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param uplo   - `'lower'` to update only `col <= row`, `'upper'` for `col >= row`
+ * @param trans  - `'no-transpose'` for A*A^T, `'transpose'` for A^T*A
+ * @param n      - order of C (C is n×n); rows of op(A)
+ * @param k      - columns of op(A) — the shared/contracted dimension
+ * @param alpha  - scalar multiplier for op(A)*op(A)^T
+ * @param A      - GpuMatrix
+ * @param lda    - leading dimension of A (must equal A.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/ssyrk/ssyrk.mjs#L21">Source code: ssyrk.mjs (L21)</a>
+ * @category BLAS Level 3
+ */
+export declare function ssyrk(
+  device: GPUDevice,
+  uplo: 'lower' | 'upper',
+  trans: 'no-transpose' | 'transpose',
+  n: number,
+  k: number,
+  alpha: number,
+  A: GpuMatrix,
+  lda: number,
+  beta: number,
+  C: GpuMatrix,
+  ldc: number,
+): Promise<{ gpuTimeMs?: number }>;

package/src/ssyrk/ssyrk.mjs

@@ -0,0 +1,177 @@
+import {
+  uploadBuffer,
+  createStorageBuffer,
+  createParamsBuffer,
+  stageReadback,
+  destroyBuffers,
+} from "../util/buffer.mjs";
+import { createBindGroup } from "../util/bindgroup.mjs";
+import { beginTimedEncoder, encodePass, submit } from "../util/compute.mjs";
+import { extractResult } from "../util/result.mjs";
+import { resolveTimestamp, 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";
+
+
+// ssyrk: C := uplo(alpha*op(A)*op(A)^T + beta*C). No dedicated shader —
+// sgemmtr's kernel with A duplicated into a separate B buffer (B := A).
+export async function ssyrk(
+  device, uplo, trans, n, k, alpha, A, lda, beta, C, ldc, layout = "row-major",
+) {
+  const AIsGpu = A instanceof GpuMatrix;
+  const CIsGpu = C instanceof GpuMatrix;
+
+  if (!(device instanceof GPUDevice))
+    throw new Error("device must be a GPUDevice.");
+  requireSameDevice(device, "ssyrk", { A, C });
+  if (uplo !== "lower" && uplo !== "upper")
+    throw new Error("uplo must be 'lower' or 'upper'.");
+  if (trans !== "no-transpose" && trans !== "transpose")
+    throw new Error("trans 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(n) || !Number.isInteger(k) || !Number.isInteger(lda) || !Number.isInteger(ldc))
+    throw new Error("n, k, lda, and ldc must be integers.");
+  if (!AIsGpu && !(A instanceof Float32Array))
+    throw new Error("A must be a Float32Array or GpuMatrix.");
+  if (!CIsGpu && !(C instanceof Float32Array))
+    throw new Error("C must be a Float32Array or GpuMatrix.");
+  if (AIsGpu && !CIsGpu)
+    throw new Error("C must be a GpuMatrix when A is a GpuMatrix.");
+  if (CIsGpu && !AIsGpu)
+    throw new Error("A must be a GpuMatrix when C is a GpuMatrix.");
+  if (n < 0 || k < 0) throw new Error("n and k must be non-negative.");
+  if (n === 0) return CIsGpu ? {} : { C };
+
+  // GpuMatrix's own .layout wins over the shared `layout` argument.
+  const effLayoutA = AIsGpu ? A.layout : layout;
+  const effLayoutC = CIsGpu ? C.layout : layout;
+
+  // A: op(A) is n x k; A itself is n x k or k x n depending on trans.
+  const aRows = effLayoutA === "column-major" ? k : n;
+  const aCols = effLayoutA === "column-major" ? n : k;
+  const aOuter = trans === "no-transpose" ? aRows : aCols;
+  const aInner = trans === "no-transpose" ? aCols : aRows;
+  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] = trans === "no-transpose" ? [n, k] : [k, n];
+    if (A.rows < aLogRows || A.cols < aLogCols)
+      throw new Error("A is too small for the given n, k, and trans.");
+  } else if (A.length < (aOuter - 1) * lda + aInner) {
+    throw new Error("A does not have enough elements for the given dimensions and lda.");
+  }
+
+  // C: always n x n symmetric — layout only affects storage order, not size.
+  if (ldc < n) throw new Error("ldc must be >= n.");
+  if (CIsGpu) {
+    if (ldc !== C.lda) throw new Error("ldc must match C.lda when C is a GpuMatrix.");
+    if (C.rows < n || C.cols < n) throw new Error("C is too small for the given n.");
+  } else if (C.length < (n - 1) * ldc + n) {
+    throw new Error("C does not have enough elements for the given dimensions and ldc.");
+  }
+
+  // Column-major A reinterpreted row-major is A^T — flip trans, same trick sgemm/sgemmtr use.
+  let transA = trans;
+  if (effLayoutA === "column-major")
+    transA = transA === "no-transpose" ? "transpose" : "no-transpose";
+  // op(B) := op(A)^T (B is A itself) — opposite of transA.
+  let transB = transA === "no-transpose" ? "transpose" : "no-transpose";
+
+  // Column-major C: same swap trick sgemm/sgemmtr use, simplified since A === B and m=n.
+  let uploEff = uplo;
+  if (effLayoutC === "column-major") {
+    [transA, transB] = [
+      transB === "no-transpose" ? "transpose" : "no-transpose",
+      transA === "no-transpose" ? "transpose" : "no-transpose",
+    ];
+    uploEff = uploEff === "lower" ? "upper" : "lower";
+  }
+
+  // Shape-based auto-select — see sgemmtr_small.wgsl/sgemmtr_large.wgsl. m=n=n here (square C).
+  const largeWgX = Math.ceil(n / BN_LARGE);
+  const largeWgY = Math.ceil(n / BM_LARGE);
+  const useLargeTile = largeWgX * largeWgY >= LARGE_TILE_WORKGROUP_THRESHOLD;
+
+  const pipeline = await getPipeline(device, useLargeTile ? "sgemmtr_large" : "sgemmtr_small");
+
+  const ABuffer = AIsGpu ? A._buf : uploadBuffer(device, A, "ssyrk-A", false);
+  const CBuffer = CIsGpu ? C._buf : uploadBuffer(device, C, "ssyrk-C", true);
+  // B := A, but as a genuinely separate buffer — re-uploaded for Float32Array,
+  // GPU-copied (see below) for GpuMatrix, since the caller owns ABuffer.
+  const BBuffer = AIsGpu
+    ? createStorageBuffer(device, ABuffer.size, "ssyrk-B", GPUBufferUsage.COPY_DST)
+    : uploadBuffer(device, A, "ssyrk-B", false);
+  const paramsBuffer = createParamsBuffer(device,
+    [
+      { value: n,   type: "u32" }, // gemmtr's m
+      { value: n,   type: "u32" }, // gemmtr's n
+      { value: k,   type: "u32" },
+      { value: alpha, type: "f32" },
+      { value: beta,  type: "f32" },
+      { value: lda, type: "u32" }, // gemmtr's lda
+      { value: lda, type: "u32" }, // gemmtr's ldb — B := A, same lda
+      { value: ldc, type: "u32" },
+      { value: transA === "transpose" ? 1 : 0, type: "u32" },
+      { value: transB === "transpose" ? 1 : 0, type: "u32" },
+      { value: uploEff === "upper" ? 1 : 0, type: "u32" },
+    ],
+    "ssyrk-params",
+  );
+
+  try {
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
+      ABuffer,
+      BBuffer,
+      CBuffer,
+      paramsBuffer,
+    ]);
+
+    const wgCount = useLargeTile
+      ? {
+        x: requireWorkgroupCount(device, largeWgX, "ssyrk", "x"),
+        y: requireWorkgroupCount(device, largeWgY, "ssyrk", "y"),
+      }
+      : {
+        x: requireWorkgroupCount(device, Math.ceil(n / BN_SMALL), "ssyrk", "x"),
+        y: requireWorkgroupCount(device, Math.ceil(n / BM_SMALL), "ssyrk", "y"),
+      };
+    // Manual encoder (not runComputePass) so the A->B duplicate copy lands
+    // on the same command encoder, strictly before the compute pass reads B.
+    const { commandEncoder, querySet, passDescriptor } = beginTimedEncoder(device);
+    if (AIsGpu) commandEncoder.copyBufferToBuffer(ABuffer, 0, BBuffer, 0, ABuffer.size);
+    encodePass(commandEncoder, pipeline, bindGroup, wgCount, passDescriptor);
+    const ts = resolveTimestamp(device, commandEncoder, querySet);
+    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);
+    destroyBuffers(BBuffer); // always our own buffer, never the caller's
+    if (!CIsGpu) destroyBuffers(CBuffer);
+    destroyBuffers(paramsBuffer);
+  }
+}