wgblas 0.1.0

package/src/sasum/sasum.d.mts

@@ -0,0 +1,44 @@
+import { GpuVector } from "../classes/GpuVector.mjs";
+
+/**
+ * Computes the sum of absolute values of a vector: result = sum(|x[i]|)
+ *
+ * {@includeCode ../../examples/sasum/sasum.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/sasum/web/sasum.html}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements (must be a positive integer)
+ * @param x - Float32Array input vector
+ * @param incx - stride for x (must be a positive integer)
+ * @returns absolute sum scalar — always a CPU readback, even for GpuVector inputs
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/sasum/sasum.mjs#L18">Source code: sasum.mjs (L18)</a>
+ * @category BLAS Level 1
+ */
+export declare function sasum(
+  device: GPUDevice,
+  n: number,
+  x: Float32Array,
+  incx: number,
+): Promise<{ asum: number } | { asum: number; gpuTimeMs: number }>;
+
+/**
+ * Computes the sum of absolute values of a vector: result = sum(|x[i]|)
+ *
+ * {@includeCode ../../examples/sasum/gpuvec.sasum.js}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements (must be a positive integer)
+ * @param x - GpuVector input vector
+ * @param incx - stride for x (must be a positive integer)
+ * @returns absolute sum scalar — always a CPU readback, even for GpuVector inputs
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/sasum/sasum.mjs#L18">Source code: sasum.mjs (L18)</a>
+ * @category BLAS Level 1
+ */
+export declare function sasum(
+  device: GPUDevice,
+  n: number,
+  x: GpuVector,
+  incx: number,
+): Promise<{ asum: number } | { asum: number; gpuTimeMs: number }>;

package/src/sasum/sasum.mjs

@@ -0,0 +1,98 @@
+import {
+  uploadBuffer,
+  createStorageBuffer,
+  createParamsBuffer,
+  createResultBuffer,
+  stageReadback,
+  destroyBuffers,
+} from "../util/buffer.mjs";
+import { createBindGroup } from "../util/bindgroup.mjs";
+import { runComputePass, submit } from "../util/compute.mjs";
+import { extractTimestamp } from "../util/benchmark.mjs";
+import { extractResult } from "../util/result.mjs";
+import { getPipeline } from "../util/pipeline.mjs";
+import { GpuVector } from "../classes/GpuVector.mjs";
+
+const WGS = 64; // workgroup size
+
+export async function sasum(device, n, x, incx) {
+  const xIsGpu = x instanceof GpuVector;
+
+  if (!(device instanceof GPUDevice))
+    throw new Error("device must be a GPUDevice.");
+  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.");
+  if (!xIsGpu && !(x instanceof Float32Array))
+    throw new Error("x must be a Float32Array or GpuVector.");
+  if (n <= 0) return { asum: 0 };
+  if (x.length < (n - 1) * incx + 1)
+    throw new Error(
+      "x does not have enough elements for the given n and incx.",
+    );
+
+  const pipelineMain = await getPipeline(device, "sasum");
+  const pipelineReduce = await getPipeline(device, "reduction/sum");
+
+  const xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "sasum-x", false);
+  const partialsBuffer = createStorageBuffer(2 * WGS * 4, "sasum-partials"); // 2*WGS partial sums of f32
+  const resultBuffer = createResultBuffer(4, "sasum-result"); // final f32 scalar
+  const paramsBuffer = createParamsBuffer(
+    [
+      { value: n, type: "u32" },
+      { value: incx, type: "u32" },
+    ],
+    "sasum-params",
+  );
+
+  const bgMain = createBindGroup(pipelineMain.getBindGroupLayout(0), [
+    xBuffer,
+    partialsBuffer,
+    paramsBuffer,
+  ]);
+  const { commandEncoder: enc1, ts: ts1 } = runComputePass(
+    pipelineMain,
+    bgMain,
+    2 * WGS,
+  ); // dispatch 2*WGS workgroups
+
+  submit(enc1);
+
+  const bgReduce = createBindGroup(pipelineReduce.getBindGroupLayout(0), [
+    partialsBuffer,
+    resultBuffer,
+  ]);
+  const { commandEncoder: enc2, ts: ts2 } = runComputePass(
+    pipelineReduce,
+    bgReduce,
+    1,
+  ); // dispatch 1 workgroup to reduce the partial sums to a single result
+  const readBuffer = stageReadback(enc2, resultBuffer);
+
+  submit(enc2);
+
+  const [gpuTime1, gpuTime2, asumArr] = await Promise.all([
+    extractTimestamp(ts1),
+    extractTimestamp(ts2),
+    extractResult(readBuffer, Float32Array),
+  ]);
+
+  // asum is always a scalar readback — both paths return { asum }
+  if (xIsGpu) {
+    destroyBuffers(partialsBuffer, resultBuffer, paramsBuffer, readBuffer);
+    if (gpuTime1 !== undefined && gpuTime2 !== undefined)
+      return { asum: asumArr[0], gpuTimeMs: gpuTime1 + gpuTime2 };
+    return { asum: asumArr[0] };
+  }
+
+  destroyBuffers(
+    xBuffer,
+    partialsBuffer,
+    resultBuffer,
+    paramsBuffer,
+    readBuffer,
+  );
+  if (gpuTime1 !== undefined && gpuTime2 !== undefined)
+    return { asum: asumArr[0], gpuTimeMs: gpuTime1 + gpuTime2 };
+  return { asum: asumArr[0] };
+}

