# 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](#1-prérequis-et-compilation-du-cli)
2. [Vérifier l’installation et l’aide](#2-vérifier-linstallation-et-laide)
3. [Valider un fichier de configuration (validate)](#3-valider-un-fichier-de-configuration-validate)
4. [Lancer une simulation (run)](#4-lancer-une-simulation-run)
5. [Comprendre le format JSON (circuits, composants, arêtes)](#5-comprendre-le-format-json)
6. [Créer notre fichier sample pas à pas](#6-créer-notre-fichier-sample-pas-à-pas)
7. [Exporter les résultats (option -o)](#7-exporter-les-résultats-option--o)
8. [Mode batch (optionnel)](#8-mode-batch-optionnel)
9. [Qualifier une machine à charge partielle (rate — IPLV / ESEER)](#9-qualifier-une-machine-à-charge-partielle-rate--iplv--eseer)
10. [Performances saisonnières (scop / seer — méthode par bins EN 14825)](#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**

```bash
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)**

```bash
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 :

```bash
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 :

```bash
./target/release/entropyk-cli
```

ou, si `target/release` est dans ton `PATH` :

```bash
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 :

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

Tu dois voir quelque chose comme :

```text
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`**

```bash
./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`**

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

**Étape 2.4 — Aide de la commande `batch`**

```bash
./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) :

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

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

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

**Étape 3.2 — Valider un autre exemple**

Par exemple un chiller R410A minimal :

```bash
./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 :

```bash
./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**

```bash
./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 :

```bash
./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**

```bash
./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)**

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

Résultat attendu (extrait) :

```text
     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**

```jsonc
{
  "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`) :

```bash
./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) :

```bash
./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`.
