wgblas 2.0.0 → 2.2.0

package/src/classes/Complex64.d.mts

@@ -0,0 +1,44 @@
+/**
+ * A single 64-bit (f64) complex number: a real and an imaginary component.
+ * Same shape as Complex32, with one deliberate difference: no f32 rounding
+ * — a plain JS number already is an f64, so re/im are kept at their full
+ * native double precision.
+ *
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/classes/Complex64.mjs#L11">Source code: Complex64.mjs (L11)</a>
+ * @category Classes
+ */
+export declare class Complex64 {
+  /**
+   * @param re - real component, full f64 precision
+   * @param im - imaginary component, full f64 precision
+   *
+   * {@includeCode ../../examples/complex64/complex64.js}
+   */
+  constructor(re: number, im: number);
+
+  /** Real component (full f64 precision). */
+  re: number;
+
+  /** Imaginary component (full f64 precision). */
+  im: number;
+}
+
+/**
+ * An array of Complex64 values — array-of-structs, the f64 sibling of
+ * Complex32Array (same overloads, same interleaved-pairs convention),
+ * backed by full-precision Complex64 elements instead of f32-rounded
+ * Complex32 ones.
+ *
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/classes/Complex64.mjs#L34">Source code: Complex64.mjs (L34)</a>
+ * @category Classes
+ */
+export declare class Complex64Array extends Array<Complex64> {
+  /**
+   * @param arg - a length (fills with that many zero-valued Complex64
+   *   entries), a flat interleaved `[re, im, re, im, ...]` list of numbers,
+   *   or an iterable of existing Complex64 instances to copy
+   *
+   * {@includeCode ../../examples/complex64array/complex64array.js}
+   */
+  constructor(arg?: number | Iterable<number> | Iterable<Complex64>);
+}

package/src/classes/Complex64.mjs

@@ -0,0 +1,76 @@
+/** @module devdocs/classes/Complex64 */
+
+/**
+ * A single 64-bit (f64) complex number: a real and an imaginary component.
+ * Same shape as Complex32 (see Complex32.mjs) with one deliberate
+ * difference: no `Math.fround` rounding here. A plain JS number already is
+ * an f64, so re/im are kept at their full native double precision instead
+ * of being truncated down to f32.
+ */
+export class Complex64 {
+  /**
+   * @param {number} re - real component, full f64 precision
+   * @param {number} im - imaginary component, full f64 precision
+   */
+  constructor(re, im) {
+    this.re = re;
+    this.im = im;
+  }
+}
+
+/**
+ * An array of Complex64 values — array-of-structs, the f64 sibling of
+ * Complex32Array (same overloads, same interleaved-pairs convention),
+ * backed by full-precision Complex64 elements instead of f32-rounded
+ * Complex32 ones.
+ *
+ *   new Complex64Array()                 // empty
+ *   new Complex64Array(length)           // length zero-valued entries
+ *   new Complex64Array([1, 5, 3, 8])     // flat [re, im, re, im, ...] pairs
+ *   new Complex64Array([z1, z2])         // copies existing Complex64 instances
+ */
+export class Complex64Array extends Array {
+  /**
+   * @param {number|Iterable<number>|Iterable<Complex64>} [arg] - a length,
+   *   a flat interleaved [re, im, ...] list of numbers, or an iterable of
+   *   existing Complex64 instances
+   */
+  constructor(arg) {
+    if (arg === undefined) {
+      super();
+      return;
+    }
+    if (typeof arg === "number") {
+      super(arg);
+      for (let i = 0; i < arg; i++) this[i] = new Complex64(0, 0);
+      return;
+    }
+
+    const items = Array.from(arg);
+    super();
+    if (items.length === 0) return;
+
+    if (items[0] instanceof Complex64) {
+      for (const z of items) {
+        if (!(z instanceof Complex64))
+          throw new Error(
+            "Complex64Array expects every element to be a Complex64.",
+          );
+        this.push(z);
+      }
+      return;
+    }
+
+    if (items.length % 2 !== 0)
+      throw new Error(
+        "Complex64Array expects an even number of interleaved [re, im, ...] values.",
+      );
+    for (let i = 0; i < items.length; i += 2) {
+      if (typeof items[i] !== "number" || typeof items[i + 1] !== "number")
+        throw new Error(
+          "Complex64Array expects interleaved [re, im, ...] values to be numbers.",
+        );
+      this.push(new Complex64(items[i], items[i + 1]));
+    }
+  }
+}

