@simulatte/doppler 0.1.9 → 0.2.0

package/src/gpu/profiler.d.ts

@@ -1,114 +0,0 @@
-/**
- * GPU Profiler - Timestamp-based Performance Profiling
- *
- * Provides GPU-side timing using WebGPU timestamp queries.
- * Falls back to CPU timing when timestamp queries unavailable.
- */
-
-/**
- * Profiling result for a single label
- */
-export interface ProfileResult {
-  /** Average time in milliseconds */
-  avg: number;
-  /** Minimum time in milliseconds */
-  min: number;
-  /** Maximum time in milliseconds */
-  max: number;
-  /** Number of samples */
-  count: number;
-  /** Total time in milliseconds */
-  total: number;
-}
-
-/**
- * GPU Profiler using timestamp queries
- */
-export declare class GPUProfiler {
-  /**
-   * @param device - WebGPU device (uses global if not provided)
-   */
-  constructor(device?: GPUDevice | null);
-
-  /**
-   * Begin timing a labeled region.
-   * Uses CPU timing; use writeTimestamp() inside passes for GPU timestamps.
-   * @param label - Unique label for this measurement
-   */
-  begin(label: string): void;
-
-  /**
-   * End timing a labeled region
-   * @param label - Label started with begin()
-   */
-  end(label: string): void;
-
-  /**
-   * Write timestamp to query set within a compute pass
-   * Call this instead of begin/end when inside a pass
-   * @param pass - Compute pass encoder
-   * @param label - Label for this measurement
-   * @param isEnd - true for end timestamp
-   */
-  writeTimestamp(pass: GPUComputePassEncoder, label: string, isEnd?: boolean): void;
-
-  /**
-   * Resolve pending timestamp queries and update results
-   * Call this after command buffer submission
-   */
-  resolve(): Promise<void>;
-
-  /**
-   * Get profiling results
-   */
-  getResults(): Record<string, ProfileResult>;
-
-  /**
-   * Get result for a specific label
-   * @param label - Label to get result for
-   */
-  getResult(label: string): ProfileResult | null;
-
-  /**
-   * Reset all profiling data
-   */
-  reset(): void;
-
-  /**
-   * Get formatted report string
-   */
-  getReport(): string;
-
-  /**
-   * Check if timestamp queries are available
-   */
-  isGPUTimingAvailable(): boolean;
-
-  /**
-   * Destroy profiler resources
-   */
-  destroy(): void;
-}
-
-/**
- * Get the global profiler instance
- */
-export function getProfiler(): GPUProfiler;
-
-/**
- * Create a new profiler instance
- * @param device - Optional GPU device
- */
-export function createProfiler(device?: GPUDevice | null): GPUProfiler;
-
-/**
- * Convenience function to time a single operation
- * @param label - Label for the operation
- * @param fn - Async function to time
- */
-export function timeOperation<T>(
-  label: string,
-  fn: () => Promise<T>
-): Promise<{ result: T; timeMs: number }>;
-
-export default GPUProfiler;

package/src/gpu/profiler.js

