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)

---

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]