@simulatte/doppler 0.1.0

package/src/debug/tensor.d.ts

@@ -0,0 +1,123 @@
+/**
+ * DOPPLER Debug Module - Tensor Inspection Utilities
+ *
+ * Tools for inspecting GPU and CPU tensors, checking health, and comparing values.
+ *
+ * @module debug/tensor
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Tensor statistics
+ */
+export interface TensorStats {
+  label: string;
+  shape: number[];
+  size: number;
+  isGPU: boolean;
+  min: number;
+  max: number;
+  mean: number;
+  std: number;
+  nanCount: number;
+  infCount: number;
+  zeroCount: number;
+  zeroPercent: string;
+  first: string[];
+  last: string[];
+}
+
+/**
+ * Tensor comparison result
+ */
+export interface TensorCompareResult {
+  label: string;
+  match: boolean;
+  maxDiff: number;
+  maxDiffIdx: number;
+  avgDiff: number;
+  mismatchCount: number;
+  mismatchPercent: string;
+  error?: string;
+}
+
+/**
+ * Tensor health check result
+ */
+export interface TensorHealthResult {
+  label: string;
+  healthy: boolean;
+  issues: string[];
+}
+
+/**
+ * Tensor inspect options
+ */
+export interface TensorInspectOptions {
+  shape?: number[];
+  maxPrint?: number;
+  checkNaN?: boolean;
+}
+
+export interface TensorSnapshot {
+  shape: number[];
+  dtype: string;
+  stats: {
+    min: number;
+    max: number;
+    maxAbs: number;
+    mean: number;
+    std: number;
+  };
+  sample: number[];
+  hasNaN: boolean;
+  hasInf: boolean;
+}
+
+// ============================================================================
+// Tensor Inspection Interface
+// ============================================================================
+
+/**
+ * Tensor inspection utilities.
+ */
+export declare const tensor: {
+  /**
+   * Inspect a GPU or CPU tensor and log statistics.
+   */
+  inspect(
+    buffer: GPUBuffer | Float32Array | Float64Array | Uint16Array,
+    label: string,
+    options?: TensorInspectOptions
+  ): Promise<TensorStats | null>;
+
+  /**
+   * Compare two tensors element-wise.
+   */
+  compare(
+    a: Float32Array,
+    b: Float32Array,
+    label: string,
+    tolerance?: number
+  ): TensorCompareResult;
+
+  /**
+   * Check tensor for common issues.
+   */
+  healthCheck(data: Float32Array, label: string): TensorHealthResult;
+};
+
+export declare function snapshotTensor(
+  buffer: GPUBuffer,
+  shape?: number[],
+  dtype?: string
+): Promise<TensorSnapshot>;
+
+export declare function snapshotFromArray(
+  arr: Float32Array,
+  shape: number[],
+  dtype?: string
+): TensorSnapshot;

package/src/debug/tensor.js

