benchforge 0.1.11 → 0.2.4

package/src/viewer/plots/LegendUtils.ts

@@ -0,0 +1,134 @@
+import * as Plot from "@observablehq/plot";
+
+/** Plot data bounds used to position the legend overlay */
+export interface LegendBounds {
+  xMin: number;
+  xMax: number;
+  yMin?: number;
+  yMax: number;
+}
+
+/** A single entry in the plot legend with color, label, and symbol style */
+export interface LegendItem {
+  color: string;
+  label: string;
+  style:
+    | "filled-dot"
+    | "hollow-dot"
+    | "vertical-bar"
+    | "vertical-line"
+    | "rect";
+  strokeDash?: string;
+}
+
+interface LegendPos {
+  legendX: number;
+  y: number;
+  textX: number;
+  xRange: number;
+  yRange: number;
+}
+
+const rectFields = { x1: "x1", x2: "x2", y1: "y1", y2: "y2" } as const;
+
+/** Build complete legend marks array, positioned in the right margin */
+export function buildLegend(bounds: LegendBounds, items: LegendItem[]): any[] {
+  const xRange = Math.max(bounds.xMax - bounds.xMin, bounds.xMax * 0.1 || 1);
+  const yRange = bounds.yMax - (bounds.yMin ?? 0);
+  const legendX = bounds.xMax + xRange * 0.04;
+  const textX = legendX + xRange * 0.03;
+  const itemHeight = yRange * 0.07;
+  const topY = bounds.yMax - yRange * 0.02;
+
+  const pos = (i: number): LegendPos => ({
+    legendX,
+    y: topY - i * itemHeight,
+    textX,
+    xRange,
+    yRange,
+  });
+  return items.flatMap((item, i) => [
+    symbolMark(pos(i), item),
+    textMark(pos(i), item.label),
+  ]);
+}
+
+function symbolMark(pos: LegendPos, item: LegendItem): any {
+  switch (item.style) {
+    case "filled-dot":
+      return dotMark(pos.legendX, pos.y, item.color, true);
+    case "hollow-dot":
+      return dotMark(pos.legendX, pos.y, item.color, false);
+    case "vertical-bar":
+      return verticalBarMark(pos, item.color);
+    case "vertical-line":
+      return verticalLineMark(pos, item.color, item.strokeDash);
+    case "rect":
+      return rectMark(pos, item.color);
+  }
+}
+
+function textMark(pos: LegendPos, label: string): any {
+  return Plot.text([{ x: pos.textX, y: pos.y, text: label }], {
+    x: "x",
+    y: "y",
+    text: "text",
+    fontSize: 11,
+    textAnchor: "start",
+    fill: "#333",
+    clip: false,
+  });
+}
+
+function dotMark(x: number, y: number, color: string, filled: boolean): any {
+  const base = { x: "x", y: "y", r: 4, clip: false };
+  const style = filled
+    ? { ...base, fill: color }
+    : { ...base, stroke: color, fill: "none", strokeWidth: 1.5 };
+  return Plot.dot([{ x, y }], style);
+}
+
+function verticalBarMark(pos: LegendPos, color: string): any {
+  const { legendX, y, xRange, yRange } = pos;
+  const hw = xRange * 0.006;
+  const hh = yRange * 0.025;
+  const data = [{ x1: legendX - hw, x2: legendX + hw, y1: y - hh, y2: y + hh }];
+  return Plot.rect(data, {
+    ...rectFields,
+    fill: color,
+    fillOpacity: 0.6,
+    clip: false,
+  });
+}
+
+function verticalLineMark(
+  pos: LegendPos,
+  color: string,
+  strokeDash?: string,
+): any {
+  const { legendX, y, yRange } = pos;
+  const half = yRange * 0.025;
+  return Plot.ruleX([legendX], {
+    y1: y - half,
+    y2: y + half,
+    stroke: color,
+    strokeWidth: 2,
+    strokeDasharray: strokeDash,
+    clip: false,
+  });
+}
+
+function rectMark(pos: LegendPos, color: string): any {
+  const { legendX, y, xRange, yRange } = pos;
+  const hw = xRange * 0.015;
+  const hh = yRange * 0.02;
+  const data = [{ x1: legendX - hw, x2: legendX + hw, y1: y - hh, y2: y + hh }];
+  return Plot.rect(data, {
+    ...rectFields,
+    fill: color,
+    fillOpacity: 0.3,
+    stroke: color,
+    strokeWidth: 1,
+    clip: false,
+  });
+}

