wgblas 2.0.0 → 2.2.0

package/src/drot/drot.mjs

@@ -0,0 +1,170 @@
+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";
+import { splitDoubleDouble, mergeDoubleDouble } from "../util/f64.mjs";
+import { requireGpuDevice, requireSameDevice } from "../util/device.mjs";
+
+// drot: x := c*x + s*y, y := -s*x + c*y, double-double (Dekker) f64
+// emulation of srot — x, y, c, and s are each split into an f32 (hi, lo)
+// pair; WGSL has no f64 type.
+export async function drot(device, n, x, incx, y, incy, c, s) {
+  const xIsGpu = x instanceof GpuVector;
+  const yIsGpu = y instanceof GpuVector;
+
+  requireGpuDevice(device);
+  requireSameDevice(device, "drot", { x, y });
+  if (
+    !Number.isInteger(n) ||
+    !Number.isInteger(incx) ||
+    !Number.isInteger(incy)
+  )
+    throw new Error("n, incx, and incy must be integers.");
+  if (typeof c !== "number") throw new Error("c must be a number.");
+  if (typeof s !== "number") throw new Error("s must be a number.");
+  if (Number.isNaN(c) || Number.isNaN(s))
+    throw new Error("c and s must not be NaN.");
+  if (!Number.isFinite(c)) throw new Error("c must be finite.");
+  if (!Number.isFinite(s)) throw new Error("s must be finite.");
+  if (incx <= 0 || incy <= 0)
+    throw new Error("incx and incy must be positive.");
+  if (!(x instanceof Float64Array) && !xIsGpu)
+    throw new Error("x must be a Float64Array or GpuVector.");
+  if (!(y instanceof Float64Array) && !yIsGpu)
+    throw new Error("y must be a Float64Array or GpuVector.");
+  if (xIsGpu && x.dtype !== Float64Array)
+    throw new Error("x must be a Float64Array-backed GpuVector.");
+  if (yIsGpu && y.dtype !== Float64Array)
+    throw new Error("y must be a Float64Array-backed GpuVector.");
+  if (xIsGpu !== yIsGpu)
+    throw new Error(
+      "x and y must be the same type (both Float64Array or both GpuVector).",
+    );
+  if (n <= 0) return xIsGpu ? {} : { x, 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.",
+    );
+
+  // Concatenated with f64/dekker.wgsl (DD struct), f64/utils/add.wgsl
+  // (fsub/negf/fastTwoSumProtected/ddAddProtected), and f64/utils/multiply.wgsl
+  // (ddMulProtected) — WGSL has no #include.
+  const f64Deps = ["f64/dekker", "f64/utils/add", "f64/utils/multiply"];
+  const pipeline = await getPipeline(device, [...f64Deps, "drot"]);
+
+  const { hi: cHi, lo: cLo } = splitDoubleDouble(new Float64Array([c]));
+  const { hi: sHi, lo: sLo } = splitDoubleDouble(new Float64Array([s]));
+
+  let xHiBuffer = null;
+  let xLoBuffer = null;
+  let yHiBuffer = null;
+  let yLoBuffer = null;
+  let paramsBuffer = null;
+  let xReadHiBuffer = null;
+  let xReadLoBuffer = null;
+  let yReadHiBuffer = null;
+  let yReadLoBuffer = null;
+
+  try {
+    if (xIsGpu) {
+      xHiBuffer = x._buf;
+      xLoBuffer = x._loBuf;
+      yHiBuffer = y._buf;
+      yLoBuffer = y._loBuf;
+    } else {
+      const xSplit = splitDoubleDouble(x);
+      const ySplit = splitDoubleDouble(y);
+      xHiBuffer = uploadBuffer(device, xSplit.hi, "drot-xHi", true);
+      xLoBuffer = uploadBuffer(device, xSplit.lo, "drot-xLo", true);
+      yHiBuffer = uploadBuffer(device, ySplit.hi, "drot-yHi", true);
+      yLoBuffer = uploadBuffer(device, ySplit.lo, "drot-yLo", true);
+    }
+    paramsBuffer = createParamsBuffer(
+      device,
+      [
+        { value: n, type: "u32" },
+        { value: cHi[0], type: "f32" },
+        { value: cLo[0], type: "f32" },
+        { value: sHi[0], type: "f32" },
+        { value: sLo[0], type: "f32" },
+        { value: incx, type: "u32" },
+        { value: incy, type: "u32" },
+      ],
+      "drot-params",
+    );
+
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
+      xHiBuffer,
+      xLoBuffer,
+      yHiBuffer,
+      yLoBuffer,
+      paramsBuffer,
+    ]);
+    const { commandEncoder, ts } = runComputePass(
+      device,
+      pipeline,
+      bindGroup,
+      calcWorkgroups(device, n),
+    );
+    xReadHiBuffer = xIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, xHiBuffer);
+    xReadLoBuffer = xIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, xLoBuffer);
+    yReadHiBuffer = yIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, yHiBuffer);
+    yReadLoBuffer = yIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, yLoBuffer);
+
+    submit(device, commandEncoder);
+
+    const gpuTimeMs = await extractTimestamp(ts);
+
+    if (xIsGpu) {
+      // xIsGpu === yIsGpu, enforced above
+      if (gpuTimeMs !== undefined) return { gpuTimeMs };
+      return {};
+    }
+
+    const xHi = await extractResult(xReadHiBuffer, Float32Array);
+    xReadHiBuffer = null; // extractResult already destroyed it
+    const xLo = await extractResult(xReadLoBuffer, Float32Array);
+    xReadLoBuffer = null;
+    const yHi = await extractResult(yReadHiBuffer, Float32Array);
+    yReadHiBuffer = null;
+    const yLo = await extractResult(yReadLoBuffer, Float32Array);
+    yReadLoBuffer = null;
+    const resultX = mergeDoubleDouble(xHi, xLo);
+    const resultY = mergeDoubleDouble(yHi, yLo);
+    if (gpuTimeMs !== undefined) return { x: resultX, y: resultY, gpuTimeMs };
+    return { x: resultX, y: resultY };
+  } finally {
+    if (!xIsGpu && xHiBuffer) destroyBuffers(xHiBuffer);
+    if (!xIsGpu && xLoBuffer) destroyBuffers(xLoBuffer);
+    if (!yIsGpu && yHiBuffer) destroyBuffers(yHiBuffer);
+    if (!yIsGpu && yLoBuffer) destroyBuffers(yLoBuffer);
+    if (paramsBuffer) destroyBuffers(paramsBuffer);
+    // Only reached if extractTimestamp or extractResult threw before
+    // clearing these — on the success path they're already null.
+    if (xReadHiBuffer) destroyBuffers(xReadHiBuffer);
+    if (xReadLoBuffer) destroyBuffers(xReadLoBuffer);
+    if (yReadHiBuffer) destroyBuffers(yReadHiBuffer);
+    if (yReadLoBuffer) destroyBuffers(yReadLoBuffer);
+  }
+}