package/src/classes/GpuMatrix.d.mts

@@ -1,3 +1,6 @@
+import { Complex32Array } from "./Complex32.mjs";
+import { Complex64Array } from "./Complex64.mjs";
+
 /**
  * Represents a Float32Array (or Float64Array) matrix stored in GPU memory,
  * row-major or column-major.
@@ -30,72 +33,69 @@ export declare class GpuMatrix {
   /** Storage layout this matrix was created with — every routine that accepts a GpuMatrix reads this automatically. */
   readonly layout: 'row-major' | 'column-major';
 
+  /** Typed array (or complex array) constructor used when reading data back from the GPU. */
+  readonly dtype: Float32ArrayConstructor | Float64ArrayConstructor | typeof Complex32Array | typeof Complex64Array;
+
   /**
-   * Uploads a Float32Array or Float64Array matrix to GPU memory, row-major
-   * or column-major. A Float64Array is split into a double-double (hi, lo)
-   * f32 pair per element (WGSL has no f64 type) and stored across two GPU
-   * buffers internally; `read()` reassembles doubles from these pairs. This
-   * gives ~48 bits of mantissa (vs. 24 for a single f32) but less than true
-   * f64 precision (52 bits), so round-tripped values are not always
-   * bit-exact with the original input.
+   * Uploads a Float32Array, Float64Array, Complex32Array, or Complex64Array
+   * matrix to GPU memory, row-major or column-major. A Float64Array is split
+   * into a double-double (hi, lo) f32 pair per element (WGSL has no f64
+   * type) and stored across two GPU buffers internally; `read()` reassembles
+   * doubles from these pairs. This gives ~48 bits of mantissa (vs. 24 for a
+   * single f32) but less than true f64 precision (52 bits), so
+   * round-tripped values are not always bit-exact with the original input.
+   * A Complex32Array is stored interleaved (`[re0, im0, re1, im1, ...]`) in
+   * one buffer; a Complex64Array gets the same double-double split applied
+   * independently to its real and imaginary components.
    *
    * `rows`/`cols` always describe the logical shape regardless of layout.
    * `lda` defaults to `cols` (row-major) or `rows` (column-major) — dense, no
    * padding. `data` must have at least `rows * lda` (row-major) or
    * `cols * lda` (column-major) elements.
    *
+   * Omitting the device falls back to the one from the last {@link init} call
+   * — the historical form, and fine for a single-GPU program. Pass a device
+   * explicitly (matching every routine's own `(device, ...)` convention)
+   * when driving more than one GPU at once, since a GpuMatrix is bound for
+   * life to whichever device created it.
+   *
    * @param data   - matrix data, in the order matching `layout`
    * @param rows   - number of rows
    * @param cols   - number of columns
    * @param lda    - leading dimension (default: `cols` for row-major, `rows` for column-major)
    * @param layout - storage layout (default: `'row-major'`)
    *
-   * @example
-   * ```js
-   * import { init, GpuMatrix } from "wgblas";
-   *
-   * await init();
-   * // 2×3 matrix: [[1,2,3],[4,5,6]]
-   * const mat = GpuMatrix.from(new Float32Array([1,2,3,4,5,6]), 2, 3);
-   * console.log(mat.rows, mat.cols, mat.lda); // 2 3 3
+   * {@includeCode ../../examples/gpumatrix-from/gpumatrix-from.js}
    *
-   * // Same logical matrix, column-major storage
-   * const matCol = GpuMatrix.from(new Float32Array([1,4,2,5,3,6]), 2, 3, undefined, "column-major");
-   * ```
+   * **Explicit device (multi-GPU):**
+   * {@includeCode ../../examples/gpumatrix-from-device/gpumatrix-from-device.js}
    */
