@simulatte/doppler 0.1.0

package/src/config/schema/emulation.schema.d.ts

@@ -0,0 +1,351 @@
+/**
+ * Emulation Config Schema
+ *
+ * Configuration for NVIDIA superchip emulation using local resources.
+ * Simulates GH200/GB200 superchips using actual VRAM, unified RAM, and OPFS storage.
+ *
+ * @module config/schema/emulation
+ */
+
+import type { EmulatedVramStats } from '../../storage/emulated-vram.js';
+
+// =============================================================================
+// Target Chip Types
+// =============================================================================
+
+/**
+ * Supported emulated chip configurations
+ */
+export type EmulatedChipType =
+  | 'gh200'        // Single GH200: 1 GPU (144GB) + 1 CPU (480GB)
+  | 'gh200-nvl2'   // GH200 NVL2: 2 GPUs (288GB) + 2 CPUs (960GB)
+  | 'gb200-8gpu'   // GB200 8-GPU Pod: 8 GPUs (1.5TB)
+  | 'gb200-nvl72'; // GB200 NVL72: 72 GPUs (13.5TB) - future
+
+/**
+ * Timing simulation modes
+ */
+export type EmulationTimingMode =
+  | 'functional'  // Verify distributed logic without timing delays
+  | 'timed'       // Inject realistic delays for compute/memory/nvlink
+  | 'hybrid';     // Timing for compute, functional for communication
+
+// =============================================================================
+// GPU Specifications
+// =============================================================================
+
+/**
+ * Specification for a single GPU
+ */
+export interface EmulatedGPUSpec {
+  /** GPU name (e.g., 'H100', 'H200', 'B200') */
+  name: string;
+  /** VRAM size in bytes */
+  vramBytes: number;
+  /** HBM bandwidth in bytes/sec */
+  hbmBandwidthBytesPerSec: number;
+  /** FP16 TFLOPS */
+  fp16Tflops: number;
+  /** FP8 TFLOPS (for B200) */
+  fp8Tflops?: number;
+}
+
+/**
+ * Specification for a CPU
+ */
+export interface EmulatedCPUSpec {
+  /** CPU name (e.g., 'Grace') */
+  name: string;
+  /** CPU core count */
+  cores: number;
+  /** Memory size in bytes */
+  memoryBytes: number;
+  /** Memory bandwidth in bytes/sec */
+  memoryBandwidthBytesPerSec: number;
+}
+
+// =============================================================================
+// Interconnect Specifications
+// =============================================================================
+
+/**
+ * NVLink interconnect specification
+ */
+export interface NVLinkSpec {
+  /** Bandwidth in bytes/sec per link */
+  bandwidthBytesPerSec: number;
+  /** Base latency in microseconds */
+  latencyUs: number;
+}
+
+/**
+ * NVLink-C2C (CPU↔GPU coherent) specification
+ */
+export interface NVLinkC2CSpec {
+  /** Bandwidth in bytes/sec */
+  bandwidthBytesPerSec: number;
+  /** Base latency in microseconds */
+  latencyUs: number;
+  /** Whether coherent memory is enabled */
+  coherent: boolean;
+}
+
+// =============================================================================
+// Cluster Topology
+// =============================================================================
+
+/**
+ * Cluster topology configuration
+ */
+export interface EmulatedClusterTopology {
+  /** Total GPU count in cluster */
+  gpuCount: number;
+  /** GPUs per node (for multi-node configs) */
+  gpusPerNode: number;
+  /** Node count (gpuCount / gpusPerNode) */
+  nodeCount: number;
+  /** CPU count (typically matches node count for superchips) */
+  cpuCount: number;
+}
+
+// =============================================================================
+// Parallelism Configuration
+// =============================================================================
+
+/**
+ * Tensor parallelism configuration
+ */
+export interface TensorParallelConfig {
+  /** Enable tensor parallelism */
+  enabled: boolean;
+  /** Degree of tensor parallelism (number of GPUs for weight sharding) */
+  degree: number;
+}
+
+/**
+ * Pipeline parallelism configuration
+ */
+export interface PipelineParallelConfig {
+  /** Enable pipeline parallelism */
+  enabled: boolean;
+  /** Number of pipeline stages */
+  stages: number;
+  /** Micro-batch count for 1F1B schedule */
+  microBatches?: number;
+}
+
+/**
+ * Data parallelism configuration
+ */
+export interface DataParallelConfig {
+  /** Enable data parallelism */
+  enabled: boolean;
+  /** Degree of data parallelism (number of model replicas) */
+  degree: number;
+}
+
+/**
+ * Expert parallelism configuration (for MoE models)
+ */
+export interface ExpertParallelConfig {
+  /** Enable expert parallelism */
+  enabled: boolean;
+  /** Degree of expert parallelism */
+  degree: number;
+}
+
+/**
+ * Complete parallelism configuration
+ */
+export interface EmulatedParallelismConfig {
+  tensorParallel: TensorParallelConfig;
+  pipelineParallel: PipelineParallelConfig;
+  dataParallel: DataParallelConfig;
+  expertParallel: ExpertParallelConfig;
+}
+
+// =============================================================================
+// Timing Scaling
+// =============================================================================
+
+/**
+ * Timing scaling factors for emulation accuracy
+ */
+export interface EmulatedTimingScaling {
+  /** Scale factor for compute operations (1.0 = real timing) */
+  computeScale: number;
+  /** Scale factor for memory operations */
+  memoryScale: number;
+  /** Scale factor for NVLink transfers */
+  nvlinkScale: number;
+}
+
+// =============================================================================
+// Resource Mapping
+// =============================================================================
+
+/**
+ * Local resource tier configuration
+ */
+export interface LocalResourceTier {
+  /** Tier name */
+  name: string;
+  /** Maximum bytes available in this tier */
+  maxBytes: number;
+  /** Approximate bandwidth in bytes/sec */
+  bandwidthBytesPerSec: number;
+}
+
+/**
+ * Local resource mapping for emulation
+ */
+export interface LocalResourceMapping {
+  /** Tier 1: Actual GPU VRAM (WebGPU buffers) */
+  tier1Vram: LocalResourceTier;
+  /** Tier 2: System RAM (ArrayBuffer/WASM heap) */
+  tier2Ram: LocalResourceTier;
+  /** Tier 3: OPFS/SSD Storage */
+  tier3Storage: LocalResourceTier;
+}
+
+// =============================================================================
+// Main Emulation Config
+// =============================================================================
+
+/**
+ * Complete emulation configuration schema
+ */
+export interface EmulationConfigSchema {
+  /** Enable emulation mode */
+  enabled: boolean;
+
+  /** Target chip configuration to emulate */
+  targetChip: EmulatedChipType;
+
+  /** Timing simulation mode */
+  timingMode: EmulationTimingMode;
+
+  /** GPU specification (populated from preset or custom) */
+  gpuSpec: EmulatedGPUSpec;
+
+  /** CPU specification (for superchips with Grace CPU) */
+  cpuSpec: EmulatedCPUSpec;
+
+  /** Cluster topology */
+  topology: EmulatedClusterTopology;
+
+  /** NVLink GPU↔GPU specification */
+  nvlink: NVLinkSpec;
+
+  /** NVLink-C2C CPU↔GPU specification */
+  nvlinkC2C: NVLinkC2CSpec;
+
+  /** Parallelism configuration */
+  parallelism: EmulatedParallelismConfig;
+
+  /** Timing scaling factors */
+  timingScaling: EmulatedTimingScaling;
+
+  /** Local resource mapping (auto-detected or override) */
+  localResources?: LocalResourceMapping;
+
+  /** OPFS root path for emulated GPU memory partitions */
+  opfsRootPath: string;
+
+  /** Maximum active working set in bytes (fits in actual VRAM) */
+  maxActiveWorkingSetBytes: number;
+
+  /** Enable detailed emulation statistics */
+  statsEnabled: boolean;
+
+  /** Log emulation operations */
+  logOperations: boolean;
+}
+
+// =============================================================================
+// Emulation Statistics
+// =============================================================================
+
+/**
+ * Statistics for a single virtual GPU
+ */
+export interface VirtualGPUStats {
+  /** GPU index */
+  gpuIndex: number;
+  /** VRAM bytes allocated */
+  vramAllocatedBytes: number;
+  /** VRAM bytes in use */
+  vramUsedBytes: number;
+  /** Number of buffer allocations */
+  allocationCount: number;
+  /** Compute operations executed */
+  computeOps: number;
+  /** Total compute time (ms) */
+  computeTimeMs: number;
+}
+
+/**
+ * Statistics for NVLink transfers
+ */
+export interface NVLinkStats {
+  /** Total bytes transferred */
+  totalBytesTransferred: number;
+  /** Number of transfers */
+  transferCount: number;
+  /** Total simulated transfer time (ms) */
+  simulatedTimeMs: number;
+  /** Actual transfer time (ms) */
+  actualTimeMs: number;
+}
+
+/**
+ * Complete emulation statistics
+ */
+export interface EmulationStats {
+  /** Per-GPU statistics */
+  gpuStats: VirtualGPUStats[];
+  /** NVLink GPU↔GPU statistics */
+  nvlinkStats: NVLinkStats;
+  /** NVLink-C2C CPU↔GPU statistics */
+  nvlinkC2CStats: NVLinkStats;
+  /** Total injected delay (ms) */
+  totalInjectedDelayMs: number;
+  /** Wall clock time (ms) */
+  wallClockTimeMs: number;
+  /** Emulated VRAM store statistics (if available) */
+  vramStore?: EmulatedVramStats;
+}
+
+// =============================================================================
+// Default Exports
+// =============================================================================
+
+/** Default GH200 GPU spec (H200 variant) */
+export declare const DEFAULT_GH200_GPU_SPEC: EmulatedGPUSpec;
+
+/** Default GH200 CPU spec (Grace) */
+export declare const DEFAULT_GH200_CPU_SPEC: EmulatedCPUSpec;
+
+/** Default NVLink spec (900 GB/s) */
+export declare const DEFAULT_NVLINK_SPEC: NVLinkSpec;
+
+/** Default NVLink-C2C spec (900 GB/s coherent) */
+export declare const DEFAULT_NVLINK_C2C_SPEC: NVLinkC2CSpec;
+
+/** Default parallelism configuration (no parallelism) */
+export declare const DEFAULT_PARALLELISM_CONFIG: EmulatedParallelismConfig;
+
+/** Default emulation configuration (disabled) */
+export declare const DEFAULT_EMULATION_CONFIG: EmulationConfigSchema;
+
+/**
+ * Create emulation config with overrides
+ */
+export declare function createEmulationConfig(
+  overrides?: Partial<EmulationConfigSchema>
+): EmulationConfigSchema;
+
+/**
+ * Get preset config for a specific chip type
+ */
+export declare function getChipPreset(chipType: EmulatedChipType): Partial<EmulationConfigSchema>;

