@higher.archi/boe 1.0.0

package/src/engines/monte-carlo/strategy.ts

@@ -0,0 +1,565 @@
+/**
+ * Monte Carlo Engine Strategy (Optimized)
+ *
+ * Core simulation logic - samples from distributions, evaluates formulas,
+ * and computes statistics across iterations.
+ *
+ * Performance optimizations:
+ * - Pre-compiled formula functions (no runtime interpretation)
+ * - Direct value context (no Fact wrapper objects)
+ * - TypedArrays for history storage
+ * - Single-pass statistics calculation
+ * - Optional sensitivity analysis
+ */
+
+import { IWorkingMemory } from '../../core/memory';
+import { Fact } from '../../core/types/fact';
+import { compileCondition, evaluateCondition, Condition } from '../../core';
+
+import {
+  CompiledMonteCarloRuleSet,
+  CompiledVariable,
+  MonteCarloOptions,
+  MonteCarloResult,
+  OutputStatistics,
+  SensitivityAnalysis,
+  FormulaContext
+} from './types';
+
+// ========================================
+// Random Number Generation
+// ========================================
+
+/**
+ * Simple seeded random number generator (Mulberry32)
+ * Returns Math.random if no seed provided, otherwise a deterministic PRNG
+ */
+function createRng(seed?: number): () => number {
+  if (seed === undefined) {
+    return Math.random;
+  }
+
+  let state = seed;
+  return () => {
+    state |= 0;
+    state = (state + 0x6d2b79f5) | 0;
+    let t = Math.imul(state ^ (state >>> 15), 1 | state);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+// ========================================
+// Distribution Samplers (Optimized - inline functions)
+// ========================================
+
+/**
+ * Sample from triangular distribution
+ */
+function sampleTriangular(
+  min: number,
+  mode: number,
+  max: number,
+  random: () => number
+): number {
+  const u = random();
+  const fc = (mode - min) / (max - min);
+
+  if (u < fc) {
+    return min + Math.sqrt(u * (max - min) * (mode - min));
+  } else {
+    return max - Math.sqrt((1 - u) * (max - min) * (max - mode));
+  }
+}
+
+/**
+ * Sample from normal distribution (Box-Muller transform)
+ */
+function sampleNormal(
+  mean: number,
+  stdDev: number,
+  random: () => number
+): number {
+  const u1 = random();
+  const u2 = random();
+  const z = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+  return mean + stdDev * z;
+}
+
+/**
+ * Sample from uniform distribution
+ */
+function sampleUniform(
+  min: number,
+  max: number,
+  random: () => number
+): number {
+  return min + random() * (max - min);
+}
+
+/**
+ * Sample from discrete distribution
+ */
+function sampleDiscrete(
+  options: number[],
+  weights: number[],
+  random: () => number
+): number {
+  const u = random();
+  let cumulative = 0;
+
+  for (let i = 0; i < options.length; i++) {
+    cumulative += weights[i];
+    if (u <= cumulative) {
+      return options[i];
+    }
+  }
+
+  return options[options.length - 1];
+}
+
+/**
+ * Sample from a compiled variable
+ */
+function sampleVariable(
+  variable: CompiledVariable,
+  random: () => number
+): number {
+  const { distribution, params } = variable;
+
+  switch (distribution) {
+    case 'triangular':
+      return sampleTriangular(params.min!, params.mode!, params.max!, random);
+    case 'normal':
+      return sampleNormal(params.mean!, params.stdDev!, random);
+    case 'uniform':
+      return sampleUniform(params.min!, params.max!, random);
+    case 'discrete':
+      return sampleDiscrete(params.options!, params.weights!, random);
+    default:
+      throw new Error(`Unknown distribution: ${distribution}`);
+  }
+}
+
+// ========================================
+// Statistics Calculation (Optimized)
+// ========================================
+
+/**
+ * Calculate statistics in a single pass where possible.
+ *
+ * Uses native TypedArray.sort() for percentile calculation - V8's implementation
+ * is highly optimized and difficult to beat with JS selection algorithms for
+ * typical percentile counts (5-10).
+ *
+ * Performance characteristics (10K elements):
+ * - Native sort: ~1ms (V8's Timsort on TypedArrays is very fast)
+ * - JS quickselect per percentile: ~0.5ms each, but 7 percentiles = ~3.5ms
+ * - Overhead from JS function calls dominates selection algorithm gains
+ */
+function calculateStatisticsOptimized(
+  history: Float64Array,
+  startIndex: number,
+  count: number,
+  percentilesToCalculate: number[]
+): OutputStatistics {
+  if (count === 0) {
+    return {
+      mean: NaN,
+      median: NaN,
+      stdDev: NaN,
+      min: NaN,
+      max: NaN,
+      percentiles: {},
+      histogram: []
+    };
+  }
+
+  // Single pass for sum, min, max (avoids separate min/max calls)
+  let sum = 0;
+  let min = Infinity;
+  let max = -Infinity;
+
+  for (let i = 0; i < count; i++) {
+    const value = history[startIndex + i];
+    sum += value;
+    if (value < min) min = value;
+    if (value > max) max = value;
+  }
+
+  const meanValue = sum / count;
+
+  // Second pass for variance (Welford's online algorithm has numerical issues
+  // for very large datasets, two-pass is more stable)
+  let sumSquaredDiff = 0;
+  for (let i = 0; i < count; i++) {
+    const diff = history[startIndex + i] - meanValue;
+    sumSquaredDiff += diff * diff;
+  }
+  const stdDevValue = Math.sqrt(sumSquaredDiff / count);
+
+  // Use native TypedArray.sort() - highly optimized in V8
+  // slice() creates a copy, sort() is in-place
+  const sorted = history.slice(startIndex, startIndex + count).sort();
+
+  // Calculate percentiles from sorted array
+  const percentiles: Record<string, number> = {};
+  for (const p of percentilesToCalculate) {
+    const index = (p / 100) * (count - 1);
+    const lower = Math.floor(index);
+    const upper = Math.ceil(index);
+
+    if (lower === upper) {
+      percentiles[`p${p}`] = sorted[lower];
+    } else {
+      const weight = index - lower;
+      percentiles[`p${p}`] = sorted[lower] * (1 - weight) + sorted[upper] * weight;
+    }
+  }
+
+  // Get median (p50) - may already be in percentiles
+  const medianIndex = (count - 1) / 2;
+  const medianLower = Math.floor(medianIndex);
+  const median = medianLower === Math.ceil(medianIndex)
+    ? sorted[medianLower]
+    : (sorted[medianLower] + sorted[medianLower + 1]) / 2;
+
+  return {
+    mean: meanValue,
+    median: percentiles['p50'] ?? median,
+    stdDev: stdDevValue,
+    min,
+    max,
+    percentiles,
+    histogram: []
+  };
+}
+
+// Histogram calculation removed for performance - rarely used in output
+
+/**
+ * Calculate Pearson correlation coefficient (optimized)
+ */
+function correlationOptimized(
+  xHistory: Float64Array,
+  xStart: number,
+  yHistory: Float64Array,
+  yStart: number,
+  count: number
+): number {
+  // First pass: calculate means
+  let sumX = 0;
+  let sumY = 0;
+  for (let i = 0; i < count; i++) {
+    sumX += xHistory[xStart + i];
+    sumY += yHistory[yStart + i];
+  }
+  const meanX = sumX / count;
+  const meanY = sumY / count;
+
+  // Second pass: calculate correlation components
+  let numerator = 0;
+  let denomX = 0;
+  let denomY = 0;
+
+  for (let i = 0; i < count; i++) {
+    const dx = xHistory[xStart + i] - meanX;
+    const dy = yHistory[yStart + i] - meanY;
+    numerator += dx * dy;
+    denomX += dx * dx;
+    denomY += dy * dy;
+  }
+
+  const denominator = Math.sqrt(denomX * denomY);
+  return denominator === 0 ? 0 : numerator / denominator;
+}
+
+// ========================================
+// Strategy Implementation (Optimized)
+// ========================================
+
+export class MonteCarloStrategy {
+  run(
+    ruleSet: CompiledMonteCarloRuleSet,
+    wm: IWorkingMemory,
+    options: MonteCarloOptions = {}
+  ): MonteCarloResult {
+    const startTime = performance.now();
+    const timings: Record<string, number> = {};
+    let phaseStart = startTime;
+
+    const { onIteration, onProgress } = options;
+    const config = ruleSet.config;
+    const iterations = config.iterations;
+    const variableCount = ruleSet.variables.length;
+    const outputCount = ruleSet.outputs.length;
+
+    // Create RNG (seeded if specified for reproducibility)
+    const random = createRng(config.seed);
+
+    // ========================================
+    // Phase 1: Build flat context with fact data
+    // ========================================
+    const ctx: FormulaContext = {};
+
+    // Flatten fact data into context
+    for (const input of ruleSet.inputs) {
+      const facts = wm.getByType(input.type);
+      if (facts.length > 0) {
+        const fact = facts[0] as Fact;
+        // Flatten: ctx['startup.currentRevenue'] = 1000000
+        if (fact.data && typeof fact.data === 'object') {
+          for (const [key, val] of Object.entries(fact.data)) {
+            if (typeof val === 'number') {
+              ctx[`${input.name}.${key}`] = val;
+            } else if (typeof val === 'boolean') {
+              ctx[`${input.name}.${key}`] = val ? 1 : 0;
+            }
+          }
+        }
+      }
+    }
+
+    timings['phase1_context'] = performance.now() - phaseStart;
+    phaseStart = performance.now();
+
+    // ========================================
+    // Phase 2: Pre-allocate TypedArrays for history
+    // ========================================
+    const variableHistory = new Float64Array(variableCount * iterations);
+    const outputHistory = new Float64Array(outputCount * iterations);
+
+    // Variable name -> index mapping
+    const variableIndex: Record<string, number> = {};
+    for (let i = 0; i < variableCount; i++) {
+      variableIndex[ruleSet.variables[i].name] = i;
+    }
+
+    // Output name -> index mapping
+    const outputIndex: Record<string, number> = {};
+    for (let i = 0; i < outputCount; i++) {
+      outputIndex[ruleSet.outputs[i].name] = i;
+    }
+
+    timings['phase2_alloc'] = performance.now() - phaseStart;
+    phaseStart = performance.now();
+
+    // ========================================
+    // Phase 3: Get or build compiled formula evaluators
+    // ========================================
+    const outputEvaluators: ((ctx: FormulaContext) => number)[] = [];
+    for (const output of ruleSet.outputs) {
+      if (output.evaluate) {
+        // Use pre-compiled function
+        outputEvaluators.push(output.evaluate);
+      } else {
+        // Fall back to interpreted evaluation
+        const compiledFormula = output.formula;
+        outputEvaluators.push((evalCtx: FormulaContext) => {
+          // Build binding context for legacy evaluator
+          const bindingContext: Record<string, Fact> = {};
+          for (const [key, value] of Object.entries(evalCtx)) {
+            bindingContext[key] = {
+              id: key,
+              type: '_ctx',
+              data: value as unknown as Record<string, any>
+            };
+            // Also add without dot path for direct variable references
+            if (!key.includes('.')) {
+              bindingContext[key] = {
+                id: key,
+                type: '_var',
+                data: value as unknown as Record<string, any>
+              };
+            }
+          }
+          const result = evaluateCondition(compiledFormula, bindingContext);
+          return typeof result === 'number' ? result : 0;
+        });
+      }
+    }
+
+    timings['phase3_compile'] = performance.now() - phaseStart;
+    phaseStart = performance.now();
+
+    // ========================================
+    // Phase 4: Run simulation iterations
+    // ========================================
+    for (let iter = 0; iter < iterations; iter++) {
+      // Sample all variables and store in context + history
+      for (let v = 0; v < variableCount; v++) {
+        const variable = ruleSet.variables[v];
+        const value = sampleVariable(variable, random);
+        ctx[variable.name] = value;
+        variableHistory[v * iterations + iter] = value;
+      }
+
+      // Evaluate each output formula
+      for (let o = 0; o < outputCount; o++) {
+        const output = ruleSet.outputs[o];
+        const value = outputEvaluators[o](ctx);
+        ctx[output.name] = value;  // Make available for subsequent outputs
+        outputHistory[o * iterations + iter] = value;
+      }
+
+      // Callbacks
+      if (onIteration) {
+        const values: Record<string, number> = {};
+        for (let v = 0; v < variableCount; v++) {
+          values[ruleSet.variables[v].name] = variableHistory[v * iterations + iter];
+        }
+        for (let o = 0; o < outputCount; o++) {
+          values[ruleSet.outputs[o].name] = outputHistory[o * iterations + iter];
+        }
+        onIteration(iter, values);
+      }
+
+      if (onProgress && iter % 1000 === 0) {
+        onProgress((iter / iterations) * 100);
+      }
+    }
+
+    timings['phase4_simulation'] = performance.now() - phaseStart;
+    phaseStart = performance.now();
+
+    // ========================================
+    // Phase 5: Calculate statistics
+    // ========================================
+    const outputStats: Record<string, OutputStatistics> = {};
+    for (let o = 0; o < outputCount; o++) {
+      const output = ruleSet.outputs[o];
+      outputStats[output.name] = calculateStatisticsOptimized(
+        outputHistory,
+        o * iterations,
+        iterations,
+        config.percentiles!
+      );
+    }
+
+    timings['phase5_stats'] = performance.now() - phaseStart;
+    phaseStart = performance.now();
+
+    // ========================================
+    // Phase 6: Sensitivity analysis (optional)
+    // ========================================
+    const sensitivity: SensitivityAnalysis = {};
+
+    if (config.includeSensitivity) {
+      for (let o = 0; o < outputCount; o++) {
+        const outputName = ruleSet.outputs[o].name;
+        sensitivity[outputName] = {};
+
+        for (let v = 0; v < variableCount; v++) {
+          const variableName = ruleSet.variables[v].name;
+          const corr = correlationOptimized(
+            variableHistory,
+            v * iterations,
+            outputHistory,
+            o * iterations,
+            iterations
+          );
+          sensitivity[outputName][variableName] = Math.abs(corr);
+        }
+      }
+    }
+
+    timings['phase6_sensitivity'] = performance.now() - phaseStart;
+    phaseStart = performance.now();
+
+    // ========================================
+    // Phase 7: Build result
+    // ========================================
+    const probability = (query: Condition): number => {
+      const compiled = compileCondition(query);
+      let count = 0;
+
+      for (let iter = 0; iter < iterations; iter++) {
+        // Build binding context for this iteration
+        const bindingContext: Record<string, Fact> = {};
+
+        for (let v = 0; v < variableCount; v++) {
+          const name = ruleSet.variables[v].name;
+          bindingContext[name] = {
+            id: name,
+            type: '_variable',
+            data: variableHistory[v * iterations + iter] as unknown as Record<string, any>
+          };
+        }
+
+        for (let o = 0; o < outputCount; o++) {
+          const name = ruleSet.outputs[o].name;
+          bindingContext[name] = {
+            id: name,
+            type: '_output',
+            data: outputHistory[o * iterations + iter] as unknown as Record<string, any>
+          };
+        }
+
+        if (evaluateCondition(compiled, bindingContext)) {
+          count++;
+        }
+      }
+
+      return count / iterations;
+    };
+
+    const executionTimeMs = Math.round((performance.now() - startTime) * 100) / 100;
+
+    timings['phase7_probability_fn'] = performance.now() - phaseStart;
+
+    // Lazy rawData - only convert TypedArrays when accessed (saves ~70ms)
+    const variableNames = ruleSet.variables.map(v => v.name);
+    const outputNames = ruleSet.outputs.map(o => o.name);
+    let rawDataCache: { variables: Record<string, number[]>; outputs: Record<string, number[]> } | null = null;
+
+    const rawData = {
+      get variables(): Record<string, number[]> {
+        if (!rawDataCache) {
+          rawDataCache = { variables: {}, outputs: {} };
+          for (let v = 0; v < variableCount; v++) {
+            rawDataCache.variables[variableNames[v]] = Array.from(
+              variableHistory.subarray(v * iterations, (v + 1) * iterations)
+            );
+          }
+          for (let o = 0; o < outputCount; o++) {
+            rawDataCache.outputs[outputNames[o]] = Array.from(
+              outputHistory.subarray(o * iterations, (o + 1) * iterations)
+            );
+          }
+        }
+        return rawDataCache.variables;
+      },
+      get outputs(): Record<string, number[]> {
+        if (!rawDataCache) {
+          rawDataCache = { variables: {}, outputs: {} };
+          for (let v = 0; v < variableCount; v++) {
+            rawDataCache.variables[variableNames[v]] = Array.from(
+              variableHistory.subarray(v * iterations, (v + 1) * iterations)
+            );
+          }
+          for (let o = 0; o < outputCount; o++) {
+            rawDataCache.outputs[outputNames[o]] = Array.from(
+              outputHistory.subarray(o * iterations, (o + 1) * iterations)
+            );
+          }
+        }
+        return rawDataCache.outputs;
+      }
+    };
+
+    // Log timings for performance analysis
+    console.log('MC Timings:', JSON.stringify(timings));
+
+    return {
+      iterations,
+      outputs: outputStats,
+      sensitivity,
+      executionTimeMs,
+      probability,
+      rawData
+    };
+  }
+}
+
+// Export singleton instance
+export const monteCarloStrategy = new MonteCarloStrategy();