@@ -1,396 +0,0 @@
-
-
-import { getDevice, hasFeature, FEATURES } from './device.js';
-import { allowReadback } from './perf-guards.js';
-import { log } from '../debug/index.js';
-import { getRuntimeConfig } from '../config/runtime.js';
-import { computeBasicStats } from '../debug/stats.js';
-
-
-
-
-
-
-
-
-
-
-export class GPUProfiler {
-  
-  #device;
-  
-  #hasTimestampQuery;
-
-  // Query set for timestamp queries (if supported)
-  
-  #querySet = null;
-  
-  #queryBuffer = null;
-  
-  #readbackBuffer = null;
-  
-  #queryCapacity = 0;
-  
-  #maxSamples = 0;
-  
-  #maxDurationMs = 0;
-
-  // Tracking state
-  
-  #activeLabels = new Map();
-  
-  #nextQueryIndex = 0;
-  
-  #pendingResolves = [];
-
-  // Results storage
-  
-  #results = new Map();
-
-  // CPU fallback timing
-  
-  #cpuTimings = new Map();
-
-  
-  constructor(device = null) {
-    this.#device = device || getDevice();
-    this.#hasTimestampQuery = this.#device?.features?.has(FEATURES.TIMESTAMP_QUERY) ?? false;
-    const runtimeProfiler = getRuntimeConfig().shared?.debug?.profiler;
-    if (!runtimeProfiler) {
-      throw new Error('runtime.shared.debug.profiler is required.');
-    }
-    this.#queryCapacity = runtimeProfiler.queryCapacity;
-    this.#maxSamples = runtimeProfiler.maxSamples;
-    this.#maxDurationMs = runtimeProfiler.maxDurationMs;
-
-    // Initialize query resources if timestamp queries available
-    if (this.#hasTimestampQuery && this.#device) {
-      this.#initQueryResources();
-    }
-  }
-
-  
-  #initQueryResources() {
-    if (!this.#device) return;
-
-    try {
-      this.#querySet = this.#device.createQuerySet({
-        type: 'timestamp',
-        count: this.#queryCapacity * 2, // Start and end for each measurement
-      });
-
-      // Buffer to hold query results (8 bytes per timestamp)
-      this.#queryBuffer = this.#device.createBuffer({
-        size: this.#queryCapacity * 2 * 8,
-        usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC,
-      });
-
-      // Readback buffer
-      this.#readbackBuffer = this.#device.createBuffer({
-        size: this.#queryCapacity * 2 * 8,
-        usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
-      });
-    } catch (e) {
-      log.warn('GPUProfiler', `Failed to create timestamp query resources: ${e}`);
-      this.#hasTimestampQuery = false;
-    }
-  }
-
-  
-  begin(label) {
-    if (this.#activeLabels.has(label)) {
-      log.warn('GPUProfiler', `Label "${label}" already active`);
-      return;
-    }
-
-    const startTime = performance.now();
-
-    // CPU timing for begin/end; GPU timestamps require writeTimestamp() in a pass.
-    this.#activeLabels.set(label, {
-      cpuStartTime: startTime,
-    });
-  }
-
-  
-  end(label) {
-    const active = this.#activeLabels.get(label);
-    if (!active) {
-      log.warn('GPUProfiler', `No active measurement for label "${label}"`);
-      return;
-    }
-
-    const endTime = performance.now();
-    this.#activeLabels.delete(label);
-
-    if (this.#hasTimestampQuery && 'startQueryIndex' in active) {
-      // GPU timing will be resolved later
-      this.#pendingResolves.push({
-        label,
-        startIndex: active.startQueryIndex,
-        endIndex: active.startQueryIndex + 1,
-        cpuStartTime: active.cpuStartTime,
-        cpuEndTime: endTime,
-      });
-    } else {
-      // CPU fallback - record immediately
-      this.#recordResult(label, endTime - active.cpuStartTime);
-    }
-  }
-
-  
-  writeTimestamp(pass, label, isEnd = false) {
-    if (!this.#hasTimestampQuery || !this.#querySet) return;
-
-    
-    let queryIndex;
-    if (!isEnd) {
-      // Start timestamp
-      queryIndex = this.#nextQueryIndex;
-      this.#nextQueryIndex += 2;
-      this.#activeLabels.set(label, {
-        startQueryIndex: queryIndex,
-        cpuStartTime: performance.now(),
-      });
-    } else {
-      // End timestamp
-      const active = this.#activeLabels.get(label);
-      if (!active || !('startQueryIndex' in active)) return;
-      queryIndex = active.startQueryIndex + 1;
-      this.#activeLabels.delete(label);
-      this.#pendingResolves.push({
-        label,
-        startIndex: active.startQueryIndex,
-        endIndex: queryIndex,
-        cpuStartTime: active.cpuStartTime,
-        cpuEndTime: performance.now(),
-      });
-    }
-
-    // Note: writeTimestamp is deprecated in modern WebGPU spec but still works in Chrome
-    // Future: migrate to timestampWrites in GPUComputePassDescriptor
-     (pass).writeTimestamp(this.#querySet, queryIndex);
-  }
-
-  
-  async resolve() {
-    if (!this.#hasTimestampQuery || this.#pendingResolves.length === 0) {
-      return;
-    }
-
-    if (!this.#device || !this.#querySet || !this.#queryBuffer || !this.#readbackBuffer) {
-      log.warn('GPUProfiler', 'Missing required resources for resolve');
-      this.#pendingResolves = [];
-      this.#nextQueryIndex = 0;
-      return;
-    }
-
-    const encoder = this.#device.createCommandEncoder();
-
-    // Resolve all timestamps to buffer
-    const maxIndex = Math.max(...this.#pendingResolves.map(p => p.endIndex)) + 1;
-    encoder.resolveQuerySet(this.#querySet, 0, maxIndex, this.#queryBuffer, 0);
-
-    // Copy to readback buffer
-    encoder.copyBufferToBuffer(
-      this.#queryBuffer,
-      0,
-      this.#readbackBuffer,
-      0,
-      maxIndex * 8
-    );
-
-    this.#device.queue.submit([encoder.finish()]);
-
-    let mapped = false;
-
-    try {
-      if (!allowReadback('GPUProfiler.resolve')) {
-        return;
-      }
-
-      await this.#readbackBuffer.mapAsync(GPUMapMode.READ);
-      mapped = true;
-      const timestamps = new BigUint64Array(this.#readbackBuffer.getMappedRange());
-
-      for (const pending of this.#pendingResolves) {
-        const startNs = timestamps[pending.startIndex];
-        const endNs = timestamps[pending.endIndex];
-        const durationMs = Number(endNs - startNs) / 1_000_000;
-
-        if (durationMs < 0 || durationMs > this.#maxDurationMs) {
-          this.#recordResult(pending.label, pending.cpuEndTime - pending.cpuStartTime);
-        } else {
-          this.#recordResult(pending.label, durationMs);
-        }
-      }
-    } finally {
-      if (mapped) {
-        this.#readbackBuffer.unmap();
-      }
-      this.#pendingResolves = [];
-      this.#nextQueryIndex = 0;
-    }
-  }
-
-  
-  #recordResult(label, timeMs) {
-    if (!this.#results.has(label)) {
-      this.#results.set(label, {
-        times: [],
-        min: Infinity,
-        max: -Infinity,
-        sum: 0,
-        count: 0,
-      });
-    }
-
-    const result = this.#results.get(label);
-    result.times.push(timeMs);
-    result.min = Math.min(result.min, timeMs);
-    result.max = Math.max(result.max, timeMs);
-    result.sum += timeMs;
-    result.count++;
-
-    // Keep only last N samples for running average
-    if (result.times.length > this.#maxSamples) {
-      const removed = result.times.shift();
-      result.sum -= removed;
-      result.count--;
-      // Recalculate min/max if needed (expensive, so only do occasionally)
-      if (result.times.length % 20 === 0) {
-        result.min = Math.min(...result.times);
-        result.max = Math.max(...result.times);
-      }
-    }
-  }
-
-  
-  getResults() {
-    
-    const output = {};
-
-    for (const [label, data] of this.#results) {
-      const stats = computeBasicStats(data.times);
-      output[label] = {
-        avg: stats.mean,
-        min: stats.min,
-        max: stats.max,
-        count: stats.count,
-        total: stats.total,
-      };
-    }
-
-    return output;
-  }
-
-  
-  getResult(label) {
-    const data = this.#results.get(label);
-    if (!data) return null;
-
-    const stats = computeBasicStats(data.times);
-    return {
-      avg: stats.mean,
-      min: stats.min,
-      max: stats.max,
-      count: stats.count,
-      total: stats.total,
-    };
-  }
-
-  
-  reset() {
-    this.#results.clear();
-    this.#activeLabels.clear();
-    this.#pendingResolves = [];
-    this.#nextQueryIndex = 0;
-  }
-
-  
-  getReport() {
-    const results = this.getResults();
-    const labels = Object.keys(results).sort();
-
-    if (labels.length === 0) {
-      return 'No profiling data collected';
-    }
-
-    let report = 'GPU Profiler Results\n';
-    report += '\u2500'.repeat(60) + '\n';
-    report += 'Label'.padEnd(30) + 'Avg (ms)'.padStart(10) + 'Min'.padStart(10) + 'Max'.padStart(10) + '\n';
-    report += '\u2500'.repeat(60) + '\n';
-
-    for (const label of labels) {
-      const r = results[label];
-      report += label.padEnd(30);
-      report += r.avg.toFixed(3).padStart(10);
-      report += r.min.toFixed(3).padStart(10);
-      report += r.max.toFixed(3).padStart(10);
-      report += '\n';
-    }
-
-    return report;
-  }
-
-  
-  isGPUTimingAvailable() {
-    return this.#hasTimestampQuery;
-  }
-
-  
-  destroy() {
-    if (this.#querySet) {
-      this.#querySet.destroy();
-      this.#querySet = null;
-    }
-    if (this.#queryBuffer) {
-      this.#queryBuffer.destroy();
-      this.#queryBuffer = null;
-    }
-    if (this.#readbackBuffer) {
-      this.#readbackBuffer.destroy();
-      this.#readbackBuffer = null;
-    }
-    this.#results.clear();
-    this.#activeLabels.clear();
-    this.#pendingResolves = [];
-    this.#nextQueryIndex = 0;
-  }
-}
-
-// Global profiler instance
-
-let globalProfiler = null;
-
-
-export function getProfiler() {
-  if (!globalProfiler) {
-    globalProfiler = new GPUProfiler();
-  }
-  return globalProfiler;
-}
-
-
-export function createProfiler(device) {
-  return new GPUProfiler(device);
-}
-
-
-export async function timeOperation(
-  label,
-  fn
-) {
-  const profiler = getProfiler();
-  profiler.begin(label);
-  const result = await fn();
-  profiler.end(label);
-  await profiler.resolve();
-
-  const timing = profiler.getResult(label);
-  return {
-    result,
-    timeMs: timing?.avg ?? 0,
-  };
-}
-
-export default GPUProfiler;