package/src/drotm/drotm.d.mts

@@ -0,0 +1,67 @@
+import { GpuVector } from "../classes/GpuVector.mjs";
+
+/**
+ * Applies a modified Givens plane rotation H to double-precision vectors x
+ * and y:
+ * $$\begin{pmatrix} x \\\\ y \end{pmatrix} \leftarrow \begin{pmatrix} h_{11} & h_{12} \\\\ h_{21} & h_{22} \end{pmatrix} \begin{pmatrix} x \\\\ y \end{pmatrix}$$
+ * — double-double (Dekker) f64 emulation of {@link srotm}, since WGSL has
+ * no native f64 type.
+ *
+ * {@includeCode ../../examples/drotm/drotm.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/drotm/web/drotm.html}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements (must be a positive integer)
+ * @param x - Float64Array input/output vector
+ * @param incx - stride for x (must be a positive integer)
+ * @param y - Float64Array input/output vector
+ * @param incy - stride for y (must be a positive integer)
+ * @param param - 5-element Float64Array: [flag, h11, h21, h12, h22]
+ *   flag = -2: identity (no-op), -1: full H, 0: unit diagonal, 1: unit off-diagonal
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/drotm/drotm.mjs#L18">Source code: drotm.mjs (L18)</a>
+ * @category BLAS Level 1
+ */
+export declare function drotm(
+  device: GPUDevice,
+  n: number,
+  x: Float64Array,
+  incx: number,
+  y: Float64Array,
+  incy: number,
+  param: Float64Array,
+): Promise<
+  | { x: Float64Array; y: Float64Array }
+  | { x: Float64Array; y: Float64Array; gpuTimeMs: number }
+>;
+
+/**
+ * Applies a modified Givens plane rotation H to double-precision vectors x
+ * and y:
+ * $$\begin{pmatrix} x \\\\ y \end{pmatrix} \leftarrow \begin{pmatrix} h_{11} & h_{12} \\\\ h_{21} & h_{22} \end{pmatrix} \begin{pmatrix} x \\\\ y \end{pmatrix}$$
+ * — GPU-resident overload; see the Float64Array overload above for the
+ * routine itself.
+ *
+ * {@includeCode ../../examples/drotm/gpu.drotm.js}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements (must be a positive integer)
+ * @param x - GpuVector input/output vector (must be Float64Array-backed, mutated in place)
+ * @param incx - stride for x (must be a positive integer)
+ * @param y - GpuVector input/output vector (must be Float64Array-backed, mutated in place)
+ * @param incy - stride for y (must be a positive integer)
+ * @param param - 5-element Float64Array: [flag, h11, h21, h12, h22]
+ *   flag = -2: identity (no-op), -1: full H, 0: unit diagonal, 1: unit off-diagonal
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/drotm/drotm.mjs#L18">Source code: drotm.mjs (L18)</a>
+ * @category BLAS Level 1
+ */
+export declare function drotm(
+  device: GPUDevice,
+  n: number,
+  x: GpuVector,
+  incx: number,
+  y: GpuVector,
+  incy: number,
+  param: Float64Array,
+): Promise<{} | { gpuTimeMs: number }>;

