Initial commit: BMAD framework + Story 1.1 Component Trait Definition

Features: - BMAD (Build Modular AI-driven Development) framework setup - BMM, BMB, CIS, Core modules configured - Story 1.1: Component trait with error handling - Workspace Cargo.toml with components crate - 31 tests passing (19 unit + 12 doc tests) Technical: - Component trait with compute_residuals, jacobian_entries, n_equations - ComponentError enum with thiserror - JacobianBuilder for sparse matrix construction - Object-safe trait supporting Box<dyn Component> - Comprehensive documentation and examples
2026-02-14 13:44:32 +01:00
parent 22dd012a74
commit 1fdfefe631
634 changed files with 70435 additions and 0 deletions
--- a/_bmad-output/planning-artifacts/architecture.md
+++ b/_bmad-output/planning-artifacts/architecture.md
--- a/_bmad-output/planning-artifacts/epics.md
+++ b/_bmad-output/planning-artifacts/epics.md
--- a/_bmad-output/planning-artifacts/prd.md
+++ b/_bmad-output/planning-artifacts/prd.md
@@ -0,0 +1,547 @@
+---
+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, etc.)
+- Support d'autres backends thermodynamiques (RefProp)
+- Parallélisation multi-threading
+
+### Vision (Future)
+
+- Simulation transitoire (dynamique, pas juste steady-state)
+- 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
+
+**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
+
+### 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
+
+### 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
+
+### 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)
+
+---
+
+## 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 :** 42  
+**Total NFRs :** 17  
+**Personas :** 5  
+**Innovations :** 5  
+
+**Last Updated :** 2026-02-12  
+**Status :** ✅ Complete & Ready for Implementation
+
+---
+
+*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.*
--- a/_bmad-output/planning-artifacts/product-brief-Entropyk-2026-02-12.md
+++ b/_bmad-output/planning-artifacts/product-brief-Entropyk-2026-02-12.md
@@ -0,0 +1,556 @@
+---
+stepsCompleted: [1, 2, 3, 4, 5]
+inputDocuments: []
+date: 2026-02-12
+author: Sepehr
+---
+
+# Product Brief: RustThermoCycle
+
+## Executive Summary
+
+RustThermoCycle is a high-performance thermodynamic cycle simulation library written in Rust, designed to overcome the fundamental limitations of current open-source tools. While Python-based solutions like tespy and CoolProp suffice for single calculations, they become prohibitive bottlenecks during multi-variable optimizations requiring 10,000+ iterations. Furthermore, existing tools couple physical models tightly with solvers, leaving users blocked when algorithms diverge at critical operating points.
+
+RustThermoCycle delivers a modular, solver-agnostic architecture that enables R&D engineers and researchers to simulate Heat Pumps and Refrigeration systems with unprecedented speed and flexibility. By leveraging Rust's zero-cost abstractions and type safety, the library supports seamless switching between Sequential Substitution (Picard) and Newton-Raphson solvers without modifying component code—a capability absent from both open-source and many commercial alternatives.
+
+The library's graph-based topology system enables Modelica-like component connection (Port A → Port B) while maintaining Rust's execution speed. Critical industry needs such as Inverse Control—calculating valve openings from target superheat constraints—are handled through integrated residual solvers. With planned WebAssembly (Wasm) compilation support, RustThermoCycle bridges the gap between high-performance simulation and accessible web interfaces.
+
+---
+
+## Core Vision
+
+### Problem Statement
+
+Current thermodynamic cycle simulation tools force users into an unacceptable trade-off: either accept Python's interpreter overhead that makes multi-variable optimization impractical, or tolerate rigid solver architectures that fail at phase transition critical points without recourse.
+
+### Problem Impact
+
+For R&D engineers dimensioning Heat Pump systems, this means:
+- **Optimization cycles measured in hours instead of minutes** when exploring design parameter spaces
+- **Solver divergence at critical operating points** halting entire simulation workflows
+- **Inability to simulate real-world control scenarios** where input variables must be calculated from output constraints (Inverse Control)
+
+For researchers testing novel cycle architectures:
+- **Limited flexibility to experiment with solver strategies** for exotic working fluids or unconventional component arrangements
+- **Maintenance burden of pure equation-based models** (à la EES) or rigid block diagrams
+
+### Why Existing Solutions Fall Short
+
+**Python-Based Tools (tespy, CoolProp bindings):**
+- Suffer from interpreter overhead making 10,000+ iteration optimizations prohibitively slow
+- Lack compile-time guarantees that could prevent unit mixing or invalid thermodynamic states
+
+**Commercial Tools (EES, Type S):**
+- Often based on pure equation approaches that are difficult to maintain and extend
+- Solver strategies typically hard-coded without runtime switching capability
+- Expensive licensing restricts academic access and collaborative development
+
+**Current Open-Source Alternatives:**
+- Tightly couple physical models with specific solver implementations
+- Provide no clean abstraction for Inverse Control scenarios common in industry
+- Miss the performance/safety balance that Rust provides
+
+### Proposed Solution
+
+RustThermoCycle delivers a modular Rust library with four architectural pillars:
+
+1. **Graph-Based Topology**: Components (Compressors, Evaporators, Condensers) connect through typed Fluid Nodes, enabling intuitive cycle construction à la Modelica but with Rust's performance.
+
+2. **Solver Decoupling via Traits**: A trait-based abstraction layer allows seamless switching between Sequential Substitution (Picard iteration) for robust initialization and Newton-Raphson (via nalgebra) for rapid quadratic convergence—without touching component implementations. Dynamic fallback between strategies when divergence is detected.
+
+3. **Inverse Control Framework**: Built-in residual solvers transform output constraints (target superheat, subcooling) into solvable systems for unknown inputs (valve openings, compressor speeds)—matching real-world control logic.
+
+4. **Academic Rigor & Portability**: 
+   - 3-Zone heat exchanger models with rigorous energy balances
+   - AHRI polynomial compressor maps
+   - CoolProp integration via Rust bindings for high-fidelity fluid properties
+   - WebAssembly compilation target for browser-based interfaces
+
+### Key Differentiators
+
+**🚀 Modelica-Like Interface in Rust**
+The unique combination of declarative component connection syntax with systems language performance. No existing tool offers this balance of expressiveness and speed.
+
+**🔄 Dynamic Multi-Solver Strategy**
+The only open-source tool enabling runtime switching between Sequential Substitution and Newton-Raphson, with automatic fallback handling. Commercial tools typically lock users into one approach.
+
+**🎛️ Native Inverse Control**
+First-class support for control-oriented simulations where outputs drive input calculations—essential for real-world Heat Pump optimization but often bolted-on or missing in other tools.
+
+**⚡ WebAssembly Ready**
+Architecture designed for future Wasm compilation, enabling high-performance simulation in web browsers without Python backend dependencies.
+
+**🔒 Type-State Safety**
+Leverages Rust's type system to enforce valid thermodynamic states at compile time (e.g., preventing negative enthalpies), catching errors before runtime.
+
+---
+
+## Target Users
+
+### Primary Users
+
+#### 1. Optimization Alice — R&D Heat Pump Engineer
+
+**Profile:**
+Alice is a thermal systems engineer at a major Heat Pump manufacturer. Her job is to optimize system performance across varying climate conditions and usage patterns. She lives in the world of SEER/SCOP ratings and regulatory compliance.
+
+**Context & Environment:**
+- Works with HVAC system simulation teams
+- Needs to generate performance maps for product certification
+- Runs parametric studies involving 10,000-50,000+ simulation points
+- Currently uses Python-based tools (tespy, CoolProp) or commercial software (EES)
+- Familiar with scripting and CLI tools, prefers automation
+
+**Pain Points:**
+- **Python interpreter overhead** makes large optimization studies run overnight instead of hours
+- **Solver divergence at critical points** (phase transitions, extreme conditions) stops entire batch runs
+- **No clean inverse control** — cannot easily specify target outputs (superheat) and solve for inputs (valve position)
+- Commercial tools are expensive and lock her into rigid solver strategies
+
+**Technical Interactions with RustThermoCycle:**
+
+*Graph Interaction:*
+- Constructs standard vapor-compression cycles programmatically via API
+- Uses pre-built component library (Compressor, Condenser, Evaporator, Expansion Valve)
+- Connects components through typed Fluid Nodes with working fluid specification
+- Expects graph validation to catch connection errors at compile time (Rust type safety)
+
+*Solver Interaction:*
+- **Primary need:** Batch execution with minimal overhead
+- Uses Sequential Substitution for initial guesses, then Newton-Raphson for convergence
+- Requires solver switching when divergence detected (automatic fallback)
+- Needs convergence diagnostics to identify problematic operating points
+- Expects parallel execution capabilities (multi-threading) for parameter sweeps
+
+*Success Moment:*
+When she runs a 50,000-point SEER map calculation in 20 minutes instead of 8 hours, with automatic handling of edge cases that used to crash her workflow.
+
+---
+
+#### 2. Graph-Builder Bob — Thermodynamics Researcher
+
+**Profile:**
+Bob is a post-doc researcher in thermal systems engineering, exploring novel refrigeration cycle architectures. He works on unconventional configurations like ejector-enhanced cycles, cascade systems with multiple working fluids, and waste heat recovery loops.
+
+**Context & Environment:**
+- Academic research lab with focus on next-generation HVAC technologies
+- Experiments with exotic working fluids and non-standard component arrangements
+- Currently uses Modelica for modeling but frustrated by its steep learning curve and performance limitations
+- Also uses EES but finds pure equation-based approaches hard to maintain
+- Comfortable with code, prefers explicit control over simulation behavior
+
+**Pain Points:**
+- **Black-box solvers crash** on his non-conventional fluid models without explanation
+- **Rigid component libraries** don't support his custom components (ejector, novel heat exchanger geometries)
+- **No visibility into solver internals** — cannot debug why convergence fails
+- **Solver hard-coding** — cannot switch strategies when Newton-Raphson diverges on exotic conditions
+
+**Technical Interactions with RustThermoCycle:**
+
+*Graph Interaction:*
+- Builds custom cycle topologies manually using `connect(A, B)` API
+- Creates custom components implementing the component Trait interface
+- Needs flexible node types (refrigerant, air, brine, multi-fluid connections)
+- Expects graph visualization/debugging capabilities to verify topology
+- Requires support for multi-domain systems (refrigerant side + air side + controls)
+
+*Solver Interaction:*
+- **Primary need:** Solver transparency and control
+- Explicitly switches between Sequential Substitution (robust for initialization) and Newton-Raphson (fast convergence)
+- Inspects residual vectors and Jacobian matrices for debugging
+- Adjusts solver parameters (tolerances, damping factors) based on physics
+- Implements custom convergence criteria for exotic cycles
+
+*Success Moment:*
+When he can define a novel ejector-enhanced cascade cycle, switch to Sequential Substitution when Newton-Raphson fails on a critical point, inspect the residuals to understand the issue, and ultimately get convergence where all other tools failed.
+
+---
+
+### Secondary Users
+
+#### 3. Web-Dev Charlie — Frontend/Full-Stack Developer
+
+**Profile:**
+Charlie builds web-based tools for HVAC companies — internal configurators, customer-facing sizing tools, and educational simulators. He's a React/TypeScript expert who needs to embed thermodynamic calculations in browser applications.
+
+**Context & Environment:**
+- Works at HVAC software consultancies or equipment manufacturers
+- Builds React/Vue applications with complex calculation needs
+- Currently forced to use Python backends (Flask/FastAPI) for thermodynamic calculations
+- Struggles with server costs and latency for real-time web applications
+- Familiar with WebAssembly concepts but hasn't worked extensively with Rust
+
+**Pain Points:**
+- **Python backend dependency** requires expensive servers and creates latency issues
+- **Cannot run heavy calculations client-side** due to Python browser limitations (PyScript too slow)
+- **Type safety gaps** between JavaScript frontend and Python backend cause runtime bugs
+- **Deployment complexity** — needs to maintain Python environments on servers
+
+**Technical Interactions with RustThermoCycle:**
+
+*Graph Interaction:*
+- Uses high-level WASM bindings to construct cycles from JSON/YAML definitions
+- Relies on pre-validated component templates (standard Heat Pump, Refrigeration unit)
+- Expects type-safe API bindings generated for TypeScript
+- Needs serialization/deserialization of cycle graphs for save/load functionality
+
+*Solver Interaction:*
+- **Primary need:** Reliability and browser performance
+- Uses default solver strategy (automatic selection) without manual tuning
+- Expects WASM-compiled library to run at near-native speed in browser
+- Requires error handling that maps Rust errors to JavaScript exceptions cleanly
+- Needs deterministic execution for consistent UI updates
+
+*Success Moment:*
+When he ships a browser-based Heat Pump configurator where customers adjust sliders (evap temp, cond temp, superheat) and see real-time COP calculations instantly—without any backend server calls.
+
+---
+
+### User Journey
+
+#### Optimization Alice — Journey Map
+
+**Discovery:**
+Finds RustThermoCycle through Rust community forums or engineering software benchmarks showing 100x speedup over Python alternatives.
+
+**Onboarding:**
+1. Installs via `cargo add rust-thermo-cycle`
+2. Runs example script simulating standard Heat Pump cycle
+3. Verifies performance with timing benchmarks
+4. Adapts existing Python scripts to Rust API
+
+**Core Usage:**
+- Writes Rust scripts defining parameter sweeps (climate zones, load profiles)
+- Constructs cycles using builder pattern API
+- Executes batch simulations with Rayon parallelization
+- Exports results to CSV/Parquet for analysis in Python/R
+- Uses Inverse Control API to solve for valve positions given target constraints
+
+**Success Moment:**
+Completes full SEER calculation (50,000 points) before lunch instead of waiting overnight. Identifies optimal charge amount and valve settings automatically.
+
+**Long-term:**
+Integrates RustThermoCycle into company's CI/CD pipeline for automated performance regression testing. Becomes internal champion for Rust adoption in simulation team.
+
+---
+
+#### Graph-Builder Bob — Journey Map
+
+**Discovery:**
+Discovers project through academic Twitter or Rust science community, intrigued by "Modelica-like interface in Rust" claim.
+
+**Onboarding:**
+1. Clones repository and builds from source
+2. Reads architecture docs on Trait-based component system
+3. Implements custom Ejector component following Component trait
+4. Constructs first exotic cycle topology using connect() API
+5. Experiments with solver switching on challenging operating points
+
+**Core Usage:**
+- Defines custom components implementing thermodynamic equations
+- Builds unconventional cycle topologies (cascade, ejector-enhanced, multi-stage)
+- Switches between Sequential Substitution and Newton-Raphson based on convergence behavior
+- Inspects residual vectors to debug convergence failures
+- Publishes research with reproducible Rust code in supplementary materials
+
+**Success Moment:**
+Successfully simulates a novel cycle architecture that diverged in all other tools, with full transparency into solver behavior and physics-based debugging.
+
+**Long-term:**
+Contributes custom components back to open-source library. Publishes paper on solver strategy comparison for exotic refrigeration cycles. Uses library for graduate course on thermodynamic system modeling.
+
+---
+
+#### Web-Dev Charlie — Journey Map
+
+**Discovery:**
+Finds project searching for "thermodynamics WebAssembly Rust" while evaluating options for client HVAC configurator project.
+
+**Onboarding:**
+1. Checks npm registry for `rust-thermo-cycle` WASM package
+2. Installs via `npm install rust-thermo-cycle`
+3. Imports TypeScript bindings in React app
+4. Loads pre-built cycle template via JSON configuration
+5. Binds UI sliders (temperatures, superheat) to WASM calculation inputs
+
+**Core Usage:**
+- Embeds WASM module in React/Vue applications
+- Constructs cycles from JSON definitions sent to WASM bindings
+- Calls solver through simplified high-level API
+- Receives results as JavaScript objects for UI rendering
+- Implements real-time updates as users adjust parameters
+- Deploys static site to CDN (no backend servers needed)
+
+**Success Moment:**
+Launches customer-facing Heat Pump selector tool where users adjust operating conditions and see instant COP/efficiency calculations — all running client-side with zero backend costs.
+
+**Long-term:**
+Builds library of reusable React components (CycleDiagram, EfficiencyChart) wrapping RustThermoCycle WASM. Creates white-label configurator product sold to HVAC manufacturers.
+
+---
+
+## Success Metrics
+
+### User Success Metrics
+
+#### Optimization Alice — Performance & Throughput
+
+**Speedup Factor (vs. Python)**
+- **Target:** 50x to 100x faster than equivalent Python (tespy / scipy.optimize)
+- **Measurement:** Average time to solve a simple Rankine cycle (1,000 iterations)
+- **Success Criteria:** Demonstrated through benchmark suite comparing identical thermodynamic problems
+
+**Simulation Throughput**
+- **Target:** > 10,000 operating points per minute on standard CPU (4 cores) using Rust parallelism (Rayon)
+- **Measurement:** Batch execution time for parametric studies across climate/load conditions
+- **Success Criteria:** SEER/SCOP mapping completes in < 20 minutes instead of 8+ hours
+
+**Batch Stability**
+- **Target:** < 0.1% Panics/Crashes over 50,000-point search space
+- **Measurement:** Automated stress testing across extreme operating conditions
+- **Success Criteria:** Software returns clean `Error` types, never crashes the process; graceful handling of divergence
+
+---
+
+#### Graph-Builder Bob — Robustness & Solver Resilience
+
+**Solver Fallback Success Rate**
+- **Target:** > 90% recovery rate when Newton-Raphson diverges
+- **Measurement:** Automatic switching to Sequential Substitution (Picard) when residual > tolerance
+- **Success Criteria:** Convergence achieved after fallback; detailed residual logs available for debugging
+
+**Thermodynamic Accuracy**
+- **Target:** Global energy balance < 1e-6 kW; Mass balance < 1e-9 kg/s
+- **Measurement:** Comparison against AHRI-certified data and validated EES examples
+- **Success Criteria:** Conservation equations satisfied within numerical precision; validation suite passes
+
+---
+
+#### Web-Dev Charlie — Portability & Integration
+
+**WebAssembly Binary Size**
+- **Target:** < 2 MB (gzipped) for complete core including essential fluid tables
+- **Measurement:** Optimized WASM build with dead code elimination
+- **Success Criteria:** Fast browser loading; CDN-friendly distribution
+
+**Time to First Solve**
+- **Target:** < 50ms to instantiate WASM module and solve first simple cycle in React app
+- **Measurement:** End-to-end integration test with React/Vue frontend
+- **Success Criteria:** Instant feedback for user interactions; zero perceived latency
+
+---
+
+### Business Objectives
+
+#### Technical Excellence & Adoption
+
+**Community Growth**
+- **3-Month Target:** 50+ GitHub stars, 5+ active contributors, 3+ research institutions evaluating
+- **12-Month Target:** 500+ GitHub stars, 20+ contributors, 2+ published papers citing the library
+
+**Industry Adoption**
+- **3-Month Target:** 2+ HVAC manufacturers in pilot evaluation
+- **12-Month Target:** 5+ commercial integrations, 1+ white-label product (Web-Dev Charlie scenario)
+
+**Open Source Sustainability**
+- **3-Month Target:** Complete documentation and API stability
+- **12-Month Target:** Stable 1.0 release with semantic versioning, established governance model
+
+---
+
+### Key Performance Indicators
+
+#### Technical KPIs
+
+| KPI | Target | Measurement Method |
+|-----|--------|-------------------|
+| Speedup vs. Python | 50-100x | Benchmark suite (criterion.rs) |
+| Batch Success Rate | 99.9% | Automated stress testing |
+| Solver Fallback Recovery | > 90% | Convergence test suite |
+| Energy Balance Precision | < 1e-6 kW | Validation against reference data |
+| WASM Bundle Size | < 2 MB | wasm-opt + gzip analysis |
+| Test Coverage | > 85% | tarpaulin + codecov |
+| Public API Documentation | 100% | rustdoc + doctest compliance |
+
+#### User Outcome KPIs
+
+| KPI | Target | Measurement Method |
+|-----|--------|-------------------|
+| SEER Map Calculation Time | < 20 min for 50K points | User-reported benchmarks |
+| Exotic Cycle Convergence | Success on 3+ novel architectures | Bob's research cases |
+| Web Integration Time | < 1 day for React app | Developer onboarding test |
+
+---
+
+### Vision of Success
+
+**The Migration Success Story:**
+
+The project will be considered a success when an engineering team can migrate their Python optimization script from an 8-hour overnight batch run to a RustThermoCycle execution completing in under 10 minutes — while maintaining the guarantee that conservation equations are satisfied to within 10^-6 precision.
+
+**Success Indicators:**
+
+✅ **Performance Unlocked:** Multi-variable optimization studies (10,000+ iterations) complete during coffee breaks, not overnight
+
+✅ **Robustness Proven:** Exotic cycle architectures converge where commercial tools fail, with full transparency into solver behavior
+
+✅ **Portability Delivered:** Browser-based configurators run thermodynamic calculations client-side at near-native speed, eliminating backend costs
+
+✅ **Quality Assured:** Every public API is documented, tested, and type-safe; thermodynamic errors caught at compile time
+
+✅ **Community Thriving:** Active open-source community with contributions from both industry (R&D engineers) and academia (researchers)
+
+---
+
+## MVP Scope
+
+### Core Features (IN - Périmètre MVP)
+
+#### 1. Graph-Based Topology System
+**Objective:** Enable Modelica-like component connection for standard vapor-compression cycles.
+
+**Implementation:**
+- Graph structure via `petgraph` or custom implementation
+- **Nodes:** Compressor, Condenser, ExpansionValve, Evaporator (4 core components)
+- **Edges:** FluidState carrying thermodynamic properties (P, h, m_dot)
+- Type-safe connections with compile-time validation
+- Builder pattern API for cycle construction
+
+**Success Criteria:** Users can programmatically construct a standard Heat Pump cycle with clear, intuitive API.
+
+---
+
+#### 2. Sequential Substitution Solver (Picard Iteration)
+**Objective:** Robust solver for steady-state cycle convergence.
+
+**Implementation:**
+- Fixed-point iteration solver with damping
+- Residual calculation based on mass and energy balances
+- Configurable convergence tolerance and max iterations
+- **Architectural Constraint:** Generic `Solver` trait designed to accommodate future Newton-Raphson implementation
+
+**Success Criteria:** Standard cycles converge reliably; solver trait abstraction allows future solver swapping without component code changes.
+
+---
+
+#### 3. Residual-Ready Architecture (Critical Foundation)
+**Objective:** Prepare foundation for Inverse Control without full implementation.
+
+**Implementation:**
+- All components expose `compute_residuals()` method
+- Residuals represent deviation between calculated and target states
+- Unified residual vector for the complete cycle
+- Jacobian structure preparation (sparsity pattern) for future Newton-Raphson
+
+**Why This Matters:** Designing for Forward-only calculation now would require major Trait refactoring for Inverse Control. Residual-ready architecture enables seamless transition to constraint-based solving in v2.
+
+**Success Criteria:** Components can report residuals; architecture supports future residual-based solving without breaking changes.
+
+---
+
+#### 4. Safe CoolProp Integration
+**Objective:** High-fidelity fluid properties with robust error handling.
+
+**Implementation:**
+- Rust bindings to CoolProp C++ library
+- Safe wrappers preventing panics (e.g., P < 0, invalid temperature ranges)
+- Error types for thermodynamic domain violations
+- Support for common refrigerants (R410A, R32, R134a)
+
+**Success Criteria:** Property calculations are safe (no panics); errors are handled gracefully with meaningful messages.
+
+---
+
+#### 5. Performance Benchmark (Proof of Concept)
+**Objective:** Demonstrate speedup vs. Python from day one.
+
+**Implementation:**
+- Benchmark suite using `criterion.rs`
+- Test case: 1,000 iterations of simple Rankine cycle
+- Comparison baseline: Equivalent Python implementation (tespy/CoolProp)
+- Target: Demonstrate measurable speedup (initial goal: 10x+ as stepping stone to 50-100x)
+
+**Success Criteria:** Benchmark proves performance advantage; "Optimization Alice" sees immediate value.
+
+---
+
+### Out of Scope for MVP (OUT - v2+)
+
+#### Deferred to v2.0
+- **Newton-Raphson Solver:** Full Jacobian matrix implementation with nalgebra
+- **Solver Fallback:** Automatic switching between Sequential Substitution and Newton-Raphson
+- **WebAssembly Build:** wasm-bindgen integration and npm package distribution
+- **Inverse Control:** Full constraint-based solving (architecture ready, implementation deferred)
+- **Custom Components:** User-defined component creation beyond core 4
+- **Advanced Components:** Ejectors, multi-stream heat exchangers, internal heat exchangers
+
+#### Deferred to v3.0+
+- **GUI/Web Interface:** Visual cycle builder, React/Vue components
+- **Optimization Framework:** Built-in parameter sweep and optimization tools
+- **Parallel Execution:** Rayon-based multi-threading for batch operations
+- **Additional Working Fluids:** Full refrigerant database integration
+
+---
+
+### MVP Success Criteria
+
+#### Technical Validation
+| Criterion | Target | Measurement |
+|-----------|--------|-------------|
+| Cycle Convergence | 100% success on standard Heat Pump cycles | Automated test suite |
+| Performance Speedup | 10x+ vs. Python (MVP stepping stone to 50-100x) | Criterion benchmarks |
+| API Stability | No breaking changes to core traits | Code review |
+| Test Coverage | > 70% for core modules | Tarpaulin coverage |
+
+#### User Validation
+| Persona | Success Indicator |
+|---------|-----------------|
+| Optimization Alice | Can run 1,000-point parameter study in < 5 minutes (vs. hours in Python) |
+| Graph-Builder Bob | Can construct custom cycle topology via code; components expose residuals for inspection |
+
+#### Community Validation
+- Public GitHub repository with clear README
+- Basic documentation (rustdoc) for all public APIs
+- At least one complete example: "Standard Heat Pump simulation"
+- CI/CD pipeline with automated testing
+
+---
+
+### Future Vision
+
+#### v2.0: Solver Flexibility & Portability
+- **Newton-Raphson Implementation:** Fast quadratic convergence for well-behaved cycles
+- **Dynamic Solver Strategy:** Automatic fallback when Newton diverges; user-controlled solver selection
+- **Inverse Control:** Full constraint-based solving — specify outputs, solve for inputs
+- **WebAssembly Target:** Browser-compatible builds for web applications
+- **TypeScript Bindings:** Type-safe integration for Web-Dev Charlie
+
+#### v3.0: Ecosystem & Advanced Features
+- **Component Library Expansion:** Ejectors, multi-stage compression, complex heat exchangers
+- **Optimization Framework:** Built-in parameter sweep, sensitivity analysis, COP optimization
+- **Parallel Execution:** Multi-threaded batch processing for massive parameter studies
+- **Visualization Tools:** SVG cycle diagrams, performance charts, T-s diagrams
+- **Industry Partnerships:** Validated component models from manufacturers
+
+#### v4.0+: Platform & Enterprise
+- **Cloud Simulation:** Distributed computing for massive design space exploration
+- **Real-time Simulation:** Hardware-in-the-loop testing with actual controllers
+- **Machine Learning Integration:** Surrogate models for ultra-fast approximations
+- **Enterprise Features:** Multi-user collaboration, version control for cycles, audit trails
+
+---
+
+### Architectural Foundation Strategy
+
+**The "Residual-Ready" Decision:**
+
+By exposing residuals at the component level in MVP, we create the mathematical foundation for Inverse Control without implementing the full constraint solver. This architectural choice:
+
+✅ **Prevents Refactoring:** Traits won't need redesign for v2 Inverse Control  
+✅ **Enables Debugging:** Users can inspect residuals during Sequential Substitution  
+✅ **Prepares for Newton:** Residual vector + sparsity pattern = ready for Jacobian assembly  
+✅ **Validates Physics:** Residuals prove conservation equations are satisfied  
+
+**Trade-off Acknowledged:** Slightly more complex component API in MVP, but pays dividends in v2.
+
+**Validation Gate:** If MVP succeeds, v2 development focuses on solver algorithms rather than architecture — dramatically reducing technical risk.