wgblas 0.1.0

package/package.json

@@ -0,0 +1,127 @@
+{
+  "name": "wgblas",
+  "version": "0.1.0",
+  "description": "BLAS on WebGPU",
+  "type": "module",
+  "main": "index.mjs",
+  "types": "./index.d.mts",
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "types": "./index.d.mts"
+    },
+    "./browser": "./dist/wgblas.browser.js",
+    "./classes/GpuVector": {
+      "import": "./src/classes/GpuVector.mjs",
+      "types": "./src/classes/GpuVector.d.mts"
+    },
+    "./random": {
+      "import": "./src/random/random.mjs",
+      "types": "./src/random/random.d.mts"
+    },
+    "./sscal": {
+      "import": "./src/sscal/sscal.mjs",
+      "types": "./src/sscal/sscal.d.mts"
+    },
+    "./sswap": {
+      "import": "./src/sswap/sswap.mjs",
+      "types": "./src/sswap/sswap.d.mts"
+    },
+    "./saxpy": {
+      "import": "./src/saxpy/saxpy.mjs",
+      "types": "./src/saxpy/saxpy.d.mts"
+    },
+    "./scopy": {
+      "import": "./src/scopy/scopy.mjs",
+      "types": "./src/scopy/scopy.d.mts"
+    },
+    "./sdot": {
+      "import": "./src/sdot/sdot.mjs",
+      "types": "./src/sdot/sdot.d.mts"
+    },
+    "./sasum": {
+      "import": "./src/sasum/sasum.mjs",
+      "types": "./src/sasum/sasum.d.mts"
+    },
+    "./snrm2": {
+      "import": "./src/snrm2/snrm2.mjs",
+      "types": "./src/snrm2/snrm2.d.mts"
+    },
+    "./isamax": {
+      "import": "./src/isamax/isamax.mjs",
+      "types": "./src/isamax/isamax.d.mts"
+    },
+    "./srot": {
+      "import": "./src/srot/srot.mjs",
+      "types": "./src/srot/srot.d.mts"
+    },
+    "./srotm": {
+      "import": "./src/srotm/srotm.mjs",
+      "types": "./src/srotm/srotm.d.mts"
+    }
+  },
+  "files": [
+    "index.mjs",
+    "index.d.mts",
+    "src/**/*.mjs",
+    "src/**/*.d.mts",
+    "dist/wgblas.browser.js"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manit2004/wgblas.git"
+  },
+  "keywords": [
+    "BLAS",
+    "WebGPU"
+  ],
+  "author": "Manit Roy",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "bugs": {
+    "url": "https://github.com/manit2004/wgblas/issues"
+  },
+  "homepage": "https://github.com/manit2004/wgblas#readme",
+  "dependencies": {
+    "webgpu": "^0.4.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.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-snrm2": "^0.3.1",
+    "@stdlib/blas-base-srot": "^0.2.1",
+    "@stdlib/blas-base-srotm": "^0.2.1",
+    "@stdlib/blas-base-sscal": "^0.3.1",
+    "@stdlib/blas-base-sswap": "^0.3.1",
+    "@stdlib/random-array-uniform": "^0.2.2",
+    "@stdlib/random-base-uniform": "^0.2.3",
+    "esbuild": "^0.28.1",
+    "eslint": "^10.6.0",
+    "fast-check": "^4.8.0",
+    "globals": "^17.7.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.0.8",
+    "prettier": "^3.9.4",
+    "typedoc": "^0.28.19",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16"
+  },
+  "scripts": {
+    "prepare": "husky",
+    "build:browser": "node scripts/build-browser.mjs",
+    "docs": "npx typedoc && npm run build:browser",
+    "prepublishOnly": "npm run build:browser"
+  },
+  "lint-staged": {
+    "*.{js,mjs,cjs}": [
+      "prettier --write",
+      "eslint"
+    ]
+  }
+}

package/src/classes/GpuVector.d.mts