package/src/saxpy/saxpy.d.mts

@@ -0,0 +1,54 @@
+import { GpuVector } from "../classes/GpuVector.mjs";
+
+/**
+ * Performs the operation y = alpha * x + y
+ *
+ * {@includeCode ../../examples/saxpy/saxpy.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/saxpy/web/saxpy.html}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements (must be a positive integer)
+ * @param alpha - scalar multiplier
+ * @param x - Float32Array input vector
+ * @param incx - stride for x (must be a positive integer)
+ * @param y - Float32Array input/output vector
+ * @param incy - stride for y (must be a positive integer)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/saxpy/saxpy.mjs#L15">Source code: saxpy.mjs (L15)</a>
+ * @category BLAS Level 1
+ */
+export declare function saxpy(
+  device: GPUDevice,
+  n: number,
+  alpha: number,
+  x: Float32Array,
+  incx: number,
+  y: Float32Array,
+  incy: number,
+): Promise<{ y: Float32Array } | { y: Float32Array; gpuTimeMs: number }>;
+
+/**
+ * Performs the operation y = alpha * x + y
+ *
+ * {@includeCode ../../examples/saxpy/gpuvec.saxpy.js}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements (must be a positive integer)
+ * @param alpha - scalar multiplier
+ * @param x - GpuVector input vector
+ * @param incx - stride for x (must be a positive integer)
+ * @param y - GpuVector input/output vector (mutated in place)
+ * @param incy - stride for y (must be a positive integer)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/saxpy/saxpy.mjs#L15">Source code: saxpy.mjs (L15)</a>
+ * @category BLAS Level 1
+ */
+export declare function saxpy(
+  device: GPUDevice,
+  n: number,
+  alpha: number,
+  x: GpuVector,
+  incx: number,
+  y: GpuVector,
+  incy: number,
+): Promise<{} | { gpuTimeMs: number }>;

package/src/saxpy/saxpy.mjs