-  static from(data: Float32Array | Float64Array, rows: number, cols: number, lda?: number, layout?: 'row-major' | 'column-major'): GpuMatrix;
+  static from(data: Float32Array | Float64Array | Complex32Array | Complex64Array, rows: number, cols: number, lda?: number, layout?: 'row-major' | 'column-major'): GpuMatrix;
+  /**
+   * @param device - GPUDevice from `init()` — the matrix is bound to this device for life
+   * @param data   - matrix data, in the order matching `layout`
+   * @param rows   - number of rows
+   * @param cols   - number of columns
+   * @param lda    - leading dimension (default: `cols` for row-major, `rows` for column-major)
+   * @param layout - storage layout (default: `'row-major'`)
+   */
+  static from(device: GPUDevice, data: Float32Array | Float64Array | Complex32Array | Complex64Array, rows: number, cols: number, lda?: number, layout?: 'row-major' | 'column-major'): GpuMatrix;
 
   /**
    * Downloads the matrix from GPU memory and returns a dense array of shape
-   * `rows × cols`, in the same layout it was created with — a `Float32Array`,
-   * or a `Float64Array` if this matrix was created from one. If `lda` exceeds
-   * the dense minimum, the leading-dimension padding is stripped so the
-   * returned array is always tightly packed.
-   *
-   * @example
-   * ```js
-   * import { init, GpuMatrix } from "wgblas";
+   * `rows × cols`, in the same layout and type it was created with. If `lda`
+   * exceeds the dense minimum, the leading-dimension padding is stripped so
+   * the returned array is always tightly packed.
    *
-   * await init();
-   * const mat = GpuMatrix.from(new Float32Array([1,2,3,4,5,6]), 2, 3);
-   * const data = await mat.read();
-   * console.log(data); // Float32Array [1, 2, 3, 4, 5, 6]
-   * ```
+   * {@includeCode ../../examples/gpumatrix-read/gpumatrix-read.js}
    */
-  read(): Promise<Float32Array | Float64Array>;
+  read(): Promise<Float32Array | Float64Array | Complex32Array | Complex64Array>;
 
   /**
    * Destroys the underlying GPU buffer. Call when the matrix is no longer
    * needed to free GPU memory.
    *
-   * @example
-   * ```js
-   * import { init, GpuMatrix } from "wgblas";
-   *
-   * await init();
-   * const mat = GpuMatrix.from(new Float32Array([1,2,3,4,5,6]), 2, 3);
-   * mat.destroy();
-   * ```
+   * {@includeCode ../../examples/gpumatrix-destroy/gpumatrix-destroy.js}
    */
   destroy(): void;
 }

package/src/classes/GpuMatrix.mjs

@@ -2,15 +2,34 @@ import { getDevice } from "../init.mjs";
 import { uploadBuffer, stageReadback } from "../util/buffer.mjs";
 import { extractResult } from "../util/result.mjs";
 import { splitDoubleDouble, mergeDoubleDouble } from "../util/f64.mjs";
