wgblas 2.0.0 → 2.1.0

package/src/strsm/strsm.mjs

@@ -4,19 +4,19 @@ import {
   createStorageBuffer,
   stageReadback,
   destroyBuffers,
+  vec4ViewBinding,
 } 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 { calcWorkgroups } from "../util/workgroup.mjs";
+import { calcWorkgroups, requireWorkgroups, requireWorkgroupCount } from "../util/workgroup.mjs";
 import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+import { BM_SMALL, BN_SMALL, BM_LARGE, BN_LARGE, LARGE_TILE_WORKGROUP_THRESHOLD } from "../util/constants.mjs";
+import { BLOCK_SIZE } from "../util/constants.mjs";
+import { requireSameDevice } from "../util/device.mjs";
 
-const BLOCK_SIZE = 64; // must match strsv_invert_block.wgsl's own constant
-const BM_SMALL = 32, BN_SMALL = 32; // sgemm_small.wgsl's block tile
-const BM_LARGE = 64, BN_LARGE = 64; // sgemm_large.wgsl's block tile
-const LARGE_TILE_WORKGROUP_THRESHOLD = 36; // same threshold sgemm/ssymm/strmm use
 
 // strsm: B := alpha*op(A)^-1*B (side='left') or alpha*B*op(A)^-1 (side='right'),
 // A triangular. Blocked substitution (strsv's own technique, generalized to
