wgblas 2.0.0 → 2.2.0

package/src/cscal/cscal.d.mts

@@ -0,0 +1,47 @@
+import { GpuVector } from "../classes/GpuVector.mjs";
+import { Complex32, Complex32Array } from "../classes/Complex32.mjs";
+
+/**
+ * Scales a complex vector by a complex constant: $$x \leftarrow \alpha x$$
+ *
+ * {@includeCode ../../examples/cscal/cscal.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/cscal/web/cscal.html}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements to scale (must be a positive integer)
+ * @param alpha - complex scalar multiplier
+ * @param x - Complex32Array input/output vector
+ * @param incx - stride for x (must be a positive integer)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/cscal/cscal.mjs">Source code: cscal.mjs</a>
+ * @category BLAS Level 1
+ */
+export declare function cscal(
+  device: GPUDevice,
+  n: number,
+  alpha: Complex32,
+  x: Complex32Array,
+  incx: number,
+): Promise<{ x: Complex32Array } | { x: Complex32Array; gpuTimeMs: number }>;
+
+/**
+ * Scales a complex vector by a complex constant: $$x \leftarrow \alpha x$$
+ *
+ * {@includeCode ../../examples/cscal/gpu.cscal.js}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements to scale (must be a positive integer)
+ * @param alpha - complex scalar multiplier
+ * @param x - Complex32Array-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/cscal/cscal.mjs">Source code: cscal.mjs</a>
+ * @category BLAS Level 1
+ */
+export declare function cscal(
+  device: GPUDevice,
+  n: number,
+  alpha: Complex32,
+  x: GpuVector,
+  incx: number,
+): Promise<{} | { gpuTimeMs: number }>;

package/src/cscal/cscal.mjs

@@ -0,0 +1,98 @@
+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 { Complex32, Complex32Array } from "../classes/Complex32.mjs";
+import { interleaveComplex32 } from "../util/complex.mjs";
+import { requireGpuDevice, requireSameDevice } from "../util/device.mjs";
+
+// cscal: x := alpha * x, complex. alpha is a Complex32; x is a Complex32Array
+// or a Complex32Array-backed GpuVector, interleaved [re0, im0, re1, im1, ...]
+// to match cscal.wgsl's single buffer.
+export async function cscal(device, n, alpha, x, incx) {
+  const xIsGpu = x instanceof GpuVector;
+
+  requireGpuDevice(device);
+  requireSameDevice(device, "cscal", { x });
+  if (!Number.isInteger(n) || !Number.isInteger(incx))
+    throw new Error("n and incx must be integers.");
+  if (!(alpha instanceof Complex32))
+    throw new Error("alpha must be a Complex32.");
+  if (Number.isNaN(alpha.re) || Number.isNaN(alpha.im))
+    throw new Error("alpha must not be NaN.");
+  if (!Number.isFinite(alpha.re) || !Number.isFinite(alpha.im))
+    throw new Error("alpha must be finite.");
+  if (incx <= 0) throw new Error("incx must be positive.");
+  if (!(x instanceof Complex32Array) && !xIsGpu)
+    throw new Error("x must be a Complex32Array or GpuVector.");
+  if (xIsGpu && x.dtype !== Complex32Array)
+    throw new Error("x must be a Complex32Array-backed GpuVector.");
+  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.",
+    );
+
+  const pipeline = await getPipeline(device, "cscal");
+
+  let xBuffer = null;
+  let paramsBuffer = null;
+  let readBuffer = null;
+
+  try {
+    xBuffer = xIsGpu
+      ? x._buf
+      : uploadBuffer(device, interleaveComplex32(x), "cscal-x", true);
+    paramsBuffer = createParamsBuffer(
+      device,
+      [
+        { value: n, type: "u32" },
+        { value: alpha.re, type: "f32" },
+        { value: alpha.im, type: "f32" },
+        { value: incx, type: "u32" },
+      ],
+      "cscal-params",
+    );
+
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
+      xBuffer,
+      paramsBuffer,
+    ]);
+    const { commandEncoder, ts } = runComputePass(
+      device,
+      pipeline,
+      bindGroup,
+      calcWorkgroups(device, n),
+    );
+    readBuffer = xIsGpu ? null : stageReadback(device, commandEncoder, xBuffer);
+
+    submit(device, commandEncoder);
+
+    const gpuTimeMs = await extractTimestamp(ts);
+
+    if (xIsGpu) {
+      if (gpuTimeMs !== undefined) return { gpuTimeMs };
+      return {};
+    }
+
+    const flat = await extractResult(readBuffer, Float32Array);
+    readBuffer = null; // extractResult already destroyed it
+    const result = new Complex32Array(flat);
+    if (gpuTimeMs !== undefined) return { x: result, gpuTimeMs };
+    return { x: result };
+  } finally {
+    if (!xIsGpu && xBuffer) destroyBuffers(xBuffer);
+    if (paramsBuffer) destroyBuffers(paramsBuffer);
+    // Only reached if extractTimestamp threw before extractResult ran.
+    if (readBuffer) destroyBuffers(readBuffer);
+  }
+}

