EVOLV/wiki/knowledge-graph.yaml

# Knowledge Graph — structured data with provenance
# Every claim has: value, source (file/commit), date, status

# ── TESTS ──
tests:
  rotatingMachine:
    basic:
      count: 10
      passing: 10
      file: nodes/rotatingMachine/test/basic/
      date: 2026-04-07
    integration:
      count: 16
      passing: 16
      file: nodes/rotatingMachine/test/integration/
      date: 2026-04-07
    edge:
      count: 17
      passing: 17
      file: nodes/rotatingMachine/test/edge/
      date: 2026-04-07
  machineGroupControl:
    basic:
      count: 1
      passing: 1
      file: nodes/machineGroupControl/test/basic/
      date: 2026-04-07
    integration:
      count: 3
      passing: 3
      file: nodes/machineGroupControl/test/integration/
      date: 2026-04-07
    edge:
      count: 1
      passing: 1
      file: nodes/machineGroupControl/test/edge/
      date: 2026-04-07

# ── METRICS ──
metrics:
  optimization_gap_to_brute_force:
    value: "0.1% max"
    source: distribution-power-table.integration.test.js
    date: 2026-04-07
    conditions: "3 pumps, 1000-step brute force, 0.05% flow tolerance"
  optimization_time_median:
    value: "0.027-0.153ms"
    source: benchmark script
    date: 2026-04-07
    conditions: "3 pumps, 6 combinations, BEP-Gravitation + refinement"
  pump_switching_stability:
    value: "1-2 transitions across 5-95% demand"
    source: stability sweep
    date: 2026-04-07
    conditions: "2% demand steps, both ascending and descending"
  pump_curves:
    H05K-S03R:
      pressure_levels: 33
      pressure_range: "700-3900 mbar"
      flow_range: "28-227 m3/h (at 2000 mbar)"
      data_points_per_level: 5
      anomalies_fixed: 3
      date: 2026-04-07
    C5-D03R-SHN1:
      pressure_levels: 26
      pressure_range: "400-2900 mbar"
      flow_range: "6-53 m3/h"
      data_points_per_level: 5
      non_convex: true
      date: 2026-04-07

# ── DISPROVEN CLAIMS ──
disproven:
  ncog_proportional_weight:
    claimed: "Distributing flow proportional to NCog weights is optimal"
    claimed_date: 2026-04-07
    disproven_date: 2026-04-07
    evidence_for: "Simple implementation in calcBestCombination"
    evidence_against: "Starves small pumps (NCog=0 gets zero flow), overloads large pumps at high demand. BEP-target + scale is correct approach."
    root_cause: "NCog is a position indicator (0-1 on flow range), not a distribution weight"
  efficiency_rounding:
    claimed: "Math.round(flow/power * 100) / 100 preserves BEP signal"
    claimed_date: pre-2026-04-07
    disproven_date: 2026-04-07
    evidence_for: "Removes floating point noise"
    evidence_against: "In canonical units (m3/s and W), Q/P ratio is ~1e-6. Rounding to 2 decimals produces 0 for all points. NCog, cog, BEP all became 0."
    root_cause: "Canonical units make the ratio very small — rounding destroys the signal"
  equal_marginal_cost_optimal:
    claimed: "Equal dP/dQ across pumps guarantees global power minimum"
    claimed_date: 2026-04-07
    disproven_date: 2026-04-07
    evidence_for: "KKT conditions for convex functions"
    evidence_against: "C5 pump curve is non-convex (dP/dQ dips from 1.3M to 453K then rises). Sparse data (5 points) causes spline artifacts."
    root_cause: "Convexity assumption fails with interpolated curves from sparse data"

# ── PERFORMANCE ──
performance:
  mgc_optimization:
    median_ms: 0.09
    p99_ms: 0.5
    tick_budget_pct: 0.015
    source: benchmark script
    date: 2026-04-07
  predict_y_call:
    complexity: "O(log n), ~O(1) for 5-10 data points"
    source: predict_class.js

# ── ARCHITECTURE ──
architecture:
  canonical_units:
    pressure: Pa
    flow: "m3/s"
    power: W
    temperature: K
  output_units:
    pressure: mbar
    flow: "m3/h"
    power: kW
    temperature: C
  node_count: 13
  submodules: 12

# ── BUGS FIXED ──
bugs_fixed:
  flowmovement_unit_mismatch:
    severity: critical
    description: "machineGroupControl sent flow in canonical (m3/s) but rotatingMachine flowmovement expected output units (m3/h). Every pump stayed at minimum."
    fix: "_canonicalToOutputFlow() conversion before all flowmovement calls"
    commit: d55f401
    date: 2026-04-07
  emergencystop_case:
    severity: critical
    description: "specificClass called executeSequence('emergencyStop') but config key was 'emergencystop'"
    fix: "Lowercase to match config"
    commit: 07af7ce
    date: 2026-04-07
  curve_data_anomalies:
    severity: high
    description: "3 flow values leaked into power column in hidrostal-H05K-S03R.json at pressures 1600, 3200, 3300 mbar"
    fix: "Linearly interpolated correct values from adjacent levels"
    commit: 024db55
    date: 2026-04-07
  efficiency_rounding:
    severity: high
    description: "Math.round(Q/P * 100) / 100 destroyed all NCog/BEP calculations"
    fix: "Removed rounding, use raw ratio"
    commit: 07af7ce
    date: 2026-04-07
  absolute_scaling_bug:
    severity: high
    description: "handleInput compared demandQout (always 0) instead of demandQ for max cap"
    fix: "Reordered conditions, use demandQ throughout"
    commit: d55f401
    date: 2026-04-07

# ── TIMELINE ──
timeline:
  - {date: 2026-04-07, commit: 024db55, desc: "Fix 3 anomalous power values in hidrostal curve"}
  - {date: 2026-04-07, commit: 07af7ce, desc: "rotatingMachine production hardening: safety + prediction + 43 tests"}
  - {date: 2026-04-07, commit: d55f401, desc: "machineGroupControl: unit fix + refinement + stability tests"}
  - {date: 2026-04-07, commit: fd9d167, desc: "Update EVOLV submodule refs"}