package/src/gpu/readback-utils.d.ts

@@ -1,16 +0,0 @@
-export interface ReadbackBufferEntry {
-  buffer: GPUBuffer;
-  destroy?: boolean;
-  offset?: number;
-  size?: number;
-}
-
-export function withMappedReadBuffer<T>(
-  buffer: GPUBuffer,
-  read: (range: ArrayBuffer) => T | Promise<T>,
-): Promise<T>;
-
-export function withMappedReadBuffers<T>(
-  entries: ReadonlyArray<ReadbackBufferEntry>,
-  read: (ranges: Array<ArrayBuffer>) => T | Promise<T>,
-): Promise<T>;

package/src/gpu/readback-utils.js

@@ -1,41 +0,0 @@
-export async function withMappedReadBuffer(buffer, read) {
-  let mapped = false;
-  try {
-    await buffer.mapAsync(GPUMapMode.READ);
-    mapped = true;
-    return await read(buffer.getMappedRange());
-  } finally {
-    if (mapped) {
-      buffer.unmap();
-    }
-  }
-}
-
-export async function withMappedReadBuffers(entries, read) {
-  const mappedEntries = [];
-  try {
-    await Promise.all(entries.map(async (entry) => {
-      await entry.buffer.mapAsync(GPUMapMode.READ);
-      mappedEntries.push(entry);
-    }));
-    const ranges = entries.map((entry) => {
-      if (entry.offset != null || entry.size != null) {
-        return entry.buffer.getMappedRange(
-          entry.offset ?? 0,
-          entry.size ?? (entry.buffer.size - (entry.offset ?? 0))
-        );
-      }
-      return entry.buffer.getMappedRange();
-    });
-    return await read(ranges);
-  } finally {
-    for (let index = mappedEntries.length - 1; index >= 0; index -= 1) {
-      mappedEntries[index].buffer.unmap();
-    }
-    for (const entry of entries) {
-      if (entry.destroy === true) {
-        entry.buffer.destroy();
-      }
-    }
-  }
-}