@@ -0,0 +1,257 @@
+
+
+import { gpuDevice } from './config.js';
+import { log } from './log.js';
+import { computeArrayStats } from './stats.js';
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+
+function f16ToF32(h) {
+  const sign = (h >> 15) & 0x1;
+  const exp = (h >> 10) & 0x1f;
+  const mant = h & 0x3ff;
+
+  if (exp === 0) {
+    return (sign ? -1 : 1) * Math.pow(2, -14) * (mant / 1024);
+  } else if (exp === 31) {
+    return mant === 0 ? (sign ? -Infinity : Infinity) : NaN;
+  }
+
+  return (sign ? -1 : 1) * Math.pow(2, exp - 15) * (1 + mant / 1024);
+}
+
+// ============================================================================
+// Tensor Inspection Interface
+// ============================================================================
+
+
+export const tensor = {
+  
+  async inspect(
+    buffer,
+    label,
+    options = {}
+  ) {
+    const { shape = [], maxPrint = 8, checkNaN = true } = options;
+
+    let data;
+    let isGPU = false;
+
+    // Handle GPU buffers
+    if (buffer && typeof buffer.mapAsync === 'function') {
+      const gpuBuffer = buffer;
+      await gpuBuffer.mapAsync(GPUMapMode.READ);
+      data = new Float32Array(gpuBuffer.getMappedRange().slice(0));
+      gpuBuffer.unmap();
+    } else if (buffer && buffer.size !== undefined && gpuDevice) {
+      isGPU = true;
+      const gpuBuffer = buffer;
+      const readSize = Math.min(gpuBuffer.size, 4096);
+      const staging = gpuDevice.createBuffer({
+        label: `debug_staging_${label}`,
+        size: readSize,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+      });
+
+      const encoder = gpuDevice.createCommandEncoder();
+      encoder.copyBufferToBuffer(gpuBuffer, 0, staging, 0, readSize);
+      gpuDevice.queue.submit([encoder.finish()]);
+
+      await staging.mapAsync(GPUMapMode.READ);
+      data = new Float32Array(staging.getMappedRange().slice(0));
+      staging.unmap();
+      staging.destroy();
+    } else if (buffer instanceof Float32Array || buffer instanceof Float64Array) {
+      data = buffer instanceof Float32Array ? buffer : new Float32Array(buffer);
+    } else if (buffer instanceof Uint16Array) {
+      data = new Float32Array(buffer.length);
+      for (let i = 0; i < buffer.length; i++) {
+        data[i] = f16ToF32(buffer[i]);
+      }
+    } else {
+      log.warn('Debug', `Cannot inspect tensor "${label}": unknown type`);
+      return null;
+    }
+
+    const statsSummary = computeArrayStats(data);
+
+    const stats = {
+      label,
+      shape,
+      size: data.length,
+      isGPU,
+      min: statsSummary.min,
+      max: statsSummary.max,
+      mean: statsSummary.mean,
+      std: statsSummary.std,
+      nanCount: statsSummary.nanCount,
+      infCount: statsSummary.infCount,
+      zeroCount: statsSummary.zeroCount,
+      zeroPercent: ((statsSummary.zeroCount / data.length) * 100).toFixed(1),
+      first: Array.from(data.slice(0, maxPrint)).map((v) => v.toFixed(4)),
+      last: Array.from(data.slice(-maxPrint)).map((v) => v.toFixed(4)),
+    };
+
+    const shapeStr = shape.length > 0 ? `[${shape.join('x')}]` : `[${data.length}]`;
+    log.debug(
+      'Tensor',
+      `${label} ${shapeStr}: min=${statsSummary.min.toFixed(4)}, max=${statsSummary.max.toFixed(4)}, mean=${statsSummary.mean.toFixed(4)}, std=${statsSummary.std.toFixed(4)}`
+    );
+
+    if (checkNaN && (statsSummary.nanCount > 0 || statsSummary.infCount > 0)) {
+      log.warn('Tensor', `${label} has ${statsSummary.nanCount} NaN and ${statsSummary.infCount} Inf values!`);
+    }
+
+    return stats;
+  },
+
+  
+  compare(
+    a,
+    b,
+    label,
+    tolerance = 1e-5
+  ) {
+    if (a.length !== b.length) {
+      log.error('Tensor', `${label}: size mismatch ${a.length} vs ${b.length}`);
+      return { label, match: false, error: 'size_mismatch', maxDiff: 0, maxDiffIdx: 0, avgDiff: 0, mismatchCount: 0, mismatchPercent: '0' };
+    }
+
+    let maxDiff = 0,
+      maxDiffIdx = 0;
+    let sumDiff = 0;
+    let mismatchCount = 0;
+
+    for (let i = 0; i < a.length; i++) {
+      const diff = Math.abs(a[i] - b[i]);
+      sumDiff += diff;
+      if (diff > maxDiff) {
+        maxDiff = diff;
+        maxDiffIdx = i;
+      }
+      if (diff > tolerance) {
+        mismatchCount++;
+      }
+    }
+
+    const avgDiff = sumDiff / a.length;
+    const match = mismatchCount === 0;
+
+    const result = {
+      label,
+      match,
+      maxDiff,
+      maxDiffIdx,
+      avgDiff,
+      mismatchCount,
+      mismatchPercent: ((mismatchCount / a.length) * 100).toFixed(2),
+    };
+
+    if (match) {
+      log.debug('Tensor', `${label}: MATCH (maxDiff=${maxDiff.toExponential(2)})`);
+    } else {
+      log.warn(
+        'Tensor',
+        `${label}: MISMATCH ${mismatchCount}/${a.length} (${result.mismatchPercent}%) maxDiff=${maxDiff.toFixed(6)} at idx=${maxDiffIdx}`
+      );
+    }
+
+    return result;
+  },
+
+  
+  healthCheck(data, label) {
+    const issues = [];
+
+    const allZero = data.every((v) => v === 0);
+    if (allZero) {
+      issues.push('ALL_ZEROS');
+    }
+
+    const hasNaN = data.some((v) => Number.isNaN(v));
+    const hasInf = data.some((v) => !Number.isFinite(v) && !Number.isNaN(v));
+    if (hasNaN) issues.push('HAS_NAN');
+    if (hasInf) issues.push('HAS_INF');
+
+    let maxAbs = 0;
+    for (let i = 0; i < data.length; i++) {
+      const abs = Math.abs(data[i]);
+      if (Number.isFinite(abs) && abs > maxAbs) maxAbs = abs;
+    }
+    if (maxAbs > 1e6) issues.push(`EXTREME_VALUES (max=${maxAbs.toExponential(2)})`);
+
+    const tinyCount = data.filter((v) => Math.abs(v) > 0 && Math.abs(v) < 1e-30).length;
+    if (tinyCount > data.length * 0.1) {
+      issues.push(`POTENTIAL_UNDERFLOW (${tinyCount} tiny values)`);
+    }
+
+    const healthy = issues.length === 0;
+
+    if (healthy) {
+      log.debug('Tensor', `${label}: healthy`);
+    } else {
+      log.warn('Tensor', `${label}: issues found - ${issues.join(', ')}`);
+    }
+
+    return { label, healthy, issues };
+  },
+};
+
+export async function snapshotTensor(buffer, shape, dtype = 'f32') {
+  try {
+    if (!gpuDevice) {
+      throw new Error('GPU device not initialized');
+    }
+    const elementSize = dtype === 'f16' ? 2 : 4;
+    const numElements = (shape ?? []).reduce((a, b) => a * b, 1);
+    const readSize = numElements > 0
+      ? Math.min(buffer.size, numElements * elementSize)
+      : buffer.size;
+    const staging = gpuDevice.createBuffer({
+      label: 'debug_snapshot_staging',
+      size: readSize,
+      usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+    });
+    const encoder = gpuDevice.createCommandEncoder();
+    encoder.copyBufferToBuffer(buffer, 0, staging, 0, readSize);
+    gpuDevice.queue.submit([encoder.finish()]);
+    await staging.mapAsync(GPUMapMode.READ);
+    const data = staging.getMappedRange().slice(0);
+    staging.unmap();
+    staging.destroy();
+    const arr = new Float32Array(data);
+    return snapshotFromArray(arr, shape ?? [arr.length], dtype);
+  } catch {
+    return {
+      shape: shape ?? [0],
+      dtype,
+      stats: { min: 0, max: 0, maxAbs: 0, mean: 0, std: 0 },
+      sample: [],
+      hasNaN: false,
+      hasInf: false,
+    };
+  }
+}
+
+export function snapshotFromArray(arr, shape, dtype = 'f32') {
+  const numElements = shape.reduce((a, b) => a * b, 1);
+  const stats = computeArrayStats(arr, Math.min(arr.length, numElements));
+
+  return {
+    shape,
+    dtype,
+    stats: {
+      min: stats.min,
+      max: stats.max,
+      maxAbs: stats.maxAbs,
+      mean: stats.mean,
+      std: stats.std,
+    },
+    sample: Array.from(arr.slice(0, 8)),
+    hasNaN: stats.nanCount > 0,
+    hasInf: stats.infCount > 0,
+  };
+}