package/src/viewer/plots/PlotTypes.ts

@@ -0,0 +1,85 @@
+/** A single timing sample from a benchmark run */
+export interface Sample {
+  benchmark: string;
+  value: number;
+  iteration: number;
+}
+
+/** A sample with warmup/optimization metadata for time series plots */
+export interface TimeSeriesPoint {
+  benchmark: string;
+  iteration: number;
+  value: number;
+  isWarmup: boolean;
+  isBaseline?: boolean;
+  isRejected?: boolean;
+  /** V8 optimization status code (e.g. 17=turbofan, 33=maglev) */
+  optStatus?: number;
+}
+
+/** Heap usage sample (in bytes) at a given iteration */
+export interface HeapPoint {
+  benchmark: string;
+  iteration: number;
+  value: number;
+}
+
+/** GcEvent flattened with benchmark name for multi-series plots */
+export interface FlatGcEvent {
+  benchmark: string;
+  sampleIndex: number;
+  duration: number;
+}
+
+/** PausePoint flattened with benchmark name for multi-series plots */
+export interface FlatPausePoint {
+  benchmark: string;
+  sampleIndex: number;
+  durationMs: number;
+}
+
+/** Display unit (ns/us/ms) with conversion and formatting functions */
+export interface TimeUnit {
+  unitSuffix: string;
+  convertValue: (ms: number) => number;
+  formatValue: (d: number) => string;
+}
+
+/** Shared Observable Plot layout: margins, dimensions, font size */
+export const plotLayout = {
+  marginTop: 24,
+  marginLeft: 70,
+  marginRight: 110,
+  marginBottom: 60,
+  width: 550,
+  height: 300,
+  style: { fontSize: "14px" },
+} as const;
+
+/** Format a number as a signed percentage string (e.g. "+1.2%", "-3.4%") */
+export function formatPct(v: number, precision = 1): string {
+  const sign = v >= 0 ? "+" : "";
+  return `${sign}${v.toFixed(precision)}%`;
+}
+
+/** Pick display unit (ns/us/ms) based on average value magnitude (in ms) */
+export function getTimeUnit(values: number[]): TimeUnit {
+  const avg = values.reduce((s, v) => s + v, 0) / values.length;
+  const locale = (digits: number) => (d: number) =>
+    d.toLocaleString("en-US", { maximumFractionDigits: digits });
+  const fmt0 = locale(0);
+  const fmt1 = locale(1);
+  if (avg < 0.001)
+    return {
+      unitSuffix: "ns",
+      convertValue: ms => ms * 1e6,
+      formatValue: fmt0,
+    };
+  if (avg < 1)
+    return {
+      unitSuffix: "\u00b5s",
+      convertValue: ms => ms * 1e3,
+      formatValue: fmt1,
+    };
+  return { unitSuffix: "ms", convertValue: ms => ms, formatValue: fmt1 };
+}

package/src/viewer/plots/RenderPlots.ts

