---
stepsCompleted:
  - step-01-init
  - step-02-discovery
  - step-03-success
  - step-04-journeys
  - step-05-domain
  - step-06-innovation
  - step-07-project-type
  - step-08-scoping
  - step-09-functional
  - step-10-nonfunctional
  - step-11-polish
  - step-12-complete
inputDocuments:
  - /Users/sepehr/dev/Entropyk/_bmad-output/planning-artifacts/product-brief-Entropyk-2026-02-12.md
documentCounts:
  briefCount: 1
  researchCount: 0
  brainstormingCount: 0
  projectDocsCount: 0
classification:
  projectType: developer_tool
  domain: scientific
  complexity: high
  projectContext: greenfield
workflowType: prd
---

# Product Requirements Document - RustThermoCycle

**Project:** Entropyk  
**Author:** Sepehr  
**Date:** 2026-02-12  
**Status:** ✅ Complete

---

## Executive Summary

RustThermoCycle est une librairie de simulation thermodynamique haute-performance écrite en Rust. Elle vise à remplacer les outils Python existants (tespy, CoolProp) en offrant une **performance 100x supérieure** et une **robustesse garantie** grâce à une architecture solver-agnostique avec fallback intelligent.

**Différenciateur clé :** Première librairie thermodynamique industrielle offrant des garanties temporelles strictes (< 1s convergence), permettant le Hardware-in-the-Loop (HIL) impossible avec Python.

---

## Success Criteria

### User Success

**Le "Moment Magique" - Instantanéité Perçue :**
- L'utilisateur modifie un paramètre (ex: Température extérieure) et le résultat s'affiche instantanément sans spinner de chargement
- **Hard Constraint** : Temps de convergence Steady State < **1 seconde** même en "Cold Start"
- Pour les développeurs d'interface : Sliders réactifs sans latence perceptible

### Business Success

**Différenciation Hardware-in-the-Loop (HIL) :**
- Permettre la simulation en temps réel sur banc de test
- Fréquence de simulation > **1 Hz** (aussi rapide que le contrôleur physique)
- **Impossible avec Python** - avantage compétitif clair

### Technical Success

**Performance Hard Real-Time :**

| Métrique | Cible |
|----------|-------|
| Cycle simple (Mono-étagé) | **< 100 ms** |
| Cycle complexe (Multi-circuits) | **< 1 s** |
| Optimisation locale (Inverse Control) | **< 1 s** |
| Carte 3600 points (1h simulée) | **< 3 s totales** |

**Robustesse sous Contrainte de Temps :**
- Timeout strict ou Max Iterations obligatoire
- Mieux vaut erreur "Non-Convergence" en 0.5s que recherche infinie
- Architecture : Newton-Raphson (convergence quadratique) avec fallback optimisé

---

## Product Scope

### MVP - Minimum Viable Product

**Scope Essentiel :**
- Compresseur, Condenseur, Détendeur, Évaporateur, Économiseur
- Support CoolProp pour fluides frigorigènes
- Topologie multi-circuits (N circuits indépendants)
- Gestion des états ON/OFF/BYPASS
- Solveur avec garantie < 1s (Newton-Raphson + fallback)
- Zero-Panic Policy (Result<T, ThermoError>)
- Pas d'allocation dynamique dans la boucle de résolution

### Growth Features (Post-MVP)

- WebAssembly compilation pour interfaces web
- API graphique/visualisation des cycles
- 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)

### 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)
- **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)

---

## User Journeys

### Persona 1 : R&D Engineer - "Marie la Dimensionneuse"

**Situation :** Marie travaille chez un fabricant de pompes à chaleur. Elle doit optimiser un cycle à deux étages pour une nouvelle gamme. Avec tespy, son script Python met 3 heures pour 100 combinaisons. Elle doit livrer demain.

**Parcours :**
1. **Découverte :** Elle lit la documentation RustThermoCycle, remarque la promesse "< 1s"
2. **Première simulation :** Elle définit sa machine bi-circuit en Rust
3. **Optimisation :** Lance l'exploration paramétrique (3600 points)
4. **Climax :** Résultats en **< 3 secondes** - elle peut itérer en temps réel
5. **Résolution :** Livraison à temps, nouvelle capacité d'études paramétriques

**État émotionnel :** 😰 Stressée → 🤔 Intriguée → 😲 Étonnée → 🎉 Triomphante

