sepehr/Entropyk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Entropyk/_bmad-output/planning-artifacts/prd.md

30 KiB
Raw Permalink Blame History

stepsCompleted inputDocuments documentCounts classification workflowType
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
/Users/sepehr/dev/Entropyk/_bmad-output/planning-artifacts/product-brief-Entropyk-2026-02-12.md
briefCount researchCount brainstormingCount projectDocsCount
1 0 0 0
projectType domain complexity projectContext
developer_tool scientific high greenfield
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-02-22
Status : ✅ Complete & Ready for Implementation

Changelog :

  • 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).

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.