wgblas 0.1.2 → 1.1.0

package/src/srot/srot.mjs

@@ -24,9 +24,11 @@ export async function srot(device, n, x, incx, y, incy, c, s) {
     !Number.isInteger(incy)
   )
     throw new Error("n, incx, and incy must be integers.");
-  if (isNaN(c) || isNaN(s)) throw new Error("c and s must not be NaN.");
-  if (!isFinite(c)) throw new Error("c must be finite.");
-  if (!isFinite(s)) throw new Error("s must be finite.");
+  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 (!xIsGpu && !(x instanceof Float32Array))
@@ -49,47 +51,61 @@ export async function srot(device, n, x, incx, y, incy, c, s) {
 
   const pipeline = await getPipeline(device, "srot");
 
-  const xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "srot-x", true);
-  const yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "srot-y", true);
-  const paramsBuffer = createParamsBuffer(
-    [
-      { value: n, type: "u32" },
-      { value: c, type: "f32" },
-      { value: s, type: "f32" },
-      { value: incx, type: "u32" },
-      { value: incy, type: "u32" },
-    ],
-    "srot-params",
-  );
+  let xBuffer = null;
+  let yBuffer = null;
+  let paramsBuffer = null;
+  let readX = null;
+  let readY = null;
 
-  const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
-    xBuffer,
-    yBuffer,
-    paramsBuffer,
-  ]);
-  const { commandEncoder, ts } = runComputePass(
-    pipeline,
-    bindGroup,
-    calcWorkgroups(n),
-  );
-  const readX = xIsGpu ? null : stageReadback(commandEncoder, xBuffer);
-  const readY = yIsGpu ? null : stageReadback(commandEncoder, yBuffer);
-  submit(commandEncoder);
+  try {
+    xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "srot-x", true);
+    yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "srot-y", true);
+    paramsBuffer = createParamsBuffer(
+      [
+        { value: n, type: "u32" },
+        { value: c, type: "f32" },
+        { value: s, type: "f32" },
+        { value: incx, type: "u32" },
+        { value: incy, type: "u32" },
+      ],
+      "srot-params",
+    );
 
-  const gpuTimeMs = await extractTimestamp(ts);
+    const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
+      xBuffer,
+      yBuffer,
+      paramsBuffer,
+    ]);
+    const { commandEncoder, ts } = runComputePass(
+      pipeline,
+      bindGroup,
+      calcWorkgroups(n),
+    );
+    readX = xIsGpu ? null : stageReadback(commandEncoder, xBuffer);
+    readY = yIsGpu ? null : stageReadback(commandEncoder, yBuffer);
+    submit(commandEncoder);
 
-  if (xIsGpu && yIsGpu) {
-    destroyBuffers(paramsBuffer);
-    if (gpuTimeMs !== undefined) return { gpuTimeMs };
-    return {};
-  }
+    const gpuTimeMs = await extractTimestamp(ts);
 
-  const [xResult, yResult] = await Promise.all([
-    extractResult(readX, Float32Array),
-    extractResult(readY, Float32Array),
-  ]);
-  destroyBuffers(xBuffer, yBuffer, paramsBuffer, readX, readY);
+    if (xIsGpu && yIsGpu) {
+      if (gpuTimeMs !== undefined) return { gpuTimeMs };
+      return {};
+    }
 
-  if (gpuTimeMs !== undefined) return { x: xResult, y: yResult, gpuTimeMs };
-  return { x: xResult, y: yResult };
+    const xPromise = extractResult(readX, Float32Array);
+    const yPromise = extractResult(readY, Float32Array);
+    readX = null; // ownership transferred — extractResult's own finally destroys it
+    readY = null;
+    const [xResult, yResult] = await Promise.all([xPromise, yPromise]);
+
+    if (gpuTimeMs !== undefined) return { x: xResult, y: yResult, gpuTimeMs };
+    return { x: xResult, y: yResult };
+  } finally {
+    if (!xIsGpu && xBuffer) destroyBuffers(xBuffer);
+    if (!yIsGpu && yBuffer) destroyBuffers(yBuffer);
+    if (paramsBuffer) destroyBuffers(paramsBuffer);
+    // Only reached if extractTimestamp threw before ownership was transferred above.
+    if (readX) destroyBuffers(readX);
+    if (readY) destroyBuffers(readY);
+  }
 }