@@ -0,0 +1,69 @@
+/**
+ * Represents a Float32Array stored in GPU memory.
+ *
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/classes/GpuVector.mjs#L7">Source code: GpuVector.mjs (L7)</a>
+ * @see [MDN: GPUBuffer](https://developer.mozilla.org/en-US/docs/Web/API/GPUBuffer)
+ * @category Classes
+ */
+export declare class GpuVector {
+  /** @internal */
+  readonly _buf: GPUBuffer;
+
+  /** Number of elements in the vector. */
+  readonly length: number;
+
+  // TODO: widen to Float32ArrayConstructor | Float64ArrayConstructor when Float64 support is added
+  /** Typed array constructor used when reading data back from the GPU. */
+  readonly dtype: Float32ArrayConstructor;
+
+  /**
+   * Uploads a Float32Array to GPU memory.
+   *
+   * @param data - input vector data
+   * @returns GpuVector backed by a GPU buffer
+   *
+   * @example
+   * ```js
+   * import { init, GpuVector } from "wgblas";
+   *
+   * await init();
+   * const vec = GpuVector.from(new Float32Array([1, 2, 3, 4]));
+   * console.log("length:", vec.length, "dtype:", vec.dtype.name);
+   * ```
+   */
+  static from(data: Float32Array): GpuVector;
+
+  // TODO: return type will widen to Promise<Float32Array | Float64Array> when Float64 support is added
+  /**
+   * Reads the vector data back from GPU memory.
+   *
+   * @returns vector data as a Float32Array
+   *
+   * @example
+   * ```js
+   * import { init, GpuVector } from "wgblas";
+   *
+   * await init();
+   * const vec = GpuVector.from(new Float32Array([1, 2, 3, 4]));
+   * const data = await vec.read();
+   * console.log(data);
+   * ```
+   */
+  read(): Promise<Float32Array>;
+
+  /**
+   * Destroys the underlying GPU buffer. Call when the vector is no longer needed
+   * to free GPU memory — especially important in long-running programs.
+   *
+   * @example
+   * ```js
+   * import { init, GpuVector } from "wgblas";
+   *
+   * await init();
+   * const vec = GpuVector.from(new Float32Array([1, 2, 3, 4]));
+   * vec.destroy();
+   * console.log("GPU buffer released");
+   * ```
+   */
+  destroy(): void;
+}

package/src/classes/GpuVector.mjs

@@ -0,0 +1,33 @@
+import { getDevice } from "../init.mjs";
+import { uploadBuffer, stageReadback } from "../util/buffer.mjs";
+import { extractResult } from "../util/result.mjs";
+
+//TODO: Need to update this when we support Float64Array.
+
+export class GpuVector {
+  constructor(buffer, length, dtype = Float32Array) {
+    this._buf = buffer;
+    this.length = length;
+    this.dtype = dtype;
+  }
+
+  static from(data) {
+    if (!(data instanceof Float32Array)) {
+      throw new Error("GpuVector.from expects a Float32Array.");
+    }
+    const buf = uploadBuffer(data, "gpu-vector", true);
+    return new GpuVector(buf, data.length, data.constructor);
+  }
+
+  async read() {
+    const device = getDevice();
+    const enc = device.createCommandEncoder();
+    const rb = stageReadback(enc, this._buf);
+    device.queue.submit([enc.finish()]);
+    return extractResult(rb, this.dtype);
+  }
+
+  destroy() {
+    this._buf.destroy();
+  }
+}

package/src/devdocs.mjs

