chore: sync project state and current artifacts

2026-02-22 23:27:31 +01:00
parent 1b6415776e
commit dd77089b22
232 changed files with 37056 additions and 4296 deletions
--- a/_bmad-output/planning-artifacts/epic-10-enhanced-boundary-conditions.md
+++ b/_bmad-output/planning-artifacts/epic-10-enhanced-boundary-conditions.md
@@ -0,0 +1,90 @@
+# Epic 10: Enhanced Boundary Conditions
+
+**Epic ID:** epic-10  
+**Titre:** Enhanced Boundary Conditions - Sources/Puits Typés  
+**Priorité:** P1-HIGH  
+**Statut:** backlog  
+**Date Création:** 2026-02-22  
+**Dépendances:** Epic 7 (Validation & Persistence), Story 9-4 (FlowSource/FlowSink Energy Methods)
+
+---
+
+## Vision
+
+Refactoriser les conditions aux limites (`FlowSource`, `FlowSink`) pour supporter explicitement les 3 types de fluides avec leurs propriétés spécifiques:
+
+1. **Réfrigérants compressibles** - avec titre (vapor quality)
+2. **Caloporteurs liquides** - avec concentration glycol
+3. **Air humide** - avec propriétés psychrométriques
+
+---
+
+## Contexte Métier
+
+### Problème Actuel
+
+Les composants `FlowSource` et `FlowSink` actuels utilisent une distinction binaire `Incompressible`/`Compressible` qui est trop simpliste:
+
+- Pas de support pour la concentration des mélanges eau-glycol (PEG, MEG)
+- Pas de support pour les propriétés psychrométriques de l'air (humidité relative, bulbe humide)
+- Pas de distinction claire entre les propriétés des réfrigérants et des caloporteurs
+
+### Impact Utilisateur
+
+- **Marie (R&D Engineer)**: Besoin de simuler des circuits eau-glycol avec différentes concentrations
+- **Sarah (HIL Engineer)**: Besoin de conditions aux limites air réalistes pour tests de pompes à chaleur
+- **Robert (Researcher)**: Besoin de spécifier le titre des réfrigérants pour études de cycles
+
+---
+
+## Objectifs Mesurables
+
+| Objectif | Métrique | Cible |
+|----------|----------|-------|
+| Support 3 types de fluides | Types implémentés | 3/3 |
+| Nouveaux types physiques | Types ajoutés | 4 (Concentration, VolumeFlow, RelativeHumidity, VaporQuality) |
+| Rétrocompatibilité | Tests passent | 100% |
+| Documentation | Coverage | 100% des nouveaux types |
+
+---
+
+## Stories
+
+| Story ID | Titre | Estimation | Priorité | Dépendances |
+|----------|-------|------------|----------|-------------|
+| 10-1 | Nouveaux types physiques (Concentration, VolumeFlow, RelativeHumidity, VaporQuality) | 2h | P0 | Aucune |
+| 10-2 | RefrigerantSource et RefrigerantSink | 3h | P0 | 10-1 |
+| 10-3 | BrineSource et BrineSink avec support glycol | 3h | P0 | 10-1 |
+| 10-4 | AirSource et AirSink avec propriétés psychrométriques | 4h | P1 | 10-1 |
+| 10-5 | Migration et dépréciation des anciens types | 2h | P1 | 10-2, 10-3, 10-4 |
+| 10-6 | Mise à jour des bindings Python | 2h | P1 | 10-2, 10-3, 10-4 |
+
+**Estimation Totale:** 16h (2 jours)
+
+---
+
+## Risques et Mitigations
+
+| Risque | Probabilité | Impact | Mitigation |
+|--------|-------------|--------|------------|
+| CoolProp ne supporte pas les mélanges eau-glycol | Moyen | Élevé | Valider avec tests CoolProp avant implémentation |
+| Calculs psychrométriques trop lents | Faible | Moyen | Utiliser des formules approchées si nécessaire |
+| Breaking changes pour utilisateurs existants | Élevé | Élevé | Phase de dépréciation avec messages clairs |
+
+---
+
+## Critères de Succès
+
+- [ ] Les 3 types de sources/puits sont implémentés et testés
+- [ ] Les 4 nouveaux types physiques sont disponibles
+- [ ] Les anciens types sont dépréciés avec guide de migration
+- [ ] Les bindings Python sont à jour
+- [ ] La documentation est complète
+
+---
+
+## Références
+
+- [Architecture Document](../../plans/boundary-condition-refactoring-architecture.md)
+- [Story 9-4: FlowSource/FlowSink Energy Methods](../implementation-artifacts/9-4-flow-source-sink-energy-methods.md)
+- [Coherence Audit Remediation Plan](../implementation-artifacts/coherence-audit-remediation-plan.md)
--- a/_bmad-output/planning-artifacts/epic-11-technical-specifications.md
+++ b/_bmad-output/planning-artifacts/epic-11-technical-specifications.md
--- a/_bmad-output/planning-artifacts/epics.md
+++ b/_bmad-output/planning-artifacts/epics.md
@@ -122,6 +122,22 @@ This document provides the complete epic and story breakdown for Entropyk, decom

 **FR52:** Bounded Variable Step Clipping - during Newton-Raphson iterations, bounded control variables are clipped to [min, max] at EVERY iteration, preventing physically impossible values (e.g., valve > 100%) and improving convergence stability