package/src/drotm/drotm.mjs

@@ -0,0 +1,171 @@
+import {
+  uploadBuffer,
+  createParamsBuffer,
+  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 { calcWorkgroups } from "../util/workgroup.mjs";
+import { GpuVector } from "../classes/GpuVector.mjs";
+import { splitDoubleDouble, mergeDoubleDouble } from "../util/f64.mjs";
+import { requireGpuDevice, requireSameDevice } from "../util/device.mjs";
+
+// drotm: applies a modified Givens rotation H to vectors x and y —
+// double-double (Dekker) f64 emulation of srotm. x, y, and every entry of
+// param are each split into an f32 (hi, lo) pair; WGSL has no f64 type.
+export async function drotm(device, n, x, incx, y, incy, param) {
+  const xIsGpu = x instanceof GpuVector;
+  const yIsGpu = y instanceof GpuVector;
+
+  requireGpuDevice(device);
+  requireSameDevice(device, "drotm", { x, y });
+  if (
+    !Number.isInteger(n) ||
+    !Number.isInteger(incx) ||
+    !Number.isInteger(incy)
+  )
+    throw new Error("n, incx, and incy must be integers.");
+  if (!(param instanceof Float64Array) || param.length !== 5)
+    throw new Error("param must be a Float64Array of length 5.");
+  if (param[0] !== -2 && param[0] !== -1 && param[0] !== 0 && param[0] !== 1)
+    throw new Error("param[0] (flag) must be one of -2, -1, 0, or 1.");
+  if (incx <= 0 || incy <= 0)
+    throw new Error("incx and incy must be positive.");
+  if (!(x instanceof Float64Array) && !xIsGpu)
+    throw new Error("x must be a Float64Array or GpuVector.");
+  if (!(y instanceof Float64Array) && !yIsGpu)
+    throw new Error("y must be a Float64Array or GpuVector.");
+  if (xIsGpu && x.dtype !== Float64Array)
+    throw new Error("x must be a Float64Array-backed GpuVector.");
+  if (yIsGpu && y.dtype !== Float64Array)
+    throw new Error("y must be a Float64Array-backed GpuVector.");
+  if (xIsGpu !== yIsGpu)
+    throw new Error(
+      "x and y must be the same type (both Float64Array or both GpuVector).",
+    );
+  if (n <= 0 || param[0] === -2.0) return xIsGpu ? {} : { x, 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.",
+    );
+
+  // Concatenated with f64/dekker.wgsl (DD struct), f64/utils/add.wgsl
+  // (fsub/negf/fastTwoSumProtected/ddAddProtected), and f64/utils/multiply.wgsl
+  // (ddMulProtected) — WGSL has no #include.
+  const f64Deps = ["f64/dekker", "f64/utils/add", "f64/utils/multiply"];
+  const pipeline = await getPipeline(device, [...f64Deps, "drotm"]);
+
+  const { hi: paramHi, lo: paramLo } = splitDoubleDouble(param);
+
+  let xHiBuffer = null;
+  let xLoBuffer = null;
+  let yHiBuffer = null;
+  let yLoBuffer = null;
+  let paramHiBuffer = null;
+  let paramLoBuffer = null;
+  let paramsBuffer = null;
+  let xReadHiBuffer = null;
+  let xReadLoBuffer = null;
+  let yReadHiBuffer = null;
+  let yReadLoBuffer = null;
+
+  try {
+    if (xIsGpu) {
+      xHiBuffer = x._buf;
+      xLoBuffer = x._loBuf;
+      yHiBuffer = y._buf;
+      yLoBuffer = y._loBuf;
+    } else {
+      const xSplit = splitDoubleDouble(x);
+      const ySplit = splitDoubleDouble(y);
+      xHiBuffer = uploadBuffer(device, xSplit.hi, "drotm-xHi", true);
+      xLoBuffer = uploadBuffer(device, xSplit.lo, "drotm-xLo", true);
+      yHiBuffer = uploadBuffer(device, ySplit.hi, "drotm-yHi", true);
+      yLoBuffer = uploadBuffer(device, ySplit.lo, "drotm-yLo", true);
+    }
+    paramHiBuffer = uploadBuffer(device, paramHi, "drotm-paramHi", false);
+    paramLoBuffer = uploadBuffer(device, paramLo, "drotm-paramLo", false);
+    paramsBuffer = createParamsBuffer(
+      device,
+      [
+        { value: n, type: "u32" },
+        { value: incx, type: "u32" },
+        { value: incy, type: "u32" },
+      ],
+      "drotm-params",
+    );
+
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
+      xHiBuffer,
+      xLoBuffer,
+      yHiBuffer,
+      yLoBuffer,
+      paramHiBuffer,
+      paramLoBuffer,
+      paramsBuffer,
+    ]);
+    const { commandEncoder, ts } = runComputePass(
+      device,
+      pipeline,
+      bindGroup,
+      calcWorkgroups(device, n),
+    );
+    xReadHiBuffer = xIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, xHiBuffer);
+    xReadLoBuffer = xIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, xLoBuffer);
+    yReadHiBuffer = yIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, yHiBuffer);
+    yReadLoBuffer = yIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, yLoBuffer);
+
+    submit(device, commandEncoder);
+
+    const gpuTimeMs = await extractTimestamp(ts);
+
+    if (xIsGpu) {
+      // xIsGpu === yIsGpu, enforced above
+      if (gpuTimeMs !== undefined) return { gpuTimeMs };
+      return {};
+    }
+
+    const xHi = await extractResult(xReadHiBuffer, Float32Array);
+    xReadHiBuffer = null; // extractResult already destroyed it
+    const xLo = await extractResult(xReadLoBuffer, Float32Array);
+    xReadLoBuffer = null;
+    const yHi = await extractResult(yReadHiBuffer, Float32Array);
+    yReadHiBuffer = null;
+    const yLo = await extractResult(yReadLoBuffer, Float32Array);
+    yReadLoBuffer = null;
+    const resultX = mergeDoubleDouble(xHi, xLo);
+    const resultY = mergeDoubleDouble(yHi, yLo);
+    if (gpuTimeMs !== undefined) return { x: resultX, y: resultY, gpuTimeMs };
+    return { x: resultX, y: resultY };
+  } finally {
+    if (!xIsGpu && xHiBuffer) destroyBuffers(xHiBuffer);
+    if (!xIsGpu && xLoBuffer) destroyBuffers(xLoBuffer);
+    if (!yIsGpu && yHiBuffer) destroyBuffers(yHiBuffer);
+    if (!yIsGpu && yLoBuffer) destroyBuffers(yLoBuffer);
+    if (paramHiBuffer) destroyBuffers(paramHiBuffer);
+    if (paramLoBuffer) destroyBuffers(paramLoBuffer);
+    if (paramsBuffer) destroyBuffers(paramsBuffer);
+    // Only reached if extractTimestamp or extractResult threw before
+    // clearing these — on the success path they're already null.
+    if (xReadHiBuffer) destroyBuffers(xReadHiBuffer);
+    if (xReadLoBuffer) destroyBuffers(xReadLoBuffer);
+    if (yReadHiBuffer) destroyBuffers(yReadHiBuffer);
+    if (yReadLoBuffer) destroyBuffers(yReadLoBuffer);
+  }
+}