@@ -0,0 +1,81 @@
+/**
+ * A repo tour for contributors, learners, and anyone curious how a GPU BLAS
+ * library is built. Each section mirrors a major folder or system in the
+ * repository and explains the reasoning behind it — not just what the code
+ * does, but why it is shaped the way it is.
+ *
+ * ## What is BLAS?
+ *
+ * BLAS (Basic Linear Algebra Subprograms) is a standard API for vector and
+ * matrix operations — dot products, norms, scalar multiplies, matrix-vector
+ * products. It is the computational backbone of numerical computing, machine
+ * learning frameworks, and scientific software. The reference spec lives at
+ * [netlib.org/blas](https://www.netlib.org/blas/).
+ *
+ * GPUs are well-suited for BLAS: operations like saxpy (y = αx + y) are
+ * embarrassingly parallel — each element is independent — so thousands of GPU
+ * threads can work simultaneously. NVIDIA's
+ * [cuBLAS](https://docs.nvidia.com/cuda/cublas/) is the canonical example;
+ * this library applies the same idea to the browser via WebGPU.
+ *
+ * ## What is WebGPU?
+ *
+ * WebGPU is the modern browser GPU API, shipping in Chrome 113+ and Firefox
+ * nightly. It lets JavaScript programs upload data to the GPU, run compute
+ * programs on it, and read results back — without plugins or native code.
+ *
+ * > **Note:** WGSL does not support `f64` natively, so this library currently
+ * > implements single-precision (`f32`) routines only.
+ *
+ * ## What is a compute shader?
+ *
+ * Each routine runs a **compute shader** written in WGSL (a GPU program that
+ * runs thousands of instances in parallel, each processing one element). WebGPU
+ * has vertex and fragment shaders for graphics too — compute shaders are
+ * specifically for general computation. This library only uses compute shaders,
+ * so we call them simply "shaders" throughout.
+ *
+ * ## New to GPU programming?
+ *
+ * Read these two chapters from the CUDA Programming Guide — the mental models
+ * transfer directly to WebGPU; only the terminology changes. Then come back here.
+ *
+ * - [Introduction](https://docs.nvidia.com/cuda/cuda-programming-guide/01-introduction/introduction.html) —
+ *   why GPUs exist, GPU vs CPU design philosophy
+ * - [Programming Model](https://docs.nvidia.com/cuda/cuda-programming-guide/01-introduction/programming-model.html) —
+ *   threads, blocks, grids, warps, memory hierarchy
+ *
+ * ### CUDA → WebGPU terminology
+ *
+ * | CUDA | WebGPU |
+ * |---|---|
+ * | Thread | Invocation |
+ * | Thread block | Workgroup |
+ * | Grid | Dispatch |
+ * | `__global__` function | `@compute` shader |
+ * | `threadIdx.x` | `local_invocation_id` |
+ * | `blockIdx.x` | `workgroup_id` |
+ * | `blockDim.x` | `@workgroup_size(N)` |
+ * | Shared memory | `var<workgroup>` |
+ * | Global memory | Storage buffer |
+ * | `cudaMemcpy` host→device | `device.queue.writeBuffer` |
+ * | `cudaMemcpy` device→host | `mapAsync` + `getMappedRange` |
+ *
+ * ## WebGPU resources
+ *
+ * - [WebGPU Fundamentals](https://webgpufundamentals.org/webgpu/lessons/webgpu-fundamentals.html#a-run-computations-on-the-gpu) —
+ *   running computations on the GPU
+ * - [WebGPU Compute Shaders](https://webgpufundamentals.org/webgpu/lessons/webgpu-compute-shaders.html)
+ * - [GPU Compute with WebGPU](https://developer.chrome.com/docs/capabilities/web-apis/gpu-compute?hl=en) —
+ *   Chrome's practical guide to compute pipelines
+ * - [Chrome WebGPU overview](https://developer.chrome.com/docs/web-platform/webgpu/overview?hl=en)
+ *
+ * ### Further reading
+ *
+ * - [Chrome "New in WebGPU" series](https://developer.chrome.com/tags/new-in-webgpu) —
+ *   feature-by-feature changelog with code examples
+ * - [MDN WebGPU API](https://developer.mozilla.org/en-US/docs/Web/API/WebGPU_API)
+ * - [W3C WebGPU spec](https://www.w3.org/TR/webgpu/)
+ *
+ * @module devdocs
+ */

package/src/index.mjs

@@ -0,0 +1,4 @@
+/**
+ * {@include ./README.md}
+ * @module devdocs/blas-routines
+ */

package/src/init.mjs