+import {
+  interleaveComplex32,
+  splitComplex64,
+  mergeComplex64,
+} from "../util/complex.mjs";
+import { Complex32Array } from "./Complex32.mjs";
+import { Complex64Array } from "./Complex64.mjs";
 
 export class GpuMatrix {
-  constructor(buffer, rows, cols, lda, loBuffer = null, layout = "row-major") {
+  constructor(
+    buffer,
+    rows,
+    cols,
+    lda,
+    loBuffer = null,
+    layout = "row-major",
+    device = null,
+    dtype = Float32Array,
+  ) {
     this._buf = buffer;
     this._loBuf = loBuffer; // Non-null only for Float64Array-backed matrices
     this.rows = rows;
     this.cols = cols;
-    this.lda  = lda;
+    this.lda = lda;
     this.layout = layout;
+    this.dtype = dtype; // disambiguates Complex32Array from Float32Array — both have _loBuf === null
+    // See GpuVector: a GPUBuffer is bound to one device for life.
+    this.device = device ?? getDevice();
   }
 
   /**
@@ -21,21 +40,35 @@ export class GpuMatrix {
    * no padding). `data` must have at least `rows * lda` (row-major) or
    * `cols * lda` (column-major) elements.
    */
-  static from(data, rows, cols, lda, layout = "row-major") {
+  static from(deviceOrData, ...rest) {
+    const explicit = deviceOrData instanceof GPUDevice;
+    const device = explicit ? deviceOrData : getDevice();
+    const data = explicit ? rest.shift() : deviceOrData;
+    let [rows, cols, lda, layout = "row-major"] = rest;
+
     if (layout !== "row-major" && layout !== "column-major")
       throw new Error("layout must be 'row-major' or 'column-major'.");
     const isRowMajor = layout === "row-major";
     if (lda === undefined) lda = isRowMajor ? cols : rows;
 
-    if (!(data instanceof Float32Array) && !(data instanceof Float64Array))
-      throw new Error("GpuMatrix.from expects a Float32Array or Float64Array.");
+    if (
+      !(data instanceof Float32Array) &&
+      !(data instanceof Float64Array) &&
+      !(data instanceof Complex32Array) &&
+      !(data instanceof Complex64Array)
+    )
+      throw new Error(
+        "GpuMatrix.from expects a Float32Array, Float64Array, Complex32Array, or Complex64Array.",
+      );
     if (!Number.isInteger(rows) || rows <= 0)
       throw new Error("rows must be a positive integer.");
     if (!Number.isInteger(cols) || cols <= 0)
       throw new Error("cols must be a positive integer.");
     const minLda = isRowMajor ? cols : rows;
     if (!Number.isInteger(lda) || lda < minLda)
-      throw new Error(`lda must be an integer >= ${isRowMajor ? "cols" : "rows"}.`);
+      throw new Error(
+        `lda must be an integer >= ${isRowMajor ? "cols" : "rows"}.`,
+      );
 
     // Row-major: `rows` chunks of length `lda` (only the first `cols` of each used).
     // Column-major: `cols` chunks of length `lda` (only the first `rows` of each used).
@@ -48,39 +81,112 @@ export class GpuMatrix {
     if (data instanceof Float64Array) {
       const n = outerCount * lda;
       const { hi, lo } = splitDoubleDouble(data.subarray(0, n));
-      const hiBuf = uploadBuffer(hi, "gpu-matrix-f64-hi", true);
-      const loBuf = uploadBuffer(lo, "gpu-matrix-f64-lo", true);
-      return new GpuMatrix(hiBuf, rows, cols, lda, loBuf, layout);
+      const hiBuf = uploadBuffer(device, hi, "gpu-matrix-f64-hi", true);
+      const loBuf = uploadBuffer(device, lo, "gpu-matrix-f64-lo", true);
+      return new GpuMatrix(
+        hiBuf,
+        rows,
+        cols,
+        lda,
+        loBuf,
+        layout,
+        device,
+        Float64Array,
+      );
     }
 
-    const buf = uploadBuffer(data.subarray(0, outerCount * lda), "gpu-matrix", true);
-    return new GpuMatrix(buf, rows, cols, lda, null, layout);
+    if (data instanceof Complex32Array) {
+      const buf = uploadBuffer(
+        device,
+        interleaveComplex32(data, outerCount * lda),
+        "gpu-matrix-complex32",
+        true,
+      );
+      return new GpuMatrix(
+        buf,
+        rows,
+        cols,
+        lda,
+        null,
+        layout,
+        device,
+        Complex32Array,
+      );
+    }
+
+    if (data instanceof Complex64Array) {
+      const { hi, lo } = splitComplex64(data, outerCount * lda);
+      const hiBuf = uploadBuffer(device, hi, "gpu-matrix-complex64-hi", true);
+      const loBuf = uploadBuffer(device, lo, "gpu-matrix-complex64-lo", true);
+      return new GpuMatrix(
+        hiBuf,
+        rows,
+        cols,
+        lda,
+        loBuf,
+        layout,
+        device,
+        Complex64Array,
+      );
+    }
+
+    const buf = uploadBuffer(
+      device,
+      data.subarray(0, outerCount * lda),
+      "gpu-matrix",
+      true,
+    );
+    return new GpuMatrix(buf, rows, cols, lda, null, layout, device);
   }
 
   async read() {
-    const device = getDevice();
+    const device = this.device;
     const enc = device.createCommandEncoder();
-    const rb = stageReadback(enc, this._buf);
+    const rb = stageReadback(device, enc, this._buf);
     device.queue.submit([enc.finish()]);
 
     const isRowMajor = this.layout !== "column-major";
     const outerCount = isRowMajor ? this.rows : this.cols;
-    const innerLen   = isRowMajor ? this.cols : this.rows;
+    const innerLen = isRowMajor ? this.cols : this.rows;
+
+    if (this.dtype === Complex32Array) {
+      const raw = new Complex32Array(await extractResult(rb, Float32Array));
+      if (this.lda === innerLen) return raw;
+      const out = new Complex32Array(outerCount * innerLen);
+      for (let r = 0; r < outerCount; r++)
+        for (let c = 0; c < innerLen; c++)
+          out[r * innerLen + c] = raw[r * this.lda + c];
+      return out;
+    }
 
     if (this._loBuf) {
       const encLo = device.createCommandEncoder();
-      const rbLo = stageReadback(encLo, this._loBuf);
+      const rbLo = stageReadback(device, encLo, this._loBuf);
       device.queue.submit([encLo.finish()]);
 
       const [hi, lo] = await Promise.all([
         extractResult(rb, Float32Array),
         extractResult(rbLo, Float32Array),
       ]);
+
+      if (this.dtype === Complex64Array) {
+        const raw = mergeComplex64(hi, lo);
+        if (this.lda === innerLen) return raw;
+        const out = new Complex64Array(outerCount * innerLen);
+        for (let r = 0; r < outerCount; r++)
+          for (let c = 0; c < innerLen; c++)
+            out[r * innerLen + c] = raw[r * this.lda + c];
+        return out;
+      }
+
       const raw = mergeDoubleDouble(hi, lo);
       if (this.lda === innerLen) return raw;
       const out = new Float64Array(outerCount * innerLen);
       for (let r = 0; r < outerCount; r++)
-        out.set(raw.subarray(r * this.lda, r * this.lda + innerLen), r * innerLen);
+        out.set(
+          raw.subarray(r * this.lda, r * this.lda + innerLen),
+          r * innerLen,
+        );
       return out;
     }
 
@@ -88,7 +194,10 @@ export class GpuMatrix {
     if (this.lda === innerLen) return raw;
     const out = new Float32Array(outerCount * innerLen);
     for (let r = 0; r < outerCount; r++)
-      out.set(raw.subarray(r * this.lda, r * this.lda + innerLen), r * innerLen);
+      out.set(
+        raw.subarray(r * this.lda, r * this.lda + innerLen),
+        r * innerLen,
+      );
     return out;
   }
 

package/src/classes/GpuVector.d.mts

@@ -1,3 +1,6 @@
+import { Complex32Array } from "./Complex32.mjs";
+import { Complex64Array } from "./Complex64.mjs";
+
 /**
  * Represents a Float32Array stored in GPU memory.
  *
@@ -12,65 +15,58 @@ export declare class GpuVector {
   /** Number of elements in the vector. */
   readonly length: number;
 
-  /** Typed array constructor used when reading data back from the GPU. */
-  readonly dtype: Float32ArrayConstructor | Float64ArrayConstructor;
+  /** Typed array (or complex array) constructor used when reading data back from the GPU. */
+  readonly dtype: Float32ArrayConstructor | Float64ArrayConstructor | typeof Complex32Array | typeof Complex64Array;
 
   /**
-   * Uploads a Float32Array or Float64Array to GPU memory. A Float64Array is
-   * split into a double-double (hi, lo) f32 pair per element (WGSL has no
-   * f64 type) and stored across two GPU buffers internally; `read()`
-   * reassembles doubles from these pairs. This gives ~48 bits of mantissa
-   * (vs. 24 for a single f32) but less than true f64 precision (52 bits), so
-   * round-tripped values are not always bit-exact with the original input.
+   * Uploads a Float32Array, Float64Array, Complex32Array, or Complex64Array
+   * to GPU memory. A Float64Array is split into a double-double (hi, lo) f32
+   * pair per element (WGSL has no f64 type) and stored across two GPU
+   * buffers internally; `read()` reassembles doubles from these pairs. This
+   * gives ~48 bits of mantissa (vs. 24 for a single f32) but less than true
+   * f64 precision (52 bits), so round-tripped values are not always
+   * bit-exact with the original input. A Complex32Array is stored
+   * interleaved (`[re0, im0, re1, im1, ...]`) in one buffer; a
+   * Complex64Array gets the same double-double split applied independently
+   * to its real and imaginary components, interleaved per (hi, lo) channel.
+   *
+   * Omitting the device falls back to the one from the last {@link init} call
+   * — the historical form, and fine for a single-GPU program. Pass a device
+   * explicitly (matching every routine's own `(device, ...)` convention)
+   * when driving more than one GPU at once, since a GpuVector is bound for
+   * life to whichever device created it.
    *
    * @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);
+   * {@includeCode ../../examples/gpuvector-from/gpuvector-from.js}
    *
-   * const dvec = GpuVector.from(new Float64Array([1.1, 2.2, 3.3]));
-   * console.log("dtype:", dvec.dtype.name); // Float64Array
-   * ```
+   * **Explicit device (multi-GPU):**
+   * {@includeCode ../../examples/gpuvector-from-device/gpuvector-from-device.js}
    */
-  static from(data: Float32Array | Float64Array): GpuVector;
+  static from(data: Float32Array | Float64Array | Complex32Array | Complex64Array): GpuVector;
+  /**
+   * @param device - GPUDevice from `init()` — the vector is bound to this device for life
+   * @param data - input vector data
+   * @returns GpuVector backed by a GPU buffer
+   */
+  static from(device: GPUDevice, data: Float32Array | Float64Array | Complex32Array | Complex64Array): GpuVector;
 
   /**
    * Reads the vector data back from GPU memory.
    *
-   * @returns vector data as a Float32Array, or a Float64Array if this vector
-   * was created from one
+   * @returns vector data in the same shape it was created from — a
+   * Float32Array, Float64Array, Complex32Array, or Complex64Array
    *
-   * @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);
-   * ```
+   * {@includeCode ../../examples/gpuvector-read/gpuvector-read.js}
    */
-  read(): Promise<Float32Array | Float64Array>;
+  read(): Promise<Float32Array | Float64Array | Complex32Array | Complex64Array>;
 
   /**
    * 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");
-   * ```
+   * {@includeCode ../../examples/gpuvector-destroy/gpuvector-destroy.js}
    */
   destroy(): void;
 }

package/src/classes/GpuVector.mjs

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