wgblas 2.2.1 → 2.3.0

package/src/dger/dger.mjs

@@ -0,0 +1,213 @@
+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 { GpuVector } from "../classes/GpuVector.mjs";
+import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+import { splitDoubleDouble, mergeDoubleDouble } from "../util/f64.mjs";
+import { requireGpuDevice, requireSameDevice } from "../util/device.mjs";
+
+// dger: A := alpha * x * y^T + A, double-double (Dekker) f64 emulation of
+// sger — x, y, A, and alpha are each split into an f32 (hi, lo) pair; WGSL
+// has no f64 type.
+export async function dger(
+  device,
+  m,
+  n,
+  alpha,
+  x,
+  incx,
+  y,
+  incy,
+  A,
+  lda,
+  layout = "row-major",
+) {
+  const AIsGpu = A instanceof GpuMatrix;
+
+  requireGpuDevice(device);
+  requireSameDevice(device, "dger", { A, x, y });
+  if (layout !== "row-major" && layout !== "column-major")
+    throw new Error("layout must be 'row-major' or 'column-major'.");
+  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 (
+    !Number.isInteger(m) ||
+    !Number.isInteger(n) ||
+    !Number.isInteger(incx) ||
+    !Number.isInteger(incy) ||
+    !Number.isInteger(lda)
+  )
+    throw new Error("m, n, incx, incy, and lda must be integers.");
+  if (incx <= 0 || incy <= 0)
+    throw new Error("incx and incy must be positive.");
+  if (!AIsGpu && !(A instanceof Float64Array))
+    throw new Error("A must be a Float64Array or GpuMatrix.");
+  if (AIsGpu && A.dtype !== Float64Array)
+    throw new Error("A must be a Float64Array-backed GpuMatrix.");
+  if (AIsGpu && lda !== A.lda)
+    throw new Error("lda must match A.lda when A is a GpuMatrix.");
+  // A.rows/A.cols are fixed regardless of layout — check against original m/n before the swap below.
+  if (AIsGpu && (A.rows < m || A.cols < n))
+    throw new Error("A is too small for the given m and n.");
+
+  // GpuMatrix's own layout wins over the argument; column-major A reinterpreted row-major is A^T, so swap x/y and m/n to reproduce it (transpose of a rank-1 update swaps its two vectors).
+  const effLayout = AIsGpu ? A.layout : layout;
+  if (effLayout === "column-major") {
+    [m, n] = [n, m];
+    [x, y] = [y, x];
+    [incx, incy] = [incy, incx];
+  }
+
+  const xIsGpu = x instanceof GpuVector;
+  const yIsGpu = y instanceof GpuVector;
+
+  if (lda < n) throw new Error("lda must be >= n.");
+  if (!xIsGpu && !(x instanceof Float64Array))
+    throw new Error("x must be a Float64Array or GpuVector.");
+  if (!yIsGpu && !(y instanceof Float64Array))
+    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 (xIsGpu && !AIsGpu)
+    throw new Error("A must be a GpuMatrix when x and y are GpuVectors.");
+  if (AIsGpu && !xIsGpu)
+    throw new Error("x and y must be GpuVectors when A is a GpuMatrix.");
+  if (AIsGpu && xIsGpu && A._buf === x._buf)
+    throw new Error("A and x must not reference the same GPU buffer.");
+  if (AIsGpu && yIsGpu && A._buf === y._buf)
+    throw new Error("A and y must not reference the same GPU buffer.");
+  if (m < 0 || n < 0) throw new Error("m and n must be non-negative.");
+  if (m === 0 || n === 0) return AIsGpu ? {} : { A };
+
+  if (!AIsGpu && A.length < (m - 1) * lda + n)
+    throw new Error(
+      "A does not have enough elements for the given m, n, and lda.",
+    );
+  if (x.length < (m - 1) * incx + 1)
+    throw new Error(
+      "x does not have enough elements for the given m 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 f64Deps = ["f64/dekker", "f64/utils/add", "f64/utils/multiply"];
+  const pipeline = await getPipeline(device, [...f64Deps, "dger"], "dger_main");
+
+  const { hi: alphaHi, lo: alphaLo } = splitDoubleDouble(
+    new Float64Array([alpha]),
+  );
+
+  let xHiBuffer = null;
+  let xLoBuffer = null;
+  let yHiBuffer = null;
+  let yLoBuffer = null;
+  let AHiBuffer = null;
+  let ALoBuffer = 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;
+      AHiBuffer = A._buf;
+      ALoBuffer = A._loBuf;
+    } else {
+      const xSplit = splitDoubleDouble(x);
+      const ySplit = splitDoubleDouble(y);
+      const ASplit = splitDoubleDouble(A);
+      xHiBuffer = uploadBuffer(device, xSplit.hi, "dger-xHi", false);
+      xLoBuffer = uploadBuffer(device, xSplit.lo, "dger-xLo", false);
+      yHiBuffer = uploadBuffer(device, ySplit.hi, "dger-yHi", false);
+      yLoBuffer = uploadBuffer(device, ySplit.lo, "dger-yLo", false);
+      AHiBuffer = uploadBuffer(device, ASplit.hi, "dger-AHi", true);
+      ALoBuffer = uploadBuffer(device, ASplit.lo, "dger-ALo", true);
+    }
+    paramsBuffer = createParamsBuffer(
+      device,
+      [
+        { value: m, type: "u32" },
+        { value: n, type: "u32" },
+        { value: alphaHi[0], type: "f32" },
+        { value: alphaLo[0], type: "f32" },
+        { value: incx, type: "u32" },
+        { value: incy, type: "u32" },
+        { value: lda, type: "u32" },
+      ],
+      "dger-params",
+    );
+
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
+      xHiBuffer,
+      xLoBuffer,
+      yHiBuffer,
+      yLoBuffer,
+      AHiBuffer,
+      ALoBuffer,
+      paramsBuffer,
+    ]);
+
+    // One workgroup per row of A; clamped to device limit — the shader's
+    // grid-stride loop handles remaining rows when m > dispatch count.
+    const wgCount = Math.min(m, device.limits.maxComputeWorkgroupsPerDimension);
+    const { commandEncoder, ts } = runComputePass(
+      device,
+      pipeline,
+      bindGroup,
+      wgCount,
+    );
+    readHiBuffer = AIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, AHiBuffer);
+    readLoBuffer = AIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, ALoBuffer);
+
+    submit(device, commandEncoder);
+
+    const gpuTimeMs = await extractTimestamp(ts);
+
+    if (AIsGpu) {
+      if (gpuTimeMs !== undefined) return { gpuTimeMs };
+      return {};
+    }
+
+    const hi = await extractResult(readHiBuffer, Float32Array);
+    readHiBuffer = null;
+    const lo = await extractResult(readLoBuffer, Float32Array);
+    readLoBuffer = null;
+    const result = mergeDoubleDouble(hi, lo);
+    if (gpuTimeMs !== undefined) return { A: result, gpuTimeMs };
+    return { A: result };
+  } finally {
+    if (!xIsGpu && xHiBuffer) destroyBuffers(xHiBuffer);
+    if (!xIsGpu && xLoBuffer) destroyBuffers(xLoBuffer);
+    if (!yIsGpu && yHiBuffer) destroyBuffers(yHiBuffer);
+    if (!yIsGpu && yLoBuffer) destroyBuffers(yLoBuffer);
+    if (!AIsGpu && AHiBuffer) destroyBuffers(AHiBuffer);
+    if (!AIsGpu && ALoBuffer) destroyBuffers(ALoBuffer);
+    if (paramsBuffer) destroyBuffers(paramsBuffer);
+    if (readHiBuffer) destroyBuffers(readHiBuffer);
+    if (readLoBuffer) destroyBuffers(readLoBuffer);
+  }
+}

