Utilities API

Helper functions and benchmarking tools.

---

Benchmark

Performance measurement utilities.

Constructor

constructor(context: GPUContext)

Create a new Benchmark instance.

---

Methods

measureOperation

async measureOperation(
  operation: () => Promise<Tensor>,
  warmup?: number
): Promise<number>

Measure the execution time of a single operation.

Parameters:

• operation: Async function returning a tensor
• warmup: Number of warmup runs (default: 1)

Returns: Execution time in milliseconds

Example:

const bench = new Benchmark(context);
const time = await bench.measureOperation(async () => {
  return await conv2d.forward([input, weights], params);
});
console.log(`Operation took ${time}ms`);

---

measureRepeated

async measureRepeated(
  operation: () => Promise<Tensor>,
  iterations: number,
  warmup?: number
): Promise<BenchmarkResult>

Measure execution time over multiple runs.

Returns:

interface BenchmarkResult {
  avg: number;    // Average time (ms)
  min: number;    // Minimum time (ms)
  max: number;    // Maximum time (ms)
  std: number;    // Standard deviation (ms)
  times: number[]; // All measurements
}

Example:

const result = await bench.measureRepeated(
  async () => await conv2d.forward([input, weights], params),
  100
);
console.log(`Average: ${result.avg}ms (±${result.std}ms)`);

---

compareOperations

async compareOperations(
  operations: { name: string; fn: () => Promise<Tensor> }[],
  iterations: number
): Promise<ComparisonResult[]>

Compare performance of multiple operations.

Example:

const results = await bench.compareOperations([
  { 
    name: 'Sequential', 
    fn: async () => {
      const c = await conv2d.forward([input, weights], params);
      const b = await bias.add(c, biasTensor);
      return await relu.forward([b], params);
    }
  },
  { 
    name: 'Fused', 
    fn: async () => await fused.forward([input, weights, bias], params)
  }
], 100);

// Results show relative speedup

---

Reference Implementations

CPU reference implementations for testing and validation.

conv2dCPU

function conv2dCPU(
  input: Float32Array,
  weights: Float32Array,
  inputShape: [number, number, number, number],
  kernelShape: [number, number, number, number],
  stride: [number, number],
  padding: [number, number]
): Float32Array

CPU convolution implementation.

---

reluCPU

function reluCPU(input: Float32Array): Float32Array

CPU ReLU implementation.

---

softmaxCPU

function softmaxCPU(input: Float32Array): Float32Array

CPU softmax implementation.

---

maxPool2dCPU

function maxPool2dCPU(
  input: Float32Array,
  shape: [number, number, number, number],
  poolSize: [number, number],
  stride: [number, number]
): Float32Array

CPU max pooling implementation.

---

denseCPU

function denseCPU(
  input: Float32Array,
  weights: Float32Array,
  bias: Float32Array,
  inputSize: number,
  outputSize: number
): Float32Array

CPU dense layer implementation.

---

Im2Col Utilities

Convolution optimization utilities.

im2col

function im2col(
  input: Float32Array,
  inputShape: [number, number, number, number],
  kernelSize: [number, number],
  stride: [number, number],
  padding: [number, number]
): Float32Array

Transform input for GEMM-based convolution.

---

col2im

function col2im(
  col: Float32Array,
  outputShape: [number, number, number, number],
  kernelSize: [number, number],
  stride: [number, number],
  padding: [number, number]
): Float32Array

Reverse im2col transformation.

---

Error Classes

WebGPUNotSupportedError

class WebGPUNotSupportedError extends Error {
  constructor(message?: string);
}

Thrown when WebGPU is not available in the browser.

---

DeviceInitializationError

class DeviceInitializationError extends Error {
  constructor(message?: string);
}

Thrown when GPU device initialization fails.

---

InvalidShapeError

class InvalidShapeError extends Error {
  constructor(message?: string);
}

Thrown when tensor shapes are incompatible.

---

BufferSizeError

class BufferSizeError extends Error {
  constructor(message?: string);
}

Thrown when buffer sizes don't match expected dimensions.