Entropyk/tools/circuit-builder-ui/REFERENCE.md

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.