package/src/dsymv/dsymv.d.mts

@@ -0,0 +1,84 @@
+import { GpuVector } from "../classes/GpuVector.mjs";
+import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+
+/**
+ * Performs the symmetric matrix-vector operation $$y \leftarrow \alpha A x + \beta y$$
+ * in double precision (double-double emulation — WGSL has no native f64 type).
+ *
+ * A is an n×n symmetric matrix stored in row-major order. Only the triangle
+ * specified by `uplo` is referenced; the other triangle is inferred by symmetry.
+ *
+ * {@includeCode ../../examples/dsymv/dsymv.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/dsymv/web/dsymv.html}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param uplo   - `'lower'` to use the lower triangle, `'upper'` to use the upper triangle
+ * @param n      - order of the matrix A (number of rows and columns)
+ * @param alpha  - scalar multiplier for A*x
+ * @param A      - Float64Array, row-major or column-major (see `layout`), at least (n-1)*lda+n elements
+ * @param lda    - leading dimension of A (>= n either way — A is square)
+ * @param x      - Float64Array input vector, length at least (n-1)*incx+1
+ * @param incx   - stride for x (must be a positive integer)
+ * @param beta   - scalar multiplier for y
+ * @param y      - Float64Array input/output vector, length at least (n-1)*incy+1
+ * @param incy   - stride for y (must be a positive integer)
+ * @param layout - storage layout of `A` (default: `'row-major'`); for a symmetric
+ *   matrix, column-major storage just means the *other* triangle is the one
+ *   physically referenced for a given `uplo`
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/dsymv/dsymv.mjs#L19">Source code: dsymv.mjs (L19)</a>
+ * @category BLAS Level 2
+ */
+export declare function dsymv(
+  device: GPUDevice,
+  uplo: 'lower' | 'upper',
+  n: number,
+  alpha: number,
+  A: Float64Array,
+  lda: number,
+  x: Float64Array,
+  incx: number,
+  beta: number,
+  y: Float64Array,
+  incy: number,
+  layout?: 'row-major' | 'column-major',
+): Promise<{ y: Float64Array; gpuTimeMs?: number }>;
+
+/**
+ * Performs the symmetric matrix-vector operation $$y \leftarrow \alpha A x + \beta y$$
+ * in double precision (double-double emulation).
+ *
+ * x and y are kept resident on the GPU. A must be a GpuMatrix (Float64Array-
+ * backed); its own `layout` (set at `GpuMatrix.from` time) determines the
+ * operation — there is no separate `layout` argument here.
+ *
+ * {@includeCode ../../examples/dsymv/gpu.dsymv.js}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param uplo   - `'lower'` to use the lower triangle, `'upper'` to use the upper triangle
+ * @param n      - order of the matrix A
+ * @param alpha  - scalar multiplier for A*x
+ * @param A      - GpuMatrix (Float64Array-backed), GPU-resident
+ * @param lda    - leading dimension of A (must equal A.lda)
+ * @param x      - GpuVector input vector (Float64Array-backed, not mutated)
+ * @param incx   - stride for x (must be a positive integer)
+ * @param beta   - scalar multiplier for y
+ * @param y      - GpuVector input/output vector (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/dsymv/dsymv.mjs#L19">Source code: dsymv.mjs (L19)</a>
+ * @category BLAS Level 2
+ */
+export declare function dsymv(
+  device: GPUDevice,
+  uplo: 'lower' | 'upper',
+  n: number,
+  alpha: number,
+  A: GpuMatrix,
+  lda: number,
+  x: GpuVector,
+  incx: number,
+  beta: number,
+  y: GpuVector,
+  incy: number,
+): Promise<{ gpuTimeMs?: number }>;