@@ -0,0 +1,90 @@
+import {
+  uploadBuffer,
+  createParamsBuffer,
+  stageReadback,
+  destroyBuffers,
+} from "../util/buffer.mjs";
+import { createBindGroup } from "../util/bindgroup.mjs";
+import { runComputePass, submit } from "../util/compute.mjs";
+import { extractResult } from "../util/result.mjs";
+import { extractTimestamp } from "../util/benchmark.mjs";
+import { getPipeline } from "../util/pipeline.mjs";
+import { calcWorkgroups } from "../util/workgroup.mjs";
+import { GpuVector } from "../classes/GpuVector.mjs";
+
+export async function saxpy(device, n, alpha, x, incx, y, incy) {
+  const xIsGpu = x instanceof GpuVector;
+  const yIsGpu = y instanceof GpuVector;
+
+  if (!(device instanceof GPUDevice))
+    throw new Error("device must be a GPUDevice.");
+  if (
+    !Number.isInteger(n) ||
+    !Number.isInteger(incx) ||
+    !Number.isInteger(incy)
+  )
+    throw new Error("n, incx, and incy must be integers.");
+  if (isNaN(alpha)) throw new Error("alpha must not be NaN.");
+  if (!isFinite(alpha)) throw new Error("alpha must be finite.");
+  if (incx <= 0 || incy <= 0)
+    throw new Error("incx and incy must be positive.");
+  if (!xIsGpu && !(x instanceof Float32Array))
+    throw new Error("x must be a Float32Array or GpuVector.");
+  if (!yIsGpu && !(y instanceof Float32Array))
+    throw new Error("y must be a Float32Array or GpuVector.");
+  if (xIsGpu !== yIsGpu)
+    throw new Error(
+      "x and y must be the same type (both Float32Array or both GpuVector).",
+    );
+  if (n <= 0) return yIsGpu ? {} : { y };
+  if (x.length < (n - 1) * incx + 1)
+    throw new Error(
+      "x does not have enough elements for the given n and incx.",
+    );
+  if (y.length < (n - 1) * incy + 1)
+    throw new Error(
+      "y does not have enough elements for the given n and incy.",
+    );
+
+  const pipeline = await getPipeline(device, "saxpy");
+
+  const xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "saxpy-x", false);
+  const yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "saxpy-y", true);
+  const paramsBuffer = createParamsBuffer(
+    [
+      { value: n, type: "u32" },
+      { value: alpha, type: "f32" },
+      { value: incx, type: "u32" },
+      { value: incy, type: "u32" },
+    ],
+    "saxpy-params",
+  );
+
+  const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
+    xBuffer,
+    yBuffer,
+    paramsBuffer,
+  ]);
+  const { commandEncoder, ts } = runComputePass(
+    pipeline,
+    bindGroup,
+    calcWorkgroups(n),
+  );
+  const readBuffer = yIsGpu ? null : stageReadback(commandEncoder, yBuffer);
+
+  submit(commandEncoder);
+
+  const gpuTimeMs = await extractTimestamp(ts);
+
+  if (yIsGpu && xIsGpu) {
+    destroyBuffers(paramsBuffer);
+    if (gpuTimeMs !== undefined) return { gpuTimeMs };
+    return {};
+  }
+
+  const result = await extractResult(readBuffer, Float32Array);
+  destroyBuffers(xBuffer, yBuffer, paramsBuffer, readBuffer);
+
+  if (gpuTimeMs !== undefined) return { y: result, gpuTimeMs };
+  return { y: result };
+}

package/src/scopy/scopy.d.mts

@@ -0,0 +1,50 @@
+import { GpuVector } from "../classes/GpuVector.mjs";
+
+/**
+ * Performs the operation y = x
+ *
+ * {@includeCode ../../examples/scopy/scopy.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/scopy/web/scopy.html}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements (must be a positive integer)
+ * @param x - Float32Array input vector
+ * @param incx - stride for x (must be a positive integer)
+ * @param y - Float32Array output vector
+ * @param incy - stride for y (must be a positive integer)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/scopy/scopy.mjs#L15">Source code: scopy.mjs (L15)</a>
+ * @category BLAS Level 1
+ */
+export declare function scopy(
+  device: GPUDevice,
+  n: number,
+  x: Float32Array,
+  incx: number,
+  y: Float32Array,
+  incy: number,
+): Promise<{ y: Float32Array } | { y: Float32Array; gpuTimeMs: number }>;
+
+/**
+ * Performs the operation y = x
+ *
+ * {@includeCode ../../examples/scopy/gpuvec.scopy.js}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements (must be a positive integer)
+ * @param x - GpuVector input vector
+ * @param incx - stride for x (must be a positive integer)
+ * @param y - GpuVector output vector (mutated in place)
+ * @param incy - stride for y (must be a positive integer)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/scopy/scopy.mjs#L15">Source code: scopy.mjs (L15)</a>
+ * @category BLAS Level 1
+ */
+export declare function scopy(
+  device: GPUDevice,
+  n: number,
+  x: GpuVector,
+  incx: number,
+  y: GpuVector,
+  incy: number,
+): Promise<{} | { gpuTimeMs: number }>;