package/src/dscal/dscal.d.mts

@@ -0,0 +1,52 @@
+import { GpuVector } from "../classes/GpuVector.mjs";
+
+/**
+ * Scales a double-precision vector by a constant: $$x \leftarrow \alpha x$$
+ *
+ * `x` and `alpha` are each split into a (hi, lo) double-double f32 pair (see
+ * `splitDoubleDouble`/`f64.mjs`) since WGSL has no f64 type; the multiply
+ * 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.
+ *
+ * {@includeCode ../../examples/dscal/dscal.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/dscal/web/dscal.html}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements to scale (must be a positive integer)
+ * @param alpha - scalar multiplier
+ * @param x - Float64Array input/output vector
+ * @param incx - stride for x (must be a positive integer)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/dscal/dscal.mjs">Source code: dscal.mjs</a>
+ * @category BLAS Level 1
+ */
+export declare function dscal(
+  device: GPUDevice,
+  n: number,
+  alpha: number,
+  x: Float64Array,
+  incx: number,
+): Promise<{ x: Float64Array } | { x: Float64Array; gpuTimeMs: number }>;
+
+/**
+ * Scales a double-precision vector by a constant: $$x \leftarrow \alpha x$$
+ *
+ * {@includeCode ../../examples/dscal/gpu.dscal.js}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements to scale (must be a positive integer)
+ * @param alpha - scalar multiplier
+ * @param x - Float64Array-backed GpuVector input/output vector (mutated in place)
+ * @param incx - stride for x (must be a positive integer)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/dscal/dscal.mjs">Source code: dscal.mjs</a>
+ * @category BLAS Level 1
+ */
+export declare function dscal(
+  device: GPUDevice,
+  n: number,
+  alpha: number,
+  x: GpuVector,
+  incx: number,
+): Promise<{} | { gpuTimeMs: number }>;