package/src/gpu/submit-tracker.d.ts

@@ -1,111 +0,0 @@
-/**
- * Submit Tracker - Measures GPU submit overhead for optimization benchmarking.
- *
- * @module gpu/submit-tracker
- */
-
-/** Whether to track submits (disable in production for perf) */
-export let TRACK_SUBMITS: boolean;
-
-/** Submit statistics */
-export interface SubmitStats {
-  /** Number of queue.submit() calls */
-  count: number;
-  /** Total time spent in submit calls (ms) */
-  totalMs: number;
-  /** Average time per submit (ms) */
-  avgMs: number;
-  /** Max time for a single submit (ms) */
-  maxMs: number;
-  /** Min time for a single submit (ms) */
-  minMs: number;
-  /** Submit timestamps for detailed analysis */
-  timestamps: number[];
-  /** Submit counts by source */
-  bySource?: Map<string, number>;
-}
-
-/** Phase-based submit statistics */
-export interface PhaseSubmitStats {
-  prefill: SubmitStats;
-  decode: SubmitStats;
-  other: SubmitStats;
-}
-
-/** Current phase for submit tracking */
-export type SubmitPhase = 'prefill' | 'decode' | 'other';
-
-/**
- * Enable/disable submit tracking.
- * @param enabled - Whether to track submits
- */
-export function setTrackSubmits(enabled: boolean): void;
-
-/**
- * Reset submit statistics.
- * Call before starting a new measurement.
- */
-export function resetSubmitStats(): void;
-
-/**
- * Set the current phase for submit tracking.
- * @param phase - The phase to track ('prefill', 'decode', or 'other')
- */
-export function setSubmitPhase(phase: SubmitPhase): void;
-
-/**
- * Record a submit call.
- * Call this from a wrapper around queue.submit().
- * @param durationMs - Time spent in this submit call
- * @param source - Optional source identifier (e.g., "pipeline.ts:prefill", "layer.ts:attention")
- */
-export function recordSubmit(durationMs: number, source?: string): void;
-
-/**
- * Get current submit statistics.
- * @returns Submit statistics
- */
-export function getSubmitStats(): SubmitStats;
-
-/**
- * Get submit statistics for a specific phase.
- * @param phase - The phase to get stats for
- * @returns Submit statistics for the phase
- */
-export function getPhaseSubmitStats(phase: SubmitPhase): SubmitStats;
-
-/**
- * Get submit statistics for all phases.
- * @returns Submit statistics by phase
- */
-export function getAllPhaseSubmitStats(): PhaseSubmitStats;
-
-/**
- * Log submit statistics summary.
- * @param label - Label for the log output
- */
-export function logSubmitStats(label?: string): void;
-
-/**
- * Log submit statistics for all phases.
- * @param label - Label for the log output
- */
-export function logAllPhaseSubmitStats(label?: string): void;
-
-/**
- * Wrap a GPU queue to track submit calls.
- * @param queue - GPU queue to wrap
- * @returns Wrapped queue with tracking
- */
-export function wrapQueueForTracking(queue: GPUQueue): GPUQueue;
-
-/**
- * Estimate submit overhead savings from batching.
- * @param currentStats - Current submit stats (unbatched)
- * @param targetSubmits - Target number of submits after batching
- * @returns Estimated time savings in ms
- */
-export function estimateBatchingSavings(
-  currentStats: SubmitStats,
-  targetSubmits?: number
-): { savedSubmits: number; estimatedSavingsMs: number };