### Persona 2 : Web Developer - "Charlie le Configurateur"

**Situation :** Charlie développe un configurateur web B2B. Il veut des sliders réactifs sans spinner.

**Parcours :**
1. **Setup :** Compile RustThermoCycle en WebAssembly
2. **Intégration :** Expose l'API via wasm-bindgen
3. **UI :** Crée composant React avec sliders
4. **Climax :** Déplace un slider → Recalcul en **< 100ms**, expérience fluide
5. **Résolution :** Configurateur supérieur aux concurrents, clients enchantés

**État émotionnel :** 🤔 Curieux → 🛠️ Concentré → ✨ Magique → 🚀 Confiant

### Persona 3 : Researcher - "Robert le Topologue"

**Situation :** Robert est doctorant. Cycle CO2 avec Éjecteur + sous-refroidisseur. EES = 200 équations manuelles. tespy diverge au point critique. Il est bloqué.

**Parcours :**
1. **Installation :** Découvre l'API Graphe RustThermoCycle
2. **Modélisation :** Instancie `Ejector`, `FlashTank`, `Compressor`, connecte avec `system.connect()`
3. **Debug :** Active mode "Verbose" pour voir les résidus
4. **Climax :** Newton-Raphson diverge → **Fallback auto** en Substitution Séquentielle → stabilisation → retour Newton → **Convergé en 450ms**
5. **Résolution :** Publie son papier avec code reproductible, bilan d'exergie validé auto

**État émotionnel :** 😤 Bloqué → 🤨 Dubitatif → 😮 Fasciné → 🎓 Accompli

### Persona 4 : HIL & Control Engineer - "Sarah du Banc d'Essai"

**Situation :** Sarah doit valider algorithme de dégivrage sur PLC réel. Besoin de "Jumeau Numérique" temps réel. Python trop lent (GC pauses).

**Parcours :**
1. **Setup :** Compile RustThermoCycle en `.dll` / `.so` avec FFI C
2. **Configuration :** Modèle reçoit ouverture vanne (Input), renvoie Pression (Output) toutes les 100ms
3. **Test :** Lancement banc d'essai
4. **Climax :** Calcul état thermodynamique en **12ms** (< 100ms limite), mémoire stable (Rust ownership), 48h sans interruption
5. **Résolution :** Validation avant prototype physique, économie 3 semaines chambre climatique

**État émotionnel :** ⏱️ Pressée → 🔧 Technique → 🎯 Précise → 💰 Victorieuse

### Persona 5 : Data Engineer - "David le Batch-Processor"

**Situation :** David génère des datasets massifs pour entraîner des modèles IA (Surrogate Models). Besoin de throughput maximal.

**Parcours :**
1. **Architecture :** Utilise RustThermoCycle via CLI
2. **Parallélisation :** Exploite `Send + Sync` pour utiliser 100% des cœurs CPU
3. **Exécution :** Batch de millions de scénarios
4. **Climax :** Throughput maximum, zero contention, résultats cohérents
5. **Résolution :** Dataset d'entraînement généré rapidement, modèle IA prêt

**État émotionnel :** 📊 Ambitieux → ⚡ Performant → 🧮 Satisfait

### Journey Requirements Summary

**Capacités révélées par les parcours :**

| Parcours | Capacités Critiques |
|----------|---------------------|
| **Marie (R&D)** | Multi-circuits, Optimisation paramétrique, Performance < 1s |
| **Charlie (Web)** | WebAssembly compilation, API exposable, Latence < 100ms |
| **Robert (Chercheur)** | API Graphe intuitive, Fallback solver auto, Debug verbose, Validation exergie |
| **Sarah (HIL)** | FFI C (`.dll`/`.so`), Temps réel < 100ms, Memory safety (48h+), Deterministe |
| **David (Batch)** | Thread-Safety (`Send + Sync`), CLI, Parallélisation multi-cœur |

**Pattern commun :** Le **Solver-agnostic avec fallback** et la **performance hard real-time** sont des différenciateurs transversaux essentiels.

---

## Domain-Specific Requirements

### 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)
- Le code doit ingérer les polynômes de performance compressors au format industriel standard