package/src/dscal/dscal.mjs

@@ -0,0 +1,119 @@
+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";
+import { splitDoubleDouble, mergeDoubleDouble } from "../util/f64.mjs";
+import { requireGpuDevice, requireSameDevice } from "../util/device.mjs";
+
+// dscal: x := alpha * x, double-double (Dekker) f64 emulation of sscal — x
+// and alpha are each split into an f32 (hi, lo) pair; WGSL has no f64 type.
+export async function dscal(device, n, alpha, x, incx) {
+  const xIsGpu = x instanceof GpuVector;
+
+  requireGpuDevice(device);
+  if (!Number.isInteger(n) || !Number.isInteger(incx))
+    throw new Error("n and incx must be integers.");
+  if (typeof alpha !== "number") throw new Error("alpha must be a number.");
+  if (Number.isNaN(alpha)) throw new Error("alpha must not be NaN.");
+  if (!Number.isFinite(alpha)) throw new Error("alpha must be finite.");
+  if (!(x instanceof Float64Array) && !xIsGpu)
+    throw new Error("x must be a Float64Array or GpuVector.");
+  if (xIsGpu && x.dtype !== Float64Array)
+    throw new Error("x must be a Float64Array-backed GpuVector.");
+  if (incx <= 0) throw new Error("incx must be positive.");
+  requireSameDevice(device, "dscal", { x });
+  if (n <= 0) return xIsGpu ? {} : { x };
+  if (x.length < (n - 1) * incx + 1)
+    throw new Error(
+      "x does not have enough elements for the given n and incx.",
+    );
+
+  // Concatenated with f64/dekker.wgsl (DD struct), f64/utils/add.wgsl
+  // (fsub/negf/fastTwoSumProtected), and f64/utils/multiply.wgsl
+  // (ddMulProtected) — WGSL has no #include.
+  const f64Deps = ["f64/dekker", "f64/utils/add", "f64/utils/multiply"];
+  const pipeline = await getPipeline(device, [...f64Deps, "dscal"]);
+
+  const { hi: alphaHi, lo: alphaLo } = splitDoubleDouble(
+    new Float64Array([alpha]),
+  );
+
+  let xHiBuffer = null;
+  let xLoBuffer = null;
+  let paramsBuffer = null;
+  let readHiBuffer = null;
+  let readLoBuffer = null;
+
+  try {
+    if (xIsGpu) {
+      xHiBuffer = x._buf;
+      xLoBuffer = x._loBuf;
+    } else {
+      const { hi, lo } = splitDoubleDouble(x);
+      xHiBuffer = uploadBuffer(device, hi, "dscal-xHi", true);
+      xLoBuffer = uploadBuffer(device, lo, "dscal-xLo", true);
+    }
+    paramsBuffer = createParamsBuffer(
+      device,
+      [
+        { value: n, type: "u32" },
+        { value: alphaHi[0], type: "f32" },
+        { value: alphaLo[0], type: "f32" },
+        { value: incx, type: "u32" },
+      ],
+      "dscal-params",
+    );
+
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
+      xHiBuffer,
+      xLoBuffer,
+      paramsBuffer,
+    ]);
+    const { commandEncoder, ts } = runComputePass(
+      device,
+      pipeline,
+      bindGroup,
+      calcWorkgroups(device, n),
+    );
+    readHiBuffer = xIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, xHiBuffer);
+    readLoBuffer = xIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, xLoBuffer);
+
+    submit(device, commandEncoder);
+
+    const gpuTimeMs = await extractTimestamp(ts);
+
+    if (xIsGpu) {
+      if (gpuTimeMs !== undefined) return { gpuTimeMs };
+      return {};
+    }
+
+    const hi = await extractResult(readHiBuffer, Float32Array);
+    readHiBuffer = null; // extractResult already destroyed it
+    const lo = await extractResult(readLoBuffer, Float32Array);
+    readLoBuffer = null;
+    const result = mergeDoubleDouble(hi, lo);
+    if (gpuTimeMs !== undefined) return { x: result, gpuTimeMs };
+    return { x: result };
+  } finally {
+    if (!xIsGpu && xHiBuffer) destroyBuffers(xHiBuffer);
+    if (!xIsGpu && xLoBuffer) destroyBuffers(xLoBuffer);
+    if (paramsBuffer) destroyBuffers(paramsBuffer);
+    // Only reached if extractTimestamp or extractResult threw before
+    // clearing these — on the success path they're already null.
+    if (readHiBuffer) destroyBuffers(readHiBuffer);
+    if (readLoBuffer) destroyBuffers(readLoBuffer);
+  }
+}

