feat(components): add ThermoState generators and Eurovent backend demo
This commit is contained in:
Sepehr
@@ -102,6 +102,16 @@ This document provides the complete epic and story breakdown for Entropyk, decom
|
||||
|
||||
**FR42:** System includes Automatic Initialization Heuristic (Smart Guesser) proposing coherent initial pressure values based on source/sink temperatures
|
||||
|
||||
**FR43:** Components support calibration parameters (Calib: f_m, f_dp, f_ua, f_power, f_etav) to match simulation to real machine test data
|
||||
|
||||
**FR44:** System can validate results against ASHRAE 140 / BESTEST test cases (post-MVP)
|
||||
|
||||
**FR45:** System supports inverse calibration (parameter estimation from test bench data)
|
||||
|
||||
**FR46:** Explicit Air Coil components (EvaporatorCoil, CondenserCoil) for finned air heat exchangers (post-MVP)
|
||||
|
||||
**FR47:** Each refrigeration component natively exposes a complete thermodynamic state (Pressure, Temperature, T_sat, Quality, Superheat, Subcooling, Mass flow, Reynolds, Enthalpy, Entropy) easily accessible without complex recalculations.
|
||||
|
||||
### NonFunctional Requirements
|
||||
|
||||
**NFR1:** Steady State convergence time < **1 second** for standard cycle in Cold Start
|
||||
@@ -236,6 +246,11 @@ This document provides the complete epic and story breakdown for Entropyk, decom
|
||||
| FR40 | Epic 2 | Incompressible fluids support |
|
||||
| FR41 | Epic 7 | JSON serialization |
|
||||
| FR42 | Epic 4 | Smart initialization heuristic |
|
||||
| FR43 | Epic 7 | Component calibration parameters (Calib) |
|
||||
| FR44 | Epic 7 | ASHRAE 140 / BESTEST validation |
|
||||
| FR45 | Epic 7 | Inverse calibration (parameter estimation) |
|
||||
| FR46 | Epic 1 | Air Coils (EvaporatorCoil, CondenserCoil) |
|
||||
| FR47 | Epic 2 | Rich Thermodynamic State Abstraction |
|
||||
|
||||
## Epic List
|
||||
|
||||
@@ -244,7 +259,7 @@ This document provides the complete epic and story breakdown for Entropyk, decom
|
||||
|
||||
**Innovation:** Trait-based "Lego" architecture to add Compressors, Pumps, VFDs, Pipes, etc.
|
||||
|
||||
**FRs covered:** FR1, FR2, FR3, FR4, FR5, FR6, FR7, FR8
|
||||
**FRs covered:** FR1, FR2, FR3, FR4, FR5, FR6, FR7, FR8, FR46
|
||||
|
||||
---
|
||||
|
||||
@@ -253,7 +268,7 @@ This document provides the complete epic and story breakdown for Entropyk, decom
|
||||
|
||||
**Innovation:** 100x performance with tabular tables, automatic CO2 damping.
|
||||
|
||||
**FRs covered:** FR25, FR26, FR27, FR28, FR29, FR40
|
||||
**FRs covered:** FR25, FR26, FR27, FR28, FR29, FR40, FR47
|
||||
|
||||
---
|
||||
|
||||
@@ -298,7 +313,7 @@ This document provides the complete epic and story breakdown for Entropyk, decom
|
||||
|
||||
**Innovation:** Complete traceability and scientific reproducibility.
|
||||
|
||||
**FRs covered:** FR35, FR36, FR37, FR38, FR39, FR41
|
||||
**FRs covered:** FR35, FR36, FR37, FR38, FR39, FR41, FR43, FR44, FR45
|
||||
|
||||
---
|
||||
|
||||
@@ -539,6 +554,22 @@ This document provides the complete epic and story breakdown for Entropyk, decom
|
||||
|
||||
---
|
||||
|
||||
### Story 2.8: Rich Thermodynamic State Abstraction
|
||||
|
||||
**As a** system engineer,
|
||||
**I want** components to expose a comprehensive `ThermoState` structure (P, T, T_sat, Quality, tsh, Reynolds, Enthalpy, Entropy, etc.),
|
||||
**So that** I don't have to manually calculate these from raw state arrays after solver convergence.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** a converged component (e.g., Compressor or Condenser)
|
||||
**When** I call `component.outlet_thermo_state()`
|
||||
**Then** it returns a `ThermoState` object
|
||||
**And** the object contains dynamically resolved saturated temperature, vapor quality, superheat, and phase
|
||||
**And** `FluidBackend` natively supports resolving this full snapshot in one trait call `full_state(p, h)`
|
||||
|
||||
---
|
||||
|
||||
## Epic 3: System Topology (Graph)
|
||||
|
||||
### Story 3.1: System Graph Structure
|
||||
@@ -1007,3 +1038,136 @@ This document provides the complete epic and story breakdown for Entropyk, decom
|
||||
**And** human-readable, versioned format
|
||||
**And** explicit error if backend missing on load
|
||||
**And** error specifies required backend version
|
||||
|
||||
---
|
||||
|
||||
### Story 7.6: Component Calibration Parameters (Calib)
|
||||
|
||||
**As a** R&D engineer matching simulation to real machine test data,
|
||||
**I want** calibration factors (Calib: f_m, f_dp, f_ua, f_power, f_etav) on components,
|
||||
**So that** simulation results align with manufacturer test data and field measurements.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** a component with nominal model parameters
|
||||
**When** Calib (calibration factors) are set (default 1.0 = no correction)
|
||||
**Then** f_m scales mass flow: ṁ_eff = f_m × ṁ_nominal (Compressor, Expansion Valve)
|
||||
**And** f_dp scales pressure drop: ΔP_eff = f_dp × ΔP_nominal (Pipe, Heat Exchanger)
|
||||
**And** f_ua scales thermal conductance: UA_eff = f_ua × UA_nominal (Evaporator, Condenser)
|
||||
**And** f_power scales compressor power: Ẇ_eff = f_power × Ẇ_nominal (Compressor)
|
||||
**And** f_etav scales volumetric efficiency: η_v,eff = f_etav × η_v,nominal (Compressor, displacement models)
|
||||
|
||||
**Given** calibration factors from test data optimization
|
||||
**When** running simulation with calibrated components
|
||||
**Then** results match test data within configurable tolerance (e.g., capacity ±2%, power ±3%)
|
||||
**And** Calib values are serializable in JSON (persisted with system definition)
|
||||
**And** calibration workflow order documented: f_m → f_dp → f_ua, then f_power (prevents parameter fighting)
|
||||
|
||||
**Given** a calibrated system
|
||||
**When** loading from JSON
|
||||
**Then** Calib parameters are restored
|
||||
**And** traceability metadata includes calibration source (test data hash or identifier)
|
||||
|
||||
---
|
||||
|
||||
### Story 7.7: ASHRAE 140 / BESTEST Validation (post-MVP)
|
||||
|
||||
**As a** simulation engineer seeking industrial credibility,
|
||||
**I want** to validate Entropyk against ASHRAE Standard 140 and BESTEST test cases,
|
||||
**So that** results are comparable to EnergyPlus, TRNSYS, and Modelica.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** ASHRAE 140 / Airside HVAC BESTEST (AE101–AE445) test case definitions
|
||||
**When** running Entropyk on equivalent cycle configurations
|
||||
**Then** results fall within documented tolerance bands vs reference
|
||||
**And** discrepancies are documented (algorithmic, modeling assumptions)
|
||||
**And** CI includes regression tests for selected cases
|
||||
|
||||
**Given** a new Entropyk release
|
||||
**When** running validation suite
|
||||
**Then** no regression beyond tolerance
|
||||
**And** validation report generated (JSON or markdown)
|
||||
|
||||
---
|
||||
|
||||
### Story 7.8: Inverse Calibration (Parameter Estimation)
|
||||
|
||||
**As a** R&D engineer with test bench data,
|
||||
**I want** to estimate Calib (or component) parameters from measured data,
|
||||
**So that** the model matches my machine without manual tuning.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** test data (P, T, ṁ, Ẇ, Q at multiple operating points)
|
||||
**When** running inverse calibration
|
||||
**Then** optimizer minimizes error (e.g., MAPE) between model and data
|
||||
**And** estimated Calib (or coefficients) are returned
|
||||
**And** supports constraints (e.g., 0.8 ≤ f_ua ≤ 1.2)
|
||||
**And** calibration order respected (f_m → f_dp → f_ua → f_power)
|
||||
|
||||
**Given** calibrated parameters
|
||||
**When** saving system
|
||||
**Then** Calib values and calibration_source (data hash) persisted in JSON
|
||||
|
||||
---
|
||||
|
||||
### Story 1.9: Air Coils (EvaporatorCoil, CondenserCoil) (post-MVP)
|
||||
|
||||
**As a** HVAC engineer modeling split systems or air-source heat pumps,
|
||||
**I want** explicit EvaporatorCoil and CondenserCoil components,
|
||||
**So that** air-side heat exchangers (finned) are clearly distinguished from water-cooled.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** an EvaporatorCoil (refrigerant + air)
|
||||
**When** defining the component
|
||||
**Then** 4 ports: refrigerant in/out, air in/out
|
||||
**And** UA or geometry (fins, tubes) configurable
|
||||
**And** integrates with Fan for air flow
|
||||
**And** Calib (f_ua, f_dp) applicable
|
||||
|
||||
**Given** a CondenserCoil
|
||||
**Then** same structure as EvaporatorCoil
|
||||
**And** refrigerant condenses on hot side, air on cold side
|
||||
|
||||
---
|
||||
|
||||
### Story 1.10: Pipe Helpers for Water and Refrigerant
|
||||
|
||||
**As a** HVAC engineer modeling refrigerant and incompressible fluid circuits (water, seawater, glycol),
|
||||
**I want** convenient constructors `Pipe::for_incompressible()` and `Pipe::for_refrigerant()` with explicit ρ/μ from a fluid backend,
|
||||
**So that** I can create pipes without hardcoding fluid properties in the component.
|
||||
|
||||
**Acceptance Criteria:**
|
||||
|
||||
**Given** an incompressible fluid circuit (water, seawater, glycol)
|
||||
**When** calling `Pipe::for_incompressible(geometry, port_inlet, port_outlet, density, viscosity)`
|
||||
**Then** accepts explicit ρ, μ obtained from IncompressibleBackend (Story 2.7)
|
||||
**And** no hardcoded fluid properties in components crate
|
||||
**And** doc examples show water and glycol usage
|
||||
|
||||
**Given** a refrigerant circuit (R134a, R410A, CO2, etc.)
|
||||
**When** calling `Pipe::for_refrigerant(geometry, port_inlet, port_outlet, density, viscosity)`
|
||||
**Then** accepts explicit ρ, μ (from CoolProp/tabular at design point)
|
||||
**And** doc examples show refrigerant circuit usage
|
||||
**And** doc states that ρ, μ vary with P,T — design-point values are typical
|
||||
|
||||
**Given** the Pipe module documentation
|
||||
**When** reading the crate-level and `Pipe` docs
|
||||
**Then** explicitly states that Pipe serves for both refrigerant and incompressible fluids
|
||||
**And** includes a "Fluid Support" section: refrigerant (ρ/μ from backend) vs incompressible (ρ/μ from IncompressibleBackend)
|
||||
|
||||
---
|
||||
|
||||
## Future Epics (Vision – littérature HVAC)
|
||||
|
||||
*Non planifiés – alignement avec EnergyPlus, Modelica, TRNSYS :*
|
||||
|
||||
| Epic | Thème | Référence littérature |
|
||||
|------|-------|------------------------|
|
||||
| **Transient** | Simulation dynamique, start-up/shutdown, ODEs | Reddy, Purdue IIAR |
|
||||
| **Part-load** | Courbes PLF, pertes de cyclage | EnergyPlus PLF |
|
||||
| **Frost/Defrost** | Givre, dégivrage, enthalpy method | arXiv 2412.00017 |
|
||||
| **Moving Boundary** | Échangeurs discretisés, zones phase | Modelica Buildings, TIL Suite |
|
||||
| **Export ML** | Données synthétiques pour surrogates | arXiv 2505.15041 |
|
||||
|
||||
Reference in New Issue
Block a user