**Propriétés Fluides (NIST/CoolProp) :**
- **Gold Standard :** NIST REFPROP
- **Open Source :** CoolProp référence
- **Exigence Performance :** Système capable de charger des tables de fluides (Tabular Interpolation) pour correspondre aux résultats NIST à **< 0.01%** près, tout en étant **100x plus rapide** que l'appel EOS direct

### Précision & Tolérances (Grade "Simulation Scientifique Critique")

| Type de Bilan | Tolérance |
|---------------|-----------|
| **Bilan de Masse** | Σ ṁ_in - Σ ṁ_out < **10⁻⁹ kg/s** (quasi-zéro machine) |
| **Bilan Énergétique** | Σ Q̇ + Ẇ - Σ (ṁ · h) < **10⁻⁶ kW** (1 milliwatt) |
| **Convergence Pression** | Résidu maximal : **1 Pa** (10⁻⁵ bar) |

*Note : La tolérance "bricolage" de 0.1% est inacceptable pour l'optimisation numérique (accumulation d'erreurs).*

### Traçabilité & Reproductibilité

Chaque résultat de simulation (`SimulationResult`) doit contenir un header de métadonnées :
- `solver_version` : Version du moteur Rust (ex: 0.1.0)
- `fluid_backend` : Version de la librairie fluide (ex: CoolProp 6.4.1)
- `input_hash` : Hash SHA-256 de la configuration d'entrée pour garantir la correspondance résultat/inputs

### Aspects Spécifiques au Domaine (Critical Pain Points)

#### A. Gestion du Point Critique (Critical Region)
- **Problème :** Pour le CO2 (R744), le cycle passe souvent au-dessus du point critique
- **Risque :** Les dérivées partielles (∂P/∂ρ) explosent (NaN) près du point critique
- **Solution :** Le solveur doit utiliser un "Damping" (amortissement) automatique dans cette zone

#### B. Glissement de Température (Temperature Glide)
- **Problème :** Pour les mélanges zeotropiques (R454B, R32/R125), la température change pendant l'évaporation à pression constante
- **Risque :** Calcul des échangeurs supposant T_sat = Constante (erreur significative)
- **Solution :** Le calcul doit intégrer le glissement (Bubble Point → Dew Point) sans approximation

---

## Innovation & Novel Patterns

### Detected Innovation Areas

#### Innovation #1 : Architecture Solver-Agnostic avec Fallback Intelligent ⭐
**Signal :** Newton-Raphson diverge → Fallback auto en Substitution Séquentielle → retour Newton → Convergé  
**Innovation :** Aucun outil existant ne permet de switcher dynamiquement entre solveurs sans modifier le code modèle  
**Impact :** Convergence garantie même dans les zones critiques (CO2 au point critique)  
**Statut :** **Innovation Critique (Money Maker)** - La robustesse est le différenciateur commercial principal

#### Innovation #2 : Performance Hard Real-Time Garantie
**Signal :** < 1s Cold Start, < 100ms cycle simple, déterministe 12ms pour HIL  
**Innovation :** Première librairie thermodynamique avec garanties temporelles strictes  
**Impact :** Hardware-in-the-Loop possible (impossible avec Python/GC pauses)

#### Innovation #3 : Topologie Multi-Circuits avec Couplage Thermique
**Signal :** N circuits indépendants avec échangeurs thermiques entre circuits  
**Innovation :** Graphe orienté multi-fluides dans un même modèle  
**Impact :** Simulation native de machines complexes (pompes à chaleur double-circuit)

#### Innovation #4 : Zero-Panic + No-Allocation
**Signal :** Result<T, ThermoError>, pas d'allocation dynamique dans la boucle  
**Innovation :** Garanties mémoire Rust appliquées au calcul scientifique  
**Impact :** Certification possible, déploiement embarqué (48h+ sans fuite)

#### Innovation #5 : Native Inverse Control via Residual Embedding ⭐
**Signal :** "Calculer l'ouverture de vanne pour une surchauffe cible"  
**Innovation :** Consigne de contrôle intégrée directement comme équation résiduelle dans la matrice système  
**Différence :** Pas de boucle d'optimisation externe - la vanne devient une inconnue du système résolue simultanément  
**Impact :** Simulation du comportement d'un régulateur PID parfait en "One-Shot", sans itérations externes

### Market Context & Competitive Landscape