@@ -0,0 +1,230 @@
+import {
+  average,
+  splitByOffsets,
+  tukeyKeep,
+} from "../../stats/StatisticalUtils.ts";
+import type { BenchmarkEntry, ReportData } from "../ReportData.ts";
+import type {
+  FlatGcEvent,
+  FlatPausePoint,
+  HeapPoint,
+  Sample,
+  TimeSeriesPoint,
+} from "./PlotTypes.ts";
+
+/** Benchmark entry tagged with whether it's the baseline for comparison */
+export interface PreparedBenchmark extends BenchmarkEntry {
+  isBaseline: boolean;
+}
+
+/** All sample data flattened across benchmarks into arrays for plotting */
+export interface FlattenedData {
+  allSamples: Sample[];
+  timeSeries: TimeSeriesPoint[];
+  heapSeries: HeapPoint[];
+  baselineHeapSeries: HeapPoint[];
+  allGcEvents: FlatGcEvent[];
+  allPausePoints: FlatPausePoint[];
+}
+
+/** Combine baseline and benchmarks into a single list with display names */
+export function prepareBenchmarks(
+  group: ReportData["groups"][0],
+): PreparedBenchmark[] {
+  const base = group.baseline;
+  const current = group.benchmarks.map(b => ({ ...b, isBaseline: false }));
+  if (!base) return current;
+
+  const baseName = base.name.endsWith("(baseline)")
+    ? base.name
+    : base.name + " (baseline)";
+  return [{ ...base, name: baseName, isBaseline: true }, ...current];
+}
+
+/** Collect all sample data across benchmarks into flat arrays for plotting */
+export function flattenSamples(benchmarks: PreparedBenchmark[]): FlattenedData {
+  const out: FlattenedData = {
+    allSamples: [],
+    timeSeries: [],
+    heapSeries: [],
+    baselineHeapSeries: [],
+    allGcEvents: [],
+    allPausePoints: [],
+  };
+  for (const b of benchmarks) {
+    if (b.samples?.length) flattenBenchmark(b, out);
+  }
+  return out;
+}
+
+/** @return batch count from the first benchmark with batchOffsets, or 0 */
+export function batchCount(benchmarks: PreparedBenchmark[]): number {
+  return (
+    benchmarks.find(b => b.batchOffsets?.length)?.batchOffsets?.length ?? 0
+  );
+}
+
+/** Filter flattened data to a single batch, re-indexing iterations from 0 */
+export function filterToBatch(
+  flat: FlattenedData,
+  benchmarks: PreparedBenchmark[],
+  batchIndex: number,
+): FlattenedData {
+  const ranges = new Map<string, [number, number]>();
+  for (const b of benchmarks) {
+    const offsets = b.batchOffsets;
+    if (!offsets?.length) continue;
+    const start = offsets[batchIndex];
+    const end =
+      batchIndex + 1 < offsets.length
+        ? offsets[batchIndex + 1]
+        : b.samples.length;
+    ranges.set(b.name, [start, end]);
+  }
+
+  const inBatch = (name: string, iter: number) => {
+    const r = ranges.get(name);
+    return r ? iter >= r[0] && iter < r[1] : true;
+  };
+  const reindex = (name: string, iter: number) => {
+    const r = ranges.get(name);
+    return r ? iter - r[0] : iter;
+  };
+  const sliceIter = <T extends { benchmark: string; iteration: number }>(
+    arr: T[],
+  ) =>
+    arr
+      .filter(d => inBatch(d.benchmark, d.iteration))
+      .map(d => ({ ...d, iteration: reindex(d.benchmark, d.iteration) }));
+
+  return {
+    allSamples: sliceIter(flat.allSamples),
+    timeSeries: sliceIter(flat.timeSeries.filter(d => !d.isWarmup)),
+    heapSeries: sliceIter(flat.heapSeries),
+    baselineHeapSeries: sliceIter(flat.baselineHeapSeries),
+    allGcEvents: flat.allGcEvents.filter(d =>
+      inBatch(d.benchmark, d.sampleIndex),
+    ),
+    allPausePoints: flat.allPausePoints.filter(d =>
+      inBatch(d.benchmark, d.sampleIndex),
+    ),
+  };
+}
+
+/** Extract time series, heap, GC, and pause data from one benchmark */
+function flattenBenchmark(b: PreparedBenchmark, out: FlattenedData): void {
+  flattenWarmup(b, b.name, out);
+  flattenSamplesAndHeap(b, b.name, out);
+  flattenGcEvents(b, b.name, out);
+  flattenPausePoints(b, b.name, out);
+}
+
+/** Warmup samples get negative iteration indices so they appear left of zero */
+function flattenWarmup(
+  b: PreparedBenchmark,
+  name: string,
+  out: FlattenedData,
+): void {
+  const warmupCount = b.warmupSamples?.length || 0;
+  b.warmupSamples?.forEach((value, i) => {
+    out.timeSeries.push({
+      benchmark: name,
+      iteration: i - warmupCount,
+      value,
+      isWarmup: true,
+    });
+  });
+}
+
+/** Populate timeSeries, allSamples (excluding rejected), and heap data */
+function flattenSamplesAndHeap(
+  b: PreparedBenchmark,
+  name: string,
+  out: FlattenedData,
+): void {
+  const rejected = rejectedIndices(b);
+  const isBase = b.isBaseline || undefined;
+  b.samples.forEach((value, i) => {
+    const isRejected = rejected?.has(i) || undefined;
+    if (!isRejected)
+      out.allSamples.push({ benchmark: name, value, iteration: i });
+    const optStatus = b.optSamples?.[i];
+    out.timeSeries.push({
+      benchmark: name,
+      iteration: i,
+      value,
+      isWarmup: false,
+      isBaseline: isBase,
+      isRejected,
+      optStatus,
+    });
+    if (b.heapSamples?.[i] !== undefined) {
+      const target = b.isBaseline ? out.baselineHeapSeries : out.heapSeries;
+      target.push({ benchmark: name, iteration: i, value: b.heapSamples[i] });
+    }
+  });
+}
+
+/** Map GC events to sample indices using cumulative sample durations */
+function flattenGcEvents(
+  b: PreparedBenchmark,
+  name: string,
+  out: FlattenedData,
+): void {
+  if (!b.gcEvents?.length) return;
+  const endTimes = cumulativeSum(b.samples);
+  for (const gc of b.gcEvents) {
+    const idx = endTimes.findIndex(t => t >= gc.offset);
+    const sampleIndex = idx >= 0 ? idx : b.samples.length - 1;
+    out.allGcEvents.push({
+      benchmark: name,
+      sampleIndex,
+      duration: gc.duration,
+    });
+  }
+}
+
+/** Flatten benchmark pause points into the shared output arrays */
+function flattenPausePoints(
+  b: PreparedBenchmark,
+  name: string,
+  out: FlattenedData,
+): void {
+  if (!b.pausePoints) return;
+  for (const p of b.pausePoints)
+    out.allPausePoints.push({
+      benchmark: name,
+      sampleIndex: p.sampleIndex,
+      durationMs: p.durationMs,
+    });
+}
+
+/** @return sample indices in Tukey-rejected batches, or undefined if none */
+function rejectedIndices(b: PreparedBenchmark): Set<number> | undefined {
+  const offsets = b.batchOffsets;
+  if (!offsets || offsets.length < 4) return undefined;
+
+  const means = splitByOffsets(b.samples, offsets).map(s => average(s));
+  const kept = new Set(tukeyKeep(means));
+
+  const rejected = new Set<number>();
+  for (let bi = 0; bi < means.length; bi++) {
+    if (!kept.has(bi)) {
+      const start = offsets[bi];
+      const end = bi + 1 < offsets.length ? offsets[bi + 1] : b.samples.length;
+      for (let j = start; j < end; j++) rejected.add(j);
+    }
+  }
+  return rejected.size > 0 ? rejected : undefined;
+}
+
+/** Running total of sample durations, used to map GC offsets to sample indices */
+function cumulativeSum(arr: number[]): number[] {
+  const result: number[] = [];
+  let sum = 0;
+  for (const v of arr) {
+    sum += v;
+    result.push(sum);
+  }
+  return result;
+}