+**FR53:** Node - Passive probe component (0 equations) for extracting P, h, T, quality, superheat, subcooling at any point in the circuit without affecting the solver
+
+**FR54:** FloodedEvaporator - Flooded evaporator where liquid refrigerant completely floods the tubes via a low-pressure receiver, producing a two-phase mixture (50-80% vapor) at the outlet
+
+**FR55:** FloodedCondenser - Accumulation condenser where condensed refrigerant forms a liquid bath around the cooling tubes to regulate condensing pressure
+
+**FR56:** Drum - Recirculation drum for evaporator recirculation cycles (2 inlets → 2 outlets: saturated liquid + saturated vapor)
+
+**FR57:** BphxExchanger - Brazed Plate Heat Exchanger configurable as DX evaporator, flooded evaporator, or condenser with plate-specific correlations
+
+**FR58:** MovingBoundaryHX - Zone-discretized heat exchanger with phase zones (superheated/two-phase/subcooled) and configurable correlation (Longo, Shah, Kandlikar, etc.)
+
+**FR59:** VendorBackend - API for vendor data (Copeland, Danfoss, SWEP, Bitzer) with compressor coefficients and heat exchanger parameters loaded from JSON/CSV
+
+**FR60:** CorrelationSelector - Heat transfer correlation selection with Longo (2004) as default for BPHX, supporting Shah (1979, 2021), Kandlikar (1990), Gungor-Winterton (1986), Gnielinski (1976), and others
+
 ### NonFunctional Requirements

 **NFR1:** Steady State convergence time < **1 second** for standard cycle in Cold Start
@@ -265,6 +281,15 @@ This document provides the complete epic and story breakdown for Entropyk, decom
 | FR49 | Epic 1 | Flow Junctions (FlowSplitter 1→N, FlowMerger N→1) for compressible & incompressible fluids |
 | FR50 | Epic 1 | Boundary Conditions (FlowSource, FlowSink) for compressible & incompressible fluids |
 | FR51 | Epic 5 | Swappable Calibration Variables (inverse calibration one-shot) |
+| FR52 | Epic 6 | Python Solver Configuration Parity - expose all Rust solver options in Python bindings |
+| FR53 | Epic 11 | Node passive probe for state extraction |
+| FR54 | Epic 11 | FloodedEvaporator |
+| FR55 | Epic 11 | FloodedCondenser |
+| FR56 | Epic 11 | Drum recirculation |
+| FR57 | Epic 11 | BphxExchanger |
+| FR58 | Epic 11 | MovingBoundaryHX |
+| FR59 | Epic 11 | VendorBackend API |
+| FR60 | Epic 11 | CorrelationSelector |

 ## Epic List

@@ -340,6 +365,19 @@ This document provides the complete epic and story breakdown for Entropyk, decom

 ---

+### Epic 9: Coherence Corrections (Post-Audit)
+**Goal:** Fix coherence issues identified during the post-development audit to ensure complete and correct thermodynamic validation.
+
+**Innovation:** Systematic remediation of type duplications and incomplete implementations.
+
+**FRs covered:** FR35, FR36 (completion of Epic 7 validation)
+
+**Status:** 🔄 In Progress (2026-02-22)
+
+**Source:** [Coherence Audit Report](../implementation-artifacts/coherence-audit-remediation-plan.md)
+
+---
+
 <!-- ALL EPICS AND STORIES -->

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

 ---

