docs: initialize project wiki from production hardening session
12 pages covering architecture, findings, and metrics from the rotatingMachine + machineGroupControl hardening work: - Overview: node inventory, what works/doesn't, current scale - Architecture: 3D pump curves, group optimization algorithm - Findings: BEP-Gravitation proof (0.1% of optimum), NCog behavior, curve non-convexity, pump switching stability - Metrics: test counts, power comparison table, performance numbers - Knowledge graph: structured YAML with all data points and provenance - Session log: 2026-04-07 production hardening - Tools: query.py, search.sh, lint.sh Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
znetsixe
161
wiki/knowledge-graph.yaml
Normal file
161
wiki/knowledge-graph.yaml
Normal file
@@ -0,0 +1,161 @@
|
||||
# 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"}
|
||||
Reference in New Issue
Block a user