package/src/debug/trace.d.ts

@@ -0,0 +1,17 @@
+import type { TraceCategory } from './config.js';
+
+export interface TraceInterface {
+  loader(message: string, data?: unknown): void;
+  kernels(message: string, data?: unknown): void;
+  logits(message: string, data?: unknown): void;
+  embed(message: string, data?: unknown): void;
+  attn(layerIdx: number, message: string, data?: unknown): void;
+  ffn(layerIdx: number, message: string, data?: unknown): void;
+  kv(layerIdx: number, message: string, data?: unknown): void;
+  sample(message: string, data?: unknown): void;
+  buffers(message: string, data?: unknown): void;
+  perf(message: string, data?: unknown): void;
+  energy(message: string, data?: unknown): void;
+}
+
+export const trace: TraceInterface;

package/src/debug/trace.js

@@ -0,0 +1,167 @@
+import {
+  enabledTraceCategories,
+  traceLayerFilter,
+  traceDecodeStep,
+  traceMaxDecodeSteps,
+  logHistory,
+  getLogHistoryLimit,
+} from './config.js';
+
+function isEnabled(category, layerIdx) {
+  if (!enabledTraceCategories.has(category)) return false;
+
+  if (layerIdx !== undefined && traceLayerFilter.length > 0) {
+    if (!traceLayerFilter.includes(layerIdx)) return false;
+  }
+
+  if (traceMaxDecodeSteps > 0 && traceDecodeStep > traceMaxDecodeSteps) {
+    return false;
+  }
+
+  return true;
+}
+
+function formatTraceMessage(category, message, layerIdx) {
+  const timestamp = performance.now().toFixed(1);
+  const layerTag = layerIdx !== undefined ? `L${layerIdx}:` : '';
+  return `[${timestamp}ms][TRACE:${category}] ${layerTag}${message}`;
+}
+
+function storeTrace(category, module, message, data) {
+  logHistory.push({
+    time: Date.now(),
+    perfTime: performance.now(),
+    level: `TRACE:${category}`,
+    module,
+    message,
+    data,
+  });
+
+  const maxHistory = getLogHistoryLimit();
+  if (logHistory.length > maxHistory) {
+    logHistory.shift();
+  }
+}
+
+export const trace = {
+  loader(message, data) {
+    if (!isEnabled('loader')) return;
+    const formatted = formatTraceMessage('loader', message);
+    storeTrace('loader', 'Loader', message, data);
+    if (data !== undefined) {
+      console.log(formatted, data);
+    } else {
+      console.log(formatted);
+    }
+  },
+
+  kernels(message, data) {
+    if (!isEnabled('kernels')) return;
+    const formatted = formatTraceMessage('kernels', message);
+    storeTrace('kernels', 'Kernels', message, data);
+    if (data !== undefined) {
+      console.log(formatted, data);
+    } else {
+      console.log(formatted);
+    }
+  },
+
+  logits(message, data) {
+    if (!isEnabled('logits')) return;
+    const formatted = formatTraceMessage('logits', message);
+    storeTrace('logits', 'Logits', message, data);
+    if (data !== undefined) {
+      console.log(formatted, data);
+    } else {
+      console.log(formatted);
+    }
+  },
+
+  embed(message, data) {
+    if (!isEnabled('embed')) return;
+    const formatted = formatTraceMessage('embed', message);
+    storeTrace('embed', 'Embed', message, data);
+    if (data !== undefined) {
+      console.log(formatted, data);
+    } else {
+      console.log(formatted);
+    }
+  },
+
+  attn(layerIdx, message, data) {
+    if (!isEnabled('attn', layerIdx)) return;
+    const formatted = formatTraceMessage('attn', message, layerIdx);
+    storeTrace('attn', `Attn:L${layerIdx}`, message, data);
+    if (data !== undefined) {
+      console.log(formatted, data);
+    } else {
+      console.log(formatted);
+    }
+  },
+
+  ffn(layerIdx, message, data) {
+    if (!isEnabled('ffn', layerIdx)) return;
+    const formatted = formatTraceMessage('ffn', message, layerIdx);
+    storeTrace('ffn', `FFN:L${layerIdx}`, message, data);
+    if (data !== undefined) {
+      console.log(formatted, data);
+    } else {
+      console.log(formatted);
+    }
+  },
+
+  kv(layerIdx, message, data) {
+    if (!isEnabled('kv', layerIdx)) return;
+    const formatted = formatTraceMessage('kv', message, layerIdx);
+    storeTrace('kv', `KV:L${layerIdx}`, message, data);
+    if (data !== undefined) {
+      console.log(formatted, data);
+    } else {
+      console.log(formatted);
+    }
+  },
+
+  sample(message, data) {
+    if (!isEnabled('sample')) return;
+    const formatted = formatTraceMessage('sample', message);
+    storeTrace('sample', 'Sample', message, data);
+    if (data !== undefined) {
+      console.log(formatted, data);
+    } else {
+      console.log(formatted);
+    }
+  },
+
+  buffers(message, data) {
+    if (!isEnabled('buffers')) return;
+    const formatted = formatTraceMessage('buffers', message);
+    storeTrace('buffers', 'Buffers', message, data);
+    if (data !== undefined) {
+      console.log(formatted, data);
+    } else {
+      console.log(formatted);
+    }
+  },
+
+  perf(message, data) {
+    if (!isEnabled('perf')) return;
+    const formatted = formatTraceMessage('perf', message);
+    storeTrace('perf', 'Perf', message, data);
+    if (data !== undefined) {
+      console.log(formatted, data);
+    } else {
+      console.log(formatted);
+    }
+  },
+
+  energy(message, data) {
+    if (!isEnabled('energy')) return;
+    const formatted = formatTraceMessage('energy', message);
+    storeTrace('energy', 'Energy', message, data);
+    if (data !== undefined) {
+      console.log(formatted, data);
+    } else {
+      console.log(formatted);
+    }
+  },
+};

