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 |
|
||||
|
||||
@@ -95,13 +95,19 @@ RustThermoCycle est une librairie de simulation thermodynamique haute-performanc
|
||||
|
||||
- WebAssembly compilation pour interfaces web
|
||||
- API graphique/visualisation des cycles
|
||||
- Composants additionnels (Pompe, Échangeur eau/eau, etc.)
|
||||
- Composants additionnels (Pompe, Échangeur eau/eau, **Coils air**)
|
||||
- Support d'autres backends thermodynamiques (RefProp)
|
||||
- Parallélisation multi-threading
|
||||
- **Validation ASHRAE 140 / BESTEST** (cas de test standardisés)
|
||||
- **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)
|
||||
|
||||
### Vision (Future)
|
||||
|
||||
- Simulation transitoire (dynamique, pas juste steady-state)
|
||||
- **Part-load / cyclage** (courbes PLF, pertes de cyclage)
|
||||
- **Frost / defrost** (pompes à chaleur air)
|
||||
- **Moving boundary** (échangeurs discretisés, zones superheated/two-phase/subcooled)
|
||||
- Intégration directe avec outils de contrôle (PLC, DDC)
|
||||
- Bibliothèque de cycles pré-configurés (standards industriels)
|
||||
- Interface graphique complète (drag & drop de composants)
|
||||
@@ -195,6 +201,11 @@ RustThermoCycle est une librairie de simulation thermodynamique haute-performanc
|
||||
|
||||
### Standards Industriels & Validation
|
||||
|
||||
**Référence littérature HVAC (EnergyPlus, TRNSYS, Modelica) :**
|
||||
- **ASHRAE Standard 140** : Méthode de test pour évaluer les logiciels de simulation énergétique bâtiment
|
||||
- **BESTEST / Airside HVAC** : Cas AE101–AE445 pour validation équipements HVAC
|
||||
- **Calibration** : Paramètres Calib (f_m, f_dp, f_ua, f_power) alignés sur Buildings Modelica, EnergyPlus, TRNSYS
|
||||
|
||||
**Composants Compressors (AHRI 540) :**
|
||||
- Implémentation stricte du standard **AHRI 540** pour la modélisation des compresseurs
|
||||
- Support des coefficients standardisés (10 coefficients) fournis par les fabricants (Bitzer, Copeland, Danfoss)
|
||||
@@ -282,6 +293,8 @@ Chaque résultat de simulation (`SimulationResult`) doit contenir un header de m
|
||||
2. **HIL Validation** : Connecter à PLC réel, mesurer latence (objectif < 20ms)
|
||||
3. **Convergence Stress Test** : Cycles CO2 proches point critique
|
||||
4. **Memory Safety Audit** : Valgrind + **Miri** (interpréteur MIR Rust) sur 48h
|
||||
5. **ASHRAE 140 / BESTEST** (post-MVP) : Cas de test standardisés pour crédibilité industrielle
|
||||
6. **Calibration inverse** : Ajustement paramètres depuis données fabricant ou banc d'essai
|
||||
|
||||
### Risk Mitigation
|
||||
|
||||
@@ -474,6 +487,7 @@ Le produit est utile uniquement si tous les éléments critiques fonctionnent en
|
||||
- **FR28** : Le système gère le glissement de température (Temperature Glide) pour mélanges zeotropiques
|
||||
- **FR29** : Le système utilise le damping automatique près du point critique (CO2 R744)
|
||||
- **FR40** : Le système gère les Fluides Incompressibles (Eau, Glycol, Air Humide simplifié) via des modèles allégés (Cp constant ou polynomial) pour les sources et puits de chaleur
|
||||
- **FR47** : Chaque composant frigorifique doit exposer nativement un état thermodynamique complet (Pression, Température, T_sat, Titre massique, Surchauffe, Sous-refroidissement, Débit massique, Reynolds, Enthalpie, Entropie) accessible facilement sans recalcul complexe par l'utilisateur.
|
||||
|
||||
### 6. API & Interfaces
|
||||
|
||||
@@ -494,6 +508,10 @@ Le produit est utile uniquement si tous les éléments critiques fonctionnent en
|
||||
- **FR37** : Chaque résultat contient métadonnées de traçabilité (version solver, version fluide, hash SHA-256 input)
|
||||
- **FR38** : Mode Debug Verbose pour afficher les résidus et l'historique de convergence
|
||||
- **FR39** : Gestion des erreurs via Result<T, ThermoError> (Zero-Panic Policy)
|
||||
- **FR43** : Les composants supportent des paramètres de calibration (Calib) pour rapprocher la simulation des données machines réelles
|
||||
- **FR44** : Le système peut valider ses résultats contre des cas de test ASHRAE 140 / BESTEST (post-MVP)
|
||||
- **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)
|
||||
|
||||
---
|
||||
|
||||
@@ -534,7 +552,7 @@ Le produit est utile uniquement si tous les éléments critiques fonctionnent en
|
||||
|
||||
**Workflow :** BMAD Create PRD
|
||||
**Steps Completed :** 12/12
|
||||
**Total FRs :** 42
|
||||
**Total FRs :** 47
|
||||
**Total NFRs :** 17
|
||||
**Personas :** 5
|
||||
**Innovations :** 5
|
||||
|
||||
Reference in New Issue
Block a user