package/src/dswap/dswap.d.mts

@@ -0,0 +1,57 @@
+import { GpuVector } from "../classes/GpuVector.mjs";
+
+/**
+ * Swaps the elements of two double-precision vectors: $$x \leftrightarrow y$$
+ * — double-double (Dekker) f64 emulation of {@link sswap}, since WGSL has
+ * no native f64 type.
+ *
+ * {@includeCode ../../examples/dswap/dswap.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/dswap/web/dswap.html}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements to swap (must be a positive integer)
+ * @param x - Float64Array first input/output vector
+ * @param incx - stride for x (must be a positive integer)
+ * @param y - Float64Array second input/output vector
+ * @param incy - stride for y (must be a positive integer)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/dswap/dswap.mjs#L22">Source code: dswap.mjs (L22)</a>
+ * @category BLAS Level 1
+ */
+export declare function dswap(
+  device: GPUDevice,
+  n: number,
+  x: Float64Array,
+  incx: number,
+  y: Float64Array,
+  incy: number,
+): Promise<
+  | { x: Float64Array; y: Float64Array }
+  | { x: Float64Array; y: Float64Array; gpuTimeMs: number }
+>;
+
+/**
+ * Swaps the elements of two double-precision vectors: $$x \leftrightarrow y$$
+ * — GPU-resident overload; see the Float64Array overload above for the
+ * routine itself.
+ *
+ * {@includeCode ../../examples/dswap/gpu.dswap.js}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements to swap (must be a positive integer)
+ * @param x - GpuVector first input/output vector (must be Float64Array-backed, mutated in place)
+ * @param incx - stride for x (must be a positive integer)
+ * @param y - GpuVector second input/output vector (must be Float64Array-backed, mutated in place)
+ * @param incy - stride for y (must be a positive integer)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/dswap/dswap.mjs#L22">Source code: dswap.mjs (L22)</a>
+ * @category BLAS Level 1
+ */
+export declare function dswap(
+  device: GPUDevice,
+  n: number,
+  x: GpuVector,
+  incx: number,
+  y: GpuVector,
+  incy: number,
+): Promise<{} | { gpuTimeMs: number }>;