@simulatte/doppler 0.1.9 → 0.2.0

package/src/debug/stats.js

@@ -1,160 +0,0 @@
-export function percentile(sorted, p) {
-  if (!sorted.length) return 0;
-  if (sorted.length === 1) return sorted[0];
-  const idx = (p / 100) * (sorted.length - 1);
-  const lo = Math.floor(idx);
-  const hi = Math.ceil(idx);
-  if (lo === hi) return sorted[lo];
-  return sorted[lo] + (sorted[hi] - sorted[lo]) * (idx - lo);
-}
-
-export function median(sorted) {
-  if (!sorted.length) return 0;
-  const mid = Math.floor(sorted.length / 2);
-  return sorted.length % 2 === 0
-    ? (sorted[mid - 1] + sorted[mid]) / 2
-    : sorted[mid];
-}
-
-export function removeOutliersIQR(values, multiplier = 1.5) {
-  if (values.length < 4) return { filtered: values, removed: 0, lower: -Infinity, upper: Infinity };
-  const sorted = [...values].sort((a, b) => a - b);
-  const q1 = percentile(sorted, 25);
-  const q3 = percentile(sorted, 75);
-  const iqr = q3 - q1;
-  const lower = q1 - multiplier * iqr;
-  const upper = q3 + multiplier * iqr;
-  const filtered = values.filter((v) => v >= lower && v <= upper);
-  return { filtered, removed: values.length - filtered.length, lower, upper };
-}
-
-export function sampleStdDev(values, meanValue) {
-  const n = values.length;
-  if (n < 2) return 0;
-  const variance = values.reduce((sum, v) => sum + (v - meanValue) ** 2, 0) / (n - 1);
-  return Math.sqrt(variance);
-}
-
-export function confidenceInterval95(stdDev, n) {
-  if (n < 2) return 0;
-  const tValue = n >= 30 ? 1.96 : 2.0 + 3.0 / n;
-  return tValue * (stdDev / Math.sqrt(n));
-}
-
-export function computeSampleStats(values, options = {}) {
-  const { outlierIqrMultiplier = 1.5 } = options;
-  const rawValues = Array.isArray(values) ? values : [];
-  const finiteValues = rawValues.filter((value) => Number.isFinite(value));
-  const { filtered, removed } = removeOutliersIQR(finiteValues, outlierIqrMultiplier);
-  const nonFiniteRemoved = rawValues.length - finiteValues.length;
-  const sorted = [...filtered].sort((a, b) => a - b);
-  const n = sorted.length;
-  const totalRemoved = removed + nonFiniteRemoved;
-
-  if (n === 0) {
-    return {
-      mean: 0,
-      median: 0,
-      min: 0,
-      max: 0,
-      p95: 0,
-      p99: 0,
-      stdDev: 0,
-      ci95: 0,
-      samples: rawValues.length,
-      samplesAfterOutlierRemoval: 0,
-      outliersRemoved: totalRemoved,
-    };
-  }
-
-  const meanValue = filtered.reduce((a, b) => a + b, 0) / n;
-  const stdDev = sampleStdDev(filtered, meanValue);
-
-  return {
-    mean: meanValue,
-    median: median(sorted),
-    min: sorted[0],
-    max: sorted[n - 1],
-    p95: percentile(sorted, 95),
-    p99: percentile(sorted, 99),
-    stdDev,
-    ci95: confidenceInterval95(stdDev, n),
-    samples: rawValues.length,
-    samplesAfterOutlierRemoval: n,
-    outliersRemoved: totalRemoved,
-  };
-}
-
-export function computeArrayStats(values, limit = values.length) {
-  const stats = {
-    min: Infinity,
-    max: -Infinity,
-    mean: 0,
-    std: 0,
-    maxAbs: 0,
-    nanCount: 0,
-    infCount: 0,
-    zeroCount: 0,
-    validCount: 0,
-  };
-
-  let sum = 0;
-  let sumSq = 0;
-  const count = Math.min(values.length, limit);
-
-  for (let i = 0; i < count; i++) {
-    const v = values[i];
-    if (Number.isNaN(v)) {
-      stats.nanCount++;
-      continue;
-    }
-    if (!Number.isFinite(v)) {
-      stats.infCount++;
-      continue;
-    }
-    if (v === 0) stats.zeroCount++;
-    stats.min = Math.min(stats.min, v);
-    stats.max = Math.max(stats.max, v);
-    sum += v;
-    sumSq += v * v;
-    stats.validCount++;
-  }
-
-  if (stats.validCount > 0) {
-    stats.mean = sum / stats.validCount;
-    const variance = sumSq / stats.validCount - stats.mean * stats.mean;
-    stats.std = Math.sqrt(Math.max(0, variance));
-    stats.maxAbs = Math.max(Math.abs(stats.min), Math.abs(stats.max));
-  } else {
-    stats.min = 0;
-    stats.max = 0;
-    stats.maxAbs = 0;
-  }
-
-  return stats;
-}
-
-export function computeBasicStats(values) {
-  const count = values.length;
-  if (!count) {
-    return { mean: 0, min: 0, max: 0, total: 0, count: 0 };
-  }
-
-  let min = Infinity;
-  let max = -Infinity;
-  let total = 0;
-
-  for (const v of values) {
-    min = Math.min(min, v);
-    max = Math.max(max, v);
-    total += v;
-  }
-
-  return {
-    mean: total / count,
-    min,
-    max,
-    total,
-    count,
-  };
-}

package/src/debug/tensor.d.ts

@@ -1,125 +0,0 @@
-/**
- * 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 {
-  ok: boolean;
-  error: string | null;
-  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

@@ -1,268 +0,0 @@
-
-
-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
-      || typeof gpuDevice.createBuffer !== 'function'
-      || typeof gpuDevice.createCommandEncoder !== 'function'
-      || !gpuDevice.queue
-      || typeof gpuDevice.queue.submit !== 'function'
-    ) {
-      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 (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return {
-      ok: false,
-      error: message,
-      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 {
-    ok: true,
-    error: null,
-    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

@@ -1,17 +0,0 @@
-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;