package/src/srotm/srotm.mjs

@@ -48,47 +48,63 @@ export async function srotm(device, n, x, incx, y, incy, param) {
 
   const pipeline = await getPipeline(device, "srotm");
 
-  const xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "srotm-x", true);
-  const yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "srotm-y", true);
-  const paramBuffer = uploadBuffer(param, "srotm-param", false);
-  const paramsBuffer = createParamsBuffer(
-    [
-      { value: n, type: "u32" },
-      { value: incx, type: "u32" },
-      { value: incy, type: "u32" },
-    ],
-    "srotm-params",
-  );
+  let xBuffer = null;
+  let yBuffer = null;
+  let paramBuffer = null;
+  let paramsBuffer = null;
+  let readX = null;
+  let readY = null;
 
-  const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
-    xBuffer,
-    yBuffer,
-    paramBuffer,
-    paramsBuffer,
-  ]);
-  const { commandEncoder, ts } = runComputePass(
-    pipeline,
-    bindGroup,
-    calcWorkgroups(n),
-  );
-  const readX = xIsGpu ? null : stageReadback(commandEncoder, xBuffer);
-  const readY = yIsGpu ? null : stageReadback(commandEncoder, yBuffer);
-  submit(commandEncoder);
+  try {
+    xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "srotm-x", true);
+    yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "srotm-y", true);
+    paramBuffer = uploadBuffer(param, "srotm-param", false);
+    paramsBuffer = createParamsBuffer(
+      [
+        { value: n, type: "u32" },
+        { value: incx, type: "u32" },
+        { value: incy, type: "u32" },
+      ],
+      "srotm-params",
+    );
 
-  const gpuTimeMs = await extractTimestamp(ts);
+    const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
+      xBuffer,
+      yBuffer,
+      paramBuffer,
+      paramsBuffer,
+    ]);
+    const { commandEncoder, ts } = runComputePass(
+      pipeline,
+      bindGroup,
+      calcWorkgroups(n),
+    );
+    readX = xIsGpu ? null : stageReadback(commandEncoder, xBuffer);
+    readY = yIsGpu ? null : stageReadback(commandEncoder, yBuffer);
+    submit(commandEncoder);
 
-  if (xIsGpu && yIsGpu) {
-    destroyBuffers(paramBuffer, paramsBuffer);
-    if (gpuTimeMs !== undefined) return { gpuTimeMs };
-    return {};
-  }
+    const gpuTimeMs = await extractTimestamp(ts);
 
-  const [xResult, yResult] = await Promise.all([
-    extractResult(readX, Float32Array),
-    extractResult(readY, Float32Array),
-  ]);
-  destroyBuffers(xBuffer, yBuffer, paramBuffer, paramsBuffer, readX, readY);
+    if (xIsGpu && yIsGpu) {
+      if (gpuTimeMs !== undefined) return { gpuTimeMs };
+      return {};
+    }
 
-  if (gpuTimeMs !== undefined) return { x: xResult, y: yResult, gpuTimeMs };
-  return { x: xResult, y: yResult };
+    const xPromise = extractResult(readX, Float32Array);
+    const yPromise = extractResult(readY, Float32Array);
+    readX = null; // ownership transferred — extractResult's own finally destroys it
+    readY = null;
+    const [xResult, yResult] = await Promise.all([xPromise, yPromise]);
+
+    if (gpuTimeMs !== undefined) return { x: xResult, y: yResult, gpuTimeMs };
+    return { x: xResult, y: yResult };
+  } finally {
+    if (!xIsGpu && xBuffer) destroyBuffers(xBuffer);
+    if (!yIsGpu && yBuffer) destroyBuffers(yBuffer);
+    if (paramBuffer) destroyBuffers(paramBuffer);
+    if (paramsBuffer) destroyBuffers(paramsBuffer);
+    // Only reached if extractTimestamp threw before ownership was transferred above.
+    if (readX) destroyBuffers(readX);
+    if (readY) destroyBuffers(readY);
+  }
 }

package/src/sscal/sscal.mjs