package/src/config/schema/emulation.schema.js

@@ -0,0 +1,299 @@
+import { loadJson } from '../../utils/load-json.js';
+import { GB } from './units.schema.js';
+
+const gh200Preset = await loadJson('../presets/platforms/nvidia-gh200.json', import.meta.url, 'Failed to load preset');
+const gh200Nvl2Preset = await loadJson('../presets/platforms/nvidia-gh200-nvl2.json', import.meta.url, 'Failed to load preset');
+const gb2008Preset = await loadJson('../presets/platforms/nvidia-gb200-8gpu.json', import.meta.url, 'Failed to load preset');
+const gb200Nvl72Preset = await loadJson('../presets/platforms/nvidia-gb200-nvl72.json', import.meta.url, 'Failed to load preset');
+
+// =============================================================================
+// GPU Specifications
+// =============================================================================
+
+export const H100_GPU_SPEC = {
+  name: 'H100',
+  vramBytes: 96 * GB,
+  hbmBandwidthBytesPerSec: 3.35e12,   // 3.35 TB/s HBM3
+  fp16Tflops: 1979,                    // ~2 PFLOPS
+};
+
+export const H200_GPU_SPEC = {
+  name: 'H200',
+  vramBytes: 144 * GB,
+  hbmBandwidthBytesPerSec: 4.8e12,     // 4.8 TB/s HBM3e
+  fp16Tflops: 1979,                     // ~2 PFLOPS
+};
+
+export const B200_GPU_SPEC = {
+  name: 'B200',
+  vramBytes: 192 * GB,
+  hbmBandwidthBytesPerSec: 8e12,       // 8 TB/s HBM3e
+  fp16Tflops: 4500,                     // 4.5 PFLOPS
+  fp8Tflops: 9000,                      // 9 PFLOPS FP8
+};
+
+export const DEFAULT_GH200_GPU_SPEC = H200_GPU_SPEC;
+
+// =============================================================================
+// CPU Specifications
+// =============================================================================
+
+export const GRACE_CPU_SPEC = {
+  name: 'Grace',
+  cores: 72,
+  memoryBytes: 480 * GB, // LPDDR5X
+  memoryBandwidthBytesPerSec: 546e9,      // 546 GB/s
+};
+
+export const DEFAULT_GH200_CPU_SPEC = GRACE_CPU_SPEC;
+
+// =============================================================================
+// NVLink Specifications
+// =============================================================================
+
+export const NVLINK_4_SPEC = {
+  bandwidthBytesPerSec: 900e9, // 900 GB/s
+  latencyUs: 1.0,              // ~1 microsecond
+};
+
+export const NVLINK_5_SPEC = {
+  bandwidthBytesPerSec: 1.8e12, // 1.8 TB/s
+  latencyUs: 0.8,               // ~0.8 microseconds
+};
+
+export const DEFAULT_NVLINK_SPEC = NVLINK_4_SPEC;
+
+export const DEFAULT_NVLINK_C2C_SPEC = {
+  bandwidthBytesPerSec: 900e9, // 900 GB/s
+  latencyUs: 0.5,              // Lower latency for coherent access
+  coherent: true,
+};
+
+// =============================================================================
+// Cluster Topologies
+// =============================================================================
+
+export const GH200_TOPOLOGY = {
+  gpuCount: 1,
+  gpusPerNode: 1,
+  nodeCount: 1,
+  cpuCount: 1,
+};
+
+export const GH200_NVL2_TOPOLOGY = {
+  gpuCount: 2,
+  gpusPerNode: 2,
+  nodeCount: 1,
+  cpuCount: 2,
+};
+
+export const GB200_8GPU_TOPOLOGY = {
+  gpuCount: 8,
+  gpusPerNode: 8,
+  nodeCount: 1,
+  cpuCount: 2,
+};
+
+export const GB200_NVL72_TOPOLOGY = {
+  gpuCount: 72,
+  gpusPerNode: 8,
+  nodeCount: 9,
+  cpuCount: 18, // 2 CPUs per node
+};
+
+// =============================================================================
+// Parallelism Defaults
+// =============================================================================
+
+export const DEFAULT_PARALLELISM_CONFIG = {
+  tensorParallel: {
+    enabled: false,
+    degree: 1,
+  },
+  pipelineParallel: {
+    enabled: false,
+    stages: 1,
+    microBatches: 1,
+  },
+  dataParallel: {
+    enabled: false,
+    degree: 1,
+  },
+  expertParallel: {
+    enabled: false,
+    degree: 1,
+  },
+};
+
+export const TP2_PARALLELISM_CONFIG = {
+  ...DEFAULT_PARALLELISM_CONFIG,
+  tensorParallel: {
+    enabled: true,
+    degree: 2,
+  },
+};
+
+export const TP8_PARALLELISM_CONFIG = {
+  ...DEFAULT_PARALLELISM_CONFIG,
+  tensorParallel: {
+    enabled: true,
+    degree: 8,
+  },
+};
+
+// =============================================================================
+// Timing Scaling Defaults
+// =============================================================================
+
+export const DEFAULT_TIMING_SCALING = {
+  computeScale: 1.0,
+  memoryScale: 1.0,
+  nvlinkScale: 1.0,
+};
+
+// =============================================================================
+// Complete Emulation Config Defaults
+// =============================================================================
+
+export const DEFAULT_EMULATION_CONFIG = {
+  enabled: false,
+  targetChip: 'gh200',
+  timingMode: 'functional',
+  gpuSpec: DEFAULT_GH200_GPU_SPEC,
+  cpuSpec: DEFAULT_GH200_CPU_SPEC,
+  topology: GH200_TOPOLOGY,
+  nvlink: DEFAULT_NVLINK_SPEC,
+  nvlinkC2C: DEFAULT_NVLINK_C2C_SPEC,
+  parallelism: DEFAULT_PARALLELISM_CONFIG,
+  timingScaling: DEFAULT_TIMING_SCALING,
+  localResources: undefined,
+  opfsRootPath: 'emulation',
+  maxActiveWorkingSetBytes: 4 * GB, // default working set
+  statsEnabled: true,
+  logOperations: false,
+};
+
+// =============================================================================
+// Chip Presets
+// =============================================================================
+
+const CHIP_PRESETS = {
+  'gh200': gh200Preset.emulation,
+  'gh200-nvl2': gh200Nvl2Preset.emulation,
+  'gb200-8gpu': gb2008Preset.emulation,
+  'gb200-nvl72': gb200Nvl72Preset.emulation,
+};
+
+export function getChipPreset(chipType) {
+  const preset = CHIP_PRESETS[chipType];
+  if (!preset) {
+    throw new Error(`Unknown chip type: ${chipType}. Valid types: ${Object.keys(CHIP_PRESETS).join(', ')}`);
+  }
+  return { ...preset };
+}
+
+export function createEmulationConfig(overrides) {
+  if (!overrides) {
+    return { ...DEFAULT_EMULATION_CONFIG };
+  }
+
+  // If targetChip is specified, apply preset first
+  const chipPreset = overrides.targetChip
+    ? getChipPreset(overrides.targetChip)
+    : {};
+  const { enabled: _enabled, ...chipPresetConfig } = chipPreset;
+  const presetParallelism = chipPresetConfig.parallelism
+    ? mergeParallelismConfig(DEFAULT_PARALLELISM_CONFIG, chipPresetConfig.parallelism)
+    : DEFAULT_PARALLELISM_CONFIG;
+  const resolvedParallelism = overrides.parallelism
+    ? mergeParallelismConfig(presetParallelism, overrides.parallelism)
+    : presetParallelism;
+
+  return {
+    ...DEFAULT_EMULATION_CONFIG,
+    ...chipPresetConfig,
+    ...overrides,
+    enabled: overrides.enabled ?? DEFAULT_EMULATION_CONFIG.enabled,
+    // Deep merge nested objects
+    gpuSpec: {
+      ...DEFAULT_EMULATION_CONFIG.gpuSpec,
+      ...chipPresetConfig.gpuSpec,
+      ...overrides.gpuSpec,
+    },
+    cpuSpec: {
+      ...DEFAULT_EMULATION_CONFIG.cpuSpec,
+      ...chipPresetConfig.cpuSpec,
+      ...overrides.cpuSpec,
+    },
+    topology: {
+      ...DEFAULT_EMULATION_CONFIG.topology,
+      ...chipPresetConfig.topology,
+      ...overrides.topology,
+    },
+    nvlink: {
+      ...DEFAULT_EMULATION_CONFIG.nvlink,
+      ...chipPresetConfig.nvlink,
+      ...overrides.nvlink,
+    },
+    nvlinkC2C: {
+      ...DEFAULT_EMULATION_CONFIG.nvlinkC2C,
+      ...chipPresetConfig.nvlinkC2C,
+      ...overrides.nvlinkC2C,
+    },
+    parallelism: resolvedParallelism,
+    timingScaling: {
+      ...DEFAULT_EMULATION_CONFIG.timingScaling,
+      ...overrides.timingScaling,
+    },
+  };
+}
+
+function mergeParallelismConfig(base, overrides) {
+  return {
+    tensorParallel: {
+      ...base.tensorParallel,
+      ...overrides.tensorParallel,
+    },
+    pipelineParallel: {
+      ...base.pipelineParallel,
+      ...overrides.pipelineParallel,
+    },
+    dataParallel: {
+      ...base.dataParallel,
+      ...overrides.dataParallel,
+    },
+    expertParallel: {
+      ...base.expertParallel,
+      ...overrides.expertParallel,
+    },
+  };
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+export function calculateTotalVram(config) {
+  return config.gpuSpec.vramBytes * config.topology.gpuCount;
+}
+
+export function calculateTotalCpuMemory(config) {
+  return config.cpuSpec.memoryBytes * config.topology.cpuCount;
+}
+
+export function formatBytes(bytes) {
+  if (bytes >= 1e12) {
+    return `${(bytes / 1e12).toFixed(1)} TB`;
+  } else if (bytes >= 1e9) {
+    return `${(bytes / 1e9).toFixed(1)} GB`;
+  } else if (bytes >= 1e6) {
+    return `${(bytes / 1e6).toFixed(1)} MB`;
+  } else if (bytes >= 1e3) {
+    return `${(bytes / 1e3).toFixed(1)} KB`;
+  }
+  return `${bytes} B`;
+}
+
+export function formatBandwidth(bytesPerSec) {
+  return `${formatBytes(bytesPerSec)}/s`;
+}