# Circuit Builder UI — Référence (basée sur le code, sans supposition)

Ce document décrit **ce qui existe réellement** dans le CLI, la lib et l’UI. Aucune supposition : uniquement ce qui est implémenté et utilisé.

---

## 1. Types de composants que le CLI crée (`run.rs` → `create_component`)

Le CLI instancie **uniquement** les types suivants. Tout autre type dans le JSON provoque une erreur « Unknown component type ».

| Type dans le JSON | Création réelle |
|-------------------|------------------|
| `ScrewEconomizerCompressor`, `ScrewCompressor` | Compresseur vis avec courbes, économiseur |
| `MchxCondenserCoil`, `MchxCoil` | Condenseur à air (UA, T_air, fan_speed, n_air) |
| `FloodedEvaporator` | Évaporateur noyé (UA, target_quality, refrigerant, secondary_fluid) |
| `Condenser`, `CondenserCoil` | Condenseur simple (UA, optionnel t_sat_k) |
| `Evaporator`, `EvaporatorCoil` | Évaporateur simple (UA, optionnel t_sat_k, superheat_k) |
| `HeatExchanger` | Échangeur LMTD avec conditions hot/cold (hot_fluid, hot_t_inlet_c, hot_pressure_bar, hot_mass_flow_kg_s, cold_*) |
| `Compressor` | Compresseur AHRI 540 (speed_rpm, displacement_m3, efficiency, fluid, m1–m10) |
| `ExpansionValve` | Détendeur (fluid, opening) |
| `Pump` | Pompe (name) — équations 0, composant pass-through |
| `Placeholder` | Composant générique (n_equations) pour compléter la topologie |

**Ce que le CLI ne crée pas** (même si la lib les a) :  
`AirSource`, `AirSink`, `BrineSource`, `BrineSink`, `WaterSource`, `WaterSink`, `Fan`.  
Ils n’apparaissent nulle part dans le `match component_type` de `run.rs`.

---

## 2. Modèle de configuration (JSON)

- **Un scénario** : `name`, `fluid`, `circuits[]`, optionnel `thermal_couplings[]`, `solver`.
- **Un circuit** : `id`, `components[]`, `edges[]`. Chaque circuit est un graphe de composants (un fluide par circuit dans l’usage actuel).
- **Une arête** : `from: "nom:port"`, `to: "nom:port"`. Ports par défaut : `inlet` (0), `outlet` (1). Pour le screw : `suction`, `discharge`, `economizer`.
- **Couplage thermique** : `hot_circuit`, `cold_circuit`, `ua`, `efficiency`. Lie deux circuits (ex. réfrigérant → eau).

Exemple réel à 2 circuits : `crates/cli/examples/heat_pump_r410a.json` (circuit 0 = réfrigérant, circuit 1 = eau, 1 thermal_coupling).

---

## 3. Ce que l’UI fait aujourd’hui (code dans `index.html`)

### Export (`buildConfig()`)

- **Un seul circuit** : `circuits: [circuit]` avec `id: 0`. Pas de circuit 1, pas de `thermal_couplings`.
- **Mapping des types UI → JSON** :
  - `WaterSource`, `WaterSink`, `AirSource`, `AirSink`, `RefrigerantSource`, `RefrigerantSink`, `FlowSplitter`, `FlowMerger` → **toujours** `type: "Placeholder"` + `n_equations: 2` (et autres params conservés). C’est obligatoire car le CLI ne connaît pas ces types.
  - `CondenserWater` → `type: "HeatExchanger"` avec hot = fluide projet (réfrigérant), cold = Water + conditions secondaires.
  - `CondenserAir` → `type: "MchxCondenserCoil"` avec `ua_nominal_kw_k`, `air_inlet_temp_c`, `fan_speed`, `n_air_exponent`, `coil_index: 0`.
  - `EvaporatorWater`, `EvaporatorAir` → `type: "HeatExchanger"` avec hot/cold cohérents (secondaire / réfrigérant).
  - `Compressor`, `ExpansionValve`, `HeatExchanger`, `Pump` → type inchangé + params.
