wgblas 1.2.1 → 2.1.0

package/index.d.mts

@@ -17,6 +17,7 @@ export { sasum } from "./src/sasum/sasum.mjs";
 export { dasum } from "./src/dasum/dasum.mjs";
 export { snrm2 } from "./src/snrm2/snrm2.mjs";
 export { isamax } from "./src/isamax/isamax.mjs";
+export { idamax } from "./src/idamax/idamax.mjs";
 export { srot } from "./src/srot/srot.mjs";
 export { srotm } from "./src/srotm/srotm.mjs";
 export { sgemv } from "./src/sgemv/sgemv.mjs";
@@ -26,15 +27,35 @@ export { strsv } from "./src/strsv/strsv.mjs";
 export { sger } from "./src/sger/sger.mjs";
 export { ssyr } from "./src/ssyr/ssyr.mjs";
 export { ssyr2 } from "./src/ssyr2/ssyr2.mjs";
+export { sgemm } from "./src/sgemm/sgemm.mjs";
+export { sgemmtr } from "./src/sgemmtr/sgemmtr.mjs";
+export { ssyrk } from "./src/ssyrk/ssyrk.mjs";
+export { ssyr2k } from "./src/ssyr2k/ssyr2k.mjs";
+export { ssymm } from "./src/ssymm/ssymm.mjs";
+export { strmm } from "./src/strmm/strmm.mjs";
+export { strsm } from "./src/strsm/strsm.mjs";
 
 /**
  * Initializes the WebGPU device.
  *
+ * Devices are cached per option set: the same options return the same device,
+ * different options a separate one — so one process can drive several GPUs
+ * (`"high-performance"` and `"low-power"` typically resolve to the discrete and
+ * integrated adapters). Each routine dispatches to the device you pass it; GPU
+ * buffers cannot cross devices, so a `GpuVector`/`GpuMatrix` from one is
+ * rejected by another. {@link cleanup} releases them all.
+ *
  * @param options.powerPreference - GPU power preference (default: `"high-performance"`).
  *   This is a hint to the browser: on dual-GPU systems, `"high-performance"` typically favors the discrete GPU
  *   and `"low-power"` favors the integrated one.
  *   See [MDN: GPU.requestAdapter()](https://developer.mozilla.org/en-US/docs/Web/API/GPU/requestAdapter).
- * @param options.benchmark - enable GPU timestamp queries; BLAS functions return `{ result, gpuTimeMs }` (default: `false`)
+ * @param options.benchmark - enable GPU timestamp queries; BLAS functions then also return `gpuTimeMs`
+ *   alongside their normal result (e.g. sscal returns `{ x, gpuTimeMs }`, saxpy returns `{ y, gpuTimeMs }`) —
+ *   see each routine's own docs for its exact return shape (default: `false`)
+ * @param options.dumpShaders - Node-only. Forwards Dawn's `dump_shaders` debug toggle, printing
+ *   each pipeline's WGSL and compiled backend IR (SPIR-V/Vulkan, MSL/Metal, or HLSL/D3D12,
+ *   whichever Dawn picked) to stderr as it compiles. A Dawn passthrough, not a wgblas format —
+ *   no effect in the browser, which gives pages no API to request compiled shader IR (default: `false`)
  *
  * @example Default (high-performance GPU)
  * ```js
@@ -59,21 +80,42 @@ export { ssyr2 } from "./src/ssyr2/ssyr2.mjs";
  * const n = 5;
  * const alpha = 2.0;
  * const x = new Float32Array([1, 2, 3, 4, 5]);
- * const { result, gpuTimeMs } = await sscal(device, n, alpha, x, 1);
+ * const { x: result, gpuTimeMs } = await sscal(device, n, alpha, x, 1);
  * console.log(`Result: [${Array.from(result).join(", ")}]`);
  * console.log(`GPU time: ${gpuTimeMs.toFixed(3)} ms`);
  * ```
+ * @example Two GPUs at once
+ * ```js
+ * import { init, cleanup, gpuName, sscal } from "wgblas";
+ * const dGpu = await init({ powerPreference: "high-performance" });
+ * const iGpu = await init({ powerPreference: "low-power" });
+ * console.log(gpuName(dGpu).description, "and", gpuName(iGpu).description);
+ * const [a, b] = await Promise.all([
+ *   sscal(dGpu, 4, 2, new Float32Array([1, 2, 3, 4]), 1),
+ *   sscal(iGpu, 4, 5, new Float32Array([1, 2, 3, 4]), 1),
+ * ]);
+ * cleanup(); // releases both
+ * ```
+ *
  * @see [Source code: init.mjs](https://github.com/manit2004/wgblas/blob/main/src/init.mjs#L18-L54)
  * @category Core
  */
 export declare function init(options?: {
   powerPreference?: GPUPowerPreference;
   benchmark?: boolean;
+  dumpShaders?: boolean;
 }): Promise<GPUDevice>;
 
 /**
- * Destroys the WebGPU device, releases the adapter, resets benchmark state, and fires all internal
- * cleanup callbacks (e.g. releasing cached GPU pipelines and buffers). Call when done (required in Node.js to prevent crash on exit).
+ * Destroys devices created by {@link init} and releases their cached pipelines and buffers.
+ * Call when done (required in Node.js to prevent crash on exit).
+ *
+ * With no argument, releases every device at once. Pass a device to release
+ * just that one and leave the others usable — handy when driving several GPUs.
+ * Unknown or already-released devices are ignored, so this is safe to call
+ * more than once.
+ *
+ * @param device - the device to release; omit to release all of them.
  *
  * @example
  * ```js
@@ -86,11 +128,14 @@ export declare function init(options?: {
  * @see [Source code: init.mjs](https://github.com/manit2004/wgblas/blob/main/src/init.mjs#L56-L65)
  * @category Core
  */