+### Story 6.6: Python Solver Configuration Parity
+
+**As a** Python data scientist (Alice),
+**I want** full access to all solver configuration options from Python,
+**So that** I can optimize convergence for complex thermodynamic systems.
+
+**Problem Statement:**
+
+The current Python bindings expose only a subset of the Rust solver configuration options. This prevents Python users from:
+- Setting initial states for cold-start solving (critical for convergence)
+- Configuring Jacobian freezing for performance optimization
+- Using advanced convergence criteria for multi-circuit systems
+- Accessing timeout behavior configuration (ZOH fallback for HIL)
+
+**Gap Analysis:**
+
+| Rust Field | Python Exposed | Impact |
+|------------|----------------|--------|
+| `initial_state` | ❌ | Cannot warm-start solver |
+| `use_numerical_jacobian` | ❌ | Cannot debug Jacobian issues |
+| `jacobian_freezing` | ❌ | Missing 80% performance optimization |
+| `convergence_criteria` | ❌ | Cannot configure multi-circuit convergence |
+| `timeout_config` | ❌ | Cannot configure ZOH fallback |
+| `previous_state` | ❌ | Cannot use HIL zero-order hold |
+| `line_search_armijo_c` | ❌ | Cannot tune line search |
+| `divergence_threshold` | ❌ | Cannot adjust divergence detection |
+
+**Acceptance Criteria:**
+
+**Given** Python script using entropyk
+**When** configuring NewtonConfig or PicardConfig
+**Then** all Rust configuration fields are accessible:
+- [ ] `initial_state: Optional[List[float]]` - warm-start from previous solution
+- [ ] `use_numerical_jacobian: bool` - finite difference Jacobian
+- [ ] `jacobian_freezing: Optional[JacobianFreezingConfig]` - reuse Jacobian optimization
+- [ ] `convergence_criteria: Optional[ConvergenceCriteria]` - multi-circuit criteria
+- [ ] `timeout_config: TimeoutConfig` - detailed timeout behavior
+- [ ] `previous_state: Optional[List[float]]` - for HIL ZOH fallback
+- [ ] `line_search_armijo_c: float` - Armijo constant
+- [ ] `line_search_max_backtracks: int` - max backtracking iterations
+- [ ] `divergence_threshold: float` - divergence detection threshold
+
+**And** `SolverStrategy` enum is exposed:
+- [ ] `SolverStrategy.newton()` - create Newton strategy
+- [ ] `SolverStrategy.picard()` - create Picard strategy
+- [ ] `SolverStrategy.default()` - default strategy (Newton)
+- [ ] `strategy.solve(system)` - uniform solve interface
+
+**And** supporting types are exposed:
+- [ ] `JacobianFreezingConfig(max_frozen_iters, threshold)`
+- [ ] `TimeoutConfig(return_best_state_on_timeout, zoh_fallback)`
+- [ ] `ConvergenceCriteria` with per-circuit tolerances
+
+**And** backward compatibility is maintained:
+- [ ] Existing Python code continues to work
+- [ ] New fields have sensible defaults
+- [ ] Deprecation warnings for removed fields
+
+**Technical Notes:**
+
+1. **Priority Order:**
+   - P0: `initial_state` (critical for convergence)
+   - P0: `SolverStrategy` (architectural consistency)
+   - P1: `jacobian_freezing` (performance)
+   - P1: `convergence_criteria` (multi-circuit)
+   - P2: Other fields (advanced tuning)
+
+2. **Implementation Approach:**
+   - Extend `PyNewtonConfig` and `PyPicardConfig` structs
+   - Add new `PySolverStrategy` wrapper class
+   - Create `PyJacobianFreezingConfig`, `PyTimeoutConfig`, `PyConvergenceCriteria`
+   - Update `lib.rs` to register new classes
+
+3. **Testing:**
+   - Unit tests for each new configuration field
+   - Integration test: solve with `initial_state` from previous solution
+   - Performance test: verify Jacobian freezing speedup
+
+**References:**
+- FR52: Python Solver Configuration Parity
+- Story 6.2: Python Bindings (PyO3) - foundation
+- Epic 4: Intelligent Solver Engine - Rust solver implementation
+
+---
+
 ## Epic 7: Validation & Persistence

 ### Story 7.1: Mass Balance Validation
@@ -1157,6 +1280,8 @@ This document provides the complete epic and story breakdown for Entropyk, decom

 ### Story 7.2: Energy Balance Validation

+**Status:** ✅ Done (2026-02-22)
+
 **As a** simulation engineer,
 **I want** First AND Second Law verification,
 **So that** thermodynamic consistency is guaranteed.
@@ -1363,6 +1488,499 @@ This document provides the complete epic and story breakdown for Entropyk, decom

 ---