package/src/dsymv/dsymv.mjs

@@ -0,0 +1,227 @@
+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 { GpuVector } from "../classes/GpuVector.mjs";
+import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+import { splitDoubleDouble, mergeDoubleDouble } from "../util/f64.mjs";
+import { requireGpuDevice, requireSameDevice } from "../util/device.mjs";
+
+// dsymv: y := alpha * A * x + beta * y, double-double (Dekker) f64 emulation
+// of ssymv — A, x, y, alpha, and beta are each split into an f32 (hi, lo)
+// pair; WGSL has no f64 type.
+export async function dsymv(
+  device,
+  uplo,
+  n,
+  alpha,
+  A,
+  lda,
+  x,
+  incx,
+  beta,
+  y,
+  incy,
+  layout = "row-major",
+) {
+  const xIsGpu = x instanceof GpuVector;
+  const yIsGpu = y instanceof GpuVector;
+  const AIsGpu = A instanceof GpuMatrix;
+
+  requireGpuDevice(device);
+  requireSameDevice(device, "dsymv", { A, x, y });
+  if (uplo !== "lower" && uplo !== "upper")
+    throw new Error("uplo must be 'lower' or 'upper'.");
+  if (layout !== "row-major" && layout !== "column-major")
+    throw new Error("layout must be 'row-major' or 'column-major'.");
+  if (
+    !Number.isInteger(n) ||
+    !Number.isInteger(incx) ||
+    !Number.isInteger(incy) ||
+    !Number.isInteger(lda)
+  )
+    throw new Error("n, incx, incy, and lda 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 (typeof beta !== "number") throw new Error("beta must be a number.");
+  if (Number.isNaN(beta)) throw new Error("beta must not be NaN.");
+  if (!Number.isFinite(beta)) throw new Error("beta must be finite.");
+  if (incx <= 0 || incy <= 0)
+    throw new Error("incx and incy must be positive.");
+  if (lda < n) throw new Error("lda must be >= n.");
+  if (!AIsGpu && !(A instanceof Float64Array))
+    throw new Error("A must be a Float64Array or GpuMatrix.");
+  if (AIsGpu && A.dtype !== Float64Array)
+    throw new Error("A must be a Float64Array-backed GpuMatrix.");
+  if (!xIsGpu && !(x instanceof Float64Array))
+    throw new Error("x must be a Float64Array or GpuVector.");
+  if (!yIsGpu && !(y instanceof Float64Array))
+    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 (xIsGpu && !AIsGpu)
+    throw new Error("A must be a GpuMatrix when x and y are GpuVectors.");
+  if (AIsGpu && !xIsGpu)
+    throw new Error("x and y must be GpuVectors when A is a GpuMatrix.");
+  if (xIsGpu && x._buf === y._buf)
+    throw new Error(
+      "x and y must not reference the same GPU buffer when both are GpuVectors.",
+    );
+  if (AIsGpu && yIsGpu && A._buf === y._buf)
+    throw new Error("A and y must not reference the same GPU buffer.");
+  if (AIsGpu && lda !== A.lda)
+    throw new Error("lda must match A.lda when A is a GpuMatrix.");
+  if (AIsGpu && (A.rows < n || A.cols < n))
+    throw new Error("A is too small for the given n.");
+  if (n < 0) throw new Error("n must be non-negative.");
+  if (n === 0) return yIsGpu ? {} : { y };
+
+  if (!AIsGpu && A.length < (n - 1) * lda + n)
+    throw new Error("A does not have enough elements for the given n and lda.");
+  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.",
+    );
+
+  // GpuMatrix's own layout wins over the argument; A is symmetric, so column-major A reinterpreted row-major just flips which triangle is stored — flip uplo to match.
+  const effLayout = AIsGpu ? A.layout : layout;
+  const isLower =
+    effLayout === "column-major" ? uplo === "upper" : uplo === "lower";
+
+  const f64Deps = ["f64/dekker", "f64/utils/add", "f64/utils/multiply"];
+  const pipeline = await getPipeline(
+    device,
+    [...f64Deps, "dsymv"],
+    "dsymv_main",
+  );
+
+  const { hi: alphaHi, lo: alphaLo } = splitDoubleDouble(
+    new Float64Array([alpha]),
+  );
+  const { hi: betaHi, lo: betaLo } = splitDoubleDouble(
+    new Float64Array([beta]),
+  );
+
+  let AHiBuffer = null;
+  let ALoBuffer = null;
+  let xHiBuffer = null;
+  let xLoBuffer = null;
+  let yHiBuffer = null;
+  let yLoBuffer = null;
+  let paramsBuffer = null;
+  let readHiBuffer = null;
+  let readLoBuffer = null;
+
+  try {
+    if (AIsGpu) {
+      AHiBuffer = A._buf;
+      ALoBuffer = A._loBuf;
+    } else {
+      const ASplit = splitDoubleDouble(A);
+      AHiBuffer = uploadBuffer(device, ASplit.hi, "dsymv-AHi", false);
+      ALoBuffer = uploadBuffer(device, ASplit.lo, "dsymv-ALo", false);
+    }
+    if (xIsGpu) {
+      xHiBuffer = x._buf;
+      xLoBuffer = x._loBuf;
+    } else {
+      const xSplit = splitDoubleDouble(x);
+      xHiBuffer = uploadBuffer(device, xSplit.hi, "dsymv-xHi", false);
+      xLoBuffer = uploadBuffer(device, xSplit.lo, "dsymv-xLo", false);
+    }
+    if (yIsGpu) {
+      yHiBuffer = y._buf;
+      yLoBuffer = y._loBuf;
+    } else {
+      const ySplit = splitDoubleDouble(y);
+      yHiBuffer = uploadBuffer(device, ySplit.hi, "dsymv-yHi", true);
+      yLoBuffer = uploadBuffer(device, ySplit.lo, "dsymv-yLo", true);
+    }
+    paramsBuffer = createParamsBuffer(
+      device,
+      [
+        { value: n, type: "u32" },
+        { value: alphaHi[0], type: "f32" },
+        { value: alphaLo[0], type: "f32" },
+        { value: betaHi[0], type: "f32" },
+        { value: betaLo[0], type: "f32" },
+        { value: incx, type: "u32" },
+        { value: incy, type: "u32" },
+        { value: lda, type: "u32" },
+        { value: isLower ? 0 : 1, type: "u32" },
+      ],
+      "dsymv-params",
+    );
+
+    const bindGroup = createBindGroup(device, pipeline.getBindGroupLayout(0), [
+      AHiBuffer,
+      ALoBuffer,
+      xHiBuffer,
+      xLoBuffer,
+      yHiBuffer,
+      yLoBuffer,
+      paramsBuffer,
+    ]);
+
+    // One workgroup per row of A; clamped to device limit — the shader's
+    // grid-stride loop handles remaining rows when n > dispatch count.
+    const wgCount = Math.min(n, device.limits.maxComputeWorkgroupsPerDimension);
+    const { commandEncoder, ts } = runComputePass(
+      device,
+      pipeline,
+      bindGroup,
+      wgCount,
+    );
+    readHiBuffer = yIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, yHiBuffer);
+    readLoBuffer = yIsGpu
+      ? null
+      : stageReadback(device, commandEncoder, yLoBuffer);
+
+    submit(device, commandEncoder);
+
+    const gpuTimeMs = await extractTimestamp(ts);
+
+    if (yIsGpu) {
+      if (gpuTimeMs !== undefined) return { gpuTimeMs };
+      return {};
+    }
+
+    const hi = await extractResult(readHiBuffer, Float32Array);
+    readHiBuffer = null;
+    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 (!AIsGpu && AHiBuffer) destroyBuffers(AHiBuffer);
+    if (!AIsGpu && ALoBuffer) destroyBuffers(ALoBuffer);
+    if (!xIsGpu && xHiBuffer) destroyBuffers(xHiBuffer);
+    if (!xIsGpu && xLoBuffer) destroyBuffers(xLoBuffer);
+    if (!yIsGpu && yHiBuffer) destroyBuffers(yHiBuffer);
+    if (!yIsGpu && yLoBuffer) destroyBuffers(yLoBuffer);
+    if (paramsBuffer) destroyBuffers(paramsBuffer);
+    if (readHiBuffer) destroyBuffers(readHiBuffer);
+    if (readLoBuffer) destroyBuffers(readLoBuffer);
+  }
+}

