Entropyk/DOCUMENTATION.md

Entropyk — Manuel technique

Entropyk est un cadre de simulation thermodynamique en régime permanent pour systèmes HVAC/R (chillers, pompes à chaleur, cycles frigorifiques). Ce manuel détaille les fondations physiques, les modèles de composants, le solveur, les DoF, et les API multi-plateformes.

Pour un tour d’horizon orienté utilisateur : README.md.
Pour le CLI JSON : crates/cli/README.md.
Pour Fixed/Free Modelica : docs/modelica-boundary-proof.md.

---

Table des matières

1. Fondations physiques
2. Fluides (entropyk-fluids)
3. Composants (entropyk-components)
4. Solveur (entropyk-solver)
5. Degrés de liberté (DoF)
6. Frontières Fixed / Free
7. Fonctionnalités avancées
8. API multi-plateformes
9. Démarrage et références

---

1. Fondations physiques

1.1 Typage dimensionnel

Chaque grandeur est un newtype SI — pas de f64 nu aux frontières publiques.

Grandeur	Unité interne SI	Symbole
Pression	Pascal (Pa)	(P)
Température	Kelvin (K)	(T)
Enthalpie massique	J/kg	(h)
Débit massique	kg/s	(\dot{m})
Densité	kg/m³	(\rho)
Puissance	W	(\dot{Q}), (\dot{W})

Les configs JSON acceptent souvent °C / bar pour l’ergonomie ; la conversion vers SI se fait à la construction des composants.

1.2 Lois de conservation

Sur chaque nœud / branche, le solveur impose localement :

• Masse : (\sum \dot{m}{\mathrm{in}} - \sum \dot{m}{\mathrm{out}} = 0) (souvent trivialisée sur branche série via ṁ partagé)
• Énergie : (\sum (\dot{m},h){\mathrm{in}} - \sum (\dot{m},h){\mathrm{out}} + \dot{Q} - \dot{W} = 0)

1.3 Vecteur d’état

Chaque arête du graphe porte trois inconnues :

[ \mathbf{x}_{\mathrm{edge}} = [\dot{m},; P,; h] ]

(Ancienne doc obsolète : ([P,h]) seul — post-CM1.x le débit est une inconnue d’arête / de branche.)

Sur une chaîne série 1-entrée / 1-sortie, les arêtes partagent souvent le même index ṁ (topologie CM1.4).

---

2. Fluides (entropyk-fluids)

Trait unifié FluidBackend : propriétés ((T,\rho,c_p,s,\ldots)) en fonction de l’état ((P,h)) (ou autres paires selon l’appel).

2.1 Implémentations

Backend	Rôle
CoolProp	Équations d’état Helmholtz — précision recherche / validation
Tabular	Tables + splines bicubiques Hermite — (O(1)), adapté HIL / WASM
Incompressible	Eau, glycols, saumures — (\rho(T)), (h \approx c_p,\Delta T)
Cached / Damped	Wrappers perf / stabilité numérique
TestBackend	Mocks pour tests sans CoolProp

Feature Cargo typique : coolprop via coolprop-sys (bibliothèque précompilée sous vendor/coolprop).

2.2 Phases

1. Sous-refroidi : (h < h_{\mathrm{sat},l}(P))
2. Diphasique : (h_{\mathrm{sat},l}(P) \le h \le h_{\mathrm{sat},v}(P))
3. Surchauffé : (h > h_{\mathrm{sat},v}(P))
4. Supercritique : au-delà du point critique (selon backend)

Titre vapeur en diphasique :

[ x = \frac{h - h_{\mathrm{sat},l}}{h_{\mathrm{sat},v} - h_{\mathrm{sat},l}} ]

---

3. Composants (entropyk-components)

Tous implémentent le trait Component :

• n_equations() — nombre de résidus
• compute_residuals(state, r) — (\mathbf{F}(\mathbf{x}))
• jacobian_entries(state, J) — (\partial\mathbf{F}/\partial\mathbf{x}) (analytique de préférence)
• ports / set_system_context / set_port_context — indices d’arêtes live

3.1 Compresseurs

IsentropicCompressor (cycles émergents courants)

• Loi de débit (si non métré) : (\dot{m} \approx \rho_{\mathrm{suc}},V,N,\eta_{\mathrm{vol}})
• Énergie de refoulement via (\eta_{\mathrm{is}})
• emergent_pressure : ne pince pas les pressions de design
• Mode ṁ externe : quand un EXV orifice Fixed métre le débit (CLI)

Compressor — AHRI 540 (10 coefficients)

[\begin{aligned} X &= C_1 + C_2 T_s + C_3 T_d + C_4 T_s^2 + C_5 T_s T_d + C_6 T_d^2 \ &\quad + C_7 T_s^3 + C_8 T_d T_s^2 + C_9 T_s T_d^2 + C_{10} T_d^3 \end{aligned}]