+## Epic 9: Coherence Corrections (Post-Audit)
+
+**Goal:** Fix coherence issues identified during the post-development audit to ensure complete and correct thermodynamic validation.
+
+**Innovation:** Systematic remediation of type duplications and incomplete implementations.
+
+**FRs covered:** FR35, FR36 (completion of Epic 7 validation)
+
+**Status:** 🔄 In Progress (2026-02-22)
+
+**Source:** [Coherence Audit Report](../implementation-artifacts/coherence-audit-remediation-plan.md)
+
+### Story 9.1: CircuitId Type Unification
+
+**As a** Rust developer,
+**I want** a single, coherent `CircuitId` type,
+**So that** I avoid compilation errors when using solver and components modules together.
+
+**Acceptance Criteria:**
+
+**Given** the codebase currently has two `CircuitId` definitions
+**When** the unification is complete
+**Then** only one `CircuitId` exists in `entropyk_core`
+**And** `From<u8>` and `From<&str>` conversions are available
+**And** all modules re-export from `entropyk_core`
+
+---
+
+### Story 9.2: FluidId Type Unification
+
+**As a** Rust developer,
+**I want** a single `FluidId` type with a consistent API,
+**So that** I avoid confusion between `fluids::FluidId` and `components::port::FluidId`.
+
+**Acceptance Criteria:**
+
+**Given** the codebase currently has two `FluidId` definitions
+**When** the unification is complete
+**Then** only one `FluidId` exists in `entropyk_fluids`
+**And** both `as_str()` method and public field access work
+**And** all modules re-export from `entropyk_fluids`
+
+---
+
+### Story 9.3: ExpansionValve Energy Methods
+
+**As a** thermodynamic simulation engine,
+**I want** `ExpansionValve` to implement `energy_transfers()` and `port_enthalpies()`,
+**So that** the energy balance is correctly validated for refrigeration cycles.
+
+**Acceptance Criteria:**
+
+**Given** an ExpansionValve in a refrigeration cycle
+**When** `check_energy_balance()` is called
+**Then** the valve is included in the validation (not skipped)
+**And** `energy_transfers()` returns `(Power(0), Power(0))` (isenthalpic)
+**And** `port_enthalpies()` returns `[h_in, h_out]`
+
+---
+
+### Story 9.4: FlowSource/FlowSink Energy Methods
+
+**As a** thermodynamic simulation engine,
+**I want** `FlowSource` and `FlowSink` to implement `energy_transfers()` and `port_enthalpies()`,
+**So that** boundary conditions are correctly accounted for in the energy balance.
+
+**Acceptance Criteria:**
+
+**Given** FlowSource or FlowSink in a system
+**When** `check_energy_balance()` is called
+**Then** the component is included in the validation
+**And** `energy_transfers()` returns `(Power(0), Power(0))`
+**And** `port_enthalpies()` returns the port enthalpy
+
+---
+
+### Story 9.5: FlowSplitter/FlowMerger Energy Methods
+
+**As a** thermodynamic simulation engine,
+**I want** `FlowSplitter` and `FlowMerger` to implement `energy_transfers()` and `port_enthalpies()`,
+**So that** junctions are correctly accounted for in the energy balance.
+
+**Acceptance Criteria:**
+
+**Given** FlowSplitter or FlowMerger in a system
+**When** `check_energy_balance()` is called
+**Then** the component is included in the validation
+**And** `energy_transfers()` returns `(Power(0), Power(0))` (adiabatic)
+**And** `port_enthalpies()` returns all port enthalpies in order
+
+---
+
+### Story 9.6: Energy Validation Logging Improvement
+
+**As a** developer debugging a simulation,
+**I want** an explicit warning when components are skipped in energy validation,
+**So that** I can quickly identify missing implementations.
+
+**Acceptance Criteria:**
+
+**Given** a component without `energy_transfers()` or `port_enthalpies()`
+**When** `check_energy_balance()` is called
+**Then** a WARN-level log is emitted with component name and type
+**And** a summary lists all skipped components
+
+---
+
+### Story 9.7: Solver Refactoring - Split Files
+
+**As a** developer maintaining the code,
+**I want** solver strategies to be in separate files,
+**So that** code maintainability is improved.
+
+**Acceptance Criteria:**
+
+**Given** the current `solver.rs` is ~2800 lines
+**When** refactoring is complete
+**Then** each file is < 500 lines
+**And** public API is unchanged
+**And** `cargo test --workspace` passes
+
+---
+
+### Story 9.8: SystemState Dedicated Struct
+
+**As a** Rust developer,
+**I want** a dedicated `SystemState` struct instead of a type alias,
+**So that** I have layout validation and typed access methods.
+
+**Acceptance Criteria:**
+
+**Given** `SystemState` is currently `Vec<f64>`
+**When** the struct is created
+**Then** `pressure(edge_idx)` returns `Pressure`
+**And** `enthalpy(edge_idx)` returns `Enthalpy`
+**And** compatibility with `AsRef<[f64]>` is maintained
+
+---
+
+## Epic 11: Advanced HVAC Components
+
+**Goal:** Implement components for industrial chillers and heat pumps (flooded, BPHX, MovingBoundary, vendor data integration)
+
+**Innovation:** Native integration of vendor data and advanced heat transfer correlations
+
+**FRs covered:** FR53, FR54, FR55, FR56, FR57, FR58, FR59, FR60
+
+**Status:** 📋 Backlog (2026-02-22)
+
+**Source:** [Technical Specifications](epic-11-technical-specifications.md)
+
+---
+
+### Story 11.1: Node - Passive Probe
+
+**As a** system modeler,
+**I want** a passive Node component (0 equations),
+**So that** I can extract P, h, T, quality, superheat, subcooling at any point in the circuit.
+
+**Status:** 📋 Backlog
+
+**FRs covered:** FR53
+
+**Acceptance Criteria:**
+
+**Given** a Node with 1 inlet and 1 outlet
+**When** the system converges
+**Then** the Node contributes 0 equations (passive)
+**And** I can read pressure, temperature, enthalpy, quality
+**And** I can read superheat (if superheated) or subcooling (if subcooled)
+**And** the Node can be used as a junction in the graph topology
+**And** NodeMeasurements struct provides all extracted values
+
+---
+
+### Story 11.2: Drum - Recirculation Drum
+
+**As a** chiller engineer,
+**I want** a Drum component for evaporator recirculation,
+**So that** I can simulate flooded evaporator cycles.
+
+**Status:** 📋 Backlog
+
+**FRs covered:** FR56
+
+**Acceptance Criteria:**
+
+**Given** a Drum with 2 inlets (feed + evaporator return) and 2 outlets (liquid + vapor)
+**When** the system converges
+**Then** liquid outlet is saturated (x=0)
+**And** vapor outlet is saturated (x=1)
+**And** mass and energy balances are satisfied
+**And** pressure equality across all ports
+**And** n_equations() returns 8
+
+---
+
+### Story 11.3: FloodedEvaporator
+
+**As a** chiller engineer,
+**I want** a FloodedEvaporator component,
+**So that** I can simulate chillers with flooded evaporators.
+
+**Status:** 📋 Backlog
+
+**FRs covered:** FR54
+
+**Acceptance Criteria:**
+
+**Given** a FloodedEvaporator with refrigerant side (flooded) and fluid side (water/glycol)
+**When** computing heat transfer
+**Then** refrigerant outlet is two-phase (50-80% vapor)
+**And** UA uses flooded-specific correlations (Longo default for BPHX)
+**And** Calib factors (f_ua, f_dp) are applicable
+**And** outlet_quality() method returns vapor quality
+**And** supports both LMTD and ε-NTU models
+
+---
+
+### Story 11.4: FloodedCondenser
+
+**As a** chiller engineer,
+**I want** a FloodedCondenser component,
+**So that** I can simulate chillers with accumulation condensers.
+
+**Status:** 📋 Backlog
+
+**FRs covered:** FR55
+
+**Acceptance Criteria:**
+
+**Given** a FloodedCondenser with refrigerant side (flooded) and fluid side (water/glycol)
+**When** computing heat transfer
+**Then** liquid bath regulates condensing pressure
+**And** outlet is subcooled liquid
+**And** UA uses flooded-specific correlations
+**And** subcooling is calculated and accessible
+
+---
+
+### Story 11.5: BphxExchanger Base
+
+**As a** thermal engineer,
+**I want** a base BphxExchanger component,
+**So that** I can configure brazed plate heat exchangers for various applications.
+
+**Status:** 📋 Backlog
+
+**FRs covered:** FR57
+
+**Acceptance Criteria:**
+
+**Given** a BphxExchanger with geometry parameters (plates, chevron angle, area)
+**When** computing heat transfer
+**Then** Longo (2004) correlation is used by default
+**And** alternative correlations can be selected via CorrelationSelector
+**And** both single-phase and two-phase zones are handled
+**And** HeatExchangerGeometry struct defines dh, area, chevron_angle, exchanger_type
+
+---
+
+### Story 11.6: BphxEvaporator
+
+**As a** heat pump engineer,
+**I want** a BphxEvaporator configured for DX or flooded operation,
+**So that** I can simulate plate evaporators accurately.
+
+**Status:** 📋 Backlog
+
+**FRs covered:** FR57
+
+**Acceptance Criteria:**
+
+**Given** a BphxEvaporator in DX mode
+**When** computing heat transfer
+**Then** superheat is calculated
+**And** outlet quality ≥ 1
+
+**Given** a BphxEvaporator in flooded mode
+**When** computing heat transfer
+**Then** outlet is two-phase
+**And** works with Drum for recirculation
+
+---
+
+### Story 11.7: BphxCondenser
+
+**As a** heat pump engineer,
+**I want** a BphxCondenser for refrigerant condensation,
+**So that** I can simulate plate condensers accurately.
+
+**Status:** 📋 Backlog
+
+**FRs covered:** FR57
+
+**Acceptance Criteria:**
+
+**Given** a BphxCondenser
+**When** computing heat transfer
+**Then** outlet is subcooled liquid
+**And** subcooling is calculated
+**And** Longo condensation correlation is used by default
+
+---
+
+### Story 11.8: CorrelationSelector
+
+**As a** simulation engineer,
+**I want** to select from multiple heat transfer correlations,
+**So that** I can compare different models or use the most appropriate one.
+
+**Status:** 📋 Backlog
+
+**FRs covered:** FR60
+
+**Acceptance Criteria:**
+
+**Given** a heat exchanger with CorrelationSelector
+**When** selecting a correlation
+**Then** available correlations include:
+- Longo (2004) - Default for BPHX evaporation/condensation
+- Shah (1979) - Tubes condensation
+- Shah (2021) - Plates condensation, recent
+- Kandlikar (1990) - Tubes evaporation
+- Gungor-Winterton (1986) - Tubes evaporation
+- Ko (2021) - Low-GWP plates
+- Dittus-Boelter (1930) - Single-phase turbulent
+- Gnielinski (1976) - Single-phase turbulent (more accurate)
+**And** each correlation implements HeatTransferCorrelation trait
+**And** each correlation documents its validity range (Re, quality, mass flux)
+**And** CorrelationResult includes h, Re, Pr, Nu, and validity status
+
+---
+
+### Story 11.9: MovingBoundaryHX - Zone Discretization
+
+**As a** precision engineer,
+**I want** a MovingBoundaryHX with phase zone discretization,
+**So that** I can model heat exchangers with accurate zone-by-zone calculations.
+
+**Status:** 📋 Backlog
+
+**FRs covered:** FR58
+
+**Acceptance Criteria:**
+
+**Given** a MovingBoundaryHX
+**When** computing heat transfer
+**Then** zones are identified: superheated / two-phase / subcooled (refrigerant side)
+**And** each zone has its own UA calculated
+**And** total UA = Σ UA_zone
+**And** pinch temperature is calculated at zone boundaries
+**And** zone_boundaries vector contains relative positions [0.0, ..., 1.0]
+**And** supports configurable number of discretization points (default 51)
+
+---
+
+### Story 11.10: MovingBoundaryHX - Cache Optimization
+
+**As a** performance-critical user,
+**I want** the MovingBoundaryHX to cache zone calculations,
+**So that** iterations 2+ are much faster.
+
+**Status:** 📋 Backlog
+
+**FRs covered:** FR58
+
+**Acceptance Criteria:**
+
+**Given** a MovingBoundaryHX with cache enabled
+**When** running iteration 1
+**Then** full zone calculation is performed (~50ms)
+**And** zone boundaries and UA are cached in MovingBoundaryCache
+
+**When** running iterations 2+
+**Then** cache is used if ΔP < 5% and Δm < 10%
+**And** computation is ~2ms (25x faster)
+**And** cache is invalidated on significant condition changes
+**And** cache includes: zone_boundaries, ua_per_zone, h_sat values, p_ref, m_ref
+
+---
+
+### Story 11.11: VendorBackend Trait
+
+**As a** library developer,
+**I want** a VendorBackend trait,
+**So that** vendor data can be loaded from multiple sources.
+
+**Status:** 📋 Backlog
+
+**FRs covered:** FR59
+
+**Acceptance Criteria:**
+
+**Given** the VendorBackend trait in new `entropyk-vendors` crate
+**When** implementing a vendor
+**Then** methods include:
+- `vendor_name()` → vendor identifier
+- `list_compressor_models()` → available models
+- `get_compressor_coefficients(model)` → AHRI 540 coefficients
+- `list_bphx_models()` → available BPHX models
+- `get_bphx_parameters(model)` → geometry and UA curves
+- `compute_ua(model, params)` → vendor-specific UA calculation (optional)
+**And** data is loaded from JSON/CSV files in data/ directory
+**And** errors are handled via VendorError enum
+
+---
+
+### Story 11.12: Copeland Parser
+
+**As a** compressor engineer,
+**I want** Copeland compressor data integration,
+**So that** I can use Copeland coefficients in simulations.
+
+**Status:** 📋 Backlog
+
+**FRs covered:** FR59
+
+**Acceptance Criteria:**
+
+**Given** Copeland compressor data files (JSON format)
+**When** loading via CopelandBackend
+**Then** AHRI 540 coefficients (10 capacity + 10 power) are extracted
+**And** valid models are discoverable via list_compressor_models()
+**And** errors for missing/invalid models are clear
+**And** data files follow format: data/copeland/compressors/{model}.json
+**And** index.json lists all available models
+
+---
+
+### Story 11.13: SWEP Parser
+
+**As a** heat exchanger engineer,
+**I want** SWEP BPHX data integration,
+**So that** I can use SWEP parameters in simulations.
+
+**Status:** 📋 Backlog
+
+**FRs covered:** FR59
+
+**Acceptance Criteria:**
+
+**Given** SWEP BPHX data files (JSON + CSV)
+**When** loading via SwepBackend
+**Then** geometry (plates, area, dh, chevron_angle) is extracted
+**And** UA nominal value is available
+**And** UA curves (mass_flow_ratio vs ua_ratio) are loaded if available
+**And** model selection is supported via list_bphx_models()
+**And** data files follow format: data/swep/bphx/{model}.json
+
+---
+
+### Story 11.14: Danfoss Parser
+
+**As a** refrigeration engineer,
+**I want** Danfoss compressor data integration,
+**So that** I can use Danfoss coefficients in simulations.
+
+**Status:** 📋 Backlog
+
+**FRs covered:** FR59
+
+**Acceptance Criteria:**
+
+**Given** Danfoss compressor data files
+**When** loading via DanfossBackend
+**Then** coefficients are extracted (AHRI 540 or Coolselector2 format)
+**And** compatible with standard compressor models
+**And** list_compressor_models() returns available models
+
+---
+
+### Story 11.15: Bitzer Parser
+
+**As a** refrigeration engineer,
+**I want** Bitzer compressor data integration,
+**So that** I can use Bitzer coefficients in simulations.
+
+**Status:** 📋 Backlog
+
+**FRs covered:** FR59
+
+**Acceptance Criteria:**
+
+**Given** Bitzer compressor data files (CSV format)
+**When** loading via BitzerBackend
+**Then** coefficients are extracted
+**And** compatible with standard compressor models
+**And** supports Bitzer polynomial format
+**And** list_compressor_models() returns available models
+
+---
+
 ## Future Epics (Vision – littérature HVAC)

 *Non planifiés – alignement avec EnergyPlus, Modelica, TRNSYS :*