@@ -31,6 +31,7 @@ export async function strsm(
 
   if (!(device instanceof GPUDevice))
     throw new Error("device must be a GPUDevice.");
+  requireSameDevice(device, "strsm", { A, B });
   if (side !== "left" && side !== "right")
     throw new Error("side must be 'left' or 'right'.");
   if (uplo !== "lower" && uplo !== "upper")
@@ -103,19 +104,22 @@ export async function strsm(
   const transferPipeline = await getPipeline(device, "block_transfer");
   const scalarPipeline = await getPipeline(device, "sscal");
 
-  const ABuffer = AIsGpu ? A._buf : uploadBuffer(A, "strsm-A", false);
-  const BBuffer = BIsGpu ? B._buf : uploadBuffer(B, "strsm-B", true);
-  const AinvBuffer = createStorageBuffer(numBlocks * BLOCK_SIZE * BLOCK_SIZE * 4, "strsm-Ainv");
+  // Null-init here and allocate inside the try below, so a throw partway
+  // through the sequence still reaches finally with every handle visible
+  // (strsv.mjs is the reference for this pattern).
+  let ABuffer = null;
+  let BBuffer = null;
+  let AinvBuffer = null;
 
   const paramsBuffers = [];
   const scratchBuffers = [];
   function scratch(size, label) {
-    const buf = createStorageBuffer(size, label);
+    const buf = createStorageBuffer(device, size, label);
     scratchBuffers.push(buf);
     return buf;
   }
   function params(entries, label) {
-    const buf = createParamsBuffer(entries, label);
+    const buf = createParamsBuffer(device, entries, label);
     paramsBuffers.push(buf);
     return buf;
   }
@@ -126,6 +130,10 @@ export async function strsm(
   const bScaleLen = (bOuter - 1) * ldb + bInner;
 
   try {
+    ABuffer = AIsGpu ? A._buf : uploadBuffer(device, A, "strsm-A", false);
+    BBuffer = BIsGpu ? B._buf : uploadBuffer(device, B, "strsm-B", true);
+    AinvBuffer = createStorageBuffer(device, numBlocks * BLOCK_SIZE * BLOCK_SIZE * 4, "strsm-Ainv");
+
     // Pre-scale B by alpha once (reuses sscal, so no per-block alpha handling).
     let preScaleBindGroup = null;
     if (alpha !== 1.0) {
@@ -137,7 +145,7 @@ export async function strsm(
         ],
         "strsm-scale-params",
       );
-      preScaleBindGroup = createBindGroup(scalarPipeline.getBindGroupLayout(0), [BBuffer, scaleParams]);
+      preScaleBindGroup = createBindGroup(device, scalarPipeline.getBindGroupLayout(0), [BBuffer, scaleParams]);
     }
 
     // Every diagonal block's inverse, fully parallel, one dispatch, unchanged.
@@ -151,7 +159,7 @@ export async function strsm(
       ],
       "strsm-invert-params",
     );
-    const invertBindGroup = createBindGroup(invertPipeline.getBindGroupLayout(0), [ABuffer, AinvBuffer, invertParams]);
+    const invertBindGroup = createBindGroup(device, invertPipeline.getBindGroupLayout(0), [ABuffer, AinvBuffer, invertParams]);
 
     // Reusable scratch buffers, sized for the worst case, bound at offset 0.
     const Bblock = scratch(BLOCK_SIZE * otherLen * 4, "strsm-Bblock");
@@ -159,15 +167,15 @@ export async function strsm(
     const Aoff = scratch(aOrder * BLOCK_SIZE * 4, "strsm-Aoff");
     const delta = scratch(aOrder * otherLen * 4, "strsm-delta");
 
-    const { commandEncoder, querySet } = beginTimedEncoder();
+    const { commandEncoder, querySet } = beginTimedEncoder(device);
 
     if (alpha === 0) {
       // BLAS: alpha=0 means A is not referenced — skip straight to B:=0.
       const zeroDesc = querySet ? { timestampWrites: { querySet, beginningOfPassWriteIndex: 0, endOfPassWriteIndex: 1 } } : undefined;
-      encodePass(commandEncoder, scalarPipeline, preScaleBindGroup, calcWorkgroups(bScaleLen), zeroDesc);
+      encodePass(commandEncoder, scalarPipeline, preScaleBindGroup, calcWorkgroups(device, bScaleLen), zeroDesc);
     } else {
       if (preScaleBindGroup) {
-        encodePass(commandEncoder, scalarPipeline, preScaleBindGroup, calcWorkgroups(bScaleLen));
+        encodePass(commandEncoder, scalarPipeline, preScaleBindGroup, calcWorkgroups(device, bScaleLen));
       }
       const invertDesc = querySet ? { timestampWrites: { querySet, beginningOfPassWriteIndex: 0 } } : undefined;
       encodePass(commandEncoder, invertPipeline, invertBindGroup, { x: BLOCK_SIZE, y: numBlocks }, invertDesc);
@@ -193,8 +201,8 @@ export async function strsm(
         ],
         "strsm-gather-B-params",
       );
-      const gatherBBindGroup = createBindGroup(transferPipeline.getBindGroupLayout(0), [Bblock, BBuffer, gatherBParams]);
-      encodePass(commandEncoder, transferPipeline, gatherBBindGroup, calcWorkgroups(blockLen, otherLen));
+      const gatherBBindGroup = createBindGroup(device, transferPipeline.getBindGroupLayout(0), [Bblock, BBuffer, gatherBParams]);
+      encodePass(commandEncoder, transferPipeline, gatherBBindGroup, requireWorkgroups(device, "strsm", blockLen, otherLen));
 
       // 2) apply: Xblock := op(Ainv_block) @ Bblock (side='left'), or the
       // transpose-trick equivalent for side='right' (same trick strmm uses).
@@ -218,15 +226,18 @@ export async function strsm(
           ],
           "strsm-apply-params",
         );
-        const applyBindGroup = createBindGroup(gemmPipeline.getBindGroupLayout(0), [
-          { buffer: AinvBuffer, offset: blockIndex * BLOCK_SIZE * BLOCK_SIZE * 4, size: BLOCK_SIZE * BLOCK_SIZE * 4 },
+        const ainvBlock = { buffer: AinvBuffer, offset: blockIndex * BLOCK_SIZE * BLOCK_SIZE * 4, size: BLOCK_SIZE * BLOCK_SIZE * 4 };
+        const applyBindGroup = createBindGroup(device, gemmPipeline.getBindGroupLayout(0), [
+          ainvBlock,
+          vec4ViewBinding(device, ainvBlock),
           Bblock,
+          vec4ViewBinding(device, Bblock),
           Xblock,
           applyParams,
         ]);
         const wg = useLarge
-          ? { x: Math.min(largeWgX, device.limits.maxComputeWorkgroupsPerDimension), y: Math.min(largeWgY, device.limits.maxComputeWorkgroupsPerDimension) }
-          : { x: Math.min(Math.ceil(ng / BN_SMALL), device.limits.maxComputeWorkgroupsPerDimension), y: Math.min(Math.ceil(mg / BM_SMALL), device.limits.maxComputeWorkgroupsPerDimension) };
+          ? { x: requireWorkgroupCount(device, largeWgX, "strsm", "x"), y: requireWorkgroupCount(device, largeWgY, "strsm", "y") }
+          : { x: requireWorkgroupCount(device, Math.ceil(ng / BN_SMALL), "strsm", "x"), y: requireWorkgroupCount(device, Math.ceil(mg / BM_SMALL), "strsm", "y") };
         encodePass(commandEncoder, gemmPipeline, applyBindGroup, wg);
       }
 
@@ -247,9 +258,9 @@ export async function strsm(
         ],
         "strsm-scatter-params",
       );
-      const scatterBindGroup = createBindGroup(transferPipeline.getBindGroupLayout(0), [Xblock, BBuffer, scatterParams]);
+      const scatterBindGroup = createBindGroup(device, transferPipeline.getBindGroupLayout(0), [Xblock, BBuffer, scatterParams]);
       const scatterDesc = isLastPass && !hasRemaining && querySet ? { timestampWrites: { querySet, endOfPassWriteIndex: 1 } } : undefined;
-      encodePass(commandEncoder, transferPipeline, scatterBindGroup, calcWorkgroups(blockLen, otherLen), scatterDesc);
+      encodePass(commandEncoder, transferPipeline, scatterBindGroup, requireWorkgroups(device, "strsm", blockLen, otherLen), scatterDesc);
 
       // 4) trailing update: subtract this block's contribution from B.
       if (!hasRemaining) continue;
@@ -268,8 +279,8 @@ export async function strsm(
         ],
         "strsm-gather-A-params",
       );
-      const gatherABindGroup = createBindGroup(transferPipeline.getBindGroupLayout(0), [Aoff, ABuffer, gatherAParams]);
-      encodePass(commandEncoder, transferPipeline, gatherABindGroup, calcWorkgroups(remCount, blockLen));
+      const gatherABindGroup = createBindGroup(device, transferPipeline.getBindGroupLayout(0), [Aoff, ABuffer, gatherAParams]);
+      encodePass(commandEncoder, transferPipeline, gatherABindGroup, requireWorkgroups(device, "strsm", remCount, blockLen));
 
       {
         const mg = remCount, ng = otherLen, kg = blockLen;
@@ -291,10 +302,17 @@ export async function strsm(
           ],
           "strsm-update-params",
         );
-        const updateBindGroup = createBindGroup(gemmPipeline.getBindGroupLayout(0), [Aoff, Xblock, delta, updateParams]);
+        const updateBindGroup = createBindGroup(device, gemmPipeline.getBindGroupLayout(0), [
+          Aoff,
+          vec4ViewBinding(device, Aoff),
+          Xblock,
+          vec4ViewBinding(device, Xblock),
+          delta,
+          updateParams,
+        ]);
         const wg = useLarge
-          ? { x: Math.min(largeWgX, device.limits.maxComputeWorkgroupsPerDimension), y: Math.min(largeWgY, device.limits.maxComputeWorkgroupsPerDimension) }
-          : { x: Math.min(Math.ceil(ng / BN_SMALL), device.limits.maxComputeWorkgroupsPerDimension), y: Math.min(Math.ceil(mg / BM_SMALL), device.limits.maxComputeWorkgroupsPerDimension) };
+          ? { x: requireWorkgroupCount(device, largeWgX, "strsm", "x"), y: requireWorkgroupCount(device, largeWgY, "strsm", "y") }
+          : { x: requireWorkgroupCount(device, Math.ceil(ng / BN_SMALL), "strsm", "x"), y: requireWorkgroupCount(device, Math.ceil(mg / BM_SMALL), "strsm", "y") };
         encodePass(commandEncoder, gemmPipeline, updateBindGroup, wg);
       }
 
