sepehr
5bd180b5b8
Some checks failed
CI / check (push) Has been cancelled
Capture uncommitted solver robustness work (regularization, domain errors, linear solver lifecycle, tube DP/MSH), web workbench updates, and synced BMAD skills across IDE agent folders before starting BPHX pressure-drop. Co-authored-by: Cursor <cursoragent@cursor.com>
285 lines
9.8 KiB
Markdown
285 lines
9.8 KiB
Markdown
# 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`.
|