package/src/scopy/scopy.mjs

@@ -0,0 +1,87 @@
+import {
+  uploadBuffer,
+  createParamsBuffer,
+  stageReadback,
+  destroyBuffers,
+} from "../util/buffer.mjs";
+import { createBindGroup } from "../util/bindgroup.mjs";
+import { runComputePass, submit } from "../util/compute.mjs";
+import { extractResult } from "../util/result.mjs";
+import { extractTimestamp } from "../util/benchmark.mjs";
+import { getPipeline } from "../util/pipeline.mjs";
+import { calcWorkgroups } from "../util/workgroup.mjs";
+import { GpuVector } from "../classes/GpuVector.mjs";
+
+export async function scopy(device, n, x, incx, y, incy) {
+  const xIsGpu = x instanceof GpuVector;
+  const yIsGpu = y instanceof GpuVector;
+
+  if (!(device instanceof GPUDevice))
+    throw new Error("device must be a GPUDevice.");
+  if (
+    !Number.isInteger(n) ||
+    !Number.isInteger(incx) ||
+    !Number.isInteger(incy)
+  )
+    throw new Error("n, incx, and incy must be integers.");
+  if (incx <= 0 || incy <= 0)
+    throw new Error("incx and incy must be positive.");
+  if (!xIsGpu && !(x instanceof Float32Array))
+    throw new Error("x must be a Float32Array or GpuVector.");
+  if (!yIsGpu && !(y instanceof Float32Array))
+    throw new Error("y must be a Float32Array or GpuVector.");
+  if (xIsGpu !== yIsGpu)
+    throw new Error(
+      "x and y must be the same type (both Float32Array or both GpuVector).",
+    );
+  if (n <= 0) return yIsGpu ? {} : { y };
+  if (x.length < (n - 1) * incx + 1)
+    throw new Error(
+      "x does not have enough elements for the given n and incx.",
+    );
+  if (y.length < (n - 1) * incy + 1)
+    throw new Error(
+      "y does not have enough elements for the given n and incy.",
+    );
+
+  const pipeline = await getPipeline(device, "scopy");
+
+  const xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "scopy-x", false);
+  const yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "scopy-y", true);
+  const paramsBuffer = createParamsBuffer(
+    [
+      { value: n, type: "u32" },
+      { value: incx, type: "u32" },
+      { value: incy, type: "u32" },
+    ],
+    "scopy-params",
+  );
+
+  const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
+    xBuffer,
+    yBuffer,
+    paramsBuffer,
+  ]);
+  const { commandEncoder, ts } = runComputePass(
+    pipeline,
+    bindGroup,
+    calcWorkgroups(n),
+  );
+  const readBuffer = yIsGpu ? null : stageReadback(commandEncoder, yBuffer);
+
+  submit(commandEncoder);
+
+  const gpuTimeMs = await extractTimestamp(ts);
+
+  if (yIsGpu && xIsGpu) {
+    destroyBuffers(paramsBuffer);
+    if (gpuTimeMs !== undefined) return { gpuTimeMs };
+    return {};
+  }
+
+  const result = await extractResult(readBuffer, Float32Array);
+  destroyBuffers(xBuffer, yBuffer, paramsBuffer, readBuffer);
+
+  if (gpuTimeMs !== undefined) return { y: result, gpuTimeMs };
+  return { y: result };
+}

package/src/sdot/sdot.d.mts