@@ -311,16 +329,16 @@ export async function strsm(
         ],
         "strsm-scatter-sub-params",
       );
-      const scatterSubBindGroup = createBindGroup(transferPipeline.getBindGroupLayout(0), [delta, BBuffer, scatterSubParams]);
+      const scatterSubBindGroup = createBindGroup(device, transferPipeline.getBindGroupLayout(0), [delta, BBuffer, scatterSubParams]);
       const subDesc = isLastPass && querySet ? { timestampWrites: { querySet, endOfPassWriteIndex: 1 } } : undefined;
-      encodePass(commandEncoder, transferPipeline, scatterSubBindGroup, calcWorkgroups(remCount, otherLen), subDesc);
+      encodePass(commandEncoder, transferPipeline, scatterSubBindGroup, requireWorkgroups(device, "strsm", remCount, otherLen), subDesc);
       }
     }
 
-    const ts = resolveTimestamp(commandEncoder, querySet);
-    const readBuffer = BIsGpu ? null : stageReadback(commandEncoder, BBuffer);
+    const ts = resolveTimestamp(device, commandEncoder, querySet);
+    const readBuffer = BIsGpu ? null : stageReadback(device, commandEncoder, BBuffer);
 
-    submit(commandEncoder);
+    submit(device, commandEncoder);
 
     const gpuTimeMs = await extractTimestamp(ts);
 