--- a/_bmad-output/planning-artifacts/implementation-readiness-report-2026-02-21.md
+++ b/_bmad-output/planning-artifacts/implementation-readiness-report-2026-02-21.md
@@ -0,0 +1,89 @@
+---
+stepsCompleted: [1]
+includedFiles: ['prd.md', 'architecture.md', 'epics.md']
+---
+
+# Implementation Readiness Assessment Report
+
+**Date:** 2026-02-21
+**Project:** Entropyk
+
+## PRD Files Found
+
+**Whole Documents:**
+- prd.md
+
+## Architecture Files Found
+
+**Whole Documents:**
+- architecture.md
+
+## Epics & Stories Files Found
+
+**Whole Documents:**
+- epics.md
+
+## UX Design Files Found
+- None found.
+
+## UX Alignment Assessment
+
+### UX Document Status
+
+Not Found
+
+### Alignment Issues
+
+No explicit UX/UI documentation was found to align with the PRD and Architecture.
+
+### Warnings
+
+⚠️ **WARNING: Missing UX Documentation for Web Features**
+The PRD implies UI/UX requirements for end-users, specifically for web interfaces.
+- **FR33** mentions WebAssembly compilation support for web interfaces.
+- **Persona 2 (Charlie)** explicitly builds a web configurator with reactive sliders.
+- Post-MVP features mention expanding to a complete graphical interface with drag & drop components.
+A lack of UX documentation means there are no wireframes, design systems, or specific user flows defined for these visual and interactive elements. If UI development is part of Phase 4 implementation, this represents a significant gap that must be addressed before front-end development starts.
+
+## Epic Quality Review
+
+### 🔴 Critical Violations
+
+- **Technical Epics Rather Than User Value**: Almost all Epics (Epic 1: Extensible Component Framework, Epic 2: Fluid Properties Backend, Epic 3: System Topology, Epic 4: Intelligent Solver Engine) act as technical milestones rather than user-centric features. While this is a developer tool, epics should ideally be framed around what the end-user (developer/engineer) can accomplish, e.g., "Simulate a Single-Stage Heat Pump" rather than "Build a System Topology Graph".
+- **Epic Independence & Forward Dependencies**: The epics are highly coupled. Epic 4 (Solver) cannot function without Epic 1 (Components) and Epic 3 (Topology). This breaks the rule of epic independence. Story 5.6 (Control Variable Step Clipping) explicitly patches a deficiency in Story 4.2 (Newton-Raphson), demonstrating tight cross-epic coupling and forward/backward dependencies.
+
+### 🟠 Major Issues
+
+- **Story Sizing & Horizontal Slicing**: Stories like "Story 4.2: Newton-Raphson Implementation" and "Story 2.2: CoolProp Integration" represent massive horizontal architectural slices rather than vertical slices of user value. This makes them difficult to test independently without other system parts.
+
+### 🟡 Minor Concerns
+
+- **Acceptance Criteria Granularity**: Some acceptance criteria are broad (e.g., "handles missing backends gracefully with fallbacks") and might require further refinement to be fully testable by a developer.
+- **Database/Storage Timing**: N/A for this project as it is a stateless library, but JSON serialization (Epic 7) depends heavily on the graph and fluid backend structures being absolutely final.
+
+### Remediation Recommendations
+
+1. **Reframe Epics around User Value**: Consider re-slicing epics horizontally to deliver end-user value incrementally. For example, Epic 1 could be "Simulate basic refrigerant cycle" (building the minimum components, subset of topology, and simple solver). Epic 2 could be "Simulate complex multi-circuit machines" etc.
+2. **Acceptance as a Developer Tool exception**: Given the highly mathematical and coupled nature of simulation engines, the current architecture-led epic breakdown may be the only practical way to build the foundation. However, the team must be aware that true "user value" won't be demonstrable until Epic 4 (Solver) is completed.
+
+## Summary and Recommendations
+
+### Overall Readiness Status
+
+READY
+
+### Critical Issues Requiring Immediate Action
+
+Given the nature of the project (a deeply technical simulation library), true "Critical" issues blocking implementation are essentially zero. However, the following must be addressed to ensure smooth sailing:
+1. **UX/UI Definition for Web Features**: If the upcoming sprint includes the interface wrapper for the WebAssembly target (as implied by Persona 2 Charlie), design documentation or wireframes MUST be created before front-end work begins to avoid ad-hoc UI development.
+2. **Acceptance of Architectural Epics**: The team must formally accept that the epics are structured as technical milestones (Components, Fluid Backend, Topology, Solver) and not strictly independent user features. This means real end-to-end user value will only be unlocked once Epic 4 (Solver Engine) is integrated.
+
+### Recommended Next Steps
+
+1. **Acknowledge Technical Epic Structure**: Ensure the implementation team understands the cross-dependencies between Epic 1, Epic 2, Epic 3, and Epic 4.
+2. **Draft UX Requirements**: If Web UI is within scope for the immediate phase of development, write a short UX Document detailing the web configurator layout, slider interactions, and expected visual outputs.
+3. **Begin Implementation Phase**: The technical PRD is phenomenally detailed, rigorous physical tolerances are set, and architectural decisions are comprehensively mapped. The project is highly ready for code development.
+
+### Final Note
+
+This assessment identified 2 main issues across 4 categories (primarily around UX documentation and technical epic structuring). Address the UX gaps if front-end development is imminent. Otherwise, the pristine quality of the PRD and Architecture documents provides an exceptionally strong foundation to proceed to implementation.
--- a/_bmad-output/planning-artifacts/prd.md
+++ b/_bmad-output/planning-artifacts/prd.md
@@ -102,6 +102,43 @@ RustThermoCycle est une librairie de simulation thermodynamique haute-performanc
 - **Calibration inverse** (estimation des paramètres depuis données banc d'essai)
 - **Export données synthétiques** (génération de datasets pour ML/surrogates)

+### Advanced HVAC Components (Epic 11)
+
+**Composants pour Chillers et Pompes à Chaleur Industriels:**
+
+| Composant | Description | Priorité |
+|-----------|-------------|----------|
+| **Node** | Sonde passive (0 équations) pour extraction P, h, T, x, SH, SC | P0 |
+| **Drum** | Ballon de recirculation (2 in → 2 out: liquide saturé + vapeur saturée) | P0 |
+| **FloodedEvaporator** | Évaporateur noyé avec récepteur BP (sortie diphasique 50-80% vapeur) | P0 |
+| **FloodedCondenser** | Condenseur à accumulation (bain liquide régule P_cond) | P0 |
+| **BphxExchanger** | Échangeur à plaques brasées configurable (DX/Flooded) | P0 |
+| **MovingBoundaryHX** | Échangeur discretisé par zones de phase (SH/TP/SC) | P1 |
+| **VendorBackend** | API données fournisseurs (Copeland, Danfoss, SWEP, Bitzer) | P1 |
+
+**Corrélations de Transfert Thermique:**
+
+| Corrélation | Application | Défaut |
+|-------------|-------------|--------|
+| Longo (2004) | Plaques BPHX évap/cond | ✅ Défaut BPHX |
+| Shah (1979, 2021) | Tubes condensation | ✅ Défaut tubes |
+| Kandlikar (1990) | Tubes évaporation | Alternative |
+| Gungor-Winterton (1986) | Tubes évaporation | Alternative |
+| Gnielinski (1976) | Monophasique turbulent | Défaut mono |
+
+**Architecture VendorBackend:**
+```
+entropyk-vendors/
+├── data/
+│   ├── copeland/compressors/*.json
+│   ├── danfoss/compressors/*.json
+│   ├── swep/bphx/*.json
+│   └── bitzer/compressors/*.csv
+└── src/
+    ├── vendor_api.rs (trait VendorBackend)
+    └── compressors/{copeland,danfoss,bitzer}.rs
+```
+
 ### Vision (Future)

 - Simulation transitoire (dynamique, pas juste steady-state)
@@ -516,6 +553,7 @@ Le produit est utile uniquement si tous les éléments critiques fonctionnent en
 - **FR45** : Le système supporte la calibration inverse (estimation des paramètres depuis données banc d'essai)
 - **FR46** : Composants Coils air explicites (EvaporatorCoil, CondenserCoil) pour batteries à ailettes (post-MVP)
 - **FR51** : Le système permet d'échanger les coefficients de calibration (f_m, f_ua, f_power, etc.) en inconnues du solveur et les valeurs mesurées (Tsat, capacité, puissance) en contraintes, pour une calibration inverse en One-Shot sans optimiseur externe
+- **FR52** : Les bindings Python exposent la totalité des options de configuration du solveur Rust (initial_state, jacobian_freezing, convergence_criteria, timeout_config, etc.) pour permettre l'optimisation de la convergence depuis Python

 ---

@@ -556,15 +594,16 @@ Le produit est utile uniquement si tous les éléments critiques fonctionnent en

 **Workflow :** BMAD Create PRD  
 **Steps Completed :** 12/12  
-**Total FRs :** 51  
+**Total FRs :** 52  
 **Total NFRs :** 17  
 **Personas :** 5  
 **Innovations :** 5  

-**Last Updated :** 2026-02-21  
+**Last Updated :** 2026-02-22  
 **Status :** ✅ Complete & Ready for Implementation

 **Changelog :**
+- `2026-02-22` : Ajout FR52 (Python Solver Configuration Parity) — exposition complète des options de solveur en Python (Story 6.6).
 - `2026-02-21` : Ajout FR51 (Swappable Calibration Variables) — calibration inverse One-Shot via échange f_ ↔ contraintes (Story 5.5).
 - `2026-02-20` : Ajout FR49 (FlowSplitter/FlowMerger) et FR50 (FlowSource/FlowSink) — composants de jonction et conditions aux limites pour fluides compressibles et incompressibles (Story 1.11 et 1.12).