-export declare function cleanup(): void;
+export declare function cleanup(device?: GPUDevice): void;
 
 /**
  * Returns the GPU device name from the WebGPU adapter info. Must be called after `init()`.
  *
+ * @param device - which device to report on; defaults to the one from the first
+ *   `init()` call. Pass it explicitly when driving more than one GPU.
+ *
  * @example
  * ```js
  * import { init, gpuName } from "wgblas";
@@ -101,4 +146,4 @@ export declare function cleanup(): void;
  * @see [Source code: init.mjs](https://github.com/manit2004/wgblas/blob/main/src/init.mjs#L81-L87)
  * @category Core
  */
-export declare function gpuName(): { description: string; device: string };
+export declare function gpuName(device?: GPUDevice): { description: string; device: string };

package/index.mjs

@@ -15,6 +15,7 @@ export { sasum } from "./src/sasum/sasum.mjs";
 export { dasum } from "./src/dasum/dasum.mjs";
 export { snrm2 } from "./src/snrm2/snrm2.mjs";
 export { isamax } from "./src/isamax/isamax.mjs";
+export { idamax } from "./src/idamax/idamax.mjs";
 export { srot } from "./src/srot/srot.mjs";
 export { srotm } from "./src/srotm/srotm.mjs";
 export { sgemv } from "./src/sgemv/sgemv.mjs";
@@ -24,3 +25,10 @@ export { strsv } from "./src/strsv/strsv.mjs";
 export { sger } from "./src/sger/sger.mjs";
 export { ssyr } from "./src/ssyr/ssyr.mjs";
 export { ssyr2 } from "./src/ssyr2/ssyr2.mjs";
+export { sgemm } from "./src/sgemm/sgemm.mjs";
+export { sgemmtr } from "./src/sgemmtr/sgemmtr.mjs";
+export { ssyrk } from "./src/ssyrk/ssyrk.mjs";
+export { ssyr2k } from "./src/ssyr2k/ssyr2k.mjs";
+export { ssymm } from "./src/ssymm/ssymm.mjs";
+export { strmm } from "./src/strmm/strmm.mjs";
+export { strsm } from "./src/strsm/strsm.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wgblas",
-  "version": "1.2.1",
+  "version": "2.1.0",
   "description": "BLAS on WebGPU",
   "type": "module",
   "main": "index.mjs",
@@ -59,6 +59,10 @@
       "import": "./src/isamax/isamax.mjs",
       "types": "./src/isamax/isamax.d.mts"
     },
