wgblas 2.1.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

@@ -13,7 +13,7 @@ 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";
+import { requireGpuDevice, requireSameDevice } from "../util/device.mjs";
 
 // Blocked triangular solve via explicit block inversion (invert/apply/update passes) instead of barrier-per-row substitution.
 
@@ -39,13 +39,23 @@ 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'.");
@@ -77,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.",
@@ -89,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");
@@ -117,7 +127,8 @@ export async function strsv(device, uplo, trans, diag, n, A, lda, x, incx, layou
     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,
+    AinvBuffer = createStorageBuffer(
+      device,
       numBlocks * BLOCK_SIZE * BLOCK_SIZE * 4,
       "strsv-Ainv",
     );
@@ -130,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(device);
 
     // Pre-pass: every block's inverse, fully parallel, one dispatch.
-    invertParams = createParamsBuffer(device,
+    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(device, 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];
@@ -167,28 +203,43 @@ 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(device, 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(device, 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(device, commandEncoder, querySet);
-    const readBuffer = xIsGpu ? null : stageReadback(device, commandEncoder, xBuffer);
+    const readBuffer = xIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, xBuffer);
 
     submit(device, commandEncoder);
 

package/src/util/benchmark.mjs

@@ -71,9 +71,11 @@ export function resolveTimestamp(device, 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/buffer.mjs

@@ -29,7 +29,7 @@ function requireStorageSize(device, byteSize, label) {
   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.`,
+        `maxStorageBufferBindingSize (${maxSize} bytes). The operands are too large for this device.`,
     );
   }
 }
@@ -51,7 +51,12 @@ function requireStorageSize(device, byteSize, label) {
  * @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(device, data, label = "blas-input", readback = false) {
+export function uploadBuffer(
+  device,
+  data,
+  label = "blas-input",
+  readback = false,
+) {
   const byteSize = data.byteLength;
   requireStorageSize(device, byteSize, label);
 
@@ -86,7 +91,12 @@ export function uploadBuffer(device, data, label = "blas-input", readback = fals
  * @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(device, size, label = "blas-storage", extraUsage = 0) {
+export function createStorageBuffer(
+  device,
+  size,
+  label = "blas-storage",
+  extraUsage = 0,
+) {
   requireStorageSize(device, size, label);
   return device.createBuffer({
     label,
@@ -125,7 +135,6 @@ export function createResultBuffer(device, size, label = "blas-result") {
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUCommandEncoder/copyBufferToBuffer GPUCommandEncoder.copyBufferToBuffer()}
  */
 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",
@@ -134,9 +143,11 @@ export function stageReadback(device, 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;
@@ -179,10 +190,17 @@ function vec4FallbackBuffer(device) {
 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 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: vec4FallbackBuffer(device),
+      offset: 0,
+      size: VEC4_ELEM_BYTES,
+    };
   }
   return { buffer, offset, size };
 }
@@ -206,12 +224,16 @@ 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 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);
+  const maxFlat =
+    (Math.max(outerCount, 1) - 1) * stride + (Math.max(innerCount, 1) - 1);
   return Math.floor(maxFlat / 4) * 4 + 4 <= viewFloats;
 }
 
@@ -226,7 +248,6 @@ export function vec4Usable(entry, stride, outerCount, innerCount) {
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUQueue/writeBuffer GPUQueue.writeBuffer()}
  */
 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;
+}

package/src/util/compute.mjs

@@ -1,9 +1,6 @@
 /** @module devdocs/utility-functions/compute */
 import { beginTimestamp, resolveTimestamp } from "./benchmark.mjs";
 
-// Anchors the pass encoder to its command encoder to prevent premature GC.
-const _passEncoders = new WeakMap();
-
 /**
  * Finalises `commandEncoder` into a command buffer and submits it to the GPU queue.
  * @param {GPUCommandEncoder} commandEncoder
@@ -40,7 +37,13 @@ export function beginTimedEncoder(device) {
  * @param {object} [passDescriptor] - passed to `beginComputePass`, e.g. for timestamp writes
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUCommandEncoder/beginComputePass GPUCommandEncoder.beginComputePass()}
  */
-export function encodePass(commandEncoder, pipeline, bindGroup, workgroups, passDescriptor) {
+export function encodePass(
+  commandEncoder,
+  pipeline,
+  bindGroup,
+  workgroups,
+  passDescriptor,
+) {
   const passEncoder = commandEncoder.beginComputePass(passDescriptor);
 
   passEncoder.setPipeline(pipeline);
@@ -50,12 +53,14 @@ export function encodePass(commandEncoder, pipeline, bindGroup, workgroups, pass
     passEncoder.dispatchWorkgroups(workgroups);
   } else {
     // `?? 1` is load-bearing — confirmed passing undefined (from an {x,y}-only caller) crashes the process, not just no-ops.
-    passEncoder.dispatchWorkgroups(workgroups.x, workgroups.y, workgroups.z ?? 1);
+    passEncoder.dispatchWorkgroups(
+      workgroups.x,
+      workgroups.y,
+      workgroups.z ?? 1,
+    );
   }
 
   passEncoder.end();
-
-  _passEncoders.set(commandEncoder, passEncoder);
 }
 
 /**
@@ -69,7 +74,8 @@ export function encodePass(commandEncoder, pipeline, bindGroup, workgroups, pass
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createCommandEncoder GPUDevice.createCommandEncoder()}
  */
 export function runComputePass(device, pipeline, bindGroup, workgroups) {
-  const { commandEncoder, querySet, passDescriptor } = beginTimedEncoder(device);
+  const { commandEncoder, querySet, passDescriptor } =
+    beginTimedEncoder(device);
   encodePass(commandEncoder, pipeline, bindGroup, workgroups, passDescriptor);
 
   const ts = resolveTimestamp(device, commandEncoder, querySet);

package/src/util/device.mjs

@@ -2,6 +2,20 @@
 import { GpuVector } from "../classes/GpuVector.mjs";
 import { GpuMatrix } from "../classes/GpuMatrix.mjs";
 
+/**
+ * Throws if `device` is not a `GPUDevice`.
+ *
+ * Every routine's first guard, extracted since the check and message are
+ * identical across all of them.
+ *
+ * @param {GPUDevice} device - the value to check
+ * @throws {Error} if `device` is not a `GPUDevice`
+ */
+export function requireGpuDevice(device) {
+  if (!(device instanceof GPUDevice))
+    throw new Error("device must be a GPUDevice.");
+}
+
 /**
  * Throws if any GPU-resident operand belongs to a device other than the one
  * the routine was called with.
@@ -22,12 +36,13 @@ import { GpuMatrix } from "../classes/GpuMatrix.mjs";
  */
 export function requireSameDevice(device, routine, operands) {
   for (const [name, value] of Object.entries(operands)) {
-    if (!(value instanceof GpuVector) && !(value instanceof GpuMatrix)) continue;
+    if (!(value instanceof GpuVector) && !(value instanceof GpuMatrix))
+      continue;
     if (value.device !== device) {
       throw new Error(
         `${routine}: ${name} belongs to a different GPUDevice than the one passed in. ` +
-        "GPU buffers cannot be shared across devices — recreate the operand on this " +
-        "device, or call the routine with the device that owns it.",
+          "GPU buffers cannot be shared across devices — recreate the operand on this " +
+          "device, or call the routine with the device that owns it.",
       );
     }
   }

package/src/util/pipeline.mjs

@@ -23,7 +23,14 @@ export async function getPipeline(device, shaderName, entryPoint = "main") {
   const names = Array.isArray(shaderName) ? shaderName : [shaderName];
   const key = `${names.join("+")}::${entryPoint}`;
   if (!byName.has(key)) {
-    byName.set(key, await loadShader(device, names, entryPoint));
+    // Cache the in-flight promise (not its resolved value) so a concurrent
+    // call awaits the same compile instead of starting a duplicate one;
+    // drop the entry on failure so a later call can retry.
+    const pending = loadShader(device, names, entryPoint).catch((err) => {
+      byName.delete(key);
+      throw err;
+    });
+    byName.set(key, pending);
   }
   return byName.get(key);
 }
@@ -39,7 +46,8 @@ async function loadCode(shaderName) {
   if (typeof process === "undefined" || !process.versions?.node) {
     const { shaderSources } = await import("../shaders/index.mjs");
     const src = shaderSources[shaderName];
-    if (!src) throw new Error(`Shader "${shaderName}" not found in browser bundle.`);
+    if (!src)
+      throw new Error(`Shader "${shaderName}" not found in browser bundle.`);
     return src;
   } else {
     const { readFileSync } = await import("fs");
@@ -66,8 +74,32 @@ async function loadCode(shaderName) {
  */
 export async function loadShader(device, shaderNames, entryPoint = "main") {
   const label = shaderNames.join("+");
-  const code = (await Promise.all(shaderNames.map(loadCode))).join("\n");
+  const codes = await Promise.all(shaderNames.map(loadCode));
 
+  // Per-file line ranges within the concatenated module, so a compile error
+  // reports as "<file>.wgsl:<local line>" instead of a whole-module line
+  // number — confusing for multi-file pipelines like dasum's.
+  let offset = 0;
+  const ranges = codes.map((c, i) => {
+    const lineCount = c.split("\n").length;
+    const range = {
+      name: shaderNames[i],
+      startLine: offset + 1,
+      endLine: offset + lineCount,
+    };
+    offset += lineCount;
+    return range;
+  });
+  const locate = (lineNum) => {
+    const range =
+      lineNum &&
+      ranges.find((r) => lineNum >= r.startLine && lineNum <= r.endLine);
+    return range
+      ? `${range.name}.wgsl:${lineNum - range.startLine + 1}`
+      : `line ${lineNum}`;
+  };
+
+  const code = codes.join("\n");
   const shaderModule = device.createShaderModule({ label, code });
 
   const info = await shaderModule.getCompilationInfo();
@@ -75,7 +107,7 @@ export async function loadShader(device, shaderNames, entryPoint = "main") {
   const errors = info.messages.filter((m) => m.type === "error");
   if (errors.length > 0) {
     throw new Error(
-      `Shader "${label}" compilation failed:\n${errors.map((m) => `  line ${m.lineNum}: ${m.message}`).join("\n")}`,
+      `Shader "${label}" compilation failed:\n${errors.map((m) => `  ${locate(m.lineNum)}: ${m.message}`).join("\n")}`,
     );
   }
 
@@ -83,7 +115,10 @@ export async function loadShader(device, shaderNames, entryPoint = "main") {
   // this project's WebGPU backend is unstable (intermittent multi-minute hangs and wrong
   // results, confirmed by bisection) when entryPoint is set explicitly, even to the shader's
   // only/correct entry point. Auto-detecting the single entry point is the stable path.
-  const compute = entryPoint === "main" ? { module: shaderModule } : { module: shaderModule, entryPoint };
+  const compute =
+    entryPoint === "main"
+      ? { module: shaderModule }
+      : { module: shaderModule, entryPoint };
   const pipeline = device.createComputePipeline({
     label,
     layout: "auto",

package/src/util/workgroup.mjs

@@ -2,7 +2,10 @@
 // Fixed sizes match the shader declarations (WGS = 64 for 1D, 8×8 = 64 threads
 // for 2D) — see constants.mjs, which is where both values are defined and
 // where the WGSL cross-check hangs off.
-import { WGS as WORKGROUP_SIZE_1D, TILE_WG_2D as WORKGROUP_SIZE_2D } from "./constants.mjs";
+import {
+  WGS as WORKGROUP_SIZE_1D,
+  TILE_WG_2D as WORKGROUP_SIZE_2D,
+} from "./constants.mjs";
 
 /**
  * Calculates the number of workgroups to dispatch, clamped to the device's
@@ -53,8 +56,8 @@ export function requireWorkgroupCount(device, count, routine, dim = "x") {
   if (count > max)
     throw new Error(
       `${routine}: this problem needs ${count} workgroups in ${dim}, but the device allows ` +
-      `${max} (maxComputeWorkgroupsPerDimension). The operands are too large for this device — ` +
-      `split the operation into smaller blocks.`,
+        `${max} (maxComputeWorkgroupsPerDimension). The operands are too large for this device — ` +
+        `split the operation into smaller blocks.`,
     );
   return count;
 }
@@ -71,9 +74,23 @@ export function requireWorkgroupCount(device, count, routine, dim = "x") {
  */
 export function requireWorkgroups(device, routine, rows, cols) {
   if (cols === undefined)
-    return requireWorkgroupCount(device, Math.ceil(rows / WORKGROUP_SIZE_1D), routine);
+    return requireWorkgroupCount(
+      device,
+      Math.ceil(rows / WORKGROUP_SIZE_1D),
+      routine,
+    );
   return {
-    x: requireWorkgroupCount(device, Math.ceil(cols / WORKGROUP_SIZE_2D), routine, "x"),
-    y: requireWorkgroupCount(device, Math.ceil(rows / WORKGROUP_SIZE_2D), routine, "y"),
+    x: requireWorkgroupCount(
+      device,
+      Math.ceil(cols / WORKGROUP_SIZE_2D),
+      routine,
+      "x",
+    ),
+    y: requireWorkgroupCount(
+      device,
+      Math.ceil(rows / WORKGROUP_SIZE_2D),
+      routine,
+      "y",
+    ),
   };
 }