wgblas 2.1.0 → 2.2.0

package/src/ssymv/ssymv.mjs

@@ -11,15 +11,27 @@ 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";
+import { requireGpuDevice, requireSameDevice } from "../util/device.mjs";
 
-export async function ssymv(device, uplo, n, alpha, A, lda, x, incx, beta, y, incy, layout = "row-major") {
+export async function ssymv(
+  device,
+  uplo,
+  n,
+  alpha,
+  A,
+  lda,
+  x,
+  incx,
+  beta,
+  y,
+  incy,
+  layout = "row-major",
+) {
   const xIsGpu = x instanceof GpuVector;
   const yIsGpu = y instanceof GpuVector;
   const AIsGpu = A instanceof GpuMatrix;
 
-  if (!(device instanceof GPUDevice))
-    throw new Error("device must be a GPUDevice.");
+  requireGpuDevice(device);
   requireSameDevice(device, "ssymv", { A, x, y });
   if (uplo !== "lower" && uplo !== "upper")
     throw new Error("uplo must be 'lower' or 'upper'.");
@@ -32,12 +44,10 @@ export async function ssymv(device, uplo, n, alpha, A, lda, x, incx, beta, y, in
     !Number.isInteger(lda)
   )
     throw new Error("n, incx, incy, and lda must be integers.");
-  if (typeof alpha !== "number")
-    throw new Error("alpha must be a number.");
+  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 (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 (incx <= 0 || incy <= 0)
@@ -58,7 +68,9 @@ export async function ssymv(device, uplo, n, alpha, A, lda, x, incx, beta, y, in
   if (AIsGpu && !xIsGpu)
     throw new Error("x and y must be GpuVectors when A is a GpuMatrix.");
   if (xIsGpu && x._buf === y._buf)
-    throw new Error("x and y must not reference the same GPU buffer when both are GpuVectors.");
+    throw new Error(
+      "x and y must not reference the same GPU buffer when both are GpuVectors.",
+    );
   if (AIsGpu && lda !== A.lda)
     throw new Error("lda must match A.lda when A is a GpuMatrix.");
   if (AIsGpu && (A.rows < n || A.cols < n))
@@ -67,9 +79,7 @@ export async function ssymv(device, uplo, n, alpha, A, lda, x, incx, beta, y, in
   if (n === 0) return yIsGpu ? {} : { y };
 
   if (!AIsGpu && A.length < (n - 1) * lda + n)
-    throw new Error(
-      "A does not have enough elements for the given n and lda.",
-    );
+    throw new Error("A does not have enough elements for the given n and lda.");
   if (x.length < (n - 1) * incx + 1)
     throw new Error(
       "x does not have enough elements for the given n and incx.",
@@ -81,7 +91,8 @@ export async function ssymv(device, uplo, n, alpha, A, lda, x, incx, beta, y, in
 
   // GpuMatrix's own layout wins over the argument; A is symmetric, so column-major A reinterpreted row-major just flips which triangle is stored — flip uplo to match.
   const effLayout = AIsGpu ? A.layout : layout;
-  const isLower = effLayout === "column-major" ? uplo === "upper" : uplo === "lower";
+  const isLower =
+    effLayout === "column-major" ? uplo === "upper" : uplo === "lower";
 
   const pipeline = await getPipeline(device, "ssymv");
 
@@ -94,14 +105,15 @@ export async function ssymv(device, uplo, n, alpha, A, lda, x, incx, beta, y, in
     ABuffer = AIsGpu ? A._buf : uploadBuffer(device, A, "ssymv-A", false);
     xBuffer = xIsGpu ? x._buf : uploadBuffer(device, x, "ssymv-x", false);
     yBuffer = yIsGpu ? y._buf : uploadBuffer(device, y, "ssymv-y", true);
-    paramsBuffer = createParamsBuffer(device,
+    paramsBuffer = createParamsBuffer(
+      device,
       [
-        { value: n,               type: "u32" },
-        { value: alpha,           type: "f32" },
-        { value: beta,            type: "f32" },
-        { value: incx,            type: "u32" },
-        { value: incy,            type: "u32" },
-        { value: lda,             type: "u32" },
+        { value: n, type: "u32" },
+        { value: alpha, type: "f32" },
+        { value: beta, type: "f32" },
+        { value: incx, type: "u32" },
+        { value: incy, type: "u32" },
+        { value: lda, type: "u32" },
         { value: isLower ? 0 : 1, type: "u32" },
       ],
       "ssymv-params",
@@ -115,8 +127,15 @@ export async function ssymv(device, uplo, n, alpha, A, lda, x, incx, beta, y, in
     ]);
 
     const wgCount = Math.min(n, device.limits.maxComputeWorkgroupsPerDimension);
-    const { commandEncoder, ts } = runComputePass(device, pipeline, bindGroup, wgCount);
-    const readBuffer = yIsGpu ? null : stageReadback(device, commandEncoder, yBuffer);
+    const { commandEncoder, ts } = runComputePass(
+      device,
+      pipeline,
+      bindGroup,
+      wgCount,
+    );
+    const readBuffer = yIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, yBuffer);
 
     submit(device, commandEncoder);
 
@@ -136,4 +155,4 @@ export async function ssymv(device, uplo, n, alpha, A, lda, x, incx, beta, y, in
     if (!yIsGpu && yBuffer) destroyBuffers(yBuffer);
     if (paramsBuffer) destroyBuffers(paramsBuffer);
   }
-}
+}

package/src/ssyr/ssyr.d.mts

@@ -2,7 +2,7 @@ import { GpuVector } from "../classes/GpuVector.mjs";
 import { GpuMatrix } from "../classes/GpuMatrix.mjs";
 
 /**
- * Performs the symmetric rank-1 update A = alpha * x * x^T + A
+ * Performs the symmetric rank-1 update $$A \leftarrow \alpha x x^{T} + A$$
  *
  * A is an n×n symmetric matrix stored in row-major order, updated in place.
  * Only the triangle specified by `uplo` is referenced and updated; the other
@@ -40,7 +40,7 @@ export declare function ssyr(
 ): Promise<{ A: Float32Array; gpuTimeMs?: number }>;
 
 /**
- * Performs the symmetric rank-1 update A = alpha * x * x^T + A
+ * Performs the symmetric rank-1 update $$A \leftarrow \alpha x x^{T} + A$$
  *
  * x and A are both kept resident on the GPU. `A`'s own `layout` (set at
  * `GpuMatrix.from` time) determines the operation — there is no separate

package/src/ssyr/ssyr.mjs

@@ -11,14 +11,23 @@ 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";
+import { requireGpuDevice, requireSameDevice } from "../util/device.mjs";
 
-export async function ssyr(device, uplo, n, alpha, x, incx, A, lda, layout = "row-major") {
+export async function ssyr(
+  device,
+  uplo,
+  n,
+  alpha,
+  x,
+  incx,
+  A,
+  lda,
+  layout = "row-major",
+) {
   const xIsGpu = x instanceof GpuVector;
   const AIsGpu = A instanceof GpuMatrix;
 
-  if (!(device instanceof GPUDevice))
-    throw new Error("device must be a GPUDevice.");
+  requireGpuDevice(device);
   requireSameDevice(device, "ssyr", { A, x });
   if (uplo !== "lower" && uplo !== "upper")
     throw new Error("uplo must be 'lower' or 'upper'.");
@@ -26,8 +35,7 @@ export async function ssyr(device, uplo, n, alpha, x, incx, A, lda, layout = "ro
     throw new Error("layout must be 'row-major' or 'column-major'.");
   if (!Number.isInteger(n) || !Number.isInteger(incx) || !Number.isInteger(lda))
     throw new Error("n, incx, and lda must be integers.");
-  if (typeof alpha !== "number")
-    throw new Error("alpha must be a number.");
+  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 (incx <= 0) throw new Error("incx must be positive.");
@@ -52,11 +60,14 @@ export async function ssyr(device, uplo, n, alpha, x, incx, A, lda, layout = "ro
   if (!AIsGpu && A.length < (n - 1) * lda + n)
     throw new Error("A does not have enough elements for the given n and lda.");
   if (x.length < (n - 1) * incx + 1)
-    throw new Error("x does not have enough elements for the given n and incx.");
+    throw new Error(
+      "x does not have enough elements for the given n and incx.",
+    );
 
   // GpuMatrix's own layout wins over the argument; A is symmetric, so column-major A reinterpreted row-major just flips which triangle is stored — flip uplo to match.
   const effLayout = AIsGpu ? A.layout : layout;
-  const isLower = effLayout === "column-major" ? uplo === "upper" : uplo === "lower";
+  const isLower =
+    effLayout === "column-major" ? uplo === "upper" : uplo === "lower";
 
   const pipeline = await getPipeline(device, "ssyr");
 
@@ -67,12 +78,13 @@ export async function ssyr(device, uplo, n, alpha, x, incx, A, lda, layout = "ro
   try {
     xBuffer = xIsGpu ? x._buf : uploadBuffer(device, x, "ssyr-x", false);
     ABuffer = AIsGpu ? A._buf : uploadBuffer(device, A, "ssyr-A", true);
-    paramsBuffer = createParamsBuffer(device,
+    paramsBuffer = createParamsBuffer(
+      device,
       [
-        { value: n,               type: "u32" },
-        { value: alpha,           type: "f32" },
-        { value: incx,            type: "u32" },
-        { value: lda,             type: "u32" },
+        { value: n, type: "u32" },
+        { value: alpha, type: "f32" },
+        { value: incx, type: "u32" },
+        { value: lda, type: "u32" },
         { value: isLower ? 0 : 1, type: "u32" },
       ],
       "ssyr-params",
@@ -87,8 +99,15 @@ export async function ssyr(device, uplo, n, alpha, x, incx, A, lda, layout = "ro
     // 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(device, pipeline, bindGroup, wgCount);
-    const readBuffer = AIsGpu ? null : stageReadback(device, commandEncoder, ABuffer);
+    const { commandEncoder, ts } = runComputePass(
+      device,
+      pipeline,
+      bindGroup,
+      wgCount,
+    );
+    const readBuffer = AIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, ABuffer);
 
     submit(device, commandEncoder);
 

package/src/ssyr2/ssyr2.d.mts

@@ -2,7 +2,7 @@ import { GpuVector } from "../classes/GpuVector.mjs";
 import { GpuMatrix } from "../classes/GpuMatrix.mjs";
 
 /**
- * Performs the symmetric rank-2 update A = alpha * x * y^T + alpha * y * x^T + A
+ * Performs the symmetric rank-2 update $$A \leftarrow \alpha x y^{T} + \alpha y x^{T} + A$$
  *
  * A is an n×n symmetric matrix stored in row-major order, updated in place.
  * Only the triangle specified by `uplo` is referenced and updated; the other
@@ -44,7 +44,7 @@ export declare function ssyr2(
 ): Promise<{ A: Float32Array; gpuTimeMs?: number }>;
 
 /**
- * Performs the symmetric rank-2 update A = alpha * x * y^T + alpha * y * x^T + A
+ * Performs the symmetric rank-2 update $$A \leftarrow \alpha x y^{T} + \alpha y x^{T} + A$$
  *
  * x, y, and A are all kept resident on the GPU. `A`'s own `layout` (set at
  * `GpuMatrix.from` time) determines the operation — there is no separate

package/src/ssyr2/ssyr2.mjs

@@ -11,15 +11,26 @@ 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";
+import { requireGpuDevice, requireSameDevice } from "../util/device.mjs";
 
-export async function ssyr2(device, uplo, n, alpha, x, incx, y, incy, A, lda, layout = "row-major") {
+export async function ssyr2(
+  device,
+  uplo,
+  n,
+  alpha,
+  x,
+  incx,
+  y,
+  incy,
+  A,
+  lda,
+  layout = "row-major",
+) {
   const xIsGpu = x instanceof GpuVector;
   const yIsGpu = y instanceof GpuVector;
   const AIsGpu = A instanceof GpuMatrix;
 
-  if (!(device instanceof GPUDevice))
-    throw new Error("device must be a GPUDevice.");
+  requireGpuDevice(device);
   requireSameDevice(device, "ssyr2", { A, x, y });
   if (uplo !== "lower" && uplo !== "upper")
     throw new Error("uplo must be 'lower' or 'upper'.");
@@ -32,8 +43,7 @@ export async function ssyr2(device, uplo, n, alpha, x, incx, y, incy, A, lda, la
     !Number.isInteger(lda)
   )
     throw new Error("n, incx, incy, and lda must be integers.");
-  if (typeof alpha !== "number")
-    throw new Error("alpha must be a number.");
+  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 (incx <= 0 || incy <= 0)
@@ -58,7 +68,9 @@ export async function ssyr2(device, uplo, n, alpha, x, incx, y, incy, A, lda, la
   if (AIsGpu && yIsGpu && A._buf === y._buf)
     throw new Error("A and y must not reference the same GPU buffer.");
   if (xIsGpu && x._buf === y._buf)
-    throw new Error("x and y must not reference the same GPU buffer when both are GpuVectors.");
+    throw new Error(
+      "x and y must not reference the same GPU buffer when both are GpuVectors.",
+    );
   if (AIsGpu && lda !== A.lda)
     throw new Error("lda must match A.lda when A is a GpuMatrix.");
   if (AIsGpu && (A.rows < n || A.cols < n))
@@ -69,13 +81,18 @@ export async function ssyr2(device, uplo, n, alpha, x, incx, y, incy, A, lda, la
   if (!AIsGpu && A.length < (n - 1) * lda + n)
     throw new Error("A does not have enough elements for the given n and lda.");
   if (x.length < (n - 1) * incx + 1)
-    throw new Error("x does not have enough elements for the given n and incx.");
+    throw new Error(
+      "x does not have enough elements for the given n and incx.",
+    );
   if (y.length < (n - 1) * incy + 1)
-    throw new Error("y does not have enough elements for the given n and incy.");
+    throw new Error(
+      "y does not have enough elements for the given n and incy.",
+    );
 
   // GpuMatrix's own layout wins over the argument; A is symmetric, so column-major A reinterpreted row-major just flips which triangle is stored (no x/y swap needed — x*y^T+y*x^T is already symmetric under swapping them).
   const effLayout = AIsGpu ? A.layout : layout;
-  const isLower = effLayout === "column-major" ? uplo === "upper" : uplo === "lower";
+  const isLower =
+    effLayout === "column-major" ? uplo === "upper" : uplo === "lower";
 
   const pipeline = await getPipeline(device, "ssyr2");
 
@@ -88,13 +105,14 @@ export async function ssyr2(device, uplo, n, alpha, x, incx, y, incy, A, lda, la
     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,
+    paramsBuffer = createParamsBuffer(
+      device,
       [
-        { value: n,               type: "u32" },
-        { value: alpha,           type: "f32" },
-        { value: incx,            type: "u32" },
-        { value: incy,            type: "u32" },
-        { value: lda,             type: "u32" },
+        { value: n, type: "u32" },
+        { value: alpha, type: "f32" },
+        { value: incx, type: "u32" },
+        { value: incy, type: "u32" },
+        { value: lda, type: "u32" },
         { value: isLower ? 0 : 1, type: "u32" },
       ],
       "ssyr2-params",
@@ -110,8 +128,15 @@ 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(device, pipeline, bindGroup, wgCount);
-    const readBuffer = AIsGpu ? null : stageReadback(device, commandEncoder, ABuffer);
+    const { commandEncoder, ts } = runComputePass(
+      device,
+      pipeline,
+      bindGroup,
+      wgCount,
+    );
+    const readBuffer = AIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, ABuffer);
 
     submit(device, commandEncoder);
 

package/src/ssyr2k/ssyr2k.d.mts

@@ -2,7 +2,8 @@ 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) —
+ * $$C \leftarrow \mathrm{uplo}(\alpha \mathrm{op}(A) \mathrm{op}(B)^{T} + \alpha \mathrm{op}(B) \mathrm{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.
  *
@@ -57,7 +58,7 @@ export declare function ssyr2k(
 
 /**
  * Performs the symmetric rank-2k update
- * C := uplo(alpha * op(A) * op(B)^T + alpha * op(B) * op(A)^T + beta * C)
+ * $$C \leftarrow \mathrm{uplo}(\alpha \mathrm{op}(A) \mathrm{op}(B)^{T} + \alpha \mathrm{op}(B) \mathrm{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