docs(bmad): sync status and renumber Epic 8 (Fluid-Component integration)

2026-02-20 22:29:42 +01:00 · 2026-02-20 22:29:42 +01:00 · 2d3d19665b
commit 2d3d19665b
parent 3dbdfba967
6 changed files with 804 additions and 3 deletions
--- a/_bmad-output/implementation-artifacts/1-8-auxiliary-and-transport-components.md
+++ b/_bmad-output/implementation-artifacts/1-8-auxiliary-and-transport-components.md
@ -0,0 +1,200 @@
+# Story 1.8: Auxiliary & Transport Components (Enhanced)
+
+Status: done
+
+## Story
+
+As a system integrator,
+I want to model Pumps, Fans, Pipes with supplier curves and external DLL/API support,
+So that I can simulate complete HVAC systems with accurate manufacturer data.
+
+## Acceptance Criteria
+
+1. **Pump Component** (AC: #1)
+   - [x] Create `Pump` component with polynomial curves (Q-H, efficiency, power)
+   - [x] Implement 3rd-order polynomial: H = a0 + a1*Q + a2*Q² + a3*Q³
+   - [x] Implement efficiency curve: η = b0 + b1*Q + b2*Q²
+   - [x] Affinity laws integration for VFD speed control
+   - [x] Implement `Component` trait
+
+2. **Fan Component** (AC: #2)
+   - [x] Create `Fan` component with polynomial curves (Q-P, efficiency, power)
+   - [x] Implement 3rd-order polynomial: P_static = a0 + a1*Q + a2*Q² + a3*Q³
+   - [x] Implement efficiency curve
+   - [x] Affinity laws integration for VFD speed control
+   - [x] Implement `Component` trait
+
+3. **Pipe Component** (AC: #3)
+   - [x] Create `Pipe` component with length and diameter
+   - [x] Implement Darcy-Weisbach pressure drop
+   - [x] Implement Haaland friction factor approximation
+   - [x] Implement `Component` trait
+
+4. **Compressor AHRI Enhancement** (AC: #4)
+   - [x] Add 2D polynomial curves: m_dot = f(SST, SDT)
+   - [x] Add 2D polynomial curves: Power = g(SST, SDT)
+   - [x] Keep existing AHRI 540 coefficients as alternative
+
+5. **External Component Interface** (AC: #5)
+   - [x] Create `ExternalModel` trait for DLL/API components
+   - [x] Implement FFI loader via libloading for .so/.dll (stub)
+   - [x] Implement HTTP client for API-based models (stub)
+   - [x] Thread-safe wrapper for external calls
+
+6. **State Management** (AC: #6)
+   - [x] Implement `StateManageable` for Pump
+   - [x] Implement `StateManageable` for Fan
+   - [x] Implement `StateManageable` for Pipe
+
+7. **Testing** (AC: #7)
+   - [x] Unit tests for pump curves and affinity laws
+   - [x] Unit tests for fan curves
+   - [x] Unit tests for pipe pressure drop
+   - [x] Unit tests for 2D polynomial curves
+   - [x] Mock tests for external model interface
+
+## Tasks / Subtasks
+
+- [x] Create polynomial curve module (AC: #1, #2, #4)
+  - [x] Define `PolynomialCurve` struct with coefficients
+  - [x] Implement 1D polynomial evaluation (pump/fan curves)
+  - [x] Implement 2D polynomial evaluation (compressor SST/SDT)
+  - [x] Add validation for coefficients
+
+- [x] Create Pump component (AC: #1)
+  - [x] Define Pump struct with ports, curves, VFD support
+  - [x] Implement Q-H curve: H = a0 + a1*Q + a2*Q² + a3*Q³
+  - [x] Implement efficiency curve: η = f(Q)
+  - [x] Implement hydraulic power: P_hydraulic = ρ*g*Q*H/η
+  - [x] Apply affinity laws when speed_ratio != 1.0
+  - [x] Implement Component trait
+
+- [x] Create Fan component (AC: #2)
+  - [x] Define Fan struct with ports, curves, VFD support
+  - [x] Implement static pressure curve: P = a0 + a1*Q + a2*Q² + a3*Q³
+  - [x] Implement efficiency curve
+  - [x] Apply affinity laws for VFD
+  - [x] Implement Component trait
+
+- [x] Create Pipe component (AC: #3)
+  - [x] Define Pipe struct with length, diameter, roughness
+  - [x] Implement Haaland friction factor: 1/√f = -1.8*log10[(ε/D/3.7)^1.11 + 6.9/Re]
+  - [x] Implement Darcy-Weisbach: ΔP = f * (L/D) * (ρv²/2)
+  - [x] Implement Component trait
+
+- [x] Enhance Compressor with 2D curves (AC: #4)
+  - [x] Add `SstSdtCoefficients` struct for 2D polynomials
+  - [x] Implement mass_flow = Σ(a_ij * SST^i * SDT^j)
+  - [x] Implement power = Σ(b_ij * SST^i * SDT^j)
+  - [x] Add enum to select AHRI vs SST/SDT model
+
+- [x] Create External Model Interface (AC: #5)
+  - [x] Define `ExternalModel` trait
+  - [x] Create `FfiModel` wrapper using libloading (stub)
+  - [x] Create `HttpModel` wrapper using reqwest (stub)
+  - [x] Thread-safe error handling for external calls
+
+- [x] Add StateManageable implementations (AC: #6)
+  - [x] Implement for Pump
+  - [x] Implement for Fan
+  - [x] Implement for Pipe
+
+- [x] Write tests (AC: #7)
+  - [x] Test polynomial curve evaluation
+  - [x] Test pump Q-H and efficiency curves
+  - [x] Test fan static pressure curves
+  - [x] Test affinity laws (speed variation)
+  - [x] Test pipe pressure drop with Haaland
+  - [x] Test 2D polynomial for compressor
+  - [x] Test external model mock interface
+
+## Dev Notes
+
+### Key Formulas
+
+**Pump/Fan Polynomial Curves:**
+```
+H = a0 + a1*Q + a2*Q² + a3*Q³  (Head/Pressure curve)
+η = b0 + b1*Q + b2*Q²          (Efficiency curve)
+P_hydraulic = ρ*g*Q*H/η        (Power consumption)
+```
+
+**Affinity Laws (VFD):**
+```
+Q2/Q1 = N2/N1
+H2/H1 = (N2/N1)²
+P2/P1 = (N2/N1)³
+```
+
+**2D Polynomial for Compressor (SST/SDT):**
+```
+m_dot = Σ a_ij * SST^i * SDT^j  (i,j = 0,1,2...)
+Power = Σ b_ij * SST^i * SDT^j
+SST = Saturated Suction Temperature
+SDT = Saturated Discharge Temperature
+```
+
+**Darcy-Weisbach + Haaland:**
+```
+ΔP = f * (L/D) * (ρ * v² / 2)
+1/√f = -1.8 * log10[(ε/D/3.7)^1.11 + 6.9/Re]
+```
+
+### File Locations
+- `crates/components/src/pump.rs`
+- `crates/components/src/fan.rs`
+- `crates/components/src/pipe.rs`
+- `crates/components/src/polynomials.rs`
+- `crates/components/src/external_model.rs`
+
+## Dev Agent Record
+
+### Agent Model Used
+Claude (Anthropic)
+
+### Implementation Plan
+1. Created polynomial module with 1D and 2D polynomial support
+2. Implemented Pump with Q-H curves, efficiency, and affinity laws
+3. Implemented Fan with static pressure curves and affinity laws
+4. Implemented Pipe with Darcy-Weisbach and Haaland friction factor
+5. Created ExternalModel trait with FFI and HTTP stubs
+6. Added StateManageable for all new components
+7. Comprehensive unit tests for all components
+
+### File List
+
+**New Files:**
+- crates/components/src/polynomials.rs
+- crates/components/src/pump.rs
+- crates/components/src/fan.rs
+- crates/components/src/pipe.rs
+- crates/components/src/external_model.rs
+
+**Modified Files:**
+- crates/components/src/lib.rs
+
+### Completion Notes
+- Pump, Fan, and Pipe components fully implemented
+- All polynomial curve types (1D and 2D) working
+- External model interface provides extensibility for vendor DLLs/APIs
+- All tests passing (265 tests)
+
+### Change Log
+- 2026-02-15: Initial implementation of polynomials, pump, fan, pipe, external_model
+- 2026-02-15: Added StateManageable implementations for all new components
+- 2026-02-15: All tests passing
+- 2026-02-17: **CODE REVIEW FIXES APPLIED:**
+  - **AC #4 Fixed**: Updated `Compressor` struct to use `CompressorModel` enum (supports both AHRI 540 and SST/SDT models)
+    - Changed struct field from `coefficients: Ahri540Coefficients` to `model: CompressorModel`
+    - Added `with_model()` constructor for SST/SDT model selection
+    - Updated `mass_flow_rate()` to accept SST/SDT temperatures
+    - Updated power methods to use selected model
+    - Added `ahri540_coefficients()` and `sst_sdt_coefficients()` getter methods
+  - **AC #5 Fixed**: Made external model stubs functional
+    - `FfiModel::new()` now creates working mock (identity function) instead of returning error
+    - `HttpModel::new()` now creates working mock (identity function) instead of returning error
+    - Both stubs properly validate inputs and return identity-like Jacobian matrices
+  - **Error Handling Fixed**: Added proper handling for `speed_ratio=0` in `Pump::pressure_rise()`, `Pump::efficiency()`, `Fan::static_pressure_rise()`, and `Fan::efficiency()` to prevent infinity/NaN issues
+  - All 297 tests passing
+
+---
--- a/_bmad-output/implementation-artifacts/3-5-zero-flow-branch-handling.md
+++ b/_bmad-output/implementation-artifacts/3-5-zero-flow-branch-handling.md
@ -0,0 +1,232 @@
+# Story 3.5: Zero-Flow Branch Handling
+
+Status: done
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a simulation user,
+I want zero-flow handling with regularization,
+so that OFF components don't cause numerical instabilities.
+
+## Acceptance Criteria
+
+1. **No Division-by-Zero** (AC: #1)
+   - Given a branch with mass flow = 0 (e.g. component in Off state)
+   - When computing residuals
+   - Then no division-by-zero occurs anywhere in component or solver code
+   - And all expressions that divide by mass flow (or by quantities derived from it) use regularization
+
+2. **Regularization Applied** (AC: #2)
+   - Given expressions of the form f(ṁ) where ṁ appears in denominator (e.g. Q/ṁ, ΔP/ṁ², Re = ρvD/μ with v∝ṁ)
+   - When ṁ is near or equal to zero
+   - Then a small epsilon (ε) is used in denominators (e.g. ṁ_eff = max(ṁ, ε) or 1/(ṁ + ε) with ε documented)
+   - And ε is chosen to avoid NaN/Inf while preserving solver convergence (e.g. 1e-12 kg/s or project constant)
+
+3. **Pressure Continuity When OFF** (AC: #3)
+    - Given a component in Off state (zero mass flow)
+    - When assembling residuals and Jacobian
+    - Then the branch produces consistent residuals (for Pipe: ṁ = 0 which blocks flow; for other components may use P_in = P_out where appropriate)
+    - And residual/Jacobian remain consistent (no singular rows/columns)
+    - **Note**: "Pressure continuity" in the original spec was misleading. For a Pipe, Off means blocked (ṁ = 0), not P_in = P_out. P_in = P_out would be BYPASS mode.
+
+4. **Well-Conditioned Jacobian** (AC: #4)
+   - Given a system with one or more zero-flow branches
+   - When the Jacobian is assembled
+   - Then the Jacobian remains well-conditioned (no zero rows, no degenerate columns from 0/0)
+   - And regularization does not introduce spurious convergence or destroy physical meaning
+
+## Tasks / Subtasks
+
+- [x] Define zero-flow regularization constant (AC: #1, #2)
+  - [x] Add `MIN_MASS_FLOW_REGULARIZATION` (e.g. 1e-12 kg/s) in a single place (core or solver)
+  - [x] Document when to use: any division by mass flow or by Re/capacity-rate derived from ṁ
+  - [x] Use `MassFlow::max(self, MIN)` or equivalent in components that divide by ṁ
+- [x] Audit and fix component residual/Jacobian for zero flow (AC: #1, #2)
+  - [x] Pipe: ensure Re and friction factor never divide by zero (already has reynolds.max(1.0) in simplified; extend to Haaland/Swamee-Jain if needed)
+  - [x] Heat exchangers: ε-NTU and LMTD already use c_min < 1e-10 and dt guards; confirm all paths and document ε
+  - [x] Compressor, expansion valve, pump, fan: already set ṁ residual to 0 when Off; ensure no other division by ṁ in same component
+  - [x] Any formula Q/ṁ or ΔP/ṁ²: use regularized denominator
+- [x] Pressure continuity for OFF branches (AC: #3)
+  - [x] When component is Off, residual for that branch: use P_in - P_out = 0 (and h continuity if needed) instead of flow equation
+  - [x] Ensure state vector and equation ordering support this (solver/system already use component.compute_residuals; components already return different residuals for Off)
+  - [x] Document in solver or component trait how Off is communicated (state machine / OperationalState)
+- [x] Jacobian consistency for zero-flow (AC: #4)
+  - [x] Components that switch to pressure-continuity when Off must provide correct Jacobian entries (∂(P_in - P_out)/∂P_in, ∂/∂P_out)
+  - [x] No zero rows: every equation must depend on state; use regularization so derivatives exist
+  - [x] Add unit test: system with one branch Off, solve or one Newton step, no NaN/Inf in residuals or Jacobian
+- [x] Tests
+  - [x] Test: single branch with ṁ = 0, residuals computed without panic, no NaN/Inf
+  - [x] Test: Jacobian assembled for system with one Off component, no zero row, finite entries
+  - [x] Test: regularization constant used in at least one component (e.g. Pipe or heat exchanger) and documented
+  - [x] Test: small non-zero ṁ (e.g. 1e-10) vs regular ṁ produces consistent behavior (no discontinuity at 0)
+
+## Dev Notes
+
+### Epic Context
+
+**Epic 3: System Topology (Graph)** — Enable component assembly via Ports and manage multi-circuits with thermal coupling. FR13 (zero-flow branch handling) maps to `crates/solver` and `crates/components`.
+
+**Story Dependencies:**
+- Story 3.1 (System graph structure) — done
+- Story 3.2 (Port compatibility validation) — done
+- Story 3.3 (Multi-circuit machine definition) — done
+- Story 3.4 (Thermal coupling) — done
+- Epic 1 (Component trait, state machine OFF/BYPASS) — done; components already implement Off with zero mass flow residual
+
+### Architecture Context
+
+**Technical Stack:**
+- Rust, entropyk-core (MassFlow, Pressure, NewType), entropyk-components (Component, state machine), entropyk-solver (residual/Jacobian assembly)
+- No new external crates; use existing constants and types
+
+**Code Structure:**
+- `crates/core/src/types.rs` or `crates/solver` — single constant for MIN_MASS_FLOW_REGULARIZATION (or MIN_REYNOLDS_REGULARIZATION if preferred)
+- `crates/components/src/pipe.rs` — friction factor and Reynolds already guard; ensure all code paths use regularization
+- `crates/components/src/heat_exchanger/` — eps_ntu.rs, lmtd.rs already use 1e-10 guards; document and align with project ε
+- `crates/components/src/compressor.rs`, `expansion_valve.rs`, `pump.rs`, `fan.rs` — Off residuals already set (e.g. residuals[0] = state[0] for ṁ); ensure no division by ṁ elsewhere
+- `crates/solver/src/system.rs` — compute_residuals, assemble_jacobian call into components; no change needed if components are fixed
+
+**Relevant Architecture:**
+- **FR13:** System mathematically handles zero-flow branches without division by zero (epics.md)
+- **NFR7:** Zero-Panic Policy (architecture)
+- **Component Trait:** compute_residuals(state, residuals), jacobian_entries(state, jacobian) — components must return well-defined residuals and derivatives for all states including ṁ = 0
+- **Pre-allocation / no allocation in hot path** — regularization must be a constant or simple max; no heap in solver loop
+
+### Developer Context
+
+**Existing Implementation:**
+- **Pipe:** `FrictionFactor::simplified` uses `reynolds.max(1.0)`; Haaland/Swamee-Jain use `reynolds <= 0.0` → return 0.02. Ensure Re = ρvD/μ never has zero denominator (v ∝ ṁ); use max(ṁ, ε) or max(Re, 1.0) where Re is computed.
+- **Heat exchangers:** eps_ntu uses `c_min < 1e-10` → return 0.0 heat transfer; LMTD uses `dt1.abs() < 1e-10`, `(dt1-dt2).abs()/...max(1e-10)`. C_min = ṁ·Cp; when ṁ = 0, c_min = 0 already guarded.
+- **Compressor / Pump / Fan / Expansion valve:** In Off state, mass-flow residual is set to zero (or state[0]) and power/heat to zero; no division by ṁ in those paths. Audit any shared helpers that compute Q/ṁ or similar.
+- **State machine:** OperationalState::Off is already used; components already branch on state for residuals.
+
+**Design Decisions:**
+1. **Where to put ε:** Prefer one constant in `entropyk_core` (e.g. `types.rs` or a small `constants` module) so both solver and components can use it without circular dependency. Alternative: solver and components each define the same value and a test asserts equality.
+2. **Pressure continuity for Off:** Components already implement Off by zeroing flow residual. If the residual is “ṁ - 0 = 0” and state holds ṁ, that’s already correct. For branches where the unknown is P/h and ṁ is fixed to 0, the equation can be P_in = P_out (and h_in = h_out) so the Jacobian has full rank. Confirm with current state layout (edges hold P, h; components get state slice).
+3. **Regularization formula:** Use `effective_mass_flow = mass_flow.max(MIN_MASS_FLOW_REGULARIZATION)` for any term that divides by ṁ, or `denom = mass_flow + MIN_MASS_FLOW_REGULARIZATION` where appropriate. Prefer max so that at ṁ = 0 we use ε and at ṁ > ε we use real ṁ.
+
+### Technical Requirements
+
+**Regularization:**
+- Define `MIN_MASS_FLOW_REGULARIZATION` (e.g. 1e-12 kg/s). Use `MassFlow` NewType and `max(self, MassFlow::from_kg_per_s(MIN))` or equivalent.
+- Any expression dividing by ṁ (or by Re, C_min, etc. derived from ṁ) must use regularized value in denominator.
+- Document in rustdoc: “When mass flow is zero or below MIN_MASS_FLOW_REGULARIZATION, denominators use regularization to avoid division by zero.”
+
+**Pressure continuity (Off):**
+- For a component in Off state, residuals must enforce physical consistency (e.g. P_in = P_out, h_in = h_out) so the system is well-posed.
+- Jacobian entries for those equations must be non-zero where they depend on P_in, P_out (and h if applicable).
+
+**Error handling:**
+- No panics; no unwrap/expect in residual or Jacobian code paths for zero flow.
+- Return finite f64; use regularization so that NaN/Inf never occur.
+
+### Architecture Compliance
+
+- **NewType pattern:** Use `MassFlow`, `Pressure`, `Enthalpy` from core; regularization constant can be `MassFlow` or f64 in kg/s documented.
+- **No bare f64** in public API where physical meaning exists.
+- **tracing:** Optional `tracing::debug!` when regularization is applied (e.g. “zero-flow branch regularized”) to aid debugging.
+- **Result<T, E>** where applicable; no panic in production.
+- **approx** for float tests; use epsilon consistent with 1e-9 kg/s mass balance and 1e-6 energy.
+
+### Library/Framework Requirements
+
+- **entropyk_core:** MassFlow, Pressure, Enthalpy; add or use constant for MIN_MASS_FLOW_REGULARIZATION.
+- **entropyk_components:** Component, OperationalState, compute_residuals, jacobian_entries, get_ports; Pipe, heat exchanger models, compressor, pump, fan, expansion valve.
+- **entropyk_solver:** System::compute_residuals, assemble_jacobian; no API change required if components are fixed.
+
+### File Structure Requirements
+
+**Modified files (likely):**
+- `crates/core/src/types.rs` or new `crates/core/src/constants.rs` — MIN_MASS_FLOW_REGULARIZATION (and re-export)
+- `crates/components/src/pipe.rs` — ensure all friction/Re paths use regularization
+- `crates/components/src/heat_exchanger/eps_ntu.rs` — document 1e-10 as c_min/c_r regularization; align with core constant if desired
+- `crates/components/src/heat_exchanger/lmtd.rs` — document dt regularization
+- Any component that divides by ṁ (search for `/ m_dot`, `/ mass_flow`, `/ ṁ` and add max(ṁ, ε))
+
+**New files (optional):**
+- None required; constants can live in existing types or a small constants module.
+
+**Tests:**
+- Unit tests in components (pipe, heat exchanger) for ṁ = 0 and ṁ = ε.
+- Integration test in solver: build small graph with one branch Off, call compute_residuals and assemble_jacobian, assert no NaN/Inf and no zero row.
+
+### Testing Requirements
+
+- **Unit (components):** Residual and Jacobian at ṁ = 0 and at ṁ = MIN_MASS_FLOW_REGULARIZATION; all values finite.
+- **Unit (solver):** System with one node in Off state; residuals and Jacobian assembled; no panic, no NaN/Inf; optional one Newton step.
+- **Regression:** Existing tests (e.g. 3-2, 3-4, component tests) must still pass; regularization must not change behavior when ṁ >> ε.
+- Use `approx::assert_relative_eq` with epsilon 1e-6 or 1e-9 as appropriate; assert `residuals.iter().all(|r| r.is_finite())`, `jacobian_entries.all(|(_, _, v)| v.is_finite())`.
+
+### Previous Story Intelligence (3.4)
+
+- Thermal coupling uses coupling_residuals and coupling_jacobian_entries; no mass flow in coupling (heat only).
+- System has thermal_couplings, circuit_id, multi-circuit; zero-flow is per-branch (per edge/component), not per circuit.
+- Story 3.4 noted “Story 3.5 (Zero-flow) — independent”; 3.5 can be implemented without changing coupling.
+- Components already implement Off; 3.5 is about ensuring no division-by-zero and well-conditioned Jacobian when Off (or any branch with ṁ = 0).
+
+### Project Context Reference
+
+- **FR13:** [Source: _bmad-output/planning-artifacts/epics.md — System mathematically handles zero-flow branches without division by zero]
+- **NFR7 Zero-Panic:** [Source: _bmad-output/planning-artifacts/architecture.md]
+- **Mass balance 1e-9 kg/s, Energy 1e-6 kW:** [Source: architecture, epics]
+- **Pipe friction:** [Source: crates/components/src/pipe.rs — FrictionFactor, reynolds.max(1.0)]
+- **ε-NTU c_min guard:** [Source: crates/components/src/heat_exchanger/eps_ntu.rs — c_min < 1e-10]
+
+### Story Completion Status
+
+- **Status:** done
+- **Completion note:** Implementation complete with code review fixes. MIN_MASS_FLOW_REGULARIZATION in core; Pipe friction (Haaland/Swamee-Jain) and heat exchanger (ε-NTU, LMTD) documented/regularized; solver test for zero-flow branch residuals/Jacobian with zero-row check; small non-zero flow continuity test added.
+
+## Change Log
+
+- 2026-02-18: **Code Review Fixes** — Fixed MockComponent to provide Jacobian entries (was causing zero-row bug). Added zero-row check to test_zero_flow_branch_residuals_and_jacobian_finite. Added test_pipe_small_nonzero_flow_continuity. Added import of MIN_MASS_FLOW_REGULARIZATION_KG_S in pipe.rs friction_factor module. Improved eps_ntu.rs documentation referencing project constant. Clarified AC#3 (pressure continuity is not literal P_in=P_out for Pipe Off). All tests pass; status → done.
+- 2026-02-17: Story 3.5 implementation. Core: MIN_MASS_FLOW_REGULARIZATION_KG_S and MassFlow::regularized(). Pipe: Re regularization in haaland/swamee_jain; zero-flow tests. Heat exchangers: doc/comment for c_min and LMTD guards. Solver: test_zero_flow_branch_residuals_and_jacobian_finite. All ACs satisfied; status → review.
+
+## Senior Developer Review (AI)
+
+**Reviewer:** Claude (GLM-5) on 2026-02-18
+
+### Issues Found and Fixed
+
+1. **[HIGH] MockComponent missing Jacobian entries** — `MockComponent::jacobian_entries` was empty, causing zero-row Jacobian bug. Fixed by adding identity entries.
+
+2. **[HIGH] Missing zero-row check in test** — `test_zero_flow_branch_residuals_and_jacobian_finite` only checked for finite values, not zero rows. Fixed by adding row non-zero assertion.
+
+3. **[HIGH] Missing small non-zero flow test** — Task required continuity test at ṁ = ε. Added `test_pipe_small_nonzero_flow_continuity`.
+
+4. **[MEDIUM] MIN_MASS_FLOW_REGULARIZATION_KG_S not imported** — pipe.rs friction_factor module used local constant without referencing project constant. Fixed by adding import and documentation.
+
+5. **[MEDIUM] eps_ntu.rs documentation incomplete** — Added reference to MIN_MASS_FLOW_REGULARIZATION_KG_S explaining different epsilon scales.
+
+6. **[LOW] AC#3 misleading wording** — Clarified that "pressure continuity" doesn't mean P_in = P_out for Pipe Off (that's BYPASS). Pipe Off means ṁ = 0 (blocked).
+
+## Dev Agent Record
+
+### Agent Model Used
+
+{{agent_model_name_version}}
+
+### Debug Log References
+
+N/A
+
+### Completion Notes List
+
+- Added `MIN_MASS_FLOW_REGULARIZATION_KG_S` (1e-12 kg/s) and `MassFlow::regularized()` in `crates/core/src/types.rs`; re-exported from lib.
+- Pipe: `friction_factor::haaland` and `swamee_jain` clamp Reynolds to at least 1.0 to avoid division by zero; added tests for Re=0 and small Re and for `pressure_drop(0)` / `pressure_drop(1e-15)`.
+- Heat exchangers: documented zero-flow regularization in `eps_ntu.rs` (c_min < 1e-10) and added comment in `lmtd.rs` for dt guards.
+- Solver: added `test_zero_flow_branch_residuals_and_jacobian_finite` (mock Off branch, state=0, residuals and Jacobian all finite).
+- All tests pass for core, components, solver (fluids crate not tested due to CoolProp build).
+
+### File List
+
+- crates/core/src/types.rs (modified: MIN_MASS_FLOW_REGULARIZATION_KG_S, MassFlow::regularized(), test_mass_flow_regularized)
+- crates/core/src/lib.rs (modified: re-export MIN_MASS_FLOW_REGULARIZATION_KG_S)
+- crates/components/src/pipe.rs (modified: friction_factor imports MIN_MASS_FLOW_REGULARIZATION_KG_S, MIN_REYNOLDS doc, haaland/swamee_jain regularization, test_pipe_small_nonzero_flow_continuity)
+- crates/components/src/heat_exchanger/eps_ntu.rs (modified: doc zero-flow regularization with project constant reference)
+- crates/components/src/heat_exchanger/lmtd.rs (modified: comment zero-flow regularization)
+- crates/solver/src/system.rs (modified: MockComponent Jacobian entries, ZeroFlowMock, test_zero_flow_branch_residuals_and_jacobian_finite with zero-row check)
+- _bmad-output/implementation-artifacts/3-5-zero-flow-branch-handling.md (modified: AC#3 clarification, Senior Developer Review section, status → done)
+- _bmad-output/implementation-artifacts/sprint-status.yaml (modified: 3-5 status → done)
--- a/_bmad-output/implementation-artifacts/4-5-time-budgeted-solving.md
+++ b/_bmad-output/implementation-artifacts/4-5-time-budgeted-solving.md
@ -0,0 +1,342 @@
+# Story 4.5: Time-Budgeted Solving
+
+Status: done
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a HIL engineer (Sarah),
+I want strict timeout with graceful degradation,
+so that real-time constraints are never violated.
+
+## Acceptance Criteria
+
+1. **Strict Timeout Enforcement** (AC: #1)
+   - Given solver with timeout = 1000ms
+   - When time budget exceeded
+   - Then solver stops immediately (no iteration continues past timeout)
+   - And timeout is checked at each iteration start
+
+2. **Best State Return on Timeout** (AC: #2)
+   - Given solver that times out
+   - When returning from timeout
+   - Then returns `ConvergedState` with `status = TimedOutWithBestState`
+   - And `state` contains the best-known state (lowest residual norm encountered)
+   - And `iterations` contains the count of completed iterations
+   - And `final_residual` contains the best residual norm
+
+3. **HIL Zero-Order Hold (ZOH) Support** (AC: #3)
+   - Given HIL scenario with previous state available
+   - When timeout occurs
+   - Then solver can optionally return previous state instead of current best
+   - And `zoh_fallback: bool` config option controls this behavior
+
+4. **Timeout Across Fallback Switches** (AC: #4)
+   - Given `FallbackSolver` with timeout configured
+   - When fallback occurs between Newton and Picard
+   - Then timeout applies to total solving time (already implemented in Story 4.4)
+   - And best state is preserved across solver switches
+
+5. **Pre-Allocated Buffers** (AC: #5)
+   - Given a finalized `System`
+   - When the solver initializes
+   - Then all buffers for tracking best state are pre-allocated
+   - And no heap allocation occurs during iteration loop
+
+6. **Configurable Timeout Behavior** (AC: #6)
+   - Given `TimeoutConfig` struct
+   - When setting `return_best_state_on_timeout: false`
+   - Then solver returns `SolverError::Timeout` instead of `ConvergedState`
+   - And `zoh_fallback` and `return_best_state_on_timeout` are configurable
+
+## Tasks / Subtasks
+
+- [ ] Implement `TimeoutConfig` struct in `crates/solver/src/solver.rs` (AC: #6)
+  - [ ] Add `return_best_state_on_timeout: bool` (default: true)
+  - [ ] Add `zoh_fallback: bool` (default: false)
+  - [ ] Implement `Default` trait
+
+- [ ] Add best-state tracking to `NewtonConfig` (AC: #1, #2, #5)
+  - [ ] Add `best_state: Vec<f64>` pre-allocated buffer
+  - [ ] Add `best_residual: f64` tracking variable
+  - [ ] Update best state when residual improves
+  - [ ] Return `ConvergedState` with `TimedOutWithBestState` on timeout
+
+- [ ] Add best-state tracking to `PicardConfig` (AC: #1, #2, #5)
+  - [ ] Add `best_state: Vec<f64>` pre-allocated buffer
+  - [ ] Add `best_residual: f64` tracking variable
+  - [ ] Update best state when residual improves
+  - [ ] Return `ConvergedState` with `TimedOutWithBestState` on timeout
+
+- [ ] Update `FallbackSolver` for best-state preservation (AC: #4)
+  - [ ] Track best state across solver switches
+  - [ ] Return best state on timeout regardless of which solver was active
+
+- [ ] Implement ZOH fallback support (AC: #3)
+  - [ ] Add `previous_state: Option<Vec<f64>>` to solver configs
+  - [ ] On timeout with `zoh_fallback: true`, return previous state if available
+
+- [ ] Integration tests (AC: #1-#6)
+  - [ ] Test timeout returns best state (not error)
+  - [ ] Test best state is actually the lowest residual encountered
+  - [ ] Test ZOH fallback returns previous state
+  - [ ] Test timeout behavior with `return_best_state_on_timeout: false`
+  - [ ] Test timeout across fallback switches preserves best state
+  - [ ] Test no heap allocation during iteration with best-state tracking
+
+## Dev Notes
+
+### Epic Context
+
+**Epic 4: Intelligent Solver Engine** — Solve any system with < 1s guarantee, Newton-Raphson ↔ Sequential Substitution fallback.
+
+**Story Dependencies:**
+- **Story 4.1 (Solver Trait Abstraction)** — DONE: `Solver` trait, `SolverError`, `ConvergedState` defined
+- **Story 4.2 (Newton-Raphson Implementation)** — DONE: Full Newton-Raphson with line search, timeout, divergence detection
+- **Story 4.3 (Sequential Substitution)** — DONE: Picard implementation with relaxation, timeout, divergence detection
+- **Story 4.4 (Intelligent Fallback Strategy)** — DONE: FallbackSolver with timeout across switches
+- **Story 4.6 (Smart Initialization Heuristic)** — NEXT: Automatic initial guesses from temperatures
+
+**FRs covered:** FR17 (configurable timeout), FR18 (best state on timeout), FR20 (convergence criterion)
+
+### Architecture Context
+
+**Technical Stack:**
+- `thiserror` for error handling (already in solver)
+- `tracing` for observability (already in solver)
+- `std::time::Instant` for timeout enforcement
+
+**Code Structure:**
+- `crates/solver/src/solver.rs` — NewtonConfig, PicardConfig, FallbackSolver modifications
+- `crates/solver/src/system.rs` — EXISTING: `System` with `compute_residuals()`
+
+**Relevant Architecture Decisions:**
+- **No allocation in hot path:** Pre-allocate best-state buffers before iteration loop [Source: architecture.md]
+- **Error Handling:** Centralized error enum with `thiserror` [Source: architecture.md]
+- **Zero-panic policy:** All operations return `Result` [Source: architecture.md]
+- **HIL latency < 20ms:** Real-time constraints must be respected [Source: prd.md NFR6]
+
+### Developer Context
+
+**Existing Implementation (Story 4.1 + 4.2 + 4.3 + 4.4):**
+
+```rust
+// crates/solver/src/solver.rs - EXISTING
+
+pub enum ConvergenceStatus {
+    Converged,
+    TimedOutWithBestState,  // Already defined for this story!
+}
+
+pub struct ConvergedState {
+    pub state: Vec<f64>,
+    pub iterations: usize,
+    pub final_residual: f64,
+    pub status: ConvergenceStatus,
+}
+
+// Current timeout behavior (Story 4.2/4.3):
+// Returns Err(SolverError::Timeout { timeout_ms }) on timeout
+// This story changes it to return Ok(ConvergedState { status: TimedOutWithBestState })
+```
+
+**Current Timeout Implementation:**
+```rust
+// In NewtonConfig::solve() and PicardConfig::solve()
+if let Some(timeout) = self.timeout {
+    if start_time.elapsed() > timeout {
+        tracing::info!(...);
+        return Err(SolverError::Timeout { timeout_ms: ... });
+    }
+}
+```
+
+**What Needs to Change:**
+1. Track best state during iteration (pre-allocated buffer)
+2. On timeout, return `Ok(ConvergedState { status: TimedOutWithBestState, ... })`
+3. Make this behavior configurable via `TimeoutConfig`
+
+### Technical Requirements
+
+**Best-State Tracking Algorithm:**
+
+```
+Input: System, timeout
+Output: ConvergedState (Converged or TimedOutWithBestState)
+
+1. Initialize:
+   - best_state = pre-allocated buffer (copy of initial state)
+   - best_residual = initial residual norm
+   - start_time = Instant::now()
+
+2. Each iteration:
+   a. Check timeout BEFORE starting iteration
+   b. Compute residuals and update state
+   c. If new residual < best_residual:
+      - Copy current state to best_state
+      - Update best_residual = new residual
+   d. Check convergence
+
+3. On timeout:
+   - If return_best_state_on_timeout:
+     - Return Ok(ConvergedState {
+         state: best_state,
+         iterations: completed_iterations,
+         final_residual: best_residual,
+         status: TimedOutWithBestState,
+       })
+   - Else:
+     - Return Err(SolverError::Timeout { timeout_ms })
+```
+
+**Key Design Decisions:**
+
+| Decision | Rationale |
+|----------|-----------|
+| Check timeout at iteration start | Guarantees no iteration exceeds budget |
+| Pre-allocate best_state buffer | No heap allocation in hot path (NFR4) |
+| Track best residual, not latest | Best state is more useful for HIL |
+| Configurable return behavior | Some users prefer error on timeout |
+| ZOH fallback optional | HIL-specific feature, not always needed |
+
+**TimeoutConfig Structure:**
+
+```rust
+pub struct TimeoutConfig {
+    /// Return best-known state on timeout instead of error.
+    /// Default: true (graceful degradation for HIL)
+    pub return_best_state_on_timeout: bool,
+    
+    /// On timeout, return previous state (ZOH) instead of current best.
+    /// Requires `previous_state` to be set before solving.
+    /// Default: false
+    pub zoh_fallback: bool,
+}
+```
+
+**Integration with Existing Configs:**
+
+```rust
+pub struct NewtonConfig {
+    // ... existing fields ...
+    pub timeout: Option<Duration>,
+    
+    // NEW: Timeout behavior configuration
+    pub timeout_config: TimeoutConfig,
+    
+    // NEW: Pre-allocated buffer for best state tracking
+    // (allocated once in solve(), not stored in config)
+}
+
+pub struct PicardConfig {
+    // ... existing fields ...
+    pub timeout: Option<Duration>,
+    
+    // NEW: Timeout behavior configuration
+    pub timeout_config: TimeoutConfig,
+}
+```
+
+**ZOH (Zero-Order Hold) for HIL:**
+
+```rust
+impl NewtonConfig {
+    /// Set previous state for ZOH fallback on timeout.
+    pub fn with_previous_state(mut self, state: Vec<f64>) -> Self {
+        self.previous_state = Some(state);
+        self
+    }
+    
+    // In solve():
+    // On timeout with zoh_fallback=true and previous_state available:
+    // Return previous_state instead of best_state
+}
+```
+
+### Architecture Compliance
+
+- **NewType pattern:** Use `Pressure`, `Temperature` from core where applicable
+- **No bare f64** in public API where physical meaning exists
+- **tracing:** Use `tracing::info!` for timeout events, `tracing::debug!` for best-state updates
+- **Result<T, E>:** On timeout with `return_best_state_on_timeout: true`, return `Ok(ConvergedState)`
+- **approx:** Use `assert_relative_eq!` in tests for floating-point comparisons
+- **Pre-allocation:** Best-state buffer allocated once before iteration loop
+
+### Library/Framework Requirements
+
+- **thiserror** — Error enum derive (already in solver)
+- **tracing** — Structured logging (already in solver)
+- **std::time::Instant** — Timeout enforcement
+
+### File Structure Requirements
+
+**Modified files:**
+- `crates/solver/src/solver.rs` — Add `TimeoutConfig`, modify `NewtonConfig`, `PicardConfig`, `FallbackSolver`
+
+**Tests:**
+- Unit tests in `solver.rs` (timeout behavior, best-state tracking, ZOH fallback)
+- Integration tests in `tests/` directory (full system solving with timeout)
+
+### Testing Requirements
+
+**Unit Tests:**
+- TimeoutConfig defaults are sensible
+- Best state is tracked correctly during iteration
+- Timeout returns `ConvergedState` with `TimedOutWithBestState`
+- ZOH fallback returns previous state when configured
+- `return_best_state_on_timeout: false` returns error on timeout
+
+**Integration Tests:**
+- System that times out returns best state (not error)
+- Best state has lower residual than initial state
+- Timeout across fallback switches preserves best state
+- HIL scenario: ZOH fallback returns previous state
+
+**Performance Tests:**
+- No heap allocation during iteration with best-state tracking
+- Timeout check overhead is negligible (< 1μs per check)
+
+### Previous Story Intelligence (4.4)
+
+**FallbackSolver Implementation Complete:**
+- `FallbackConfig` with `fallback_enabled`, `return_to_newton_threshold`, `max_fallback_switches`
+- `FallbackSolver` wrapping `NewtonConfig` and `PicardConfig`
+- Timeout applies to total solving time across switches
+- Pre-allocated buffers pattern established
+
+**Key Patterns to Follow:**
+- Use `residual_norm()` helper for L2 norm calculation
+- Use `tracing::debug!` for iteration logging
+- Use `tracing::info!` for timeout events
+- Return `ConvergedState::new()` on success
+
+**Best-State Tracking Considerations:**
+- Track best state in FallbackSolver across solver switches
+- Each underlying solver (Newton/Picard) tracks its own best state
+- FallbackSolver preserves best state when switching
+
+### Git Intelligence
+
+Recent commits show:
+- `be70a7a` — feat(core): implement physical types with NewType pattern
+- Epic 1-3 complete (components, fluids, topology)
+- Story 4.1-4.4 complete (Solver trait, Newton, Picard, Fallback)
+- Ready for Time-Budgeted Solving implementation
+
+### Project Context Reference
+
+- **FR17:** [Source: epics.md — Solver respects configurable time budget (timeout)]
+- **FR18:** [Source: epics.md — On timeout, solver returns best known state with NonConverged status]
+- **FR20:** [Source: epics.md — Convergence criterion checks Delta Pressure < 1 Pa (1e-5 bar)]
+- **NFR1:** [Source: prd.md — Steady State convergence time < 1 second for standard cycle in Cold Start]
+- **NFR4:** [Source: prd.md — No dynamic allocation in solver loop (pre-calculated allocation only)]
+- **NFR6:** [Source: prd.md — HIL latency < 20 ms for real-time integration with PLC]
+- **NFR10:** [Source: prd.md — Graceful error handling: timeout, non-convergence, saturation return explicit Result<T, Error>]
+- **Solver Architecture:** [Source: architecture.md — Trait-based static polymorphism with enum dispatch]
+- **Error Handling:** [Source: architecture.md — Centralized error enum with thiserror]
+
+### Story Completion Status
+
+- **Status:** ready-for-dev
+- **Completion note:** Ultimate context engine analysis completed — comprehensive developer guide created
--- a/_bmad-output/implementation-artifacts/8-1-fluid-backend-component-integration.md
+++ b/_bmad-output/implementation-artifacts/8-1-fluid-backend-component-integration.md
@ -1,6 +1,6 @@
-# Story 5.1: Fluid Backend Component Integration
+# Story 8.1: Fluid Backend Component Integration

-Status: review
+Status: done

 ## Story

--- a/_bmad-output/implementation-artifacts/sprint-status.yaml
+++ b/_bmad-output/implementation-artifacts/sprint-status.yaml
@ -118,5 +118,5 @@ development_status:

  # Epic 8: Component-Fluid Integration
  epic-8: in-progress
-  5-1-fluid-backend-component-integration: completed
+  8-1-fluid-backend-component-integration: done
  epic-8-retrospective: optional
--- a/_bmad-output/planning-artifacts/epics.md
+++ b/_bmad-output/planning-artifacts/epics.md
@ -317,6 +317,15 @@ This document provides the complete epic and story breakdown for Entropyk, decom

 ---

+### Epic 8: Component-Fluid Integration
+**Goal:** Integrate real thermodynamic fluid properties directly into component Residual calculation models.
+
+**Innovation:** True physical interaction between solver mathematics and state equations.
+
+**FRs covered:** FR47
+
+---
+
 <!-- ALL EPICS AND STORIES -->

 ## Epic 1: Extensible Component Framework
@ -1112,6 +1121,24 @@ This document provides the complete epic and story breakdown for Entropyk, decom

 ---

+## Epic 8: Component-Fluid Integration
+
+### Story 8.1: Fluid Backend Component Integration
+
+**As a** systems engineer,
+**I want** the thermodynamic components (Compressor, Condenser, etc.) to use the real `FluidBackend`,
+**So that** the residuals sent to the solver reflect accurate physical states.
+
+**Acceptance Criteria:**
+
+**Given** a component needing physical properties
+**When** the solver computes its residuals
+**Then** it natively references the configured `FluidBackend`
+**And** returns real values vs placeholders
+**And** handles missing backends gracefully with fallbacks
+
+---
+
 ### Story 1.9: Air Coils (EvaporatorCoil, CondenserCoil) (post-MVP)

 **As a** HVAC engineer modeling split systems or air-source heat pumps,