wgblas 2.0.0 → 2.2.0

package/src/strsv/strsv.d.mts

@@ -2,8 +2,9 @@ import { GpuVector } from "../classes/GpuVector.mjs";
 import { GpuMatrix } from "../classes/GpuMatrix.mjs";
 
 /**
- * Solves the triangular system op(A) * x = b for x, in place (x holds b on
- * input, the solution on output).
+ * Solves the triangular system for $x$, in place — x holds b on input, the
+ * solution on output:
+ * $$\mathrm{op}(A) x = b$$
  *
  * A is an n×n triangular matrix stored in row-major order. Only the triangle
  * specified by `uplo` is referenced; the other triangle is not accessed.
@@ -42,7 +43,8 @@ export declare function strsv(
 ): Promise<{ x: Float32Array; gpuTimeMs?: number }>;
 
 /**
- * Solves the triangular system op(A) * x = b for x, in place.
+ * Solves the triangular system for $x$, in place:
+ * $$\mathrm{op}(A) x = b$$
  *
  * x is kept resident on the GPU (mutated in place). A must be a GpuMatrix;
  * its own `layout` (set at `GpuMatrix.from` time) determines the operation —

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 { requireGpuDevice, 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) {
@@ -38,13 +39,24 @@ function createSharedParamsBuffer(device, data, label) {
   return buffer;
 }
 
-export async function strsv(device, uplo, trans, diag, n, A, lda, x, incx, layout = "row-major") {
+export async function strsv(
+  device,
+  uplo,
+  trans,
+  diag,
+  n,
+  A,
+  lda,
+  x,
+  incx,
+  layout = "row-major",
+) {
   const xIsGpu = x instanceof GpuVector;
   const AIsGpu = A instanceof GpuMatrix;
   const isUnit = diag === "unit";
 
-  if (!(device instanceof GPUDevice))
-    throw new Error("device must be a GPUDevice.");
+  requireGpuDevice(device);
+  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 +77,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))
@@ -73,9 +87,7 @@ export async function strsv(device, uplo, trans, diag, n, A, lda, x, incx, layou
   if (n === 0) return xIsGpu ? {} : { x };
 
   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.",
@@ -85,7 +97,9 @@ export async function strsv(device, uplo, trans, diag, n, A, lda, x, incx, layou
   const effLayout = AIsGpu ? A.layout : layout;
   const isColMajor = effLayout === "column-major";
   const isLower = isColMajor ? uplo === "upper" : uplo === "lower";
-  const isNoTrans = isColMajor ? trans === "transpose" : trans === "no-transpose";
+  const isNoTrans = isColMajor
+    ? trans === "transpose"
+    : trans === "no-transpose";
 
   const invertPipeline = await getPipeline(device, "strsv_invert_block");
   const applyPipeline = await getPipeline(device, "strsv_apply_inverse");
@@ -109,11 +123,12 @@ 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(
+      device,
       numBlocks * BLOCK_SIZE * BLOCK_SIZE * 4,
       "strsv-Ainv",
     );
@@ -126,35 +141,60 @@ export async function strsv(device, uplo, trans, diag, n, A, lda, x, incx, layou
       const blockEnd = Math.min(blockStart + BLOCK_SIZE, n);
       return [incx, blockIndex, blockStart, blockEnd];
     });
-    applyParamsBuffer = createSharedParamsBuffer(device, applyData, "strsv-apply-params");
+    applyParamsBuffer = createSharedParamsBuffer(
+      device,
+      applyData,
+      "strsv-apply-params",
+    );
 
     const updateData = packBlockParams(numBlocks, stride, (blockIndex) => {
       const blockStart = blockIndex * BLOCK_SIZE;
       const blockEnd = Math.min(blockStart + BLOCK_SIZE, n);
-      return [n, incx, lda, isNoTrans ? 0 : 1, isLower ? 0 : 1, blockStart, blockEnd];
+      return [
+        n,
+        incx,
+        lda,
+        isNoTrans ? 0 : 1,
+        isLower ? 0 : 1,
+        blockStart,
+        blockEnd,
+      ];
     });
-    updateParamsBuffer = createSharedParamsBuffer(device, updateData, "strsv-update-params");
+    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(
+      device,
       [
-        { value: n,                 type: "u32" },
-        { value: lda,               type: "u32" },
+        { value: n, type: "u32" },
+        { value: lda, type: "u32" },
         { value: isNoTrans ? 0 : 1, type: "u32" },
-        { value: isLower ? 0 : 1,   type: "u32" },
-        { value: isUnit ? 1 : 0,    type: "u32" },
+        { value: isLower ? 0 : 1, type: "u32" },
+        { value: isUnit ? 1 : 0, type: "u32" },
       ],
       "strsv-invert-params",
     );
-    const invertBindGroup = createBindGroup(invertPipeline.getBindGroupLayout(0), [
-      ABuffer, AinvBuffer, invertParams,
-    ]);
+    const invertBindGroup = createBindGroup(
+      device,
+      invertPipeline.getBindGroupLayout(0),
+      [ABuffer, AinvBuffer, invertParams],
+    );
     const invertDesc = querySet
       ? { timestampWrites: { querySet, beginningOfPassWriteIndex: 0 } }
       : undefined;
-    encodePass(commandEncoder, invertPipeline, invertBindGroup, { x: BLOCK_SIZE, y: numBlocks }, invertDesc);
+    encodePass(
+      commandEncoder,
+      invertPipeline,
+      invertBindGroup,
+      { x: BLOCK_SIZE, y: numBlocks },
+      invertDesc,
+    );
 
     for (let bi = 0; bi < blockStarts.length; bi++) {
       const blockStart = blockStarts[bi];
@@ -163,30 +203,45 @@ 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), [
-        AinvBuffer, xBuffer, { buffer: applyParamsBuffer, offset: paramsOffset, size: 16 },
-      ]);
+      const applyBindGroup = createBindGroup(
+        device,
+        applyPipeline.getBindGroupLayout(0),
+        [
+          AinvBuffer,
+          xBuffer,
+          { buffer: applyParamsBuffer, offset: paramsOffset, size: 16 },
+        ],
+      );
 
-      const applyDesc = isLastPass && querySet
-        ? { timestampWrites: { querySet, endOfPassWriteIndex: 1 } }
-        : undefined;
+      const applyDesc =
+        isLastPass && querySet
+          ? { timestampWrites: { querySet, endOfPassWriteIndex: 1 } }
+          : undefined;
       encodePass(commandEncoder, applyPipeline, applyBindGroup, 1, applyDesc);
 
       const remaining = forward ? n - blockEnd : blockStart;
       if (remaining === 0) continue;
 
-      const updateBindGroup = createBindGroup(updatePipeline.getBindGroupLayout(0), [
-        ABuffer, xBuffer, { buffer: updateParamsBuffer, offset: paramsOffset, size: 32 },
-      ]);
+      const updateBindGroup = createBindGroup(
+        device,
+        updatePipeline.getBindGroupLayout(0),
+        [
+          ABuffer,
+          xBuffer,
+          { buffer: updateParamsBuffer, offset: paramsOffset, size: 32 },
+        ],
+      );
 
       const wgCount = Math.min(remaining, maxWg);
       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({
@@ -73,9 +71,11 @@ export function resolveTimestamp(commandEncoder, querySet) {
     usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
   });
   commandEncoder.copyBufferToBuffer(
-    resolveBuffer, 0,   // src, srcOffset
-    tsReadBuffer,  0,   // dst, dstOffset
-    16,                 // full 16 bytes (both timestamps)
+    resolveBuffer,
+    0, // src, srcOffset
+    tsReadBuffer,
+    0, // dst, dstOffset
+    16, // full 16 bytes (both timestamps)
   );
   // resolveBuffer is returned to prevent GC — the copy command is only encoded here, not yet executed.
   return { tsReadBuffer, resolveBuffer, querySet };

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,14 @@ 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 +82,22 @@ 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 +108,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,14 +128,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({
     label: "blas-readback",
@@ -113,26 +143,111 @@ export function stageReadback(commandEncoder, sourceBuffer) {
   });
 
   commandEncoder.copyBufferToBuffer(
-    sourceBuffer, 0,              // src, srcOffset
-    readBuffer,   0,              // dst, dstOffset
-    sourceBuffer.size,            // full copy, no partial reads
+    sourceBuffer,
+    0, // src, srcOffset
+    readBuffer,
+    0, // dst, dstOffset
+    sourceBuffer.size, // full copy, no partial reads
   );
 
   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/complex.mjs

@@ -0,0 +1,87 @@
+/** @module devdocs/utility-functions/complex */
+import { splitDoubleDouble, mergeDoubleDouble } from "./f64.mjs";
+import { Complex64, Complex64Array } from "../classes/Complex64.mjs";
+
+// Complex32Array <-> interleaved [re0, im0, re1, im1, ...] f32 buffer — one
+// buffer, not a (hi, lo) pair like Float64Array (see f64.mjs), since re/im
+// need no error compensation. Matches cuBLAS/stdlib's own complex layout.
+
+/**
+ * Interleaves the first `n` elements of a Complex32Array into a flat f32
+ * buffer ready for `uploadBuffer`.
+ * @param {import("../classes/Complex32.mjs").Complex32Array} data
+ * @param {number} [n] - element count to interleave (default: data.length)
+ * @returns {Float32Array} length `2*n`, [re0, im0, re1, im1, ...]
+ * @public
+ */
+export function interleaveComplex32(data, n = data.length) {
+  const flat = new Float32Array(n * 2);
+  for (let i = 0; i < n; i++) {
+    flat[i * 2] = data[i].re;
+    flat[i * 2 + 1] = data[i].im;
+  }
+  return flat;
+}
+
+// Complex64Array <-> a double-double (hi, lo) pair of interleaved f32
+// buffers. re and im each need their own (hi, lo) split (see f64.mjs) —
+// zipped together per channel, [reHi0,imHi0,...] / [reLo0,imLo0,...],
+// rather than four separate buffers, so GpuVector/GpuMatrix's existing
+// two-buffer shape covers this dtype with no restructuring.
+
+/**
+ * Splits the first `n` elements of a Complex64Array into an interleaved
+ * double-double (hi, lo) pair of f32 buffers.
+ * @param {Complex64Array} data
+ * @param {number} [n] - element count to split (default: data.length)
+ * @returns {{hi: Float32Array, lo: Float32Array}} each length `2*n`,
+ *   [reHi0, imHi0, reHi1, imHi1, ...] / [reLo0, imLo0, reLo1, imLo1, ...]
+ * @public
+ */
+export function splitComplex64(data, n = data.length) {
+  const re = new Float64Array(n);
+  const im = new Float64Array(n);
+  for (let i = 0; i < n; i++) {
+    re[i] = data[i].re;
+    im[i] = data[i].im;
+  }
+  const { hi: reHi, lo: reLo } = splitDoubleDouble(re);
+  const { hi: imHi, lo: imLo } = splitDoubleDouble(im);
+
+  const hi = new Float32Array(n * 2);
+  const lo = new Float32Array(n * 2);
+  for (let i = 0; i < n; i++) {
+    hi[i * 2] = reHi[i];
+    hi[i * 2 + 1] = imHi[i];
+    lo[i * 2] = reLo[i];
+    lo[i * 2 + 1] = imLo[i];
+  }
+  return { hi, lo };
+}
+
+/**
+ * Reassembles a Complex64Array from an interleaved double-double (hi, lo)
+ * pair of f32 buffers — the inverse of splitComplex64.
+ * @param {Float32Array} hi - [reHi0, imHi0, reHi1, imHi1, ...]
+ * @param {Float32Array} lo - [reLo0, imLo0, reLo1, imLo1, ...]
+ * @returns {Complex64Array}
+ * @public
+ */
+export function mergeComplex64(hi, lo) {
+  const n = hi.length / 2;
+  const reHi = new Float32Array(n),
+    reLo = new Float32Array(n);
+  const imHi = new Float32Array(n),
+    imLo = new Float32Array(n);
+  for (let i = 0; i < n; i++) {
+    reHi[i] = hi[i * 2];
+    imHi[i] = hi[i * 2 + 1];
+    reLo[i] = lo[i * 2];
+    imLo[i] = lo[i * 2 + 1];
+  }
+  const re = mergeDoubleDouble(reHi, reLo);
+  const im = mergeDoubleDouble(imHi, imLo);
+  const out = new Complex64Array(n);
+  for (let i = 0; i < n; i++) out[i] = new Complex64(re[i], im[i]);
+  return out;
+}