package/src/dasum/dasum.d.mts

@@ -2,9 +2,9 @@ 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
+ * 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,7 +31,7 @@ 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/gpu.dasum.js}
  *

package/src/dasum/dasum.mjs

@@ -13,14 +13,14 @@ 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";
-
-const WGS = 64; // workgroup size
+import { WGS } from "../util/constants.mjs";
+import { requireGpuDevice, requireSameDevice } from "../util/device.mjs";
 
 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.");
+  requireGpuDevice(device);
+  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.");
@@ -39,7 +39,10 @@ export async function dasum(device, n, x, incx) {
   // #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"]);
+  const pipelineReduce = await getPipeline(device, [
+    ...f64Deps,
+    "reduction/sumF64",
+  ]);
 
   let xHiBuffer = null;
   let xLoBuffer = null;
@@ -57,14 +60,23 @@ 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");
+    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" },
@@ -72,31 +84,37 @@ export async function dasum(device, n, x, incx) {
       "dasum-params",
     );
 
-    const bgMain = createBindGroup(
-      pipelineMain.getBindGroupLayout(0),
-      [xHiBuffer, xLoBuffer, partialsHiBuffer, partialsLoBuffer, paramsBuffer],
-    );
+    const bgMain = createBindGroup(device, pipelineMain.getBindGroupLayout(0), [
+      xHiBuffer,
+      xLoBuffer,
+      partialsHiBuffer,
+      partialsLoBuffer,
+      paramsBuffer,
+    ]);
     const { commandEncoder: enc1, ts: ts1 } = runComputePass(
+      device,
       pipelineMain,
       bgMain,
       2 * WGS,
     ); // dispatch 2*WGS workgroups
 
-    submit(enc1);
+    submit(device, enc1);
 
     const bgReduce = createBindGroup(
+      device,
       pipelineReduce.getBindGroupLayout(0),
       [partialsHiBuffer, partialsLoBuffer, resultHiBuffer, resultLoBuffer],
     );
     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);
@@ -123,7 +141,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/daxpy/daxpy.d.mts

@@ -0,0 +1,56 @@
+import { GpuVector } from "../classes/GpuVector.mjs";
+
+/**
+ * Performs the operation $$y \leftarrow \alpha x + y$$ — double-double
+ * (Dekker) f64 emulation of {@link saxpy}, since WGSL has no native f64 type.
+ *
+ * {@includeCode ../../examples/daxpy/daxpy.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/daxpy/web/daxpy.html}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements (must be a positive integer)
+ * @param alpha - scalar multiplier
+ * @param x - Float64Array input 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)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/daxpy/daxpy.mjs#L18">Source code: daxpy.mjs (L18)</a>
+ * @category BLAS Level 1
+ */
+export declare function daxpy(
+  device: GPUDevice,
+  n: number,
+  alpha: number,
+  x: Float64Array,
+  incx: number,
+  y: Float64Array,
+  incy: number,
+): Promise<{ y: Float64Array } | { y: Float64Array; gpuTimeMs: number }>;
+
+/**
+ * Performs the operation $$y \leftarrow \alpha x + y$$ — GPU-resident
+ * overload; see the Float64Array overload above for the routine itself.
+ *
+ * {@includeCode ../../examples/daxpy/gpu.daxpy.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 (must be Float64Array-backed)
+ * @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)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/daxpy/daxpy.mjs#L18">Source code: daxpy.mjs (L18)</a>
+ * @category BLAS Level 1
+ */
+export declare function daxpy(
+  device: GPUDevice,
+  n: number,
+  alpha: number,
+  x: GpuVector,
+  incx: number,
+  y: GpuVector,
+  incy: number,
+): Promise<{} | { gpuTimeMs: number }>;