@@ -0,0 +1,52 @@
+import { GpuVector } from "../classes/GpuVector.mjs";
+
+/**
+ * Computes the dot product of two vectors: result = sum(x[i] * y[i])
+ *
+ * {@includeCode ../../examples/sdot/sdot.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/sdot/web/sdot.html}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements (must be a positive integer)
+ * @param x - Float32Array input vector
+ * @param incx - stride for x (must be a positive integer)
+ * @param y - Float32Array input vector
+ * @param incy - stride for y (must be a positive integer)
+ * @returns dot product scalar — always a CPU readback, even for GpuVector inputs
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/sdot/sdot.mjs#L18">Source code: sdot.mjs (L18)</a>
+ * @category BLAS Level 1
+ */
+export declare function sdot(
+  device: GPUDevice,
+  n: number,
+  x: Float32Array,
+  incx: number,
+  y: Float32Array,
+  incy: number,
+): Promise<{ dot: number } | { dot: number; gpuTimeMs: number }>;
+
+/**
+ * Computes the dot product of two vectors: result = sum(x[i] * y[i])
+ *
+ * {@includeCode ../../examples/sdot/gpuvec.sdot.js}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements (must be a positive integer)
+ * @param x - GpuVector input vector
+ * @param incx - stride for x (must be a positive integer)
+ * @param y - GpuVector input vector
+ * @param incy - stride for y (must be a positive integer)
+ * @returns dot product scalar — always a CPU readback, even for GpuVector inputs
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/sdot/sdot.mjs#L18">Source code: sdot.mjs (L18)</a>
+ * @category BLAS Level 1
+ */
+export declare function sdot(
+  device: GPUDevice,
+  n: number,
+  x: GpuVector,
+  incx: number,
+  y: GpuVector,
+  incy: number,
+): Promise<{ dot: number } | { dot: number; gpuTimeMs: number }>;

package/src/sdot/sdot.mjs

@@ -0,0 +1,118 @@
+import {
+  uploadBuffer,
+  createStorageBuffer,
+  createParamsBuffer,
+  createResultBuffer,
+  stageReadback,
+  destroyBuffers,
+} from "../util/buffer.mjs";
+import { createBindGroup } from "../util/bindgroup.mjs";
+import { runComputePass, submit } from "../util/compute.mjs";
+import { extractTimestamp } from "../util/benchmark.mjs";
+import { extractResult } from "../util/result.mjs";
+import { getPipeline } from "../util/pipeline.mjs";
+import { GpuVector } from "../classes/GpuVector.mjs";
+
+const WGS = 64; //workgroup size
+
+export async function sdot(device, n, x, incx, y, incy) {
+  const xIsGpu = x instanceof GpuVector;
+  const yIsGpu = y instanceof GpuVector;
+
+  if (!(device instanceof GPUDevice))
+    throw new Error("device must be a GPUDevice.");
+  if (
+    !Number.isInteger(n) ||
+    !Number.isInteger(incx) ||
+    !Number.isInteger(incy)
+  )
+    throw new Error("n, incx, and incy must be integers.");
+  if (incx <= 0 || incy <= 0)
+    throw new Error("incx and incy must be positive.");
+  if (!xIsGpu && !(x instanceof Float32Array))
+    throw new Error("x must be a Float32Array or GpuVector.");
+  if (!yIsGpu && !(y instanceof Float32Array))
+    throw new Error("y must be a Float32Array or GpuVector.");
+  if (xIsGpu !== yIsGpu)
+    throw new Error(
+      "x and y must be the same type (both Float32Array or both GpuVector).",
+    );
+  if (n <= 0) return { dot: 0 };
+  if (x.length < (n - 1) * incx + 1)
+    throw new Error(
+      "x does not have enough elements for the given n and incx.",
+    );
+  if (y.length < (n - 1) * incy + 1)
+    throw new Error(
+      "y does not have enough elements for the given n and incy.",
+    );
+
+  const pipelineMain = await getPipeline(device, "sdot");
+  const pipelineReduce = await getPipeline(device, "reduction/sum");
+
+  const xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "sdot-x", false);
+  const yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "sdot-y", false);
+  const partialsBuffer = createStorageBuffer(2 * WGS * 4, "sdot-partials"); //to hold 2*WGS partial sums of f32
+  const resultBuffer = createResultBuffer(4, "sdot-result"); //to hold the final float32 dot product
+  const paramsBuffer = createParamsBuffer(
+    [
+      { value: n, type: "u32" },
+      { value: incx, type: "u32" },
+      { value: incy, type: "u32" },
+    ],
+    "sdot-params",
+  );
+
+  const bgMain = createBindGroup(pipelineMain.getBindGroupLayout(0), [
+    xBuffer,
+    yBuffer,
+    partialsBuffer,
+    paramsBuffer,
+  ]);
+  const { commandEncoder: enc1, ts: ts1 } = runComputePass(
+    pipelineMain,
+    bgMain,
+    2 * WGS,
+  ); //dispatch 2*WGS workgroups
+
+  submit(enc1);
+
+  const bgReduce = createBindGroup(pipelineReduce.getBindGroupLayout(0), [
+    partialsBuffer,
+    resultBuffer,
+  ]);
+  const { commandEncoder: enc2, ts: ts2 } = runComputePass(
+    pipelineReduce,
+    bgReduce,
+    1,
+  ); // dispatch 1 workgroup to reduce the partial sums to a single result
+  const readBuffer = stageReadback(enc2, resultBuffer);
+
+  submit(enc2);
+
+  const [gpuTime1, gpuTime2, dotArr] = await Promise.all([
+    extractTimestamp(ts1),
+    extractTimestamp(ts2),
+    extractResult(readBuffer, Float32Array),
+  ]);
+
+  // dot is always a scalar readback — both paths return { dot }
+  if (xIsGpu && yIsGpu) {
+    destroyBuffers(partialsBuffer, resultBuffer, paramsBuffer, readBuffer);
+    if (gpuTime1 !== undefined && gpuTime2 !== undefined)
+      return { dot: dotArr[0], gpuTimeMs: gpuTime1 + gpuTime2 };
+    return { dot: dotArr[0] };
+  }
+
+  destroyBuffers(
+    xBuffer,
+    yBuffer,
+    partialsBuffer,
+    resultBuffer,
+    paramsBuffer,
+    readBuffer,
+  );
+  if (gpuTime1 !== undefined && gpuTime2 !== undefined)
+    return { dot: dotArr[0], gpuTimeMs: gpuTime1 + gpuTime2 };
+  return { dot: dotArr[0] };
+}