| Solution | Limitation | Notre Avantage |
|----------|-----------|----------------|
| **tespy** | Python lent, solveur unique, divergence = crash | 100x plus rapide, fallback intelligent |
| **EES** | Équations manuelles, pas d'API graphe | API intuitive, modèle composant |
| **CoolProp** | Backend thermo uniquement, pas de solveur cycle | Intégration native, multi-circuits |
| **Commercial** | Solveur verrouillé, pas d'accès interne | Solver-agnostic, open source |

### Validation Approach

1. **Benchmark vs tespy/CoolProp** : Même cycle, mesurer speedup (objectif 100x)
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

#### Si le solveur ne converge pas dans le budget temps (HIL) :

**Stratégie de Dégradation Gracieuse :**

1. **Time-Budgeted Solving :** Vérification horloge système à chaque itération, arrêt si `elapsed > max_time`
2. **Zero-Order Hold (ZOH) avec Flag :** Retour du résultat précédent avec `ComputationStatus::Timeout`
3. **Jacobian Freezing :** Option de ne pas recalculer la Jacobienne à chaque pas (gain 80% CPU, perte de précision minime acceptable en HIL)

**Cas Extrême :** Si Newton-Raphson + fallback ne converge pas dans 0.5s
- Retour immédiat avec status `NonConverged`
- Utilisation du dernier état stable connu
- Logging détaillé pour diagnostic post-mortem

---

## Developer Tool Specific Requirements

### Language Support & FFI Strategy

**Rust Native (Le Cœur) :**
- API pure et "Safe" pour les développeurs d'applications (Charlie)
- Focus sur l'ergonomie Rust (ownership, types, performance)

**Python Bindings via PyO3 & Maturin (Le "Cheval de Troie") :**
- Permettre à Alice de remplacer `import tespy` par `import rust_thermo_cycle` sans réécrire sa logique
- **Vecteur d'adoption #1** : "Gardez votre Python, mais allez 100x plus vite"
- Distribution : Wheels pré-compilées (manylinux) sur PyPI

**C FFI via cbindgen (Pour le HIL) :**
- Génération automatique des headers `.h` pour intégration C/C++
- PLC, LabView, Simulink compatibles

### Packaging & Distribution

| Canal | Méthode | Utilisateur |
|-------|---------|-------------|
| **Rust** | `crates.io` | Développeurs Rust |
| **Python** | `pip install rust-thermo-cycle` (Wheels PyPI) | Data Scientists, R&D |
| **C/C++** | Headers + Librairies dynamiques | Intégrateurs HIL |
| **Docker** | Image `rust-thermo-lab` (JupyterLab + Rust kernel + CoolProp) | Nouveaux utilisateurs |

### Documentation Strategy

**API Docs (rustdoc) :**
- Signatures de fonctions, traits, types
- Documentation inline avec exemples de code

**Physics Manual (mdBook) :**
- Explication des équations résolues (Peng-Robinson, etc.)
- Guide du physicien, pas juste du développeur
- Formules mathématiques avec MathJax

**ADR (Architecture Decision Records) :**
- Pourquoi Newton-Raphson vs Broyden ?
- Pourquoi CoolProp vs RefProp ?
- Pourquoi Graphe vs Équations ?

### Code Examples Prioritaires

1. **"Benchmark Demo" (Le Vendeur) :**
   ```
   1000 simulations PAC simple
   Temps total : 450ms
   (Est. Python : 45s)
   Speedup : 100x
   ```

2. **"Inverse Control" :**
   - Définir `Superheat_Target = 5K`
   - Laisser le solveur trouver l'ouverture de vanne

3. **"Hybrid PyO3" :**
   - Python appelle Rust pour calcul lourd
   - Matplotlib pour tracer diagramme P-h

### DevEx & Qualité

**CI/CD Pipeline (GitHub Actions) :**
- `cargo test` : Unit tests
- `cargo bench` : Performance regression
- `valgrind` : Memory leaks (FFI)
- `cargo clippy -- -D warnings` : Tolérance zéro sur le style
- `miri test` : Undefined behavior detection

**Qualité Code :**
- `#![deny(warnings)]` dans `lib.rs`
- 100% documentation publique
- Examples compilés et testés dans CI

---

## Project Scoping & Phased Development

### MVP Strategy & Philosophy

**MVP Approach :** Platform MVP  
Le produit est utile uniquement si tous les éléments critiques fonctionnent ensemble : solveur robuste (fallback), performance garantie (< 1s), API ergonomique (Rust + Python).