@@ -0,0 +1,105 @@
+import { benchmarkMode } from "./util/benchmark.mjs";
+
+let _device = null;
+let _adapter = null;
+let _gpu = null; // eslint-disable-line no-unused-vars
+let _benchmarkEnabled = false;
+
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+export async function init({
+  powerPreference = "high-performance",
+  benchmark = false,
+} = {}) {
+  if (_device) {
+    return _device;
+  }
+
+  let gpu;
+  // Browser exposes WebGPU natively via navigator.gpu.
+  // Node.js has no navigator, so we polyfill using the "webgpu" npm package which also
+  // injects WebGPU globals (GPUBufferUsage, GPUShaderStage, etc.) into globalThis.
+  if (typeof window === "undefined") {
+    const { create, globals } = await import("webgpu");
+    Object.assign(globalThis, globals);
+    gpu = create([]);
+    _gpu = gpu;
+  } else {
+    gpu = navigator.gpu;
+  }
+
+  if (!gpu) {
+    throw new Error("WebGPU not supported in this environment.");
+  }
+
+  _adapter =
+    (await gpu.requestAdapter({ powerPreference })) ??
+    (await gpu.requestAdapter());
+  if (!_adapter) {
+    throw new Error("No WebGPU adapter found.");
+  }
+
+  _benchmarkEnabled = benchmark;
+  _device = await _adapter.requestDevice(benchmarkMode(_adapter, benchmark));
+  // Fires for any GPU error not caught by a pushErrorScope/popErrorScope pair — surfaces silent GPU failures to the console.
+  // See: https://developer.mozilla.org/en-US/docs/Web/API/GPUDevice/uncapturederror_event
+  _device.addEventListener("uncapturederror", (e) => {
+    console.error("Uncaptured GPU error:", e.error.message);
+  });
+
+  return _device;
+}
+
+export function cleanup() {
+  if (_device) {
+    _device.destroy();
+    _device = null;
+  }
+  _adapter = null;
+  _gpu = null;
+  _benchmarkEnabled = false;
+}
+
+export function gpuName() {
+  if (!_adapter) {
+    throw new Error("WebGPU adapter not initialized — call init() first.");
+  }
+  const { device, description } = _adapter.info;
+  return {
+    description: description || "unknown",
+    device: device || "unknown",
+  };
+}
+
+// ── Library internals (not part of the public API) ───────────────────────────
+
+/** @returns {boolean} whether benchmark mode was enabled in the last `init()` call */
+export function isBenchmarkEnabled() {
+  return _benchmarkEnabled;
+}
+
+/**
+ * Returns the active `GPUDevice`. Throws if `init()` has not been called.
+ * @returns {GPUDevice}
+ * @throws {Error} if the device is not initialized
+ */
+export function getDevice() {
+  if (!_device) {
+    throw new Error("WebGPU device not initialized — call init() first.");
+  }
+  return _device;
+}
+
+/**
+ * Returns the active `GPUAdapter`. Throws if `init()` has not been called.
+ * @returns {GPUAdapter}
+ * @throws {Error} if the adapter is not initialized
+ */
+export function getAdapter() {
+  if (!_adapter) {
+    throw new Error("WebGPU adapter not initialized — call init() first.");
+  }
+  return _adapter;
+}
+

package/src/isamax/isamax.d.mts

@@ -0,0 +1,46 @@
+import { GpuVector } from "../classes/GpuVector.mjs";
+
+/**
+ * Returns the 0-based index of the element with the largest absolute value.
+ * Ties are broken in favour of the lower index, matching CBLAS behaviour.
+ *
+ * {@includeCode ../../examples/isamax/isamax.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/isamax/web/isamax.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 0-based index of max |x[i]|
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/isamax/isamax.mjs#L18">Source code: isamax.mjs (L18)</a>
+ * @category BLAS Level 1
+ */
+export declare function isamax(
+  device: GPUDevice,
+  n: number,
+  x: Float32Array,
+  incx: number,
+): Promise<{ index: number } | { index: number; gpuTimeMs: number }>;
+
+/**
+ * Returns the 0-based index of the element with the largest absolute value.
+ * Ties are broken in favour of the lower index, matching CBLAS behaviour.
+ *
+ * {@includeCode ../../examples/isamax/gpuvec.isamax.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 0-based index of max |x[i]|
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/isamax/isamax.mjs#L18">Source code: isamax.mjs (L18)</a>
+ * @category BLAS Level 1
+ */
+export declare function isamax(
+  device: GPUDevice,
+  n: number,
+  x: GpuVector,
+  incx: number,
+): Promise<{ index: number } | { index: number; gpuTimeMs: number }>;

package/src/isamax/isamax.mjs