package/src/shaders/browser-shaders.mjs

@@ -0,0 +1,27 @@
+import argmax from "./reduction/argmax.wgsl";
+import sum from "./reduction/sum.wgsl";
+import sscal from "./sscal.wgsl";
+import sswap from "./sswap.wgsl";
+import saxpy from "./saxpy.wgsl";
+import scopy from "./scopy.wgsl";
+import sdot from "./sdot.wgsl";
+import sasum from "./sasum.wgsl";
+import snrm2 from "./snrm2.wgsl";
+import srot from "./srot.wgsl";
+import srotm from "./srotm.wgsl";
+import isamax from "./isamax.wgsl";
+
+export const shaderSources = {
+  "reduction/argmax": argmax,
+  "reduction/sum": sum,
+  sscal,
+  sswap,
+  saxpy,
+  scopy,
+  sdot,
+  sasum,
+  snrm2,
+  srot,
+  srotm,
+  isamax,
+};

package/src/shaders/index.mjs

@@ -0,0 +1,27 @@
+/**
+ * ## Structure
+ *
+ * `shaders/*.wgsl` — one WGSL compute shader per BLAS routine (sscal, saxpy, sdot, …).
+ *
+ * `shaders/browser-shaders.mjs` — the browser's runtime shader source. In Node.js, shaders are
+ * read directly from disk via `readFileSync`. In the browser there is no filesystem, so this file
+ * provides all shader strings inline. Vite bundles it by importing each `.wgsl` file as a string.
+ *
+ * ## Cross-shader patterns
+ *
+ * **Fixed workgroup size of 64.** Every shader declares `const WGS: u32 = 64` and
+ * `@workgroup_size(64)`. 64 is the minimum `maxComputeInvocationsPerWorkgroup` guaranteed across
+ * all WebGPU devices, so this works everywhere without querying device limits.
+ *
+ * **Single bind group.** All bindings use `@group(0)`. This means the JS side always calls
+ * `pipeline.getBindGroupLayout(0)` — no secondary groups to track.
+ *
+ * The `@binding` indices must match the position of each resource in the array passed to
+ * `createBindGroup` — it assigns `binding: 0, 1, 2 …` sequentially, with `resultBuffer` appended last.
+ *
+ * **All counts and strides are `u32`.** `n`, `x_inc`, `y_inc`, and any other index fields in the
+ * `Params` uniform struct are unsigned. This avoids implicit sign-extension when they appear in
+ * index expressions like `id * params.x_inc`.
+ *
+ * @module devdocs/shaders
+ */