wgblas 0.1.2 → 1.0.0

package/src/strsv/strsv.mjs

@@ -0,0 +1,212 @@
+import {
+  uploadBuffer,
+  createParamsBuffer,
+  createStorageBuffer,
+  stageReadback,
+  destroyBuffers,
+} from "../util/buffer.mjs";
+import { createBindGroup } from "../util/bindgroup.mjs";
+import { beginTimedEncoder, encodePass, submit } from "../util/compute.mjs";
+import { extractResult } from "../util/result.mjs";
+import { resolveTimestamp, extractTimestamp } from "../util/benchmark.mjs";
+import { getPipeline } from "../util/pipeline.mjs";
+import { GpuVector } from "../classes/GpuVector.mjs";
+import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+
+// Blocked triangular solve, explicit-inversion variant: a pre-pass inverts
+// every diagonal block in parallel (strsv_invert_block.wgsl), then each
+// block is solved via a dense matvec against its inverse (strsv_apply_inverse.wgsl)
+// instead of a barrier-per-row substitution. strsv_update.wgsl (propagating
+// a solved block onto remaining rows) is unchanged.
+const BLOCK_SIZE = 64;
+
+// Packs one small uniform struct per block into a single shared buffer
+// (at `blockIndex * stride`) instead of allocating numBlocks separate tiny
+// buffers — measured CPU-side overhead (buffer/bind-group setup, not actual
+// GPU compute) was 66-83% of total wall-clock time before this, dominated
+// by the O(numBlocks) createBuffer/writeBuffer calls the old per-block loop
+// made. `stride` must be a multiple of the device's uniform offset alignment
+// (device.limits.minUniformBufferOffsetAlignment) so each block's slot is a
+// valid fixed-offset binding.
+function packBlockParams(numBlocks, stride, fieldsPerBlock) {
+  const data = new ArrayBuffer(numBlocks * stride);
+  const view = new DataView(data);
+  for (let blockIndex = 0; blockIndex < numBlocks; blockIndex++) {
+    const fields = fieldsPerBlock(blockIndex);
+    const base = blockIndex * stride;
+    fields.forEach((value, i) => view.setUint32(base + i * 4, value, true));
+  }
+  return data;
+}
+
+function createSharedParamsBuffer(device, data, label) {
+  const buffer = device.createBuffer({
+    label,
+    size: data.byteLength,
+    usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+  });
+  device.queue.writeBuffer(buffer, 0, data);
+  return buffer;
+}
+
+export async function strsv(device, uplo, trans, diag, n, A, lda, x, incx) {
+  const xIsGpu = x instanceof GpuVector;
+  const AIsGpu = A instanceof GpuMatrix;
+  const isLower = uplo === "lower";
+  const isNoTrans = trans === "no-transpose";
+  const isUnit = diag === "unit";
+
+  if (!(device instanceof GPUDevice))
+    throw new Error("device must be a GPUDevice.");
+  if (!isLower && uplo !== "upper")
+    throw new Error("uplo must be 'lower' or 'upper'.");
+  if (!isNoTrans && trans !== "transpose")
+    throw new Error("trans must be 'no-transpose' or 'transpose'.");
+  if (!isUnit && diag !== "non-unit")
+    throw new Error("diag must be 'unit' or 'non-unit'.");
+  if (!Number.isInteger(n) || !Number.isInteger(incx) || !Number.isInteger(lda))
+    throw new Error("n, incx, and lda must be integers.");
+  if (incx <= 0) throw new Error("incx must be positive.");
+  if (lda < n) throw new Error("lda must be >= n.");
+  if (!AIsGpu && !(A instanceof Float32Array))
+    throw new Error("A must be a Float32Array or GpuMatrix.");
+  if (!xIsGpu && !(x instanceof Float32Array))
+    throw new Error("x must be a Float32Array or GpuVector.");
+  if (xIsGpu && !AIsGpu)
+    throw new Error("A must be a GpuMatrix when x is a GpuVector.");
+  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))
+    throw new Error("A is too small for the given n.");
+  if (n < 0) throw new Error("n must be non-negative.");
+  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.",
+    );
+  if (x.length < (n - 1) * incx + 1)
+    throw new Error(
+      "x does not have enough elements for the given n and incx.",
+    );
+
+  const invertPipeline = await getPipeline(device, "strsv_invert_block");
+  const applyPipeline = await getPipeline(device, "strsv_apply_inverse");
+  const updatePipeline = await getPipeline(device, "strsv_update");
+
+  // Same forward/backward pairing the shaders use.
+  const forward = isNoTrans === isLower;
+  const blockStarts = [];
+  for (let s = 0; s < n; s += BLOCK_SIZE) blockStarts.push(s);
+  if (!forward) blockStarts.reverse();
+  const numBlocks = blockStarts.length;
+
+  const maxWg = device.limits.maxComputeWorkgroupsPerDimension;
+  const stride = device.limits.minUniformBufferOffsetAlignment;
+
+  let ABuffer = null;
+  let xBuffer = null;
+  let AinvBuffer = null;
+  let applyParamsBuffer = null;
+  let updateParamsBuffer = null;
+  let invertParams = null;
+
+  try {
+    ABuffer = AIsGpu ? A._buf : uploadBuffer(A, "strsv-A", false);
+    xBuffer = xIsGpu ? x._buf : uploadBuffer(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(
+      numBlocks * BLOCK_SIZE * BLOCK_SIZE * 4,
+      "strsv-Ainv",
+    );
+
+    // Every block's {blockStart, blockEnd} is fixed by its natural index
+    // regardless of traversal direction, so both packed buffers are indexed
+    // by blockIndex (0..numBlocks-1), not by loop position.
+    const applyData = packBlockParams(numBlocks, stride, (blockIndex) => {
+      const blockStart = blockIndex * BLOCK_SIZE;
+      const blockEnd = Math.min(blockStart + BLOCK_SIZE, n);
+      return [incx, blockIndex, blockStart, blockEnd];
+    });
+    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];
+    });
+    updateParamsBuffer = createSharedParamsBuffer(device, updateData, "strsv-update-params");
+
+    const { commandEncoder, querySet } = beginTimedEncoder();
+
+    // Pre-pass: every block's inverse, fully parallel, one dispatch.
+    invertParams = createParamsBuffer(
+      [
+        { 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" },
+      ],
+      "strsv-invert-params",
+    );
+    const invertBindGroup = createBindGroup(invertPipeline.getBindGroupLayout(0), [
+      ABuffer, AinvBuffer, invertParams,
+    ]);
+    const invertDesc = querySet
+      ? { timestampWrites: { querySet, beginningOfPassWriteIndex: 0 } }
+      : undefined;
+    encodePass(commandEncoder, invertPipeline, invertBindGroup, { x: BLOCK_SIZE, y: numBlocks }, invertDesc);
+
+    for (let bi = 0; bi < blockStarts.length; bi++) {
+      const blockStart = blockStarts[bi];
+      const blockEnd = Math.min(blockStart + BLOCK_SIZE, n);
+      const blockIndex = blockStart / BLOCK_SIZE;
+      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 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 wgCount = Math.min(remaining, maxWg);
+      encodePass(commandEncoder, updatePipeline, updateBindGroup, wgCount);
+    }
+
+    const ts = resolveTimestamp(commandEncoder, querySet);
+    const readBuffer = xIsGpu ? null : stageReadback(commandEncoder, xBuffer);
+
+    submit(commandEncoder);
+
+    const gpuTimeMs = await extractTimestamp(ts);
+
+    if (xIsGpu) {
+      if (gpuTimeMs !== undefined) return { gpuTimeMs };
+      return {};
+    }
+
+    const result = await extractResult(readBuffer, Float32Array);
+    if (gpuTimeMs !== undefined) return { x: result, gpuTimeMs };
+    return { x: result };
+  } finally {
+    if (!AIsGpu && ABuffer) destroyBuffers(ABuffer);
+    if (!xIsGpu && xBuffer) destroyBuffers(xBuffer);
+    if (AinvBuffer) destroyBuffers(AinvBuffer);
+    if (applyParamsBuffer) destroyBuffers(applyParamsBuffer);
+    if (updateParamsBuffer) destroyBuffers(updateParamsBuffer);
+    if (invertParams) destroyBuffers(invertParams);
+  }
+}