package/src/dsyr/dsyr.d.mts

@@ -0,0 +1,73 @@
+import { GpuVector } from "../classes/GpuVector.mjs";
+import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+
+/**
+ * Performs the symmetric rank-1 update $$A \leftarrow \alpha x x^{T} + A$$ in
+ * double precision (double-double emulation — WGSL has no native f64 type).
+ *
+ * A is an n×n symmetric matrix stored in row-major order, updated in place.
+ * Only the triangle specified by `uplo` is referenced and updated; the other
+ * triangle is left untouched (implied by symmetry).
+ *
+ * {@includeCode ../../examples/dsyr/dsyr.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/dsyr/web/dsyr.html}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param uplo   - `'lower'` to use the lower triangle, `'upper'` to use the upper triangle
+ * @param n      - order of the matrix A (number of rows and columns)
+ * @param alpha  - scalar multiplier for x*x^T
+ * @param x      - Float64Array input vector, length at least (n-1)*incx+1
+ * @param incx   - stride for x (must be a positive integer)
+ * @param A      - Float64Array, row-major or column-major (see `layout`), at least (n-1)*lda+n elements
+ * @param lda    - leading dimension of A (>= n either way — A is square)
+ * @param layout - storage layout of `A` (default: `'row-major'`); for a symmetric
+ *   matrix, column-major storage just means the *other* triangle is the one
+ *   physically referenced for a given `uplo`
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/dsyr/dsyr.mjs#L18">Source code: dsyr.mjs (L18)</a>
+ * @category BLAS Level 2
+ */
+export declare function dsyr(
+  device: GPUDevice,
+  uplo: 'lower' | 'upper',
+  n: number,
+  alpha: number,
+  x: Float64Array,
+  incx: number,
+  A: Float64Array,
+  lda: number,
+  layout?: 'row-major' | 'column-major',
+): Promise<{ A: Float64Array; gpuTimeMs?: number }>;
+
+/**
+ * Performs the symmetric rank-1 update $$A \leftarrow \alpha x x^{T} + A$$ in
+ * double precision (double-double emulation).
+ *
+ * x and A are both kept resident on the GPU. `A`'s own `layout` (set at
+ * `GpuMatrix.from` time) determines the operation — there is no separate
+ * `layout` argument here.
+ *
+ * {@includeCode ../../examples/dsyr/gpu.dsyr.js}
+ *
+ * @param device - GPUDevice from `init()`
+ * @param uplo   - `'lower'` to use the lower triangle, `'upper'` to use the upper triangle
+ * @param n      - order of the matrix A
+ * @param alpha  - scalar multiplier for x*x^T
+ * @param x      - GpuVector input vector (Float64Array-backed, not mutated)
+ * @param incx   - stride for x (must be a positive integer)
+ * @param A      - GpuMatrix (Float64Array-backed), mutated in place
+ * @param lda    - leading dimension of A (must equal A.lda)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/dsyr/dsyr.mjs#L18">Source code: dsyr.mjs (L18)</a>
+ * @category BLAS Level 2
+ */
+export declare function dsyr(
+  device: GPUDevice,
+  uplo: 'lower' | 'upper',
+  n: number,
+  alpha: number,
+  x: GpuVector,
+  incx: number,
+  A: GpuMatrix,
+  lda: number,
+): Promise<{ gpuTimeMs?: number }>;