Entropyk/docs/CLI_TUTORIAL.md

Tutoriel Entropyk CLI — Mode ligne de commande

Ce tutoriel décrit pas à pas, sans raccourci, comment utiliser l’outil Entropyk en mode CLI pour construire et lancer une simulation thermodynamique. À la fin, tu auras un système sample fonctionnel et une config JSON réutilisable.

Public : utilisateur qui veut tester le CLI (validate, run, batch) et construire un premier système sample.

---

Sommaire

1. Prérequis et compilation du CLI
2. Vérifier l’installation et l’aide
3. Valider un fichier de configuration (validate)
4. Lancer une simulation (run)
5. Comprendre le format JSON (circuits, composants, arêtes)
6. Créer notre fichier sample pas à pas
7. Exporter les résultats (option -o)
8. Mode batch (optionnel)
9. Qualifier une machine à charge partielle (rate — IPLV / ESEER)
10. Performances saisonnières (scop / seer — méthode par bins EN 14825)

---

1. Prérequis et compilation du CLI

Tu dois être à la racine du dépôt Entropyk et avoir Rust installé (rustc, cargo).

Étape 1.1 — Aller à la racine du projet

cd /chemin/vers/Entropyk

Remplace /chemin/vers/Entropyk par ton chemin réel (par exemple ~/dev/Entropyk).

Étape 1.2 — Compiler le CLI (release, pour de bonnes perfs)

cargo build --release --package entropyk-cli

La première fois, la compilation peut prendre une à deux minutes. À la fin, l’exécutable se trouve ici :

• Linux / macOS : target/release/entropyk-cli
• Windows : target\release\entropyk-cli.exe

Étape 1.3 — Vérifier que l’exécutable existe

Sous Linux/macOS :

ls -l target/release/entropyk-cli

Tu dois voir un fichier binaire. Pour l’appeler, tu peux soit utiliser le chemin complet, soit te placer à la racine du projet et lancer :

./target/release/entropyk-cli

ou, si target/release est dans ton PATH :

entropyk-cli

Dans la suite du tutoriel, on utilisera ./target/release/entropyk-cli depuis la racine du projet pour être explicite.

---

2. Vérifier l’installation et l’aide

Étape 2.1 — Afficher l’aide générale

Depuis la racine du projet :

./target/release/entropyk-cli --help

Tu dois voir quelque chose comme :

Batch thermodynamic simulation CLI

Usage: entropyk-cli [OPTIONS] <COMMAND>

Commands:
  run       Run a single simulation from a configuration file
  batch     Run multiple simulations from a directory
  validate  Validate a configuration file without running
  help      Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose  Enable verbose output
  -q, --quiet    Suppress all output except errors
  -h, --help     Print help

Étape 2.2 — Aide de la commande run

./target/release/entropyk-cli run --help

Tu dois voir les options --config / -c (fichier JSON) et --output / -o (fichier de sortie).

Étape 2.3 — Aide de la commande validate

./target/release/entropyk-cli validate --help

Étape 2.4 — Aide de la commande batch

./target/release/entropyk-cli batch --help

Une fois ces aides lues, tu sais qu’il y a trois commandes principales : validate, run, batch. On commence par validate pour s’assurer qu’un fichier de config est valide avant de lancer une simulation.

---

3. Valider un fichier de configuration (validate)

La commande validate charge le fichier JSON, parse la config (circuits, composants, arêtes, solver, etc.) et affiche si tout est valide. Elle ne lance pas la simulation.

Étape 3.1 — Utiliser un exemple fourni

Le dépôt contient des exemples dans crates/cli/examples/. On prend le plus simple : simple_working.json.

Commande (depuis la racine du projet) :

./target/release/entropyk-cli validate --config crates/cli/examples/simple_working.json

Tu dois voir un bandeau « ENTROPYK CLI - Configuration Validation » et à la fin :

  ✓ Configuration is valid
  File: crates/cli/examples/simple_working.json

Étape 3.2 — Valider un autre exemple

Par exemple un chiller R410A minimal :

./target/release/entropyk-cli validate --config crates/cli/examples/chiller_r410a_minimal.json

Étape 3.3 — Vérifier qu’une erreur est bien détectée

Crée un fichier JSON invalide (par exemple un fichier vide ou du texte qui n’est pas du JSON) et lance :

./target/release/entropyk-cli validate --config /chemin/vers/fichier_invalide.json

Tu dois obtenir un message d’erreur (par exemple « Configuration error » ou erreur de parsing). Cela confirme que validate sert bien à vérifier la config avant de lancer une simulation.

---

[Sections 4 à 8 à compléter au fur et à mesure]

---