@@ -19,8 +19,10 @@ export async function sscal(device, n, alpha, x, incx) {
     throw new Error("device must be a GPUDevice.");
   if (!Number.isInteger(n) || !Number.isInteger(incx))
     throw new Error("n and incx must be integers.");
-  if (isNaN(alpha)) throw new Error("alpha must not be NaN.");
-  if (!isFinite(alpha)) throw new Error("alpha must be finite.");
+  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 (incx <= 0) throw new Error("incx must be positive.");
   if (!(x instanceof Float32Array) && !(x instanceof GpuVector))
     throw new Error("x must be a Float32Array or GpuVector.");
@@ -32,40 +34,49 @@ export async function sscal(device, n, alpha, x, incx) {
 
   const pipeline = await getPipeline(device, "sscal");
 
-  const xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "sscal-x", true);
-  const paramsBuffer = createParamsBuffer(
-    [
-      { value: n, type: "u32" },
-      { value: alpha, type: "f32" },
-      { value: incx, type: "u32" },
-    ],
-    "sscal-params",
-  );
+  let xBuffer = null;
+  let paramsBuffer = null;
+  let readBuffer = null;
 
-  const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
-    xBuffer,
-    paramsBuffer,
-  ]);
-  const { commandEncoder, ts } = runComputePass(
-    pipeline,
-    bindGroup,
-    calcWorkgroups(n),
-  );
-  const readBuffer = xIsGpu ? null : stageReadback(commandEncoder, xBuffer);
+  try {
+    xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "sscal-x", true);
+    paramsBuffer = createParamsBuffer(
+      [
+        { value: n, type: "u32" },
+        { value: alpha, type: "f32" },
+        { value: incx, type: "u32" },
+      ],
+      "sscal-params",
+    );
 
-  submit(commandEncoder);
+    const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
+      xBuffer,
+      paramsBuffer,
+    ]);
+    const { commandEncoder, ts } = runComputePass(
+      pipeline,
+      bindGroup,
+      calcWorkgroups(n),
+    );
+    readBuffer = xIsGpu ? null : stageReadback(commandEncoder, xBuffer);
 
-  const gpuTimeMs = await extractTimestamp(ts);
+    submit(commandEncoder);
 
-  if (xIsGpu) {
-    destroyBuffers(paramsBuffer);
-    if (gpuTimeMs !== undefined) return { gpuTimeMs };
-    return {};
-  }
+    const gpuTimeMs = await extractTimestamp(ts);
 
-  const result = await extractResult(readBuffer, Float32Array);
-  destroyBuffers(xBuffer, paramsBuffer, readBuffer);
+    if (xIsGpu) {
+      if (gpuTimeMs !== undefined) return { gpuTimeMs };
+      return {};
+    }
 
-  if (gpuTimeMs !== undefined) return { result, gpuTimeMs };
-  return result;
+    const result = await extractResult(readBuffer, Float32Array);
+    readBuffer = null; // extractResult already destroyed it
+    if (gpuTimeMs !== undefined) return { x: result, gpuTimeMs };
+    return 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/sswap/sswap.mjs

@@ -46,45 +46,60 @@ export async function sswap(device, n, x, incx, y, incy) {
 
   const pipeline = await getPipeline(device, "sswap");
 
-  const xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "sswap-x", true);
-  const yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "sswap-y", true);
-  const paramsBuffer = createParamsBuffer(
-    [
-      { value: n, type: "u32" },
-      { value: incx, type: "u32" },
-      { value: incy, type: "u32" },
-    ],
-    "sswap-params",
-  );
+  let xBuffer = null;
+  let yBuffer = null;
+  let paramsBuffer = null;
+  let xReadBuffer = null;
+  let yReadBuffer = null;
 
-  const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
-    xBuffer,
-    yBuffer,
-    paramsBuffer,
-  ]);
-  const { commandEncoder, ts } = runComputePass(
-    pipeline,
-    bindGroup,
-    calcWorkgroups(n),
-  );
-  const xReadBuffer = xIsGpu ? null : stageReadback(commandEncoder, xBuffer);
-  const yReadBuffer = yIsGpu ? null : stageReadback(commandEncoder, yBuffer);
+  try {
+    xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "sswap-x", true);
+    yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "sswap-y", true);
+    paramsBuffer = createParamsBuffer(
+      [
+        { value: n, type: "u32" },
+        { value: incx, type: "u32" },
+        { value: incy, type: "u32" },
+      ],
+      "sswap-params",
+    );
 