où (X) est (\dot{m}) ou (\dot{W}) selon le jeu de coeffs. Unités (T_s,T_d) selon la convention du jeu (souvent °F pour AHRI).

Cartes SST/SDT

[\dot{m} = \sum_{i,j} A_{ij},\mathrm{SST}^i,\mathrm{SDT}^j]

Utilisé aussi pour ScrewEconomizerCompressor (vis + port écono, VFD, slide valve).

CentrifugalCompressor

Carte polytropique (facteur de débit, nombre de Mach périphérique).

3.2 Détente

IsenthalpicExpansionValve / EXV

Trois modes :

Mode	Équations	Effet de opening
Isenthalpique seul (emergent_pressure, sans orifice_kv)	(h_{\mathrm{out}}-h_{\mathrm{in}}=0)	Aucun — ṁ = compresseur
Orifice Fixed (orifice_kv + fix_opening: true)	+ (\dot{m}=K_v\cdot o\cdot\sqrt{2\rho\Delta P})	Paramètre physique
Orifice Free (fix_opening: false)	idem, (o) inconnu	Régulation / contrôleur

ExpansionValve, CapillaryTube, ReversingValve, BypassValve

Voir fiches sous docs/components/ et meta UI apps/web/src/lib/componentMeta.ts.

3.3 Conduits (Pipe)

Chute de pression Darcy–Weisbach :

[ \Delta P = f,\frac{L}{D},\frac{\rho v^2}{2},\quad \frac{1}{\sqrt{f}} \approx -1{,}8\log_{10}!\left[\left(\frac{\varepsilon/D}{3{,}7}\right)^{1{,}11}+\frac{6{,}9}{Re}\right] ]

(Haaland). Mode edge-coupled CLI :

• pressure_drop_pa > 0 → ΔP imposé constant
• pressure_drop_pa = 0 → ΔP Darcy depuis géométrie + ṁ live

3.4 Échangeurs

HeatExchanger générique (ε-NTU / LMTD)

[ \dot{Q} = \varepsilon, C_{\min},(T_{h,\mathrm{in}}-T_{c,\mathrm{in}}) ]

• Contre-courant : (\varepsilon = \dfrac{1-e^{-NTU(1-C^)}}{1-C^ e^{-NTU(1-C^*)}})
• Évap / cond (changement de phase, (C^*\to 0)) : (\varepsilon = 1-e^{-NTU})

En mode 4 ports live : + fermetures isobares (P_{\mathrm{out}}-P_{\mathrm{in}}=0) par flux (pattern Modelica Free-P).

Condenser / Evaporator / FloodedEvaporator

• Côté frigorigène : bilans + fermetures SC / SH / vapeur saturée / qualité
• emergent_pressure : P flotte, fermée par l’énergie + closures
• Secondaire 4 ports : énergie + momentum (isobare ou ΔP quadratique de rating)

ΔP secondaire type rating :

[ \Delta P_{\mathrm{sec}} = \Delta P_{\mathrm{rated}}\left(\frac{\dot{m}}{\dot{m}_{\mathrm{rated}}}\right)^2 ]

via secondary_rated_pressure_drop_pa + secondary_rated_m_flow_kg_s.

Autres HX

Bphx*, AirCooledCondenser, FinCoilCondenser, MchxCondenserCoil, Economizer, GasCooler, ShellAndTubeHx, FanCoilUnit, FreeCoolingExchanger — corrélations / géométries dédiées (voir modules heat_exchanger/).

3.5 Frontières

Famille	Rôle
RefrigerantSource / Sink	BC frigorigène (P, qualité / h, ṁ)
BrineSource / Sink	Eau / glycol (P, T, ṁ, concentration)
AirSource / Sink	Air humide (psychrométrie)

3.6 Hydraulique / air / jonctions

Pump, Fan (courbes + affinity laws), FlowSplitter / FlowMerger, Drum (séparateur L/V flooded), ThermalLoad, HeatSource, Anchor, Node.

---

4. Solveur (entropyk-solver)

On résout (\mathbf{F}(\mathbf{x})=\mathbf{0}) sur le vecteur d’état global (arêtes + actionneurs + couplages).

4.1 Newton–Raphson (défaut CLI)

[ \mathbf{J}(\mathbf{x}_k),\Delta\mathbf{x} = -\mathbf{F}(\mathbf{x}k),\quad \mathbf{x}{k+1} = \mathrm{clamp}\bigl(\mathbf{x}_k + \alpha,\Delta\mathbf{x}\bigr) ]

• Jacobien : assemblé depuis les jacobian_entries des composants (analytique)
• Armijo : réduit (\alpha) si le résidu ne diminue pas (activé CLI si contrôles / orifice / Free-P eau)
• Gel de Jacobien : réutilisation de (\mathbf{J}) pendant (N) itérations stables
• Bornes : ex. (P \ge 10,\mathrm{kPa}) (MIN_SOLVER_PRESSURE_PA) sur les slots pression