9. Qualifier une machine à charge partielle (rate — IPLV / ESEER)

La commande rate calcule un indice de performance à charge partielle (IPLV, NPLV, ESEER…) en re-résolvant le cycle à plusieurs points de charge, puis en les pondérant selon la norme choisie. Chaque point est une vraie résolution couplée (pas d'approximation) : on fait varier les températures secondaires et la vitesse du compresseur, et on lit l'EER émergent.

Étape 9.1 — Lancer l'exemple fourni

./target/release/entropyk-cli rate --config crates/cli/examples/rate_chiller_iplv_ahri.json

Tu obtiens un tableau des points (100/75/50/25 %) avec leur EER, puis la valeur intégrée, par exemple IPLV = 8.114. Comme la portée (« lift ») de pression diminue à charge partielle, l'EER augmente à mesure que la charge baisse.

Étape 9.2 — Choisir / changer la norme

La norme est modulable (voir docs/rating-and-seasonal-metrics.md). Dans le fichier de config rate, l'ordre de priorité est :

1. standard — objet norme inline (poids + fractions de charge) ;
2. standard_file — chemin vers un JSON de norme (résolu relativement au config) ;
3. standard_name — identifiant intégré (iplv, eseer, nplv…) ;
4. metric — enum historique.

Exemple avec une norme externe personnalisée :

./target/release/entropyk-cli rate --config crates/cli/examples/rate_chiller_custom_standard.json

Quand une norme évolue, il suffit d'éditer/remplacer le fichier de poids — aucune recompilation n'est nécessaire.

Étape 9.3 — Exporter le rapport

./target/release/entropyk-cli rate --config <config> --output rapport_iplv.json

---

10. Performances saisonnières (scop / seer — méthode par bins EN 14825)

Les commandes scop (chauffage saisonnier) et seer (refroidissement saisonnier) appliquent la méthode par bins d'EN 14825 : la machine est re-résolue à chaque température extérieure d'un climat, la demande du bâtiment est déduite d'une droite de charge, puis la saison est agrégée par un ratio d'énergie utile / énergie électrique.

Étape 10.1 — Lancer un SCOP (pompe à chaleur air/eau)

./target/release/entropyk-cli scop --config crates/cli/examples/scop_heatpump_r134a.json

Résultat attendu (extrait) :

     T[°C]        h   Demand[kW]      Cap[kW]  COP_full   backup   COP_eff
     -10.0        1        6.000        4.967     3.649      17%     2.506
       2.0      320        3.231        6.918     4.169       0%     3.613
      15.0       74        0.231        9.445     4.751       0%     3.592

  Seasonal useful:   12393.7 kWh    Seasonal electric: 3441.1 kWh
  SCOP = 3.602

Le COP pleine charge augmente quand l'air extérieur se réchauffe (moins de lift) ; aux bins les plus froids, la capacité ne suffit plus à la demande et l'appoint électrique intervient (colonne backup).

Étape 10.2 — Comprendre le fichier de config

{
  "base_config": "heatpump_r134a_air_source.json", // cycle de base (chemin relatif)
  "climate_name": "en_14825_average",              // climat intégré (bins EN 14825)
  "outdoor_side": "evaporator",                     // côté piloté par T extérieure
  "design_load_w": 6000.0,      // demande [W] à design_outdoor_c
  "design_outdoor_c": -10.0,    // T extérieure où demande = design_load_w
  "threshold_outdoor_c": 16.0,  // T extérieure où la demande s'annule
  "cd": 0.25,                   // dégradation de cyclage (PLF = 1 - Cd*(1-CR))
  "backup_cop": 1.0             // COP de l'appoint électrique (chauffage)
}

La température du bin est appliquée au secondary_inlet_temp_c de l'échangeur extérieur ; le débit et le cp du secondaire (ex. air, cp 1006 J/kg·K) restent ceux du base_config.

Étape 10.3 — Lancer un SEER (refroidissement)

Le mode seer pilote par défaut le condenseur (côté extérieur) et exige un climat de refroidissement explicite (climate_name, climate_file ou climate) :

./target/release/entropyk-cli seer --config <mon_config_seer>.json --output seer.json

Étape 10.4 — Sortie JSON

Ajoute --output rapport.json, ou utilise --quiet pour n'émettre que le JSON (pratique pour l'intégration outillée) :

./target/release/entropyk-cli --quiet scop --config crates/cli/examples/scop_heatpump_r134a.json

Note. Comme le climat est une donnée (BinClimateStandard), ajouter une nouvelle saison (climat SEER, révision future d'EN 14825…) revient à fournir un tableau de bins — sans changer le code. Détails complets dans docs/rating-and-seasonal-metrics.md.