-  submit(commandEncoder);
+    const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
+      xBuffer,
+      yBuffer,
+      paramsBuffer,
+    ]);
+    const { commandEncoder, ts } = runComputePass(
+      pipeline,
+      bindGroup,
+      calcWorkgroups(n),
+    );
+    xReadBuffer = xIsGpu ? null : stageReadback(commandEncoder, xBuffer);
+    yReadBuffer = yIsGpu ? null : stageReadback(commandEncoder, yBuffer);
 
-  const gpuTimeMs = await extractTimestamp(ts);
+    submit(commandEncoder);
 
-  if (xIsGpu && yIsGpu) {
-    destroyBuffers(paramsBuffer);
-    if (gpuTimeMs !== undefined) return { gpuTimeMs };
-    return {};
-  }
+    const gpuTimeMs = await extractTimestamp(ts);
 
-  const resultX = await extractResult(xReadBuffer, Float32Array);
-  const resultY = await extractResult(yReadBuffer, Float32Array);
+    if (xIsGpu && yIsGpu) {
+      if (gpuTimeMs !== undefined) return { gpuTimeMs };
+      return {};
+    }
 
-  destroyBuffers(xBuffer, xReadBuffer, yBuffer, yReadBuffer, paramsBuffer);
+    const resultX = await extractResult(xReadBuffer, Float32Array);
+    xReadBuffer = null; // extractResult already destroyed it
+    const resultY = await extractResult(yReadBuffer, Float32Array);
+    yReadBuffer = null; // extractResult already destroyed it
 
-  if (gpuTimeMs !== undefined) return { x: resultX, y: resultY, gpuTimeMs };
-  return { x: resultX, y: resultY };
+    if (gpuTimeMs !== undefined) return { x: resultX, y: resultY, gpuTimeMs };
+    return { x: resultX, y: resultY };
+  } finally {
+    if (!xIsGpu && xBuffer) destroyBuffers(xBuffer);
+    if (!yIsGpu && yBuffer) destroyBuffers(yBuffer);
+    if (paramsBuffer) destroyBuffers(paramsBuffer);
+    // Only reached if extractTimestamp or extractResult threw before
+    // clearing these — on the success path they're already null.
+    if (xReadBuffer) destroyBuffers(xReadBuffer);
+    if (yReadBuffer) destroyBuffers(yReadBuffer);
+  }
 }

package/src/ssymv/ssymv.d.mts