+    "./idamax": {
+      "import": "./src/idamax/idamax.mjs",
+      "types": "./src/idamax/idamax.d.mts"
+    },
     "./srot": {
       "import": "./src/srot/srot.mjs",
       "types": "./src/srot/srot.d.mts"
@@ -94,6 +98,34 @@
     "./ssyr2": {
       "import": "./src/ssyr2/ssyr2.mjs",
       "types": "./src/ssyr2/ssyr2.d.mts"
+    },
+    "./sgemm": {
+      "import": "./src/sgemm/sgemm.mjs",
+      "types": "./src/sgemm/sgemm.d.mts"
+    },
+    "./sgemmtr": {
+      "import": "./src/sgemmtr/sgemmtr.mjs",
+      "types": "./src/sgemmtr/sgemmtr.d.mts"
+    },
+    "./ssyrk": {
+      "import": "./src/ssyrk/ssyrk.mjs",
+      "types": "./src/ssyrk/ssyrk.d.mts"
+    },
+    "./ssyr2k": {
+      "import": "./src/ssyr2k/ssyr2k.mjs",
+      "types": "./src/ssyr2k/ssyr2k.d.mts"
+    },
+    "./ssymm": {
+      "import": "./src/ssymm/ssymm.mjs",
+      "types": "./src/ssymm/ssymm.d.mts"
+    },
+    "./strmm": {
+      "import": "./src/strmm/strmm.mjs",
+      "types": "./src/strmm/strmm.d.mts"
+    },
+    "./strsm": {
+      "import": "./src/strsm/strsm.mjs",
+      "types": "./src/strsm/strsm.d.mts"
     }
   },
   "files": [
@@ -110,7 +142,26 @@
   },
   "keywords": [
     "BLAS",
-    "WebGPU"
+    "WebGPU",
+    "linear-algebra",
+    "linear",
+    "algebra",
+    "subroutines",
+    "level 1",
+    "level 2",
+    "level 3",
+    "gpu",
+    "gpgpu",
+    "wgsl",
+    "compute-shader",
+    "matrix",
+    "vector",
+    "matmul",
+    "dot product",
+    "float32",
+    "float64",
+    "numerical-computing",
+    "scientific-computing"
   ],
   "author": "Manit Roy",
   "license": "Apache-2.0",
@@ -129,11 +180,13 @@
     "@commitlint/config-conventional": "^21.2.0",
     "@eslint/js": "^10.0.1",
     "@stdlib/blas-base-dasum": "^0.4.1",
+    "@stdlib/blas-base-idamax": "^0.1.1",
     "@stdlib/blas-base-isamax": "^0.1.1",
     "@stdlib/blas-base-sasum": "^0.3.1",
     "@stdlib/blas-base-saxpy": "^0.3.1",
     "@stdlib/blas-base-scopy": "^0.3.1",
     "@stdlib/blas-base-sdot": "^0.3.1",
+    "@stdlib/blas-base-sgemm": "^0.1.1",
     "@stdlib/blas-base-sgemv": "^0.1.1",
     "@stdlib/blas-base-sger": "^0.1.1",
     "@stdlib/blas-base-snrm2": "^0.3.1",
@@ -156,6 +209,7 @@
     "lint-staged": "^17.0.8",
     "prettier": "^3.9.4",
     "typedoc": "^0.28.19",
+    "typedoc-plugin-katex": "^0.1.2",
     "typescript": "^6.0.3",
     "vite": "^8.0.16"
   },

package/src/classes/GpuMatrix.mjs

