# Entropyk

Entropyk est un moteur de simulation thermodynamique pour cycles frigorifiques, pompes à chaleur et groupes d'eau glacée (chillers). Écrit en Rust, il assemble une machine sous forme de graphe de composants, résout le système d'équations non linéaires en régime permanent, et expose le même modèle via une **ligne de commande JSON**, une **API Rust**, des **bindings Python / C / WebAssembly** et une **interface web**.

> Documentation détaillée : [`DOCUMENTATION.md`](./DOCUMENTATION.md) · Tutoriel CLI : [`docs/CLI_TUTORIAL.md`](./docs/CLI_TUTORIAL.md) · Frontières Fixed/Free : [`docs/modelica-boundary-proof.md`](./docs/modelica-boundary-proof.md)

---

## Sommaire

1. [Ce qu'est Entropyk](#1-ce-quest-entropyk)
2. [Installation](#2-installation)
3. [Premier lancement](#3-premier-lancement)
4. [Architecture du dépôt](#4-architecture-du-dépôt)
5. [Le modèle : composants et câblage](#5-le-modèle--composants-et-câblage)
6. [Degrés de liberté (DoF)](#6-degrés-de-liberté-dof)
7. [Le solveur](#7-le-solveur)
8. [Catalogue des composants](#8-catalogue-des-composants)
9. [Frontières Fixed / Free (style Modelica)](#9-frontières-fixed--free-style-modelica)
10. [Le détendeur EXV et ses trois modes](#10-le-détendeur-exv-et-ses-trois-modes)
11. [Fluides et backends](#11-fluides-et-backends)
12. [La ligne de commande](#12-la-ligne-de-commande)
13. [Interface web](#13-interface-web)
14. [Bindings Python, C, WebAssembly](#14-bindings-python-c-webassembly)
15. [Exemples fournis](#15-exemples-fournis)
16. [Conventions de développement](#16-conventions-de-développement)

---

## 1. Ce qu'est Entropyk

Entropyk simule un **cycle frigorifique, une pompe à chaleur ou un chiller** en régime permanent :

1. Vous déclarez des **composants** : un compresseur, un condenseur, un détendeur, un évaporateur, et les sources d'air ou d'eau qui les alimentent.
2. Vous les **câblez** entre eux par des liaisons, par exemple la sortie du compresseur vers l'entrée du condenseur.
3. Le moteur assemble automatiquement le système d'équations, calcule ses dérivées (la matrice jacobienne), et le résout par la méthode de Newton — avec repli vers des méthodes plus robustes si besoin.
4. Vous récupérez les **pressions, enthalpies, débits, puissances et COP**, ainsi qu'un diagnostic indiquant si le système est bien équilibré (autant d'équations que d'inconnues).

Le COP (coefficient de performance) est le rapport entre la puissance utile (froid ou chaud) et la puissance électrique consommée par le compresseur.

Cas d'usage typiques :

- **Dimensionner un chiller à un point de fonctionnement** : écrire un fichier JSON décrivant la machine, puis lancer `entropyk-cli run`.
- **Laisser les pressions d'aspiration et de refoulement flotter** au lieu de les imposer : activer `emergent_pressure` sur les échangeurs et le détendeur ; les pressions résultent alors des bilans thermiques.
- **Calibrer la machine sur une cible** (surchauffe, capacité, température de sortie) : ajouter une boucle de régulation qui ajuste un actionneur (ouverture du détendeur, coefficient d'échange) pour atteindre la cible.
- **Évaluer l'efficacité saisonnière** selon les normes en vigueur (IPLV, SCOP, SEER) : les sous-commandes `rate`, `scop`, `seer` rejouent le cycle à plusieurs points de charge.
- **Qualifier un échangeur isolé** : la sous-commande `qualify` balaye la température et le débit du fluide secondaire pour produire une fiche de performance.
- **Construire un schéma à la souris** : l'interface web (`apps/web`) permet de dessiner le circuit et de lancer la simulation via le serveur `ui-server`.

---

## 2. Installation

### Prérequis

- **Rust** (toolchain stable, édition 2021).
- **CoolProp**, la bibliothèque de propriétés thermodynamiques, livrée précompilée sous `vendor/coolprop` et liée via `coolprop-sys`.
- Pour l'interface web : **Node.js** et **npm**.
- Pour les bindings Python : **[uv](https://github.com/astral-sh/uv)** (gestionnaire de paquets Python obligatoire, pas de `pip` direct).

### Build

```bash
cargo build --release
```

Le binaire CLI est `entropyk-cli` (package `entropyk-cli`).

---

## 3. Premier lancement

```bash
cargo run -p entropyk-cli -- run \
  --config crates/cli/examples/chiller_aircooled_r134a.json \
  --output result.json
```

Sortie console : statut (converged / non-converged / timeout), résidu final, nombre d'itérations, temps de calcul, équilibre DoF, états des tronçons (pression en bar, enthalpie en kJ/kg) et performances (puissance frigorifique, puissance absorbée, COP).

---

## 4. Architecture du dépôt

```
Entropyk/
├── crates/
│   ├── core/          # Types physiques de base : Pression, Température, Enthalpie, Débit…
│   ├── fluids/        # Backends de propriétés : CoolProp, tabulaire, incompressible
│   ├── components/   # Tous les composants (trait Component)
│   ├── solver/        # Graphe, DoF, Newton, Picard, fallback
│   ├── entropyk/      # Façade : SystemBuilder, SimulationResult
│   ├── cli/           # Binaire entropyk-cli + exemples JSON
│   └── vendors/       # Parsers de données constructeurs (Copeland, Danfoss, SWEP, Bitzer)
├── bindings/
│   ├── python/        # PyO3
│   ├── c/            # FFI C (cbindgen)
│   └── wasm/         # WebAssembly
├── apps/web/          # Workbench diagramme (Next.js)
├── demo/             # ui-server Axum (port 3030)
├── docs/             # Manuels, Modelica, fiches composants
└── tests/fluids/     # Tests d'intégration cross-backend
```

Flux de données :

```text
Config JSON / SystemBuilder / UI web
        |
        v
  create_component  ->  System (graphe)
        |
        v
   finalize() + porte DoF  ->  vecteur d'état [débit, pression, enthalpie] par tronçon
        |
        v
   Newton / Picard / fallback
        |
        v
   SimulationResult (états, énergies, COP, diagnostics)
```

---

## 5. Le modèle : composants et câblage

### Ce que le solveur cherche

Pour chaque tuyau reliant deux composants, le solveur doit trouver trois valeurs :

| Grandeur | Unité SI | Sens |
|----------|----------|------|
| débit massique ṁ | kg/s | combien de frigorigène circule |
| pression P | Pa | pression régnant dans ce tronçon |
| enthalpie massique h | J/kg | énergie portée par le fluide |

Ces trois valeurs sont les **inconnues** du système. Le moteur en assemble une liste (le « vecteur d'état ») et cherche les valeurs qui annulent toutes les équations en même temps.

### Une seule variable de débit pour toute la boucle

Dans un cycle simple, les composants sont branchés en boucle les uns derrière les autres, sans bifurcation : le frigorigène qui sort du compresseur entre intégralement dans le condenseur, puis dans le détendeur, puis dans l'évaporateur, puis revient au compresseur. Le débit est donc **le même partout dans la boucle**.

Plutôt que d'avoir une variable de débit par tuyau, le solveur en utilise **une seule pour toute la boucle**. Cela réduit le nombre d'inconnues et accélère la résolution. (S'il y a un branchement — débit qui se partage entre deux circuits — alors chaque branche reçoit sa propre variable de débit.)

### Câblage

Les liaisons s'écrivent `nom:port`. Par exemple :

```json
{ "from": "comp:outlet", "to": "cond:inlet" }
```

Le moteur construit le graphe à partir de ces liaisons, puis assemble les équations de chaque composant et leurs dérivées.


---

## 6. Degrés de liberté (DoF)

Le DoF (degrees of freedom, degrés de liberté) est le cœur du diagnostic. Un système est **carré** quand :

```text
nombre d'équations  =  nombre d'inconnues
```

- Trop d'équations : système **sur-contraint** (contradictoire).
- Pas assez : système **sous-contraint** (indéterminé).

Dans les deux cas, `finalize()` refuse de lancer la résolution et renvoie un diagnostic détaillé (par composant : équations déclarées, inconnues consommées, rôle de chaque équation). Chaque composant déclare son nombre d'équations et le **rôle** de chacune : bilan d'énergie, chute de pression, condition de frontière, fermeture de sortie (surchauffe, sous-refroidissement, titre), actionneur…

**Règle d'or** : aucun composant ne doit fixer à la fois le débit **et** la pression sur le même flux. C'est l'équivalent de la règle Modelica qui interdit de fermer deux fois le même degré de liberté.

---

## 7. Le solveur

Implémentation : `crates/solver`.

### Stratégies

| Stratégie JSON  | Comportement |
|-----------------|--------------|
| `"newton"` (défaut) | Newton–Raphson : `x ← x − α·J⁻¹·r`. Jacobien analytique fourni par les composants. Recherche linéaire de type Armijo activée automatiquement quand le système est sensible (contrôles, orifice, pression libre côté eau). |
| `"picard"`     | Substitution successive amortie : `x ← (1−ω)·x + ω·G(x)`, avec ω ≈ 0,5. Plus robuste, convergence plus lente. |
| `"fallback"`   | Newton d'abord ; bascule vers Picard en cas de divergence, puis retour à Newton quand le résidu redescend. |

Tolérance typique : `1e-6`. Itérations : `300` par défaut ; à augmenter pour les échangeurs dont le jacobien est partiellement numérique.

### Boucle de résolution

Un **résidu** est l'écart entre le membre gauche et le membre droit d'une équation : il vaut zéro quand l'équation est satisfaite. Le but du solveur est de rendre tous les résidus nuls en même temps. La **matrice jacobienne** est l'ensemble des dérivées des résidus par rapport aux inconnues ; elle indique dans quelle direction corriger les inconnues.

```text
1. Estimation initiale (frontières + pressions haute/basse initialisées par étages si emergent_pressure)
2. Calcul des résidus r(x) de tous les composants
3. Assemblage de la matrice jacobienne J(x) = ∂r/∂x
4. Résolution du système linéaire J·Δx = −r
5. Mise à jour x ← clamp(x + α·Δx)  (pression bornée à un minimum, actionneurs bornés)
6. Répétition jusqu'à ce que ‖r‖ passe sous la tolérance
```

### Limites assumées

- Régime **permanent** uniquement (pas de dynamique temporelle).
- Pas de CFD : les échangeurs sont des modèles 0D/1D (LMTD, ε-NTU, corrélations d'échange).
- Les propriétés fluides viennent toujours du **backend** (CoolProp…), jamais de valeurs codées en dur.

---

## 8. Catalogue des composants

Tous les composants implémentent le trait `Component` : `n_equations`, `compute_residuals`, `jacobian_entries`, ports. La chaîne `"type"` du JSON correspond exactement aux bras de `create_component` dans `crates/cli/src/run.rs`.

### 8.1 Compresseurs

| Type JSON | Rôle | Paramètres clés |
|-----------|------|-----------------|
| `IsentropicCompressor` | Compresseur à rendement isentropique + déplacement volumétrique ; mode émergent courant | `displacement_m3`, `speed_hz`, `volumetric_efficiency`, `isentropic_efficiency`, `emergent_pressure` |
| `Compressor` | Cartographie constructeur AHRI 540 (débit et puissance selon températures d'aspiration/ refoulement) | coefficients `m1`…`m10` ou carte polynomiale |
| `ScrewEconomizerCompressor` / `ScrewCompressor` | Compresseur à vis avec port économiseur, variation de fréquence, slide valve optionnel | courbes selon températures de saturation, `speed_hz` |
| `CentrifugalCompressor` | Carte polytropique (facteur de débit, nombre de Mach) | `diameter_m`, `speed_rpm`, γ, R |

En mode **émergent**, le compresseur impose la **loi de débit** (déplacement × masse volumique × rendement volumétrique) et l'énergie de refoulement ; les pressions haute/basse résultent des échangeurs. Si un détendeur à orifice fixe métre le débit, le CLI bascule le compresseur en mode « débit externe » (énergie seule) pour garder le système carré.

### 8.2 Détente et vannes

| Type JSON | Rôle | Notes |
|-----------|------|-------|
| `IsenthalpicExpansionValve` / `EXV` | Détendeur isenthalpique (`h_out = h_in`) | Sans `orifice_kv`, l'`opening` n'a **aucun effet** — voir [§10](#10-le-détendeur-exv-et-ses-trois-modes) |
| `ExpansionValve` | Détendeur à orifice, modèle Cd·A ou TXV Eames | `flow_model`, `opening`, `beta_m2`… |
| `CapillaryTube` | Capillaire adiabatique segmenté | `diameter_m`, `length_m`, `n_segments` |
| `ReversingValve` / `FourWayValve` | Vanne 4 voies pour pompe à chaleur (inversion froid/chaud) | `mode`, `pressure_drop_pa` |
| `BypassValve` | Bypass hydronique proportionnel | `opening`, `cv` |

### 8.3 Échangeurs frigorifiques

| Type JSON | Rôle | Notes |
|-----------|------|-------|
| `Condenser` / `CondenserCoil` | Condenseur + côté secondaire (eau ou air) | `ua`, `emergent_pressure`, `subcooling_k`, `secondary_fluid`, chute de pression secondaire optionnelle |
| `Evaporator` / `EvaporatorCoil` | Évaporateur à détente directe + côté secondaire | `ua`, `superheat_k` ou emergent, `secondary_fluid` |
| `FloodedEvaporator` | Évaporateur noyé / à recirculation | fermeture vapeur saturée ou `quality_control` |
| `HeatExchanger` | Échangeur générique 4 ports (LMTD / ε-NTU) | `hot_fluid_id`, `cold_fluid_id`, `ua` |
| `BphxEvaporator` / `BphxCondenser` | Échangeur à plaques brasées + corrélations d'échange | géométrie des plaques, corrélations Longo/Shah |
| `AirCooledCondenser` | Condenseur refroidi par air (T_cond ≈ air + approach) | `oat_k`, `approach_k` |
| `FinCoilCondenser` | Batterie ailettée air | géométrie tubes/ailettes |
| `MchxCondenserCoil` / `MchxCoil` | Batterie à microcanaux | géométrie des microcanaux |
| `FreeCoolingExchanger` / `FreeCooling` | Free-cooling côté eau | — |

**Pressions émergentes** (`emergent_pressure: true`) : l'échangeur ne pince plus la pression de saturation sur une température de design ; la pression flotte et est fermée par le sous-refroidissement, la surchauffe, le titre ou les bilans d'énergie.

**Côté secondaire 4 ports** : brancher `BrineSource`/`AirSource` → port `secondary_inlet` → `secondary_outlet` → `BrineSink`/`AirSink`. L'échangeur propage la pression (fermeture isobare ou chute de pression quadratique issue du rating).

### 8.4 Tuyauterie, pompes, air

| Type JSON | Rôle | Notes |
|-----------|------|-------|
| `Pipe` / `RefrigerantPipe` / `WaterPipe` / `AirDuct` / `PipeWater` / `PipeAir` | Conduits (Darcy–Weisbach) | `length_m`, `diameter_m` ; `pressure_drop_pa = 0` → chute de pression calculée par Darcy depuis la géométrie et le débit ; `> 0` → chute de pression imposée |
| `Pump` | Courbes hauteur-débit + rendement, lois de similitude | — |
| `Fan` | Courbes pression-débit + rendement, lois de similitude | souvent sur boucle air |
| `FlowSplitter` / `FlowMerger` | Jonctions de débit | — |
| `Drum` | Séparateur liquide/vapeur (flooded) | — |

### 8.5 Frontières (sources et sinks)

| Type JSON | Fluide | Impose typiquement |
|-----------|--------|--------------------|
| `RefrigerantSource` / `RefrigerantSink` | Frigorigène | pression (+ titre ou enthalpie), débit optionnel |
| `BrineSource` / `BrineSink` | Eau / glycol | température, débit, pression (Fixed/Free) |
| `AirSource` / `AirSink` | Air humide | température sèche, humidité relative, débit, pression |

Voir [§9](#9-frontières-fixed--free-style-modelica).

### 8.6 Divers

| Type JSON | Rôle |
|-----------|------|
| `ThermalLoad` | Charge thermique Q couplée |
| `HeatSource` | Injection de chaleur en ligne |
| `Anchor` / `RefrigerantNode` | Nœud / ancre de surchauffe optionnelle |
| `Placeholder` | Composant stub (tests, topologie) |

### 8.7 Intégration d'un nouveau composant

Tout nouveau composant doit être câblé **partout** :

1. Struct + trait `Component` + jacobien exact dans `crates/components`.
2. Tests unitaires (résidus, vérification du jacobien par différences finies).
3. Export dans `crates/components/src/lib.rs` et ré-export dans `crates/entropyk/src/lib.rs`.
4. Bras dans `create_component` (`crates/cli/src/run.rs`).
5. Wrapper Python (PyO3) et WASM si exposé.
6. Métadonnées UI (`apps/web/src/lib/componentMeta.ts`) si visible dans le workbench.

---

## 9. Frontières Fixed / Free (style Modelica)

Entropyk reprend la sémantique des conditions aux limites Modelica. Les sources et sinks exposent trois booléens : `fix_pressure`, `fix_temperature`, `fix_mass_flow`.

| Pattern Modelica | Source | Sink | Conséquence |
|------------------|--------|------|-------------|
| **MassFlowSource_T** (défaut Entropyk quand ṁ est imposé) | T fixée, ṁ fixé, **P libre** | P fixée, T_out libre | La chute de pression de l'échangeur ferme le degré de liberté de pression |
| **Boundary_pT** | P fixée, T fixée, ṁ libre | P fixée | Il faut une résistance hydraulique (conduit ou chute de pression d'échangeur) entre les deux pressions fixées |
| Rating T_out | ṁ libre | P fixée + T_out fixée | Le débit devient inconnu (calibration) |

**Interdit** : fixer à la fois le débit **et** la pression sur la même source sans degré de liberté ailleurs.

Chute de pression secondaire de rating (eau ou air) :

```json
"secondary_rated_pressure_drop_pa": 40000,
"secondary_rated_m_flow_kg_s": 0.5
```

---

## 10. Le détendeur EXV et ses trois modes

Le composant `IsenthalpicExpansionValve` (alias `EXV`) a trois modes selon qu'on lui donne un orifice (`orifice_kv`) ou non.

### Mode A — Isenthalpique seul (chillers classiques)

```json
{ "type": "IsenthalpicExpansionValve", "name": "exv", "emergent_pressure": true }
```

- Équation : `h_out − h_in = 0` (détente adiabatique sans travail).
- Le débit est **imposé par le compresseur** (loi de déplacement).
- L'`opening` est **ignoré**, même si l'UI affiche une valeur par défaut.

### Mode B — Orifice fixe (ouverture = paramètre)

```json
{
  "type": "IsenthalpicExpansionValve",
  "name": "exv",
  "emergent_pressure": true,
  "orifice_kv": 2.0e-6,
  "opening": 0.6,
  "fix_opening": true
}
```

Loi de débit :

```text
ṁ = Kv · opening · √(2 · ρ_in · max(ΔP, 0))
```

Le CLI met alors le compresseur en mode « débit métré » (il abandonne sa loi de déplacement) pour garder le système carré.

### Mode C — Orifice libre (ouverture = inconnue)

```json
"orifice_kv": 2.0e-6,
"fix_opening": false
```

L'`opening` devient une inconnue ; il faut une boucle de régulation (par exemple surchauffe → contrôleur saturé) pour la fermer.

> **Piège UI** : le catalogue affiche « Opening » même sans `orifice_kv`. Sans orifice explicite, changer l'ouverture ne change **rien**. Exemple dédié : `crates/cli/examples/chiller_r134a_exv_orifice.json`.

---

## 11. Fluides et backends

| Backend | Usage |
|---------|-------|
| **CoolProp** (`fluid_backend: "CoolProp"`) | Frigorigènes (R134a, R410A…), eau — défaut pour la physique sérieuse |
| **Tabular** | Tables interpolées (WASM, environnements sans CoolProp) |
| **Incompressible** | Glycols et liquides (masse volumique, viscosité de design) |
| **Cached / Damped** | Wrappers de performance et de stabilité |

Les types physiques de `entropyk-core` sont toujours en unités SI (Pa, K, J/kg, kg/s). Les JSON d'entrée acceptent souvent les °C et bar pour l'ergonomie ; la conversion est faite à la construction.

---

## 12. La ligne de commande

Binaire : `entropyk-cli` (package `entropyk-cli`).

### Sous-commandes

| Commande | Rôle |
|----------|------|
| `run` | Une simulation depuis un fichier JSON |
| `batch` | Dossier de configs, exécution parallèle |
| `validate` | Vérifie le JSON et l'équilibre DoF (build + solve de contrôle) |
| `qualify` | Qualification d'un échangeur (régime frigorigène fixe, balayage secondaire) |
| `rate` | Rating saisonnier : IPLV (AHRI 550/590) ou ESEER |
| `scop` | SCOP chauffage par bins EN 14825 |
| `seer` | SEER froid par bins EN 14825 |
| `schema` | Émet le JSON Schema du modèle (source unique pour CLI, UI, outils externes) |

Flags globaux : `-v` / `--verbose`, `-q` / `--quiet`.

### Exemples

```bash
# Build
cargo build --release -p entropyk-cli

# Simulation unique
cargo run -p entropyk-cli -- run \
  --config crates/cli/examples/chiller_aircooled_r134a.json \
  --output result.json

# Validation
cargo run -p entropyk-cli -- validate --config mon_cycle.json

# Batch
cargo run -p entropyk-cli -- batch -d ./scenarios/ -p 4 -O results.json

# Rating IPLV
cargo run -p entropyk-cli -- rate -c crates/cli/examples/rate_chiller_iplv_ahri.json

# Schéma JSON
cargo run -p entropyk-cli -- schema -o model-ir.schema.json
```

### Schéma JSON minimal

```json
{
  "name": "Mon chiller",
  "fluid": "R134a",
  "fluid_backend": "CoolProp",
  "circuits": [
    {
      "id": 0,
      "name": "Circuit principal",
      "components": [
        { "type": "IsentropicCompressor", "name": "comp" },
        { "type": "Condenser", "name": "cond" },
        { "type": "IsenthalpicExpansionValve", "name": "exv" },
        { "type": "Evaporator", "name": "evap" }
      ],
      "edges": [
        { "from": "comp:outlet", "to": "cond:inlet" },
        { "from": "cond:outlet", "to": "exv:inlet" },
        { "from": "exv:outlet", "to": "evap:inlet" },
        { "from": "evap:outlet", "to": "comp:inlet" }
      ]
    }
  ],
  "controls": [],
  "solver": {
    "strategy": "newton",
    "max_iterations": 300,
    "tolerance": 1e-6
  }
}
```

### Pipeline interne de `run`

1. Lecture de `ScenarioConfig`.
2. Pour chaque composant : `create_component(...)` (CoolProp, params, modes orifice / emergent).
3. Ajout des liaisons nommées `nom:port`.
4. `finalize()` + contrôle DoF (système carré obligatoire).
5. Estimation initiale (frontières + pressions par étages).
6. Résolution selon `solver.strategy`.
7. Sérialisation JSON : états des tronçons, performances, `dof`, `failure_diagnostics` en cas d'échec.

### Contrôles (régulation / calibration)

Bloc optionnel `controls` : boucles qui lient une **mesure** (capacité, surchauffe…) à un **actionneur** (`opening`, `z_ua`, `f_m`…). Le solveur ajoute alors les inconnues d'actionneur et les résidus de suivi au système.

---

## 13. Interface web

| Élément | Chemin |
|---------|--------|
| Front Next.js | `apps/web` |
| API Axum | `cargo run -p entropyk-demo --bin ui-server` → `http://localhost:3030` |

Fonctionnalités :

- Palette de composants avec glyphes ISO, câblage React Flow.
- Ledger DoF en temps réel (`dofLedger.ts`).
- Coach Fixed/Free Modelica (`boundaryFix.ts`, `dofCoach.ts`).
- Simulation via `POST /api/simulate`.

```bash
# Terminal 1
cargo run -q -p entropyk-demo --bin ui-server

# Terminal 2
cd apps/web && npm run dev
```

---

## 14. Bindings Python, C, WebAssembly

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

### Python (uv obligatoire)

```bash
uv pip install -e ./bindings/python
uv pip install maturin
cd bindings/python && uv run maturin develop --release
uv run pytest tests/
```

### C

```bash
cargo build --release -p entropyk-c
# header généré sous target/ (voir bindings/c/README.md)
```

### WebAssembly

Voir `bindings/wasm/README.md` — adapté aux backends tabulaires côté client.

> Certaines classes Python historiques sont encore des stubs (audit 2026-07) : vérifier les warnings à la construction et préférer le chemin CLI / Rust pour la physique complète.

---

## 15. Exemples fournis

Répertoire : `crates/cli/examples/`.

| Fichier | Intérêt |
|---------|---------|
| `chiller_aircooled_r134a.json` | Chiller air 4 ports, emergent, air + eau glacée |
| `chiller_watercooled_r410a.json` | Chiller eau R410A |
| `chiller_flooded_4port_watercooled.json` | FloodedEvaporator, DoF carré |
| `chiller_flooded_delta_t_rating.json` | Rating par ΔT |
| `chiller_r134a_emergent_pressure.json` | Pressions émergentes |
| `chiller_r134a_exv_orifice.json` | EXV avec orifice (ouverture physique) |
| `chiller_r134a_superheat_control.json` | Boucle de surchauffe |
| `chiller_r134a_slide_valve.json` | Slide valve compresseur à vis |
| `chiller_r134a_dual_circuit_staging.json` | Double circuit en cascade |
| `chiller_r134a_liquid_injection.json` | Injection liquide |
| `chiller_r134a_flooded_headpressure.json` | Flooded à pression de tête |
| `chiller_r410a_bolt_nodes.json` | Nœuds boulonnés |
| `chiller_r410a_coupled_water_loop.json` | Boucle d'eau couplée |
| `heatpump_airsource_r410a.json` | Pompe à chaleur air |
| `heatpump_r410a_reversing_valve.json` | Vanne 4 voies |
| `heatpump_r134a_fan_headpressure.json` | Pression de tête pilotée par ventilateur |
| `hx_air_water_4port.json` | Échangeur isolé air–eau |
| `bphx_evaporator_condenser.json` | Plaques brasées |
| `capillary_tube_r134a.json` | Capillaire |
| `rate_chiller_iplv_ahri.json` | Rating IPLV |
| `scop_heatpump_r134a.json` | SCOP |

---

## 16. Conventions de développement

- **Langage** : Rust, `Result<T, E>` partout — pas de `panic!` en production.
- **Jacobiens** : analytiques et exacts ; pas de différences finies sauf chemin explicitement documenté ou temporaire.
- **Types** : newtypes SI (`Pressure`, `Enthalpy`…) — pas de `f64` nus aux frontières publiques.
- **Documentation technique / commits** : anglais ; communication projet en français.
- **Git** : branche `main`, messages à l'impératif en anglais.
- **BMAD** : workflows sous `_bmad/` — suivre les fichiers YAML/XML à la lettre si activés.

### Ajouter un composant (checklist)

1. Struct + trait `Component` dans `crates/components`.
2. Tests unitaires (résidus, jacobien vérifié par différences finies).
3. Export `lib.rs` + façade `entropyk`.
4. Bras CLI `create_component`.
5. Exemple JSON sous `crates/cli/examples/`.
6. Métadonnées UI + bindings si besoin.

---

## Liens utiles

| Document | Contenu |
|----------|---------|
| [`DOCUMENTATION.md`](./DOCUMENTATION.md) | Modèles physiques, solveur, API |
| [`EXAMPLES_FULL.md`](./EXAMPLES_FULL.md) | Scénarios avancés |
| [`docs/CLI_TUTORIAL.md`](./docs/CLI_TUTORIAL.md) | Tutoriel CLI |
| [`docs/modelica-boundary-proof.md`](./docs/modelica-boundary-proof.md) | Preuve Fixed/Free |
| [`docs/components/`](./docs/components/) | Fiches composants |
| [`AGENTS.md`](./AGENTS.md) | Instructions agents / structure |
| [`crates/cli/README.md`](./crates/cli/README.md) | Détails CLI |
| [`apps/web/README.md`](./apps/web/README.md) | Interface web |

---

**Projet** : Entropyk · **Langage** : Rust · **Licence / version** : voir `Cargo.toml` (v0.1.x)