### MVP Feature Set (Phase 1)

**Core User Journeys Supported :**
- Marie (R&D) : Optimisation paramétrique avec performance < 1s
- Robert (Chercheur) : Cycle complexe avec fallback solver
- Alice (Python) : Migration depuis tespy via PyO3

**Must-Have Capabilities :**

| Domaine | Features MVP |
|---------|-------------|
| **Composants** | Compresseur (AHRI 540), Condenseur, Détendeur, Évaporateur, Économiseur (Bypass support) |
| **Topologie** | Single circuit + Multi-circuits (2 max), Couplage thermique basique |
| **Solveur** | Newton-Raphson + Substitution Séquentielle (fallback), Timeout < 1s, Critère : Delta P < 1 Pa |
| **Bindings** | Rust native (crates.io), Python (PyO3 + PyPI) |
| **Validation** | Benchmark vs tespy (100x speedup), Test CO2 point critique |

### Post-MVP Features

**Phase 2 (Growth) :**
- FFI C pour HIL (Sarah)
- WebAssembly pour web (Charlie)
- Composants additionnels (Pompe, Échangeur eau/eau)
- Optimisation multi-cœurs (David)

**Phase 3 (Expansion) :**
- Simulation transitoire (dynamique, pas juste steady-state)
- Bibliothèque de cycles pré-configurés (standards industriels)
- Interface graphique web (drag & drop)

### Risk Mitigation Strategy

**Technical Risks :**
- CoolProp instable → Fallback sur tables tabulaires NIST
- Newton-Raphson diverge → Substitution Séquentielle auto

**Market Risks :**
- Migration Python difficile → API PyO3 identique à tespy

**Resource Risks :**
- 1 développeur → Scope strict, pas de transitoire en MVP

---

## Functional Requirements

### 1. Modélisation des Composants (Component Modeling)

- **FR1** : Le système peut modéliser un Compresseur selon la norme AHRI 540 avec coefficients du fabricant
- **FR2** : Le système peut modéliser un Condenseur avec transfert thermique calculé
- **FR3** : Le système peut modéliser un Détendeur (détente isenthalpique)
- **FR4** : Le système peut modéliser un Évaporateur avec changement de phase
- **FR5** : Le système peut modéliser un Économiseur (échangeur interne) avec mode Bypass
- **FR6** : Chaque composant peut être dans l'état OperationalState (On, Off, Bypass)
- **FR7** : En mode Off, un composant actif contribue un débit massique nul au système
- **FR8** : En mode Bypass, un composant se comporte comme un tuyau adiabatique (P_in = P_out, h_in = h_out)

### 2. Gestion de la Topologie (System Topology)

- **FR9** : L'utilisateur peut définir une Machine contenant N circuits fluidiques indépendants
- **FR10** : L'utilisateur peut connecter des composants via des Ports (entrée/sortie)
- **FR11** : Le système supporte les connexions entre circuits (couplage thermique)
- **FR12** : Le système peut résoudre les N circuits simultanément ou séquentiellement
- **FR13** : Le système gère mathématiquement les branches à débit nul sans division par zéro
- **FR48** : Le système permet de définir des sous-systèmes hiérarchiques (MacroComponents/Blocks) comme dans Modelica, encapsulant une topologie interne et exposant uniquement des ports (ex: raccorder deux Chillers en parallèle).
- **FR49** : Le système fournit des composants de jonction fluidique (`FlowSplitter` 1→N et `FlowMerger` N→1) pour fluides compressibles (réfrigérant, CO₂) et incompressibles (eau, glycol, saumure), avec équations de bilan de masse, isobare et enthalpie de mélange pondérée (`with_mass_flows`).
- **FR50** : Le système fournit des composants de condition aux limites (`RefrigerantSource` et `RefrigerantSink`) pour fixer les états de pression et d'enthalpie aux bornes d'un circuit, pour fluides compressibles et incompressibles.

### 3. Résolution du Système (Solver)