@@ -333,9 +351,9 @@ export async function strsm(
     if (gpuTimeMs !== undefined) return { B: result, gpuTimeMs };
     return { B: result };
   } finally {
-    if (!AIsGpu) destroyBuffers(ABuffer);
-    if (!BIsGpu) destroyBuffers(BBuffer);
-    destroyBuffers(AinvBuffer);
+    if (!AIsGpu && ABuffer) destroyBuffers(ABuffer);
+    if (!BIsGpu && BBuffer) destroyBuffers(BBuffer);
+    if (AinvBuffer) destroyBuffers(AinvBuffer);
     destroyBuffers(scratchBuffers);
     destroyBuffers(paramsBuffers);
   }

package/src/strsv/strsv.mjs

@@ -12,9 +12,10 @@ import { resolveTimestamp, extractTimestamp } from "../util/benchmark.mjs";
 import { getPipeline } from "../util/pipeline.mjs";
 import { GpuVector } from "../classes/GpuVector.mjs";
 import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+import { BLOCK_SIZE } from "../util/constants.mjs";
+import { requireSameDevice } from "../util/device.mjs";
 
 // Blocked triangular solve via explicit block inversion (invert/apply/update passes) instead of barrier-per-row substitution.
-const BLOCK_SIZE = 64;
 
 // One shared buffer holds all blocks' params (offset blockIndex*stride) instead of one buffer per block — avoids the O(numBlocks) createBuffer/writeBuffer calls that dominated CPU time.
 function packBlockParams(numBlocks, stride, fieldsPerBlock) {
@@ -45,6 +46,7 @@ export async function strsv(device, uplo, trans, diag, n, A, lda, x, incx, layou
 
   if (!(device instanceof GPUDevice))
     throw new Error("device must be a GPUDevice.");
+  requireSameDevice(device, "strsv", { A, x });
   if (uplo !== "lower" && uplo !== "upper")
     throw new Error("uplo must be 'lower' or 'upper'.");
   if (trans !== "no-transpose" && trans !== "transpose")
@@ -65,6 +67,8 @@ export async function strsv(device, uplo, trans, diag, n, A, lda, x, incx, layou
     throw new Error("A must be a GpuMatrix when x is a GpuVector.");
   if (AIsGpu && !xIsGpu)
     throw new Error("x must be a GpuVector 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 && lda !== A.lda)
     throw new Error("lda must match A.lda when A is a GpuMatrix.");
   if (AIsGpu && (A.rows < n || A.cols < n))
@@ -109,11 +113,11 @@ export async function strsv(device, uplo, trans, diag, n, A, lda, x, incx, layou
   let invertParams = null;
 
   try {
-    ABuffer = AIsGpu ? A._buf : uploadBuffer(A, "strsv-A", false);
-    xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "strsv-x", true);
+    ABuffer = AIsGpu ? A._buf : uploadBuffer(device, A, "strsv-A", false);
+    xBuffer = xIsGpu ? x._buf : uploadBuffer(device, x, "strsv-x", true);
     // One BLOCK_SIZE x BLOCK_SIZE dense region per block (row-major), even
     // though only a triangular half is ever nonzero — see strsv_invert_block.wgsl.
-    AinvBuffer = createStorageBuffer(
+    AinvBuffer = createStorageBuffer(device,
       numBlocks * BLOCK_SIZE * BLOCK_SIZE * 4,
       "strsv-Ainv",
     );
@@ -135,10 +139,10 @@ export async function strsv(device, uplo, trans, diag, n, A, lda, x, incx, layou
     });
     updateParamsBuffer = createSharedParamsBuffer(device, updateData, "strsv-update-params");
 
-    const { commandEncoder, querySet } = beginTimedEncoder();
+    const { commandEncoder, querySet } = beginTimedEncoder(device);
 
     // Pre-pass: every block's inverse, fully parallel, one dispatch.
-    invertParams = createParamsBuffer(
+    invertParams = createParamsBuffer(device,
       [
         { value: n,                 type: "u32" },
         { value: lda,               type: "u32" },
@@ -148,7 +152,7 @@ export async function strsv(device, uplo, trans, diag, n, A, lda, x, incx, layou
       ],
       "strsv-invert-params",
     );
-    const invertBindGroup = createBindGroup(invertPipeline.getBindGroupLayout(0), [
+    const invertBindGroup = createBindGroup(device, invertPipeline.getBindGroupLayout(0), [
       ABuffer, AinvBuffer, invertParams,
     ]);
     const invertDesc = querySet
@@ -163,7 +167,7 @@ export async function strsv(device, uplo, trans, diag, n, A, lda, x, incx, layou
       const isLastPass = bi === blockStarts.length - 1;
       const paramsOffset = blockIndex * stride;
 
-      const applyBindGroup = createBindGroup(applyPipeline.getBindGroupLayout(0), [
+      const applyBindGroup = createBindGroup(device, applyPipeline.getBindGroupLayout(0), [
         AinvBuffer, xBuffer, { buffer: applyParamsBuffer, offset: paramsOffset, size: 16 },
       ]);
 
@@ -175,7 +179,7 @@ export async function strsv(device, uplo, trans, diag, n, A, lda, x, incx, layou
       const remaining = forward ? n - blockEnd : blockStart;
       if (remaining === 0) continue;
 
-      const updateBindGroup = createBindGroup(updatePipeline.getBindGroupLayout(0), [
+      const updateBindGroup = createBindGroup(device, updatePipeline.getBindGroupLayout(0), [
         ABuffer, xBuffer, { buffer: updateParamsBuffer, offset: paramsOffset, size: 32 },
       ]);
 
@@ -183,10 +187,10 @@ export async function strsv(device, uplo, trans, diag, n, A, lda, x, incx, layou
       encodePass(commandEncoder, updatePipeline, updateBindGroup, wgCount);
     }
 
-    const ts = resolveTimestamp(commandEncoder, querySet);
-    const readBuffer = xIsGpu ? null : stageReadback(commandEncoder, xBuffer);
+    const ts = resolveTimestamp(device, commandEncoder, querySet);
+    const readBuffer = xIsGpu ? null : stageReadback(device, commandEncoder, xBuffer);
 
-    submit(commandEncoder);
+    submit(device, commandEncoder);
 
     const gpuTimeMs = await extractTimestamp(ts);
 

package/src/util/benchmark.mjs

@@ -1,5 +1,5 @@
 /** @module devdocs/utility-functions/benchmark */
-import { getDevice, isBenchmarkEnabled } from "../init.mjs";
+import { isBenchmarkEnabled } from "../init.mjs";
 
 /**
  * Returns the `requestDevice` descriptor to pass to `adapter.requestDevice()`.
@@ -29,10 +29,9 @@ export function benchmarkMode(adapter, enabled) {
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUQuerySet GPUQuerySet}
  * @see {@link https://developer.chrome.com/blog/new-in-webgpu-121 Chrome 121 — timestamp queries (querySet + timestampWrites pattern, quantization caveat)}
  */
-export function beginTimestamp() {
-  if (!isBenchmarkEnabled())
+export function beginTimestamp(device) {
+  if (!isBenchmarkEnabled(device))
     return { querySet: null, passDescriptor: undefined };
-  const device = getDevice();
   // Two slots: index 0 written when the pass begins, index 1 when it ends.
   const querySet = device.createQuerySet({ type: "timestamp", count: 2 });
   const passDescriptor = {
@@ -55,9 +54,8 @@ export function beginTimestamp() {
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUCommandEncoder/resolveQuerySet GPUCommandEncoder.resolveQuerySet()}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUCommandEncoder/copyBufferToBuffer GPUCommandEncoder.copyBufferToBuffer()}
  */
-export function resolveTimestamp(commandEncoder, querySet) {
+export function resolveTimestamp(device, commandEncoder, querySet) {
   if (!querySet) return null;
-  const device = getDevice();
   // QUERY_RESOLVE and MAP_READ cannot be combined — two buffers are required.
   // resolveBuffer: GPU writes resolved nanosecond timestamps here.
   const resolveBuffer = device.createBuffer({

package/src/util/bindgroup.mjs

@@ -1,5 +1,4 @@
 /** @module devdocs/utility-functions/bindgroup */
-import { getDevice } from "../init.mjs";
 
 /**
  * Creates a `GPUBindGroup` by mapping each buffer to sequential binding indices
@@ -16,8 +15,7 @@ import { getDevice } from "../init.mjs";
  * @returns {GPUBindGroup}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createBindGroup GPUDevice.createBindGroup()}
  */
-export function createBindGroup(layout, buffers, startBinding = 0) {
-  const device = getDevice();
+export function createBindGroup(device, layout, buffers, startBinding = 0) {
   const entries = buffers.map((buffer, i) => ({
     binding: startBinding + i,
     resource: buffer instanceof GPUBuffer ? { buffer } : buffer,

package/src/util/buffer.mjs

@@ -1,5 +1,4 @@
 /** @module devdocs/utility-functions/buffer */
-import { getDevice } from "../init.mjs";
 
 /**
  * Destroys one or more GPU buffers. Accepts individual buffers or arrays of buffers.
@@ -10,12 +9,38 @@ export function destroyBuffers(...buffers) {
   buffers.flat().forEach((b) => b.destroy());
 }
 
+/**
+ * Throws if `byteSize` is more than this device can bind as a storage buffer.
+ *
+ * Every storage buffer the library creates goes through here. WebGPU accepts an
+ * oversized `createBuffer` and only rejects it later, when it is bound — as a
+ * `GPUValidationError` naming a bind group index rather than an operand, which
+ * gives no clue which allocation was at fault. Failing at creation, with the
+ * buffer's own label, points straight at it.
+ *
+ * @param {GPUDevice} device
+ * @param {number} byteSize
+ * @param {string} label - the buffer's debug label, quoted in the error
+ * @throws {Error} if `byteSize` exceeds `maxStorageBufferBindingSize`
+ * @internal
+ */
+function requireStorageSize(device, byteSize, label) {
+  const maxSize = device.limits.maxStorageBufferBindingSize;
+  if (byteSize > maxSize) {
+    throw new Error(
+      `Buffer "${label}" needs ${byteSize} bytes, exceeding this device's ` +
+      `maxStorageBufferBindingSize (${maxSize} bytes). The operands are too large for this device.`,
+    );
+  }
+}
+
 /**
  * Creates a GPU storage buffer and uploads `data` into it via mapped-at-creation.
  * The mapped view is constructed from `data`'s own typed-array constructor, so
  * bits are copied as-is regardless of element type (e.g. a Uint32Array's raw
  * bit patterns are preserved — critical for dasum's aux half, which must
  * never pass through a Float32Array view and risk NaN-bit-pattern canonicalization).
+ * @param {GPUDevice} device
  * @param {Float32Array|Uint32Array|Int32Array} data
  * @param {string} [label] - debug label visible in browser DevTools GPU inspection
  * @param {boolean} [readback=false] - add `COPY_SRC` so the buffer can be copied to a readback buffer
@@ -26,17 +51,9 @@ export function destroyBuffers(...buffers) {
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUBuffer/unmap GPUBuffer.unmap()}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUSupportedLimits GPUSupportedLimits} (`maxStorageBufferBindingSize`)
  */
-export function uploadBuffer(data, label = "blas-input", readback = false) {
-  const device = getDevice();
-
-  // User-facing boundary: give a clear error instead of a cryptic GPUValidationError.
-  const maxSize = device.limits.maxStorageBufferBindingSize;
+export function uploadBuffer(device, data, label = "blas-input", readback = false) {
   const byteSize = data.byteLength;
-  if (byteSize > maxSize) {
-    throw new Error(
-      `Buffer size ${byteSize} bytes exceeds device limit of ${maxSize} bytes.`,
-    );
-  }
+  requireStorageSize(device, byteSize, label);
 
   const usage = readback
     ? GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
@@ -60,15 +77,17 @@ export function uploadBuffer(data, label = "blas-input", readback = false) {
 /**
  * Creates an uninitialised GPU storage buffer. Used for intermediate buffers
  * that are written by a shader before being read.
+ * @param {GPUDevice} device
  * @param {number} size - byte size
  * @param {string} [label] - debug label visible in browser DevTools GPU inspection
  * @param {number} [extraUsage=0] - additional `GPUBufferUsage` flags OR'd in alongside `STORAGE`
  *   (e.g. `GPUBufferUsage.COPY_DST` for a buffer that's also a `copyBufferToBuffer` destination)
  * @returns {GPUBuffer}
+ * @throws {Error} if `size` exceeds the device's `maxStorageBufferBindingSize`
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createBuffer GPUDevice.createBuffer()}
  */
-export function createStorageBuffer(size, label = "blas-storage", extraUsage = 0) {
-  const device = getDevice();
+export function createStorageBuffer(device, size, label = "blas-storage", extraUsage = 0) {
+  requireStorageSize(device, size, label);
   return device.createBuffer({
     label,
     size,
@@ -79,13 +98,15 @@ export function createStorageBuffer(size, label = "blas-storage", extraUsage = 0
 /**
  * Creates a GPU storage buffer with `COPY_SRC` so its contents can be
  * copied to a CPU-readable readback buffer after the shader runs.
+ * @param {GPUDevice} device
  * @param {number} size - byte size
  * @param {string} [label] - debug label visible in browser DevTools GPU inspection
  * @returns {GPUBuffer}
+ * @throws {Error} if `size` exceeds the device's `maxStorageBufferBindingSize`
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createBuffer GPUDevice.createBuffer()}
  */
-export function createResultBuffer(size, label = "blas-result") {
-  const device = getDevice();
+export function createResultBuffer(device, size, label = "blas-result") {
+  requireStorageSize(device, size, label);
   return device.createBuffer({
     label,
     size,
@@ -97,13 +118,13 @@ export function createResultBuffer(size, label = "blas-result") {
  * Appends a `copyBufferToBuffer` command to `commandEncoder` that copies
  * `sourceBuffer` into a new `MAP_READ` buffer. Returns that readback buffer;
  * call `readBuffer.mapAsync(GPUMapMode.READ)` after submitting the encoder.
+ * @param {GPUDevice} device
  * @param {GPUCommandEncoder} commandEncoder
  * @param {GPUBuffer} sourceBuffer
  * @returns {GPUBuffer}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUCommandEncoder/copyBufferToBuffer GPUCommandEncoder.copyBufferToBuffer()}
  */
-export function stageReadback(commandEncoder, sourceBuffer) {
-  const device = getDevice();
+export function stageReadback(device, commandEncoder, sourceBuffer) {
 
   // COPY_DST: receives the copyBufferToBuffer transfer; MAP_READ: lets the CPU map and read it back.
   const readBuffer = device.createBuffer({
@@ -121,17 +142,90 @@ export function stageReadback(commandEncoder, sourceBuffer) {
   return readBuffer;
 }
 
+// Minimum bindable size for an array<vec4<f32>> view: one 16-byte element.
+const VEC4_ELEM_BYTES = 16;
+
+// Dummy STORAGE buffer bound into a kernel's unused vec4-view slot when the
+// real operand can't host even one vec4 (tiny-matrix edge cases, where the
+// stride check forces the scalar path anyway). Cached per device.
+const _vec4Fallbacks = new WeakMap();
+function vec4FallbackBuffer(device) {
+  let b = _vec4Fallbacks.get(device);
+  if (!b) {
+    b = device.createBuffer({
+      label: "blas-vec4-fallback",
+      size: VEC4_ELEM_BYTES,
+      usage: GPUBufferUsage.STORAGE,
+    });
+    _vec4Fallbacks.set(device, b);
+  }
+  return b;
+}
+
+/**
+ * Bind-group entry exposing `buffer`'s bytes as an `array<vec4<f32>>` view —
+ * the twin binding that lets a shader issue 16-byte vector loads alongside
+ * scalar access of the same storage (bind the same GPUBuffer twice: once as
+ * `array<f32>`, once through this). The view's size is rounded down to a
+ * multiple of 16 because some backends reject non-multiple-of-16 ranges for
+ * vec4 arrays; whenever a kernel's vector path is usable (stride % 4 == 0)
+ * the buffer size is itself a multiple of 16, so the rounding never truncates
+ * a component the vector path would actually read. Buffers smaller than one
+ * vec4 element get a shared dummy storage buffer bound instead — the shader
+ * never dereferences it on those shapes.
+ * @param {GPUBuffer|{buffer: GPUBuffer, offset?: number, size?: number}} entry - whole buffer or sub-range, matching what the scalar slot binds
+ * @returns {{buffer: GPUBuffer, offset: number, size: number}}
+ */
+export function vec4ViewBinding(device, entry) {
+  const buffer = entry instanceof GPUBuffer ? entry : entry.buffer;
+  const offset = entry instanceof GPUBuffer ? 0 : (entry.offset ?? 0);
+  const avail = (entry instanceof GPUBuffer ? entry.size : (entry.size ?? buffer.size - offset));
+  const size = Math.floor(avail / VEC4_ELEM_BYTES) * VEC4_ELEM_BYTES;
+  if (size < VEC4_ELEM_BYTES) {
+    return { buffer: vec4FallbackBuffer(device), offset: 0, size: VEC4_ELEM_BYTES };
+  }
+  return { buffer, offset, size };
+}
+
+/**
+ * Whether every in-bounds element of a matrix operand is reachable through
+ * the `array<vec4<f32>>` view that {@link vec4ViewBinding} produces for it.
+ * The view truncates the binding down to a multiple of 16 bytes, so a
+ * tightly-uploaded array can hold valid matrix elements past the view's end
+ * even while its stride is 4-aligned (e.g. a column-major m×1 operand with
+ * padded lda uploaded without padding cells). Call this with the kernel-side
+ * dimensions and only take a shader's vectorized path when it returns true;
+ * the scalar fallback reads the full storage and is always correct.
+ * @param {GPUBuffer|{buffer: GPUBuffer, offset?: number, size?: number}} entry - what the scalar slot binds
+ * @param {number} stride - the operand's leading dimension as seen by the kernel
+ * @param {number} outerCount - extent of the stride-multiplied dimension
+ * @param {number} innerCount - extent of the contiguous dimension
+ * @returns {boolean}
+ */
+export function vec4Usable(entry, stride, outerCount, innerCount) {
+  if (stride % 4 !== 0) return false;
+  const buffer = entry instanceof GPUBuffer ? entry : entry.buffer;
+  const offset = entry instanceof GPUBuffer ? 0 : (entry.offset ?? 0);
+  const avail = (entry instanceof GPUBuffer ? buffer.size : (entry.size ?? buffer.size - offset));
+  const viewFloats = Math.floor(avail / VEC4_ELEM_BYTES) * 4;
+  if (viewFloats <= 0) return false;
+  // Highest flat index any masked-in component can touch; usable iff its
+  // containing vec4 ends within the view.
+  const maxFlat = (Math.max(outerCount, 1) - 1) * stride + (Math.max(innerCount, 1) - 1);
+  return Math.floor(maxFlat / 4) * 4 + 4 <= viewFloats;
+}
+
 /**
  * Packs an array of typed scalar values into a uniform buffer aligned to 16 bytes.
  * Each entry specifies the value and its WGSL type (`"f32"`, `"u32"`, or `"i32"`).
  * The order of entries must match the field order in the shader's `Params` struct.
+ * @param {GPUDevice} device
  * @param {{ value: number, type: "f32"|"u32"|"i32" }[]} params
  * @param {string} [label] - debug label visible in browser DevTools GPU inspection
  * @returns {GPUBuffer}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUQueue/writeBuffer GPUQueue.writeBuffer()}
  */
-export function createParamsBuffer(params, label = "blas-params") {
-  const device = getDevice();
+export function createParamsBuffer(device, params, label = "blas-params") {
 
   const rawSize = params.length * 4;
   const size = Math.ceil(rawSize / 16) * 16;

package/src/util/compute.mjs

@@ -1,5 +1,4 @@
 /** @module devdocs/utility-functions/compute */
-import { getDevice } from "../init.mjs";
 import { beginTimestamp, resolveTimestamp } from "./benchmark.mjs";
 
 // Anchors the pass encoder to its command encoder to prevent premature GC.
@@ -10,8 +9,7 @@ const _passEncoders = new WeakMap();
  * @param {GPUCommandEncoder} commandEncoder
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUQueue/submit GPUQueue.submit()}
  */
-export function submit(commandEncoder) {
-  const device = getDevice();
+export function submit(device, commandEncoder) {
   device.queue.submit([commandEncoder.finish()]);
 }
 
@@ -23,9 +21,8 @@ export function submit(commandEncoder) {
  * @returns {{ commandEncoder: GPUCommandEncoder, querySet: GPUQuerySet|null, passDescriptor: object|undefined }}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createCommandEncoder GPUDevice.createCommandEncoder()}
  */
-export function beginTimedEncoder() {
-  const device = getDevice();
-  const { querySet, passDescriptor } = beginTimestamp();
+export function beginTimedEncoder(device) {
+  const { querySet, passDescriptor } = beginTimestamp(device);
   const commandEncoder = device.createCommandEncoder();
   return { commandEncoder, querySet, passDescriptor };
 }
@@ -71,11 +68,11 @@ export function encodePass(commandEncoder, pipeline, bindGroup, workgroups, pass
  * @returns {{ commandEncoder: GPUCommandEncoder, ts: any }} encoded commands and timestamp handle
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createCommandEncoder GPUDevice.createCommandEncoder()}
  */
-export function runComputePass(pipeline, bindGroup, workgroups) {
-  const { commandEncoder, querySet, passDescriptor } = beginTimedEncoder();
+export function runComputePass(device, pipeline, bindGroup, workgroups) {
+  const { commandEncoder, querySet, passDescriptor } = beginTimedEncoder(device);
   encodePass(commandEncoder, pipeline, bindGroup, workgroups, passDescriptor);
 
-  const ts = resolveTimestamp(commandEncoder, querySet);
+  const ts = resolveTimestamp(device, commandEncoder, querySet);
 
   return { commandEncoder, ts };
 }