package/src/daxpy/daxpy.mjs

@@ -0,0 +1,150 @@
+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";
+
+// daxpy: y := alpha * x + y, double-double (Dekker) f64 emulation of saxpy —
+// x, y, and alpha are each split into an f32 (hi, lo) pair; WGSL has no f64 type.
+export async function daxpy(device, n, alpha, x, incx, y, incy) {
+  const xIsGpu = x instanceof GpuVector;
+  const yIsGpu = y instanceof GpuVector;
+
+  requireGpuDevice(device);
+  if (
+    !Number.isInteger(n) ||
+    !Number.isInteger(incx) ||
+    !Number.isInteger(incy)
+  )
+    throw new Error("n, incx, and incy 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 (!(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 (incx <= 0 || incy <= 0)
+    throw new Error("incx and incy must be positive.");
+  requireSameDevice(device, "daxpy", { x, y });
+  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.",
+    );
+
+  // 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, "daxpy"]);
+
+  const { hi: alphaHi, lo: alphaLo } = splitDoubleDouble(
+    new Float64Array([alpha]),
+  );
+
+  let xHiBuffer = null;
+  let xLoBuffer = null;
+  let yHiBuffer = null;
+  let yLoBuffer = null;
+  let paramsBuffer = null;
+  let readHiBuffer = null;
+  let readLoBuffer = 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, "daxpy-xHi", false);
+      xLoBuffer = uploadBuffer(device, xSplit.lo, "daxpy-xLo", false);
+      yHiBuffer = uploadBuffer(device, ySplit.hi, "daxpy-yHi", true);
+      yLoBuffer = uploadBuffer(device, ySplit.lo, "daxpy-yLo", true);
+    }
+    paramsBuffer = createParamsBuffer(
+      device,
+      [
+        { value: n, type: "u32" },
+        { value: alphaHi[0], type: "f32" },
+        { value: alphaLo[0], type: "f32" },
+        { value: incx, type: "u32" },
+        { value: incy, type: "u32" },
+      ],
+      "daxpy-params",
+    );
+
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
+      xHiBuffer,
+      xLoBuffer,
+      yHiBuffer,
+      yLoBuffer,
+      paramsBuffer,
+    ]);
+    const { commandEncoder, ts } = runComputePass(
+      device,
+      pipeline,
+      bindGroup,
+      calcWorkgroups(device, n),
+    );
+    readHiBuffer = yIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, yHiBuffer);
+    readLoBuffer = yIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, yLoBuffer);
+
+    submit(device, commandEncoder);
+
+    const gpuTimeMs = await extractTimestamp(ts);
+
+    if (yIsGpu) {
+      // xIsGpu === yIsGpu, enforced above
+      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 { y: result, gpuTimeMs };
+    return { y: result };
+  } 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 (readHiBuffer) destroyBuffers(readHiBuffer);
+    if (readLoBuffer) destroyBuffers(readLoBuffer);
+  }
+}

package/src/dcopy/dcopy.d.mts