@@ -0,0 +1,117 @@
+import { GpuVector } from "../classes/GpuVector.mjs";
+import { GpuMatrix } from "../classes/GpuMatrix.mjs";
+
+/**
+ * Performs the symmetric matrix-vector operation y = alpha * A * x + beta * y
+ *
+ * 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/ssymv/ssymv.js}
+ *
+ * **Browser (standalone HTML):**
+ * {@includeCode ../../examples/ssymv/web/ssymv.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      - Float32Array, 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      - Float32Array 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      - Float32Array 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/ssymv/ssymv.mjs#L15">Source code: ssymv.mjs (L15)</a>
+ * @category BLAS Level 2
+ */
+export declare function ssymv(
+  device: GPUDevice,
+  uplo: 'lower' | 'upper',
+  n: number,
+  alpha: number,
+  A: Float32Array,
+  lda: number,
+  x: Float32Array,
+  incx: number,
+  beta: number,
+  y: Float32Array,
+  incy: number,
+  layout?: 'row-major' | 'column-major',
+): Promise<{ y: Float32Array; gpuTimeMs?: number }>;
+
+/**
+ * Performs the symmetric matrix-vector operation y = alpha * A * x + beta * y
+ *
+ * A is kept GPU-resident; x and y are CPU Float32Arrays. `A`'s own `layout`
+ * (set at `GpuMatrix.from` time) determines the operation — there is no
+ * separate `layout` argument here.
+ *
+ * @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, GPU-resident
+ * @param lda    - leading dimension of A (must equal A.lda)
+ * @param x      - Float32Array input vector
+ * @param incx   - stride for x (must be a positive integer)
+ * @param beta   - scalar multiplier for y
+ * @param y      - Float32Array input/output vector
+ * @param incy   - stride for y (must be a positive integer)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/ssymv/ssymv.mjs#L15">Source code: ssymv.mjs (L15)</a>
+ * @category BLAS Level 2
+ */
+export declare function ssymv(
+  device: GPUDevice,
+  uplo: 'lower' | 'upper',
+  n: number,
+  alpha: number,
+  A: GpuMatrix,
+  lda: number,
+  x: Float32Array,
+  incx: number,
+  beta: number,
+  y: Float32Array,
+  incy: number,
+): Promise<{ y: Float32Array; gpuTimeMs?: number }>;
+
+/**
+ * Performs the symmetric matrix-vector operation y = alpha * A * x + beta * y
+ *
+ * x and y are kept resident on the GPU. A must be a GpuMatrix; its own
+ * `layout` (set at `GpuMatrix.from` time) determines the operation — there is
+ * no separate `layout` argument here.
+ *
+ * {@includeCode ../../examples/ssymv/gpuvec.ssymv.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, GPU-resident
+ * @param lda    - leading dimension of A (must equal A.lda)
+ * @param x      - GpuVector input vector (not mutated)
+ * @param incx   - stride for x (must be a positive integer)
+ * @param beta   - scalar multiplier for y
+ * @param y      - GpuVector input/output vector (mutated in place)
+ * @param incy   - stride for y (must be a positive integer)
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/ssymv/ssymv.mjs#L15">Source code: ssymv.mjs (L15)</a>
+ * @category BLAS Level 2
+ */
+export declare function ssymv(
+  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/ssymv/ssymv.mjs

@@ -0,0 +1,135 @@
+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";
+
+export async function ssymv(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;
+
+  if (!(device instanceof GPUDevice))
+    throw new Error("device must be a GPUDevice.");
+  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 Float32Array))
+    throw new Error("A must be a Float32Array or GpuMatrix.");
+  if (!xIsGpu && !(x instanceof Float32Array))
+    throw new Error("x must be a Float32Array or GpuVector.");
+  if (!yIsGpu && !(y instanceof Float32Array))
+    throw new Error("y must be a Float32Array or GpuVector.");
+  if (xIsGpu !== yIsGpu)
+    throw new Error(
+      "x and y must be the same type (both Float32Array or both GpuVector).",
+    );
+  if (xIsGpu && !AIsGpu)
+    throw new Error("A must be a GpuMatrix when x and y are GpuVectors.");
+  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 && 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 pipeline = await getPipeline(device, "ssymv");
+
+  let ABuffer = null;
+  let xBuffer = null;
+  let yBuffer = null;
+  let paramsBuffer = null;
+
+  try {
+    ABuffer = AIsGpu ? A._buf : uploadBuffer(A, "ssymv-A", false);
+    xBuffer = xIsGpu ? x._buf : uploadBuffer(x, "ssymv-x", false);
+    yBuffer = yIsGpu ? y._buf : uploadBuffer(y, "ssymv-y", true);
+    paramsBuffer = createParamsBuffer(
+      [
+        { value: n,               type: "u32" },
+        { value: alpha,           type: "f32" },
+        { value: beta,            type: "f32" },
+        { value: incx,            type: "u32" },
+        { value: incy,            type: "u32" },
+        { value: lda,             type: "u32" },
+        { value: isLower ? 0 : 1, type: "u32" },
+      ],
+      "ssymv-params",
+    );
+
+    const bindGroup = createBindGroup(pipeline.getBindGroupLayout(0), [
+      ABuffer,
+      xBuffer,
+      yBuffer,
+      paramsBuffer,
+    ]);
+
+    const wgCount = Math.min(n, device.limits.maxComputeWorkgroupsPerDimension);
+    const { commandEncoder, ts } = runComputePass(pipeline, bindGroup, wgCount);
+    const readBuffer = yIsGpu ? null : stageReadback(commandEncoder, yBuffer);
+
+    submit(commandEncoder);
+
+    const gpuTimeMs = await extractTimestamp(ts);
+
+    if (yIsGpu) {
+      if (gpuTimeMs !== undefined) return { gpuTimeMs };
+      return {};
+    }
+
+    const result = await extractResult(readBuffer, Float32Array);
+    if (gpuTimeMs !== undefined) return { y: result, gpuTimeMs };
+    return { y: result };
+  } finally {
+    if (!AIsGpu && ABuffer) destroyBuffers(ABuffer);
+    if (!xIsGpu && xBuffer) destroyBuffers(xBuffer);
+    if (!yIsGpu && yBuffer) destroyBuffers(yBuffer);
+    if (paramsBuffer) destroyBuffers(paramsBuffer);
+  }
+}