4.2 Picard (substitution successive)

[ \mathbf{x}_{k+1} = (1-\omega),\mathbf{x}_k + \omega,G(\mathbf{x}_k) ]

avec (\omega \approx 0{,}5). Plus robuste, convergence linéaire. Anderson optionnel.

4.3 Fallback

1. Newton d’abord
2. Si divergence → Picard
3. Si résidu redescend sous un seuil → retour Newton
   Nombre max de bascules limité (anti-oscillation).

4.4 Homotopy

Continuation (\lambda) pour chemins difficiles (API solver avancée).

4.5 Seed

• Frontières : seed_from_boundary_conditions
• Cycles émergents : staging HP/BP distinct (build_staged_emergent_seed)
• Actionneurs libres : valeurs initiales nominales

---

5. Degrés de liberté (DoF)

Un système est carré ssi :

[ n_{\mathrm{équations}} = n_{\mathrm{inconnues}} ]

• Sur-contraint → TopologyError::DofImbalance à finalize() (porte DoF, défaut ON)
• Sous-contraint → refusé en production CLI (validate_system_dof)

Chaque résidu porte un EquationRole (Dirichlet, bilan énergie, fermeture outlet SH/SC, actionneur…).

Règle d’or : ne jamais fixer à la fois (\dot{m}) et (P) sur le même flux sans libérer un autre DoF.

Ledger UI (aide design, non bit-exact) : apps/web/src/lib/dofLedger.ts.

---

6. Frontières Fixed / Free

Alignement Modelica MassFlowSource_T / Boundary_pT — détails et sources : docs/modelica-boundary-proof.md.

Pattern	Source	Sink	Remarque
MassFlowSource_T (défaut si ṁ imposé)	Fixed T, Fixed ṁ, Free P	Fixed P, Free T_out	HX propage P (isobare / ΔP)
Boundary_pT + friction	Fixed P, Fixed T, Free ṁ	Fixed P	Pipe / ΔP HX obligatoire
Rating T_out	Free ṁ	Fixed P + Fixed T_out	ṁ devient inconnu

Flags JSON : fix_pressure, fix_temperature, fix_mass_flow.

Double Fixed-P aux deux extrémités uniquement s’il existe une résistance hydraulique entre elles.

---

7. Fonctionnalités avancées

7.1 Contrôle inverse / calibration

• Contraintes : imposer une sortie (SH = 5 K, capacité = …)
• Variables bornées : actionneurs (opening, z_ua, f_m…) avec min/max
• CLI : bloc controls (SaturatedController, etc.)

7.2 Multi-circuits et couplages thermiques

Plusieurs circuits dans circuits[] ; thermal_couplings pour un pont thermique (UA, efficacité) entre circuits. Jacobien unifié.

7.3 Ratings saisonniers / part-load

Métrique	CLI	Norme
IPLV / NPLV / ESEER	rate	AHRI 550/590, Eurovent
SCOP	scop	EN 14825
SEER	seer	EN 14825

Chaque point de charge est une vraie re-simulation du cycle, pas une interpolation de points imposés.
Référence : docs/rating-and-seasonal-metrics.md.

7.4 Qualification HX

Sous-commande qualify : régime frigorigène fixé, balayage des conditions secondaires.

---

8. API multi-plateformes

Capacité	Rust	Python	C / FFI	WASM
Création composants	IsentropicCompressor::new()…	wrappers PyO3	ek_*_create	wasm_bindgen
Finalisation	system.finalize()	idem	ek_system_finalize	idem
Solve	NewtonConfig::solve	idem	ek_solve	async JS
Mémoire	RAII	PyO3 refcount	*_free manuel	GC JS

Chemins réels des bindings : bindings/python, bindings/c, bindings/wasm (pas sous crates/).

Audit 2026-07 : certaines classes Python/C historiques restent des stubs — vérifier les warnings ; préférer CLI / Rust pour la physique complète.

---

9. Démarrage et références

# Build & test
cargo build
cargo test

# CLI
cargo run -p entropyk-cli -- run -c crates/cli/examples/chiller_aircooled_r134a.json

# UI API
cargo run -q -p entropyk-demo --bin ui-server   # :3030

Document	Contenu
README.md	Vue d’ensemble FR, catalogue composants, CLI, UI
crates/cli/README.md	Référence CLI JSON
EXAMPLES_FULL.md	Scénarios avancés
docs/CLI_TUTORIAL.md	Tutoriel pas à pas
docs/components/	Fiches composants
AGENTS.md	Conventions agents / structure dépôt

Politique d’implémentation

• Zero-panic en production (Result partout)
• Jacobiens exacts (FD seulement si chemin documenté / temporaire)
• Nouveau composant : Rust + CLI + (Python/WASM) + meta UI — voir checklist dans le README racine