package/src/util/benchmark.mjs

@@ -99,5 +99,5 @@ export async function extractTimestamp(ts) {
   tsReadBuffer.destroy();
   resolveBuffer.destroy(); // never mapped — no unmap() needed
   querySet.destroy();
-  return Number(timestamps[1] - timestamps[0]) / 1e6;
+  return Math.max(0, Number(timestamps[1] - timestamps[0])) / 1e6;
 }

package/src/util/bindgroup.mjs

@@ -2,21 +2,25 @@
 import { getDevice } from "../init.mjs";
 
 /**
- * Creates a `GPUBindGroup` by mapping each buffer to sequential binding indices (0, 1, 2 …).
- * `resultBuffer` is appended last so its binding index follows all input buffers.
- * The order of `buffers` must match the `@binding` indices declared in the shader.
+ * Creates a `GPUBindGroup` by mapping each buffer to sequential binding indices
+ * (startBinding, startBinding + 1, …). The order of `buffers` must match the `@binding`s
+ * declared in the shader.
  * @param {GPUBindGroupLayout} layout - from `pipeline.getBindGroupLayout(0)`; the layout is derived automatically from the shader because `loadShader` uses `layout: "auto"`
- * @param {GPUBuffer[]} buffers - input and intermediate buffers in binding order
- * @param {GPUBuffer|null} [resultBuffer=null] - appended as the final binding if provided
+ * @param {(GPUBuffer|{buffer: GPUBuffer, offset: number, size: number})[]} buffers - input and
+ *   intermediate buffers in binding order; a plain `GPUBuffer` binds the whole buffer, or pass
+ *   `{buffer, offset, size}` to bind a sub-range — e.g. many small per-call param structs packed
+ *   into one shared buffer instead of allocating a separate tiny buffer per call
+ * @param {number} [startBinding=0] - binding index of `buffers[0]`; nonzero only when a shader's
+ *   own bindings don't start at 0 — e.g. a module built by concatenating two `.wgsl` files where
+ *   the second file's bindings continue after the first's own bindings (if any)
  * @returns {GPUBindGroup}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createBindGroup GPUDevice.createBindGroup()}
  */