package/src/diffusion/image-regression.d.ts

@@ -0,0 +1,31 @@
+export interface DiffusionImageRegressionMetrics {
+  samples: number;
+  mae: number;
+  mse: number;
+  rmse: number;
+  maxAbsDiff: number;
+  psnr: number;
+}
+
+export interface DiffusionImageRegressionTolerance {
+  maxAbsDiff?: number;
+  mae?: number;
+  rmse?: number;
+  minPsnr?: number;
+}
+
+export declare function computeImageFingerprint(
+  pixels: Uint8Array | Uint8ClampedArray
+): string;
+
+export declare function computeImageRegressionMetrics(
+  actualPixels: Uint8Array | Uint8ClampedArray,
+  expectedPixels: Uint8Array | Uint8ClampedArray
+): DiffusionImageRegressionMetrics;
+
+export declare function assertImageRegressionWithinTolerance(
+  actualPixels: Uint8Array | Uint8ClampedArray,
+  expectedPixels: Uint8Array | Uint8ClampedArray,
+  tolerance?: DiffusionImageRegressionTolerance,
+  contextLabel?: string
+): DiffusionImageRegressionMetrics;

package/src/diffusion/image-regression.js

@@ -0,0 +1,107 @@
+function toUint8ArrayView(value, label) {
+  if (value instanceof Uint8ClampedArray) {
+    return value;
+  }
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  throw new Error(`${label} must be a Uint8Array or Uint8ClampedArray.`);
+}
+
+function toToleranceValue(value, fallback) {
+  return Number.isFinite(value) ? Number(value) : fallback;
+}
+
+export function computeImageFingerprint(pixels) {
+  const view = toUint8ArrayView(pixels, 'pixels');
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < view.length; i += 1) {
+    hash ^= view[i];
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, '0');
+}
+
+export function computeImageRegressionMetrics(actualPixels, expectedPixels) {
+  const actual = toUint8ArrayView(actualPixels, 'actualPixels');
+  const expected = toUint8ArrayView(expectedPixels, 'expectedPixels');
+  if (actual.length !== expected.length) {
+    throw new Error(
+      `Image regression requires equal-length buffers: actual=${actual.length}, expected=${expected.length}.`
+    );
+  }
+
+  const count = actual.length;
+  if (count === 0) {
+    return {
+      samples: 0,
+      mae: 0,
+      mse: 0,
+      rmse: 0,
+      maxAbsDiff: 0,
+      psnr: Infinity,
+    };
+  }
+
+  let sumAbs = 0;
+  let sumSq = 0;
+  let maxAbsDiff = 0;
+  for (let i = 0; i < count; i += 1) {
+    const diff = Math.abs(actual[i] - expected[i]);
+    sumAbs += diff;
+    sumSq += diff * diff;
+    if (diff > maxAbsDiff) {
+      maxAbsDiff = diff;
+    }
+  }
+
+  const mae = sumAbs / count;
+  const mse = sumSq / count;
+  const rmse = Math.sqrt(mse);
+  const psnr = rmse === 0 ? Infinity : (20 * Math.log10(255 / rmse));
+
+  return {
+    samples: count,
+    mae,
+    mse,
+    rmse,
+    maxAbsDiff,
+    psnr,
+  };
+}
+
+export function assertImageRegressionWithinTolerance(
+  actualPixels,
+  expectedPixels,
+  tolerance = {},
+  contextLabel = 'image-regression'
+) {
+  const metrics = computeImageRegressionMetrics(actualPixels, expectedPixels);
+  const maxAbsDiffLimit = toToleranceValue(tolerance.maxAbsDiff, 0);
+  const maeLimit = toToleranceValue(tolerance.mae, 0);
+  const rmseLimit = toToleranceValue(tolerance.rmse, 0);
+  const minPsnr = toToleranceValue(tolerance.minPsnr, Infinity);
+
+  if (metrics.maxAbsDiff > maxAbsDiffLimit) {
+    throw new Error(
+      `${contextLabel}: maxAbsDiff=${metrics.maxAbsDiff.toFixed(6)} exceeded limit=${maxAbsDiffLimit}.`
+    );
+  }
+  if (metrics.mae > maeLimit) {
+    throw new Error(
+      `${contextLabel}: mae=${metrics.mae.toFixed(6)} exceeded limit=${maeLimit}.`
+    );
+  }
+  if (metrics.rmse > rmseLimit) {
+    throw new Error(
+      `${contextLabel}: rmse=${metrics.rmse.toFixed(6)} exceeded limit=${rmseLimit}.`
+    );
+  }
+  if (Number.isFinite(minPsnr) && metrics.psnr < minPsnr) {
+    throw new Error(
+      `${contextLabel}: psnr=${metrics.psnr.toFixed(6)} was below minimum=${minPsnr}.`
+    );
+  }
+
+  return metrics;
+}

package/src/diffusion/index.d.ts

@@ -0,0 +1,8 @@
+export { DiffusionPipeline, createDiffusionPipeline } from '../inference/pipelines/diffusion/pipeline.js';
+export { createDiffusionWeightLoader } from '../inference/pipelines/diffusion/weights.js';
+export { mergeDiffusionConfig, initializeDiffusion } from '../inference/pipelines/diffusion/init.js';
+export {
+  computeImageFingerprint,
+  computeImageRegressionMetrics,
+  assertImageRegressionWithinTolerance,
+} from './image-regression.js';