- **FR14** : Le système peut résoudre les équations par méthode Newton-Raphson
- **FR15** : Le système peut résoudre les équations par Substitution Séquentielle (Picard)
- **FR16** : Le solveur bascule automatiquement en Substitution Séquentielle si Newton-Raphson diverge
- **FR17** : Le solveur respecte un budget temps configurable (timeout)
- **FR18** : En cas de timeout, le solveur retourne le meilleur état connu avec statut NonConverged
- **FR19** : Le solveur peut geler le calcul de la Jacobienne pour accélérer (Jacobian Freezing)
- **FR20** : Le critère de convergence vérifie Delta Pression < 1 Pa (1e-5 bar)
- **FR21** : Pour multi-circuits, la convergence globale est atteinte quand TOUS les circuits convergent
- **FR42** : Le système inclut une heuristique d'Initialisation Automatique (Smart Guesser) proposant des valeurs de pression initiales cohérentes basées sur les températures sources/puits

### 4. Inverse Control (Régulation)

- **FR22** : L'utilisateur peut définir des contraintes de sortie (ex: Superheat = 5K)
- **FR23** : Le système calcule les entrées nécessaires (ex: ouverture vanne) en respectant des Contraintes Bornées (0.0 ≤ Valve ≤ 1.0). Si la solution est hors bornes, le solveur retourne une erreur "Saturation" ou "ControlLimitReached"
- **FR24** : L'Inverse Control est résolu simultanément avec les équations du cycle (One-Shot)

### 5. Propriétés des Fluides (Fluid Properties)

- **FR25** : Le système peut charger des propriétés de fluides via CoolProp
- **FR26** : Le système supporte les tables tabulaires (Tabular Interpolation) pour performance 100x
- **FR27** : Le système gère les fluides purs et les mélanges (R32/R125, R454B)
- **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

- **FR30** : API Rust native avec types et ownership safety
- **FR31** : Bindings Python via PyO3 avec API compatible tespy
- **FR32** : FFI C pour intégration avec systèmes externes (PLC, LabView)
- **FR33** : WebAssembly compilation supportée pour interfaces web
- **FR34** : CLI pour exécution batch de simulations

### 7. Sérialisation & Persistance

- **FR41** : Le graphe complet (Topologie + Paramètres + État du Fluide) est sérialisable/désérialisable en JSON (ou TOML)

### 8. Validation & Diagnostics

- **FR35** : Le système vérifie automatiquement le bilan de masse (Σ ṁ_in - Σ ṁ_out < 1e-9 kg/s)
- **FR36** : Le système vérifie automatiquement le bilan énergétique (Σ Q̇ + Ẇ - Σ (ṁ · h) < 1e-6 kW)
- **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)
- **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

---

## Non-Functional Requirements

### Performance

- **NFR1** : Temps de convergence Steady State < **1 seconde** pour cycle standard en Cold Start
- **NFR2** : Cycle simple (Mono-étagé) résolu en **< 100 ms**
- **NFR3** : Cycle complexe (Multi-circuits) résolu en **< 1 seconde**
- **NFR4** : Pas d'allocation dynamique dans la boucle de résolution (allocation pré-calculée uniquement)
- **NFR5** : Déterminisme garanti : mêmes entrées → mêmes résultats à 1e-9 près sur toutes les plateformes (x86, ARM, WASM)
- **NFR6** : Latence HIL < **20 ms** pour intégration temps réel avec PLC

### Fiabilité (Reliability)

- **NFR7** : Zero-Panic Policy : aucun crash même avec entrées invalides ou états impossibles
- **NFR8** : Memory Safety garantie par Rust ownership system (pas de fuite mémoire, pas de use-after-free)
- **NFR9** : Capacité à tourner **48h+** sans interruption ni dégradation (HIL/Emabarqué)
- **NFR10** : Gestion gracieuse des erreurs : timeout, non-convergence, saturation retournent Result<T, Error> explicite

### Intégration

- **NFR11** : Compatibilité CoolProp 6.4+ pour propriétés des fluides
- **NFR12** : FFI C stable : headers .h auto-générés via cbindgen, compatible C99/C++
- **NFR13** : WebAssembly déterministe : même comportement que natif, pas de source de non-déterminisme
- **NFR14** : Python bindings PyO3 : API compatible tespy pour migration facilitée

### Maintenabilité

- **NFR15** : Documentation 100% des API publiques (rustdoc)
- **NFR16** : CI/CD automatisé : tests, benchmarks, memory checks (Valgrind + Miri)
- **NFR17** : Tolérance zéro warnings : `cargo clippy -- -D warnings`

---

## Document Information