-export function createBindGroup(layout, buffers, resultBuffer = null) {
+export function createBindGroup(layout, buffers, startBinding = 0) {
   const device = getDevice();
-  const allBuffers = resultBuffer ? [...buffers, resultBuffer] : [...buffers];
-  const entries = allBuffers.map((buffer, i) => ({
-    binding: i,
-    resource: { buffer },
+  const entries = buffers.map((buffer, i) => ({
+    binding: startBinding + i,
+    resource: buffer instanceof GPUBuffer ? { buffer } : buffer,
   }));
   return device.createBindGroup({ layout, entries });
 }

package/src/util/buffer.mjs

@@ -12,7 +12,11 @@ export function destroyBuffers(...buffers) {
 
 /**
  * Creates a GPU storage buffer and uploads `data` into it via mapped-at-creation.
- * @param {Float32Array} data
+ * 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 {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
  * @throws {Error} if `data.byteLength` exceeds the device's `maxStorageBufferBindingSize`
@@ -45,7 +49,8 @@ export function uploadBuffer(data, label = "blas-input", readback = false) {
     mappedAtCreation: true,
   });
 
-  const mappedArray = new Float32Array(buffer.getMappedRange());
+  const ViewCtor = data.constructor;
+  const mappedArray = new ViewCtor(buffer.getMappedRange());
   mappedArray.set(data);
   buffer.unmap();
 

package/src/util/compute.mjs

@@ -2,6 +2,9 @@
 import { getDevice } from "../init.mjs";
 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
@@ -13,24 +16,33 @@ export function submit(commandEncoder) {
 }
 
 /**
- * Encodes and submits a single compute pass: sets the pipeline and bind group,
- * dispatches workgroups, and optionally wraps the pass in GPU timestamp queries.
- * @param {GPUComputePipeline} pipeline
- * @param {GPUBindGroup} bindGroup
- * @param {number | { x: number, y: number }} workgroups - workgroup count; number for 1D dispatch, `{x, y}` for 2D
- * @returns {{ commandEncoder: GPUCommandEncoder, ts: any }} encoded commands and timestamp handle
+ * Starts a new command encoder together with its GPU timestamp query (if
+ * benchmarking is enabled) — the pairing every routine needs before encoding
+ * its first pass, whether that's `runComputePass`'s single pass or a
+ * multi-pass routine (e.g. strsv's blocked solve) encoding several by hand.
+ * @returns {{ commandEncoder: GPUCommandEncoder, querySet: GPUQuerySet|null, passDescriptor: object|undefined }}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createCommandEncoder GPUDevice.createCommandEncoder()}
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUCommandEncoder/beginComputePass GPUCommandEncoder.beginComputePass()}
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUComputePassEncoder/setPipeline GPUComputePassEncoder.setPipeline()}
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUComputePassEncoder/setBindGroup GPUComputePassEncoder.setBindGroup()}
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUComputePassEncoder/dispatchWorkgroups GPUComputePassEncoder.dispatchWorkgroups()}
  */
-export function runComputePass(pipeline, bindGroup, workgroups) {
+export function beginTimedEncoder() {
   const device = getDevice();
-
   const { querySet, passDescriptor } = beginTimestamp();
-
   const commandEncoder = device.createCommandEncoder();
+  return { commandEncoder, querySet, passDescriptor };
+}
+
+/**
+ * Encodes one compute pass (set pipeline, set bind group, dispatch, end) onto an
+ * existing command encoder — the shared building block behind `runComputePass`,
+ * also used directly by routines that need several passes on one encoder (e.g.
+ * strsv's blocked solve, where each pass depends on the previous one completing).
+ * @param {GPUCommandEncoder} commandEncoder
+ * @param {GPUComputePipeline} pipeline
+ * @param {GPUBindGroup} bindGroup
+ * @param {number | { x: number, y: number }} workgroups - workgroup count; number for 1D dispatch, `{x, y}` for 2D
+ * @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) {
   const passEncoder = commandEncoder.beginComputePass(passDescriptor);
 
   passEncoder.setPipeline(pipeline);
@@ -44,9 +56,23 @@ export function runComputePass(pipeline, bindGroup, workgroups) {
 
   passEncoder.end();
 
-  const ts = resolveTimestamp(commandEncoder, querySet);
+  _passEncoders.set(commandEncoder, passEncoder);
+}
 
-  commandEncoder._passEncoder = passEncoder; // anchor — GC'd passEncoder may crash native encoder
+/**
+ * Encodes and submits a single compute pass: sets the pipeline and bind group,
+ * dispatches workgroups, and optionally wraps the pass in GPU timestamp queries.
+ * @param {GPUComputePipeline} pipeline
+ * @param {GPUBindGroup} bindGroup
+ * @param {number | { x: number, y: number }} workgroups - workgroup count; number for 1D dispatch, `{x, y}` for 2D
+ * @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();
+  encodePass(commandEncoder, pipeline, bindGroup, workgroups, passDescriptor);
+
+  const ts = resolveTimestamp(commandEncoder, querySet);
 
   return { commandEncoder, ts };
 }

package/src/util/f64pack.mjs

@@ -0,0 +1,152 @@
+/** @module devdocs/utility-functions/f64pack */
+
+// Scratch buffers reused across calls for bit-pattern <-> float reinterpretation.
+// dv8 is read/written exclusively through explicit big-endian DataView calls
+// (never via Float64Array, whose byte order follows host endianness) so hi/lo
+// word extraction is deterministic regardless of host architecture.
+const buf8 = new ArrayBuffer(8);
+const dv8 = new DataView(buf8);
+
+const buf4 = new ArrayBuffer(4);
+const u32View = new Uint32Array(buf4);
+const f32View = new Float32Array(buf4);
+
+function u32ToF32(bits) {
+  u32View[0] = bits >>> 0;
+  return f32View[0];
+}
+
+function f32ToU32(f) {
+  f32View[0] = f;
+  return u32View[0];
+}
+
+// Shared bit-scramble between an f64's raw fields (sign, 11-bit exponent,
+// mantissa split as a 20-bit hi word + 32-bit lo word) and a [main, aux]
+// pair. f64 has exactly 3 more exponent bits and 29 more mantissa bits than
+// f32 — 3 + 29 = 32, i.e. exactly one f32's worth of bits, all of which fit
+// in `aux`:
+//   aux.sign + aux.exponent[7:6]  (3 bits) = f64's low 3 exponent bits
+//   aux.exponent[5:0]             (6 bits) = top 6 of f64's low 29 mantissa bits
+//   aux.mantissa                  (23 bits) = bottom 23 of f64's low 29 mantissa bits
+//
+// `aux` is deliberately kept as a raw u32 integer, never converted to an
+// actual float32 value (unlike `main`, which genuinely is a float32 for
+// reuse in float-typed math like abs()). Any combination of the source bits
+// above can land on aux.exponent === 0xff — i.e. aux's bit pattern reads as
+// a NaN or Infinity if it's ever treated as a real float — and this can
+// happen not just for unusual inputs but for the RESULT of an ordinary
+// addition (see f64add.wgsl's computeSum), so it can't be filtered out at
+// the input boundary. A JS engine or GPU canonicalizes a NaN bit pattern
+// (sets its mantissa's quiet bit) the moment it passes through an actual
+// Float32Array or f32-typed GPU buffer/register as a VALUE — silently
+// corrupting the payload. Since aux never needs float semantics anywhere
+// (WGSL only ever bitcasts it back to u32 for decode()), storing/uploading/
+// reading it exclusively as Uint32Array bits (see GpuVector, buffer.mjs)
+// sidesteps the whole class of corruption rather than working around it.
+function fieldsToPacked(sign, rawExp, mantissaHi, lo) {
+  const expMain = rawExp >>> 3; // top 8 bits -> main's exponent
+  const expExtra = rawExp & 0x7; // bottom 3 bits -> stashed in aux
+
+  const mantTop3 = lo >>> 29; // top 3 bits of the low mantissa word
+  const mantMain = (mantissaHi << 3) | mantTop3; // 20 + 3 = 23 bits -> main's mantissa
+  const mantExtra29 = lo & 0x1fffffff; // bottom 29 bits -> stashed in aux
+
+  const mainBits = (sign << 31) | (expMain << 23) | mantMain;
+
+  const auxSign = (expExtra >>> 2) & 0x1;
+  const auxExpTop2 = expExtra & 0x3;
+  const auxExpBot6 = mantExtra29 >>> 23; // top 6 of the 29
+  const auxMant23 = mantExtra29 & 0x7fffff; // bottom 23 of the 29
+  const auxExp8 = (auxExpTop2 << 6) | auxExpBot6;
+
+  const auxBits = ((auxSign << 31) | (auxExp8 << 23) | auxMant23) >>> 0;
+
+  return [u32ToF32(mainBits), auxBits];
+}
+
+function packedToFields(main, auxBits) {
+  const mainBits = f32ToU32(main);
+  auxBits = auxBits >>> 0;
+
+  const sign = mainBits >>> 31;
+  const expMain = (mainBits >>> 23) & 0xff;
+  const mantMain = mainBits & 0x7fffff; // 23 bits
+
+  const auxSign = auxBits >>> 31;
+  const auxExp8 = (auxBits >>> 23) & 0xff;
+  const auxMant23 = auxBits & 0x7fffff;
+
+  const expExtra = (auxSign << 2) | (auxExp8 >>> 6); // 3 bits
+  const mantExtra29 = ((auxExp8 & 0x3f) << 23) | auxMant23; // 29 bits
+
+  const rawExp = (expMain << 3) | expExtra; // 11 bits
+  const mantissaHi = mantMain >>> 3; // top 20 bits
+  const mantTop3 = mantMain & 0x7; // bottom 3 bits of mantMain
+
+  const lo = ((mantTop3 << 29) | mantExtra29) >>> 0;
+
+  return { sign, rawExp, mantissaHi, lo };
+}
+
+// main (unlike aux) genuinely is a float32 value — it gets reinterpreted with
+// real float ops (e.g. abs() in dasum.wgsl), so it can't be transported as
+// raw u32 the way aux is. That leaves a narrow residual gap: main.exponent is
+// `rawExp >>> 3`, which hits 0xff (main's own NaN/Infinity pattern) whenever
+// the f64's raw exponent is >= 2040 — i.e. |value| >= ~1.4e306, plus actual
+// ±Infinity/NaN (rawExp === 2047). Any real Float32Array/GPU round-trip of
+// such a main would get silently NaN-canonicalized, the same corruption class
+// aux was fixed for. Since main can't take that fix, reject the range instead
+// of silently corrupting it.
+const MIN_UNSAFE_RAW_EXP = 2040;
+
+/**
+ * Packs a double into a [main, aux] pair for storage/transfer where only f32
+ * is available (e.g. WGSL, which has no f64 type). This is a raw bit
+ * repacking, not a value-preserving numeric split — neither half is a
+ * meaningful float on its own; only `unpackF64(main, aux)` reconstructs the
+ * original value.
+ * @param {number} value - finite double with |value| < ~1.4e306 (see
+ *   MIN_UNSAFE_RAW_EXP above); larger magnitudes, ±Infinity, and NaN would
+ *   produce a `main` whose bit pattern is itself NaN/Infinity-shaped, which
+ *   silently corrupts on any real float32 round-trip, so they're rejected.
+ * @returns {[number, number]} `[main, aux]` — main is a float32 value, aux is
+ *   a raw uint32 bit pattern (0 to 2^32-1). Store/transport aux exclusively
+ *   via Uint32Array/`array<u32>` — never as an actual float value — see the
+ *   comment above `fieldsToPacked`.
+ */
+export function packF64(value) {
+  dv8.setFloat64(0, value, false);
+  const hi = dv8.getUint32(0, false); // sign(1) + exponent(11) + mantissa_hi(20)
+  const lo = dv8.getUint32(4, false); // mantissa_lo(32)
+
+  const sign = hi >>> 31;
+  const rawExp = (hi >>> 20) & 0x7ff; // 11 bits
+  const mantissaHi = hi & 0xfffff; // 20 bits
+
+  if (rawExp >= MIN_UNSAFE_RAW_EXP) {
+    throw new RangeError(
+      `packF64: |${value}| is too large to pack safely (must be finite with ` +
+        `magnitude below ~1.4e306); main's bit pattern would itself be NaN/` +
+        `Infinity-shaped and get silently corrupted by any real float32 round-trip`,
+    );
+  }
+
+  return fieldsToPacked(sign, rawExp, mantissaHi, lo);
+}
+
+/**
+ * Reconstructs the original double from the [main, aux] pair produced by
+ * `packF64`. Bit-exact inverse.
+ * @param {number} main - float32 value
+ * @param {number} aux - raw uint32 bit pattern (as read from a Uint32Array/`array<u32>`)
+ * @returns {number}
+ */
+export function unpackF64(main, aux) {
+  const { sign, rawExp, mantissaHi, lo } = packedToFields(main, aux);
+  const hi = ((sign << 31) | (rawExp << 20) | mantissaHi) >>> 0;
+
+  dv8.setUint32(0, hi, false);
+  dv8.setUint32(4, lo, false);
+  return dv8.getFloat64(0, false);
+}

package/src/util/pipeline.mjs

@@ -8,18 +8,25 @@ const _pipelines = new WeakMap();
  * Returns a cached `GPUComputePipeline` for the given shader, compiling it on first use.
  * Pipelines are cached per device so reinitialization (new device) always recompiles.
  * @param {GPUDevice} device
- * @param {string} shaderName - filename without `.wgsl` extension (e.g. `"sscal"`)
+ * @param {string|string[]} shaderName - filename without `.wgsl` extension (e.g. `"sscal"`),
+ *   or an array of filenames whose source gets concatenated into one module — WGSL has no
+ *   `#include`, so this is how one shader's helper functions (e.g. f64add.wgsl's decode/
+ *   encode/computeSum) get reused from another (e.g. dasum.wgsl) without duplicating them.
+ * @param {string} [entryPoint="main"] - which `@compute` function to run; only needed when
+ *   concatenating shaders whose entry points aren't both named "main"
  * @returns {Promise<GPUComputePipeline>}
  */
-export async function getPipeline(device, shaderName) {
+export async function getPipeline(device, shaderName, entryPoint = "main") {
   if (!_pipelines.has(device)) {
     _pipelines.set(device, new Map());
   }
   const byName = _pipelines.get(device);
-  if (!byName.has(shaderName)) {
-    byName.set(shaderName, await loadShader(shaderName));
+  const names = Array.isArray(shaderName) ? shaderName : [shaderName];
+  const key = `${names.join("+")}::${entryPoint}`;
+  if (!byName.has(key)) {
+    byName.set(key, await loadShader(names, entryPoint));
   }
-  return byName.get(shaderName);
+  return byName.get(key);
 }
 
 /**
@@ -29,8 +36,8 @@ export async function getPipeline(device, shaderName) {
  * @returns {Promise<string>}
  */
 async function loadCode(shaderName) {
-  // typeof guards against ReferenceError in Node.js — accessing window directly throws if it doesn't exist.
-  if (typeof window !== "undefined") {
+  // Check for Node.js explicitly — `window` is undefined in Web Workers too, so it's not a reliable signal.
+  if (typeof process === "undefined" || !process.versions?.node) {
     const { shaderSources } = await import("../shaders/browser-shaders.mjs");
     const src = shaderSources[shaderName];
     if (!src) throw new Error(`Shader "${shaderName}" not found in browser bundle.`);
@@ -45,35 +52,43 @@ async function loadCode(shaderName) {
 }
 
 /**
- * Compiles a WGSL shader into a `GPUComputePipeline`. Throws with line-level detail if compilation fails, rather than surfacing a raw GPU error.
- * Uses `layout: "auto"` so the pipeline derives its bind group layout from the shader —
- * no manual layout definition needed.
- * @param {string} shaderName
+ * Compiles one or more WGSL shaders (concatenated, in order, into a single module) into a
+ * `GPUComputePipeline`. Throws with line-level detail if compilation fails, rather than
+ * surfacing a raw GPU error. Uses `layout: "auto"` so the pipeline derives its bind group
+ * layout from the shader — no manual layout definition needed.
+ * @param {string[]} shaderNames - filenames without `.wgsl`, concatenated in array order
+ * @param {string} [entryPoint="main"] - which `@compute` function in the combined module to run
  * @returns {Promise<GPUComputePipeline>}
  * @throws {Error} if the shader has compilation errors
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createShaderModule GPUDevice.createShaderModule()}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUShaderModule/getCompilationInfo GPUShaderModule.getCompilationInfo()}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/createComputePipeline GPUDevice.createComputePipeline()}
  */
-export async function loadShader(shaderName) {
+export async function loadShader(shaderNames, entryPoint = "main") {
   const device = getDevice();
-  const code = await loadCode(shaderName);
+  const label = shaderNames.join("+");
+  const code = (await Promise.all(shaderNames.map(loadCode))).join("\n");
 
-  const shaderModule = device.createShaderModule({ label: shaderName, code });
+  const shaderModule = device.createShaderModule({ label, code });
 
   const info = await shaderModule.getCompilationInfo();
   // GPUCompilationMessage: https://developer.mozilla.org/en-US/docs/Web/API/GPUCompilationMessage
   const errors = info.messages.filter((m) => m.type === "error");
   if (errors.length > 0) {
     throw new Error(
-      `Shader "${shaderName}" compilation failed:\n${errors.map((m) => `  line ${m.lineNum}: ${m.message}`).join("\n")}`,
+      `Shader "${label}" compilation failed:\n${errors.map((m) => `  line ${m.lineNum}: ${m.message}`).join("\n")}`,
     );
   }
 
+  // Omit entryPoint when it's the default "main" rather than always passing it explicitly —
+  // 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 pipeline = device.createComputePipeline({
-    label: shaderName,
+    label,
     layout: "auto",
-    compute: { module: shaderModule },
+    compute,
   });
 
   pipeline._shaderModule = shaderModule; // anchor — GC'd shaderModule crashes native pipeline

package/src/util/result.mjs

@@ -12,8 +12,12 @@
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/GPUBuffer/unmap GPUBuffer.unmap()}
  */
 export async function extractResult(readBuffer, readbackType = Float32Array) {
-  await readBuffer.mapAsync(GPUMapMode.READ);
-  const result = new readbackType(readBuffer.getMappedRange().slice());
-  readBuffer.unmap();
-  return result;
+  try {
+    await readBuffer.mapAsync(GPUMapMode.READ);
+    const result = new readbackType(readBuffer.getMappedRange().slice());
+    readBuffer.unmap();
+    return result;
+  } finally {
+    readBuffer.destroy();
+  }
 }