- **Arêtes** : `from: "nom:outlet"`, `to: "nom:inlet"` (noms dérivés des nœuds).

### Limites actuelles de l’UI

1. **Un seul circuit exporté** : pas de deuxième circuit (ex. eau), pas de `thermal_couplings`. Donc on ne peut pas produire un JSON du type `heat_pump_r410a.json` depuis l’UI.
2. **Sources/puits** : Source eau, Puits eau, Source air, Puits air, etc. sont exportés en **Placeholder**. Le solver les traite comme des blocs à `n_equations` sans physique (pas de vraie source air/eau). Les placer sur le schéma permet de représenter visuellement un circuit, mais ce circuit n’est pas simulé comme « circuit air » ou « circuit eau ».
3. **Ventilateur** : il n’existe pas comme composant séparé dans le CLI. Le condenseur à air est modélisé par **MchxCondenserCoil** (T_air entrée + vitesse ventilateur en paramètres). L’UI reflète ça en exportant un seul nœud « Condenseur à air » en `MchxCondenserCoil`.

---

## 4. Lib vs CLI (composants)

| Composant | Dans la lib (crates/components) | Créé par le CLI |
|-----------|--------------------------------|------------------|
| AirSource, AirSink | Oui (`air_boundary.rs`) | Non |
| BrineSource, BrineSink | Oui (`brine_boundary.rs`) | Non |
| RefrigerantSource, RefrigerantSink | (existent ou équivalent) | Non (utiliser Placeholder) |
| Fan | Oui (`fan.rs`) | Non |
| Pump | Oui | Oui (composant pass-through, 0 équations) |
| HeatExchanger | Oui | Oui (avec hot/cold conditions) |
| MchxCondenserCoil | Oui | Oui |
| Condenser / Evaporator (simples) | Oui | Oui |

Donc : **l’outil UI est cohérent avec le CLI** pour tout ce qui est exporté en Compressor, Condenser*, Evaporator*, HeatExchanger, MchxCondenserCoil, ExpansionValve, Pump, Placeholder. Les « sources air/eau » et le « ventilateur » ne sont pas des approximations de l’UI : le CLI ne propose tout simplement pas ces types.

---

## 5. Vision claire de l’outil (sans approximation)

**Aujourd’hui, l’outil est :**

- Un **éditeur visuel pour un seul circuit** (en pratique le circuit réfrigérant).
- Les nœuds « Condenseur à eau/air », « Évaporateur à eau/air » sont convertis en **HeatExchanger** ou **MchxCondenserCoil** avec les bons côtés (réfrigérant / eau ou air) et conditions aux limites. C’est aligné avec le CLI.
- Les nœuds « Source air », « Puits air », « Source eau », etc. sont des **Placeholders** : ils servent à dessiner un schéma et à garder la topologie (nombre d’arêtes, n_equations), mais le fluide « air » ou « eau » n’est pas simulé comme tel par le CLI.

**Pour aller vers une machine complète (ex. PAC air-eau) sans approximation :**

1. **Multi-circuit dans l’UI** : pouvoir définir au moins 2 circuits (ex. 0 = réfrigérant, 1 = eau) et des arêtes par circuit.
2. **Export des thermal_couplings** : quand deux circuits existent, exporter un bloc `thermal_couplings` (hot_circuit, cold_circuit, ua, efficiency).
3. **Support CLI pour sources/puits** (optionnel) : si un jour le CLI crée `AirSource`/`AirSink` ou `BrineSource`/`BrineSink`, l’UI pourra alors exporter ces types au lieu de Placeholder pour les circuits air/eau.

Ce document peut servir de base pour implémenter ces évolutions ou pour expliquer précisément le comportement actuel à un ingénieur HVAC.