**Workflow :** BMAD Create PRD  
**Steps Completed :** 12/12  
**Total FRs :** 60 (FR1-FR52 core + FR53-FR60 Epic 11)  
**Total NFRs :** 17  
**Personas :** 5  
**Innovations :** 5  

**Last Updated :** 2026-04-26
**Status :** ✅ Complete & Ready for Implementation

**Changelog :**
- `2026-04-26` : Ajout section "Pillar Mapping" et "FR Coverage Map by Pillar" pour alignement avec la restructuration en 6 piliers (voir `epic-restructuring.md`).
- `2026-02-28` : Correction du compteur FR (52→60) pour refléter les FR53-FR60 ajoutés dans epics.md pour Epic 11.
- `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 (RefrigerantSource/RefrigerantSink) — composants de jonction et conditions aux limites pour fluides compressibles et incompressibles (Story 1.11 et 1.12).

---

## Pillar Mapping

Ce PRD a été réorganisé selon une architecture à 6 piliers métier. La correspondance entre piliers et sections du PRD est la suivante :

| Pillar | Nom | PRD Sections | Crate |
|--------|-----|-------------|-------|
| P1 | Foundation | Types (FR6-FR8), Topologie (FR9-FR13, FR48) | `entropyk-core` |
| P2 | Real Components | Composants (FR1-FR5, FR46, FR53-FR60) | `entropyk-components`, `entropyk-vendors` |
| P3 | Fluid Properties | Fluides (FR25-FR29, FR40, FR47) | `entropyk-fluids` |
| P4 | Simulation & Solver | Solveur (FR14-FR21), Régulation (FR22-FR24), Validation (FR35-FR39, FR43, FR45, FR51) | `entropyk-solver` |
| P5 | User Interfaces | API (FR30-FR34), Sérialisation (FR41, FR52) | `entropyk-cli`, `bindings/*` |
| P6 | HVAC Applications | Validation industrielle (FR44), Applications futures | (pas de crate dédié) |

Voir `pillars.md` pour l'inventaire complet des stories par pilier.

## FR Coverage Map by Pillar

| FR | Pillar | Stories clés |
|----|--------|-------------|
| FR1 | P2 | P2-01 (Compressor AHRI 540) |
| FR2 | P2 | P2-02 (Generic HX Framework) |
| FR3 | P2 | P2-03 (Expansion Valve) |
| FR4 | P2 | P2-02, P2-18, P2-19, P2-21, P2-22 |
| FR5 | P2 | P2-02 (Economizer / HX Framework) |
| FR6-FR8 | P1 | P1-04 (Component State Machine) |
| FR9-FR13 | P1 | P1-05, P1-06, P1-07, P1-08, P1-09 |
| FR14-FR21 | P4 | P4-01 à P4-08 |
| FR22-FR24 | P4 | P4-09, P4-10, P4-11 |
| FR25-FR29 | P3 | P3-01 à P3-06 |
| FR30-FR34 | P5 | P5-01 à P5-04 |
| FR35-FR39 | P4 | P4-15 à P4-18 |
| FR40 | P3 | P3-07 (Incompressible Fluids) |
| FR41 | P4 | P4-19 (JSON Serialization) |
| FR42 | P4 | P4-06 (Smart Initialization) |
| FR43 | P4 | P4-20 (Calib Parameters) |
| FR44 | P6 | P6-09 (ASHRAE 140/BESTEST) |
| FR45 | P4, P6 | P4-25 (Inverse Calib Solver), P6-10 (Inverse Calib App) |
| FR46 | P2 | P2-05 (Air Coils) |
| FR47 | P3 | P3-08 (Rich ThermoState) |
| FR48 | P1 | P1-10 (Hierarchical Subsystems) |
| FR49 | P2 | P2-07 (FlowSplitter/FlowMerger) |
| FR50 | P2 | P2-08 (RefrigerantSource/Sink) |
| FR51 | P4 | P4-13 (Swappable Calibration Variables) |
| FR52 | P5 | P5-06 (Python Solver Parity) |
| FR53-FR60 | P2 | P2-16 à P2-30 (Epic 11: Advanced HVAC Components) |

---

*Ce PRD sert de fondation pour toutes les activités de développement produit. Tout le travail de conception, d'architecture et de développement doit être tracé vers les exigences et la vision documentées dans ce PRD.*