@@ -4,13 +4,15 @@ import { extractResult } from "../util/result.mjs";
 import { splitDoubleDouble, mergeDoubleDouble } from "../util/f64.mjs";
 
 export class GpuMatrix {
-  constructor(buffer, rows, cols, lda, loBuffer = null, layout = "row-major") {
+  constructor(buffer, rows, cols, lda, loBuffer = null, layout = "row-major", device = null) {
     this._buf = buffer;
     this._loBuf = loBuffer; // Non-null only for Float64Array-backed matrices
     this.rows = rows;
     this.cols = cols;
     this.lda  = lda;
     this.layout = layout;
+    // See GpuVector: a GPUBuffer is bound to one device for life.
+    this.device = device ?? getDevice();
   }
 
   /**
@@ -21,7 +23,12 @@ export class GpuMatrix {
    * no padding). `data` must have at least `rows * lda` (row-major) or
    * `cols * lda` (column-major) elements.
    */
-  static from(data, rows, cols, lda, layout = "row-major") {
+  static from(deviceOrData, ...rest) {
+    const explicit = deviceOrData instanceof GPUDevice;
+    const device = explicit ? deviceOrData : getDevice();
+    const data = explicit ? rest.shift() : deviceOrData;
+    let [rows, cols, lda, layout = "row-major"] = rest;
+
     if (layout !== "row-major" && layout !== "column-major")
       throw new Error("layout must be 'row-major' or 'column-major'.");
     const isRowMajor = layout === "row-major";
@@ -48,19 +55,19 @@ export class GpuMatrix {
     if (data instanceof Float64Array) {
       const n = outerCount * lda;
       const { hi, lo } = splitDoubleDouble(data.subarray(0, n));
-      const hiBuf = uploadBuffer(hi, "gpu-matrix-f64-hi", true);
-      const loBuf = uploadBuffer(lo, "gpu-matrix-f64-lo", true);
-      return new GpuMatrix(hiBuf, rows, cols, lda, loBuf, layout);
+      const hiBuf = uploadBuffer(device, hi, "gpu-matrix-f64-hi", true);
+      const loBuf = uploadBuffer(device, lo, "gpu-matrix-f64-lo", true);
+      return new GpuMatrix(hiBuf, rows, cols, lda, loBuf, layout, device);
     }
 
-    const buf = uploadBuffer(data.subarray(0, outerCount * lda), "gpu-matrix", true);
-    return new GpuMatrix(buf, rows, cols, lda, null, layout);
+    const buf = uploadBuffer(device, data.subarray(0, outerCount * lda), "gpu-matrix", true);
+    return new GpuMatrix(buf, rows, cols, lda, null, layout, device);
   }
 
   async read() {
-    const device = getDevice();
+    const device = this.device;
     const enc = device.createCommandEncoder();
-    const rb = stageReadback(enc, this._buf);
+    const rb = stageReadback(device, enc, this._buf);
     device.queue.submit([enc.finish()]);
 
     const isRowMajor = this.layout !== "column-major";
@@ -69,7 +76,7 @@ export class GpuMatrix {
 
     if (this._loBuf) {
       const encLo = device.createCommandEncoder();
-      const rbLo = stageReadback(encLo, this._loBuf);
+      const rbLo = stageReadback(device, encLo, this._loBuf);
       device.queue.submit([encLo.finish()]);
 
       const [hi, lo] = await Promise.all([

package/src/classes/GpuVector.mjs

@@ -4,37 +4,55 @@ import { extractResult } from "../util/result.mjs";
 import { splitDoubleDouble, mergeDoubleDouble } from "../util/f64.mjs";
 
 export class GpuVector {
-  constructor(buffer, length, dtype = Float32Array, loBuffer = null) {
+  constructor(buffer, length, dtype = Float32Array, loBuffer = null, device = null) {
     this._buf = buffer;
     this._loBuf = loBuffer; // Non-null only for Float64Array-backed vectors
     this.length = length;
     this.dtype = dtype;
+    // A GPUBuffer belongs to exactly one device and WebGPU rejects any attempt
+    // to use it with another, so every handle remembers where it lives. Routines
+    // check this to reject mixed-device operands with a clear message instead of
+    // a raw GPUValidationError.
+    this.device = device ?? getDevice();
   }
 
-  static from(data) {
+  /**
+   * Uploads a vector to GPU memory.
+   *
+   * Pass the target `GPUDevice` first — matching every routine's own
+   * `(device, ...)` convention. Omitting it falls back to the device from the
+   * last `init()`, which is the historical form and only works single-device.
+   *
+   * @param {GPUDevice|Float32Array|Float64Array} deviceOrData
+   */
+  static from(deviceOrData, maybeData) {
+    const explicit = deviceOrData instanceof GPUDevice;
+    const device = explicit ? deviceOrData : getDevice();
+    const data = explicit ? maybeData : deviceOrData;
+
     if (data instanceof Float64Array) {
       const { hi, lo } = splitDoubleDouble(data);
-      const hiBuf = uploadBuffer(hi, "gpu-vector-f64-hi", true);
-      const loBuf = uploadBuffer(lo, "gpu-vector-f64-lo", true);
-      return new GpuVector(hiBuf, data.length, Float64Array, loBuf);
+      const hiBuf = uploadBuffer(device, hi, "gpu-vector-f64-hi", true);
+      const loBuf = uploadBuffer(device, lo, "gpu-vector-f64-lo", true);
+      return new GpuVector(hiBuf, data.length, Float64Array, loBuf, device);
     }
     if (!(data instanceof Float32Array)) {
       throw new Error("GpuVector.from expects a Float32Array or Float64Array.");
     }
-    const buf = uploadBuffer(data, "gpu-vector", true);
-    return new GpuVector(buf, data.length, data.constructor);
+    const buf = uploadBuffer(device, data, "gpu-vector", true);
+    return new GpuVector(buf, data.length, data.constructor, null, device);
   }
 
   async read() {
-    const device = getDevice();
+    const device = this.device;
     const enc = device.createCommandEncoder();
-    const rb = stageReadback(enc, this._buf);
+    const rb = stageReadback(device, enc, this._buf);
     device.queue.submit([enc.finish()]);
 
     if (!this._loBuf) return extractResult(rb, this.dtype);
 
     const encLo = device.createCommandEncoder();
-    const rbLo = stageReadback(encLo, this._loBuf);
+    const rbLo = stageReadback(device, encLo, this._loBuf);
     device.queue.submit([encLo.finish()]);
 
     const [hi, lo] = await Promise.all([

package/src/dasum/dasum.d.mts

@@ -2,10 +2,10 @@ import { GpuVector } from "../classes/GpuVector.mjs";
 
 /**
  * Computes the sum of absolute values of a vector of doubles in extended
- * precision: result = sum(|x[i]|). Each element of `x` has abs() applied,
- * then is split into a (hi, lo) double-double f32 pair (see
- * `splitDoubleDouble`/`f64.mjs`) since WGSL has no f64 type; accumulation
- * uses Dekker's double-double algorithm (see `shaders/f64/dekker.wgsl`), giving ~48 bits
+ * precision: $$\text{result} = \sum_{i} |x_i|$$
+ * Each element of `x` has abs() applied, then is split into a (hi, lo) double-double f32 pair 
+ * (see `splitDoubleDouble`/`f64.mjs`) since WGSL has no f64 type; accumulation
+ * uses Dekker's double-double algorithm (see `shaders/f64/`), giving ~48 bits
  * of mantissa — more than a single f32 (24 bits) but less than true f64
  * (52 bits), so results are not bit-exact with a CPU double.
  *
@@ -31,9 +31,9 @@ export declare function dasum(
 
 /**
  * Computes the sum of absolute values of a vector of doubles in double
- * precision: result = sum(|x[i]|).
+ * precision: $$\text{result} = \sum_{i} |x_i|$$.
  *
- * {@includeCode ../../examples/dasum/gpuvec.dasum.js}
+ * {@includeCode ../../examples/dasum/gpu.dasum.js}
  *
  * @param device - GPUDevice from `init()`
  * @param n - number of elements (must be a positive integer)

package/src/dasum/dasum.mjs

@@ -13,14 +13,16 @@ import { extractResult } from "../util/result.mjs";
 import { getPipeline } from "../util/pipeline.mjs";
 import { GpuVector } from "../classes/GpuVector.mjs";
 import { splitDoubleDouble, mergeDoubleDouble } from "../util/f64.mjs";
+import { WGS } from "../util/constants.mjs";
+import { requireSameDevice } from "../util/device.mjs";
 
-const WGS = 64; // workgroup size
 
 export async function dasum(device, n, x, incx) {
   const xIsGpu = x instanceof GpuVector;
 
   if (!(device instanceof GPUDevice))
     throw new Error("device must be a GPUDevice.");
+  requireSameDevice(device, "dasum", { x });
   if (!Number.isInteger(n) || !Number.isInteger(incx))
     throw new Error("n and incx must be integers.");
   if (incx <= 0) throw new Error("incx must be positive.");
@@ -34,10 +36,12 @@ export async function dasum(device, n, x, incx) {
       "x does not have enough elements for the given n and incx.",
     );
 
-  // Concatenated with f64/dekker.wgsl for its DD struct/ddAdd helpers (WGSL
-  // has no #include); entryPoint omitted since each module has only one @compute.
-  const pipelineMain = await getPipeline(device, ["f64/dekker", "dasum"]);
-  const pipelineReduce = await getPipeline(device, ["f64/dekker", "reduction/sumF64"]);
+  // Concatenated with f64/dekker.wgsl (DD struct), f64/utils/abs.wgsl
+  // (ddAbs), and f64/utils/add.wgsl (ddAddProtected) — WGSL has no
+  // #include; entryPoint omitted since each module has only one @compute.
+  const f64Deps = ["f64/dekker", "f64/utils/abs", "f64/utils/add"];
+  const pipelineMain = await getPipeline(device, [...f64Deps, "dasum"]);
+  const pipelineReduce = await getPipeline(device, [...f64Deps, "reduction/sumF64"]);
 
   let xHiBuffer = null;
   let xLoBuffer = null;
@@ -55,14 +59,14 @@ export async function dasum(device, n, x, incx) {
       xLoBuffer = x._loBuf;
     } else {
       const { hi, lo } = splitDoubleDouble(x.map(Math.abs));
-      xHiBuffer = uploadBuffer(hi, "dasum-xHi", false);
-      xLoBuffer = uploadBuffer(lo, "dasum-xLo", false);
+      xHiBuffer = uploadBuffer(device, hi, "dasum-xHi", false);
+      xLoBuffer = uploadBuffer(device, lo, "dasum-xLo", false);
     }
-    partialsHiBuffer = createStorageBuffer(2 * WGS * 4, "dasum-partialsHi");
-    partialsLoBuffer = createStorageBuffer(2 * WGS * 4, "dasum-partialsLo");
-    resultHiBuffer = createResultBuffer(4, "dasum-result-hi");
-    resultLoBuffer = createResultBuffer(4, "dasum-result-lo");
-    paramsBuffer = createParamsBuffer(
+    partialsHiBuffer = createStorageBuffer(device, 2 * WGS * 4, "dasum-partialsHi");
+    partialsLoBuffer = createStorageBuffer(device, 2 * WGS * 4, "dasum-partialsLo");
+    resultHiBuffer = createResultBuffer(device, 4, "dasum-result-hi");
+    resultLoBuffer = createResultBuffer(device, 4, "dasum-result-lo");
+    paramsBuffer = createParamsBuffer(device,
       [
         { value: n, type: "u32" },
         { value: incx, type: "u32" },
@@ -70,31 +74,31 @@ export async function dasum(device, n, x, incx) {
       "dasum-params",
     );
 
-    const bgMain = createBindGroup(
+    const bgMain = createBindGroup(device,
       pipelineMain.getBindGroupLayout(0),
       [xHiBuffer, xLoBuffer, partialsHiBuffer, partialsLoBuffer, paramsBuffer],
     );
-    const { commandEncoder: enc1, ts: ts1 } = runComputePass(
+    const { commandEncoder: enc1, ts: ts1 } = runComputePass(device,
       pipelineMain,
       bgMain,
       2 * WGS,
     ); // dispatch 2*WGS workgroups
 
-    submit(enc1);
+    submit(device, enc1);
 
-    const bgReduce = createBindGroup(
+    const bgReduce = createBindGroup(device,
       pipelineReduce.getBindGroupLayout(0),
       [partialsHiBuffer, partialsLoBuffer, resultHiBuffer, resultLoBuffer],
     );
-    const { commandEncoder: enc2, ts: ts2 } = runComputePass(
+    const { commandEncoder: enc2, ts: ts2 } = runComputePass(device,
       pipelineReduce,
       bgReduce,
       1,
     ); // dispatch 1 workgroup to reduce the partial sums to a single result
-    readHiBuffer = stageReadback(enc2, resultHiBuffer);
-    readLoBuffer = stageReadback(enc2, resultLoBuffer);
+    readHiBuffer = stageReadback(device, enc2, resultHiBuffer);
+    readLoBuffer = stageReadback(device, enc2, resultLoBuffer);
 
-    submit(enc2);
+    submit(device, enc2);
 
     const hiPromise = extractResult(readHiBuffer, Float32Array);
     const loPromise = extractResult(readLoBuffer, Float32Array);
@@ -121,7 +125,7 @@ export async function dasum(device, n, x, incx) {
     if (resultHiBuffer) destroyBuffers(resultHiBuffer);
     if (resultLoBuffer) destroyBuffers(resultLoBuffer);
     if (paramsBuffer) destroyBuffers(paramsBuffer);
-    // Only reached if submit(enc2) threw before ownership was transferred above.
+    // Only reached if submit(device, enc2) threw before ownership was transferred above.
     if (readHiBuffer) destroyBuffers(readHiBuffer);
     if (readLoBuffer) destroyBuffers(readLoBuffer);
   }

package/src/devdocs.mjs

@@ -4,6 +4,19 @@
  * repository and explains the reasoning behind it — not just what the code
  * does, but why it is shaped the way it is.
  *
+ * ## How These Docs Are Organized
+ *
+ * The sidebar's top-level modules mirror the repository's top-level folders.
+ * `devdocs` stands in for `src/` — the module you're reading right now is a
+ * narrated walkthrough of it, with `devdocs/blas-routines` and
+ * `devdocs/shaders` covering `src/index.mjs` and `src/shaders/`
+ * respectively. Its siblings — `assets`, `benchmarks`, `examples`, `scripts`,
+ * `tests` — each document the identically-named top-level folder.
+ *
+ * `docs` is the one exception: it's the public API reference generated from
+ * `index.d.mts`, not a tour of the top-level `docs/` folder. That folder is
+ * this site's own generated output — the two just happen to share a name.
+ *
  * ## What is BLAS?
  *
  * BLAS (Basic Linear Algebra Subprograms) is a standard API for vector and

package/src/idamax/idamax.d.mts

@@ -0,0 +1,69 @@
+import { GpuVector } from "../classes/GpuVector.mjs";
+
+/**
+ * Returns the 0-based index of the element with the largest absolute value,
+ * for a vector of doubles: $$\text{index} = \arg\max_{i} |x_i|$$
+ * Each element of `x` is split into a (hi, lo)
+ * double-double f32 pair (see `splitDoubleDouble`/`f64.mjs`) since WGSL has
+ * no f64 type; comparisons use the double-double pair directly (hi, falling
+ * back to lo on an exact tie), giving ~48 bits of discriminating precision —
+ * more than a single f32 (24 bits) but less than true f64 (52 bits). Ties
+ * are broken in favour of the lower index, matching CBLAS behaviour.
+ *
+ * **NaN handling.** The search compares with `>`, which is false for NaN, so
+ * NaN elements are skipped rather than selected: a vector of all NaN returns
+ * `0`. This matches CBLAS except when `x[0]` itself is NaN — CBLAS seeds its
+ * running maximum from `x[0]`, and since no comparison against NaN succeeds it
+ * returns `0` however large the later elements are, whereas this returns the
+ * index of the largest non-NaN element. `+-Infinity` compares normally and is
+ * selected as the maximum.
+ *
+ * {@includeCode ../../examples/idamax/idamax.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/idamax/web/idamax.html}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements (must be a positive integer)
+ * @param x - Float64Array input vector
+ * @param incx - stride for x (must be a positive integer)
+ * @returns 0-based index of max |x[i]|
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/idamax/idamax.mjs#L19">Source code: idamax.mjs (L19)</a>
+ * @category BLAS Level 1
+ */
+export declare function idamax(
+  device: GPUDevice,
+  n: number,
+  x: Float64Array,
+  incx: number,
+): Promise<{ index: number } | { index: number; gpuTimeMs: number }>;
+
+/**
+ * Returns the 0-based index of the element with the largest absolute value:
+ * $$\text{index} = \arg\max_{i} |x_i|$$
+ * Ties are broken in favour of the lower index, matching CBLAS behaviour.
+ *
+ * **NaN handling.** The search compares with `>`, which is false for NaN, so
+ * NaN elements are skipped rather than selected: a vector of all NaN returns
+ * `0`. This matches CBLAS except when `x[0]` itself is NaN — CBLAS seeds its
+ * running maximum from `x[0]`, and since no comparison against NaN succeeds it
+ * returns `0` however large the later elements are, whereas this returns the
+ * index of the largest non-NaN element. `+-Infinity` compares normally and is
+ * selected as the maximum.
+ *
+ * {@includeCode ../../examples/idamax/gpu.idamax.js}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements (must be a positive integer)
+ * @param x - Float64Array-backed GpuVector input vector
+ * @param incx - stride for x (must be a positive integer)
+ * @returns 0-based index of max |x[i]|
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/idamax/idamax.mjs#L19">Source code: idamax.mjs (L19)</a>
+ * @category BLAS Level 1
+ */
+export declare function idamax(
+  device: GPUDevice,
+  n: number,
+  x: GpuVector,
+  incx: number,
+): Promise<{ index: number } | { index: number; gpuTimeMs: number }>;