@@ -0,0 +1,52 @@
+import { GpuVector } from "../classes/GpuVector.mjs";
+
+/**
+ * Performs the operation $$y \leftarrow x$$ — double-double (Dekker) f64
+ * emulation of {@link scopy}, since WGSL has no native f64 type.
+ *
+ * {@includeCode ../../examples/dcopy/dcopy.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/dcopy/web/dcopy.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)
+ * @param y - Float64Array output vector
+ * @param incy - stride for y (must be a positive integer)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/dcopy/dcopy.mjs#L20">Source code: dcopy.mjs (L20)</a>
+ * @category BLAS Level 1
+ */
+export declare function dcopy(
+  device: GPUDevice,
+  n: number,
+  x: Float64Array,
+  incx: number,
+  y: Float64Array,
+  incy: number,
+): Promise<{ y: Float64Array } | { y: Float64Array; gpuTimeMs: number }>;
+
+/**
+ * Performs the operation $$y \leftarrow x$$ — GPU-resident overload; see the
+ * Float64Array overload above for the routine itself.
+ *
+ * {@includeCode ../../examples/dcopy/gpu.dcopy.js}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param n - number of elements (must be a positive integer)
+ * @param x - GpuVector input vector (must be Float64Array-backed)
+ * @param incx - stride for x (must be a positive integer)
+ * @param y - GpuVector 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/dcopy/dcopy.mjs#L20">Source code: dcopy.mjs (L20)</a>
+ * @category BLAS Level 1
+ */
+export declare function dcopy(
+  device: GPUDevice,
+  n: number,
+  x: GpuVector,
+  incx: number,
+  y: GpuVector,
+  incy: number,
+): Promise<{} | { gpuTimeMs: number }>;

package/src/dcopy/dcopy.mjs

@@ -0,0 +1,140 @@
+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";
+
+// dcopy: y := x, double-double (Dekker) f64 emulation of scopy — x and y are
+// each split into an f32 (hi, lo) pair; WGSL has no f64 type. Unlike
+// dscal/daxpy/ddot, a copy has no arithmetic at all, so it needs no Dekker
+// shader dependencies (dekker.wgsl/add.wgsl/multiply.wgsl) — dcopy.wgsl is
+// entirely self-contained.
+export async function dcopy(device, n, x, incx, y, incy) {
+  const xIsGpu = x instanceof GpuVector;
+  const yIsGpu = y instanceof GpuVector;
+
+  requireGpuDevice(device);
+  requireSameDevice(device, "dcopy", { x, y });
+  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 (!(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 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, "dcopy");
+
+  let xHiBuffer = null;
+  let xLoBuffer = null;
+  let yHiBuffer = null;
+  let yLoBuffer = null;
+  let paramsBuffer = null;
+  let readHiBuffer = null;
+  let readLoBuffer = 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, "dcopy-xHi", false);
+      xLoBuffer = uploadBuffer(device, xSplit.lo, "dcopy-xLo", false);
+      yHiBuffer = uploadBuffer(device, ySplit.hi, "dcopy-yHi", true);
+      yLoBuffer = uploadBuffer(device, ySplit.lo, "dcopy-yLo", true);
+    }
+    paramsBuffer = createParamsBuffer(
+      device,
+      [
+        { value: n, type: "u32" },
+        { value: incx, type: "u32" },
+        { value: incy, type: "u32" },
+      ],
+      "dcopy-params",
+    );
+
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
+      xHiBuffer,
+      xLoBuffer,
+      yHiBuffer,
+      yLoBuffer,
+      paramsBuffer,
+    ]);
+    const { commandEncoder, ts } = runComputePass(
+      device,
+      pipeline,
+      bindGroup,
+      calcWorkgroups(device, n),
+    );
+    readHiBuffer = yIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, yHiBuffer);
+    readLoBuffer = yIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, yLoBuffer);
+
+    submit(device, commandEncoder);
+
+    const gpuTimeMs = await extractTimestamp(ts);
+
+    if (yIsGpu) {
+      // xIsGpu === yIsGpu, enforced above
+      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 { y: result, gpuTimeMs };
+    return { y: result };
+  } 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 (readHiBuffer) destroyBuffers(readHiBuffer);
+    if (readLoBuffer) destroyBuffers(readLoBuffer);
+  }
+}