@@ -0,0 +1,115 @@
+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;
+
+export async function isamax(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 { index: 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, "isamax");
+  const pipelineReduce = await getPipeline(device, "reduction/argmax");
+
+  const xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "isamax-x", false);
+  const partialsValBuffer = createStorageBuffer(
+    2 * WGS * 4,
+    "isamax-partials-val",
+  ); //to hold 2*WGS partial max values of f32
+  const partialsIdxBuffer = createStorageBuffer(
+    2 * WGS * 4,
+    "isamax-partials-idx",
+  ); //to hold 2*WGS partial max indices of u32
+  const resultBuffer = createResultBuffer(4, "isamax-result"); // u32 index
+  const paramsBuffer = createParamsBuffer(
+    [
+      { value: n, type: "u32" },
+      { value: incx, type: "u32" },
+    ],
+    "isamax-params",
+  );
+
+  const bgMain = createBindGroup(pipelineMain.getBindGroupLayout(0), [
+    xBuffer,
+    partialsValBuffer,
+    partialsIdxBuffer,
+    paramsBuffer,
+  ]);
+  const { commandEncoder: enc1, ts: ts1 } = runComputePass(
+    pipelineMain,
+    bgMain,
+    2 * WGS,
+  ); //dispatch 2*WGS workgroups
+
+  submit(enc1);
+
+  const bgReduce = createBindGroup(pipelineReduce.getBindGroupLayout(0), [
+    partialsValBuffer,
+    partialsIdxBuffer,
+    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, idxArr] = await Promise.all([
+    extractTimestamp(ts1),
+    extractTimestamp(ts2),
+    extractResult(readBuffer, Uint32Array),
+  ]);
+
+  const index = idxArr[0];
+
+  if (xIsGpu) {
+    destroyBuffers(
+      partialsValBuffer,
+      partialsIdxBuffer,
+      resultBuffer,
+      paramsBuffer,
+      readBuffer,
+    );
+    if (gpuTime1 !== undefined && gpuTime2 !== undefined)
+      return { index, gpuTimeMs: gpuTime1 + gpuTime2 };
+    return { index };
+  }
+
+  destroyBuffers(
+    xBuffer,
+    partialsValBuffer,
+    partialsIdxBuffer,
+    resultBuffer,
+    paramsBuffer,
+    readBuffer,
+  );
+  if (gpuTime1 !== undefined && gpuTime2 !== undefined)
+    return { index, gpuTimeMs: gpuTime1 + gpuTime2 };
+  return { index };
+}

package/src/random/random.d.mts

@@ -0,0 +1,61 @@
+/**
+ * Returns a Float32Array of n random values uniformly sampled from [low, high).
+ *
+ * @param n - number of elements
+ * @param low - lower bound (default: -1)
+ * @param high - upper bound (default: 1)
+ *
+ * @example Default range [-1, 1)
+ * ```js
+ * import { randomFloat32Array } from "wgblas";
+ *
+ * const x = randomFloat32Array(4);
+ * console.log(x); // Float32Array [ -0.42, 0.81, -0.07, 0.55 ]
+ * ```
+ *
+ * @example Custom range [0, 10)
+ * ```js
+ * import { randomFloat32Array } from "wgblas";
+ *
+ * const x = randomFloat32Array(4, 0, 10);
+ * console.log(x);
+ * ```
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/random/random.mjs#L1">Source code: random.mjs (L1)</a>
+ * @category Utilities
+ */
+export declare function randomFloat32Array(
+  n: number,
+  low?: number,
+  high?: number,
+): Float32Array;
+
+/**
+ * Returns a Float64Array of n random values uniformly sampled from [low, high).
+ *
+ * @param n - number of elements
+ * @param low - lower bound (default: -1)
+ * @param high - upper bound (default: 1)
+ *
+ * @example Default range [-1, 1)
+ * ```js
+ * import { randomFloat64Array } from "wgblas";
+ *
+ * const x = randomFloat64Array(4);
+ * console.log(x); // Float64Array [ -0.42, 0.81, -0.07, 0.55 ]
+ * ```
+ *
+ * @example Custom range [0, 10)
+ * ```js
+ * import { randomFloat64Array } from "wgblas";
+ *
+ * const x = randomFloat64Array(4, 0, 10);
+ * console.log(x);
+ * ```
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/random/random.mjs#L7">Source code: random.mjs (L7)</a>
+ * @category Utilities
+ */
+export declare function randomFloat64Array(
+  n: number,
+  low?: number,
+  high?: number,
+): Float64Array;

package/src/random/random.mjs

@@ -0,0 +1,11 @@
+export function randomFloat32Array(n, low = -1, high = 1) {
+  const x = new Float32Array(n);
+  for (let i = 0; i < n; i++) x[i] = low + Math.random() * (high - low);
+  return x;
+}
+
+export function randomFloat64Array(n, low = -1, high = 1) {
+  const x = new Float64Array(n);
+  for (let i = 0; i < n; i++) x[i] = low + Math.random() * (high - low);
+  return x;
+}