sepehr
a4f0e26263
Bring the root README, technical manual, and CLI guide in sync with post-CM1.x state (m,P,h), Modelica Fixed/Free, and current component catalog. Co-authored-by: Cursor <cursoragent@cursor.com>
318 lines
9.9 KiB
Markdown
318 lines
9.9 KiB
Markdown
# Entropyk CLI
|
||
|
||
Interface en ligne de commande pour lancer, valider et noter des simulations thermodynamiques à partir de fichiers JSON.
|
||
|
||
Binaire : `entropyk-cli` · Crate : `crates/cli` · Exemples : `crates/cli/examples/`
|
||
|
||
Le README racine ([`../../README.md`](../../README.md)) décrit l’architecture globale, les composants et le solveur. Ce document se concentre sur **l’usage CLI**.
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
cargo build --release -p entropyk-cli
|
||
|
||
# Binaire
|
||
./target/release/entropyk-cli --help # Linux / macOS
|
||
.\target\release\entropyk-cli.exe --help # Windows
|
||
```
|
||
|
||
Ou sans installer :
|
||
|
||
```bash
|
||
cargo run -p entropyk-cli -- <sous-commande> ...
|
||
```
|
||
|
||
Flags globaux : `-v` / `--verbose`, `-q` / `--quiet`.
|
||
|
||
---
|
||
|
||
## Sous-commandes
|
||
|
||
| Commande | Rôle |
|
||
|----------|------|
|
||
| `run` | Une simulation depuis un JSON |
|
||
| `batch` | Un dossier de configs, en parallèle |
|
||
| `validate` | Vérifie la config (parse / topologie) |
|
||
| `qualify` | Qualification HX (régime frigorigène fixe) |
|
||
| `rate` | IPLV (AHRI 550/590) / ESEER |
|
||
| `scop` | SCOP EN 14825 (bins chauffage) |
|
||
| `seer` | SEER EN 14825 (bins froid) |
|
||
| `schema` | Émet le JSON Schema du Model IR |
|
||
|
||
### Exemples
|
||
|
||
```bash
|
||
# Simulation unique
|
||
cargo run -p entropyk-cli -- run \
|
||
--config crates/cli/examples/chiller_aircooled_r134a.json \
|
||
--output result.json
|
||
|
||
# Validation
|
||
cargo run -p entropyk-cli -- validate --config mon_cycle.json
|
||
|
||
# Batch (4 workers)
|
||
cargo run -p entropyk-cli -- batch -d ./scenarios/ -p 4 -O results.json
|
||
|
||
# Rating IPLV
|
||
cargo run -p entropyk-cli -- rate -c crates/cli/examples/rate_chiller_iplv_ahri.json
|
||
|
||
# SCOP
|
||
cargo run -p entropyk-cli -- scop -c crates/cli/examples/scop_heatpump_r134a.json
|
||
|
||
# Schema
|
||
cargo run -p entropyk-cli -- schema -o model-ir.schema.json
|
||
```
|
||
|
||
---
|
||
|
||
## Pipeline de `run`
|
||
|
||
1. Parse `ScenarioConfig` (fluide, circuits, edges, controls, solver)
|
||
2. Pour chaque composant : `create_component` (`crates/cli/src/run.rs`)
|
||
3. Câblage des arêtes `nom:port` → `nom:port`
|
||
4. `finalize()` + **porte DoF** (système carré obligatoire)
|
||
5. Seed initial (frontières + staging HP/BP si `emergent_pressure`)
|
||
6. Solve : `newton` | `picard` | `fallback`
|
||
7. Sortie JSON : états, performances, `dof`, erreurs / `failure_diagnostics`
|
||
|
||
---
|
||
|
||
## Format de configuration
|
||
|
||
### Structure racine
|
||
|
||
```json
|
||
{
|
||
"name": "Mon chiller",
|
||
"description": "optionnel",
|
||
"fluid": "R134a",
|
||
"fluid_backend": "CoolProp",
|
||
"circuits": [ { "id": 0, "components": [], "edges": [] } ],
|
||
"controls": [],
|
||
"thermal_couplings": [],
|
||
"solver": {
|
||
"strategy": "newton",
|
||
"max_iterations": 300,
|
||
"tolerance": 1e-6
|
||
}
|
||
}
|
||
```
|
||
|
||
| Champ | Description |
|
||
|-------|-------------|
|
||
| `fluid` | Frigorigène principal du circuit (ex. `R134a`, `R410A`) |
|
||
| `fluid_backend` | `CoolProp` (défaut sérieux), Tabular, etc. |
|
||
| `circuits[]` | Un ou plusieurs circuits (id 0…n) |
|
||
| `components[]` | Objets avec `type`, `name`, + paramètres |
|
||
| `edges[]` | `{ "from": "comp:outlet", "to": "cond:inlet" }` |
|
||
| `controls[]` | Boucles inverse / SaturatedController (optionnel) |
|
||
| `solver.strategy` | `newton` (**défaut**), `picard`, `fallback` |
|
||
|
||
### Exemple moderne (chiller air, 4 ports)
|
||
|
||
Voir `examples/chiller_aircooled_r134a.json` — pattern recommandé :
|
||
|
||
- `IsentropicCompressor` + `emergent_pressure`
|
||
- `Condenser` / `Evaporator` avec secondaires `AirSource`/`BrineSource` → HX → sinks
|
||
- `IsenthalpicExpansionValve` isenthalpique (sans orifice sauf besoin)
|
||
- Sources : Fixed T + Fixed ṁ + **Free P** ; sinks : Fixed P
|
||
|
||
```bash
|
||
cargo run -p entropyk-cli -- run \
|
||
-c crates/cli/examples/chiller_aircooled_r134a.json
|
||
```
|
||
|
||
---
|
||
|
||
## Types de composants CLI
|
||
|
||
Chaînes `type` reconnues par `create_component` (liste non exhaustive — voir le match dans `src/run.rs`).
|
||
|
||
### Compresseurs
|
||
|
||
| Type | Paramètres utiles |
|
||
|------|-------------------|
|
||
| `IsentropicCompressor` | `displacement_m3`, `speed_hz`, `volumetric_efficiency`, `isentropic_efficiency`, `emergent_pressure` |
|
||
| `Compressor` | Cartes AHRI 540 (`m1`…`m10`) ou SST/SDT |
|
||
| `ScrewEconomizerCompressor` / `ScrewCompressor` | Courbes SST/SDT, VFD, slide valve |
|
||
| `CentrifugalCompressor` | `diameter_m`, `speed_rpm`, γ, R |
|
||
|
||
### Détente
|
||
|
||
| Type | Paramètres utiles | Attention |
|
||
|------|-------------------|-----------|
|
||
| `IsenthalpicExpansionValve` / `EXV` | `emergent_pressure`, `t_evap_k` | Sans `orifice_kv`, **`opening` est ignoré** |
|
||
| `ExpansionValve` | `opening`, `flow_model`, `beta_m2`… | |
|
||
| `CapillaryTube` | `diameter_m`, `length_m`, `n_segments` | |
|
||
| `ReversingValve` / `FourWayValve` | `mode`, `pressure_drop_pa` | |
|
||
| `BypassValve` | `opening`, `cv` | |
|
||
|
||
**EXV orifice** (débit physique) :
|
||
|
||
```json
|
||
{
|
||
"type": "IsenthalpicExpansionValve",
|
||
"name": "exv",
|
||
"emergent_pressure": true,
|
||
"orifice_kv": 2.0e-6,
|
||
"opening": 0.6,
|
||
"fix_opening": true
|
||
}
|
||
```
|
||
|
||
Loi : `ṁ = Kv · opening · √(2 · ρ · max(ΔP, 0))`.
|
||
Avec orifice Fixed, le CLI met le compresseur en ṁ métré. Voir `examples/chiller_r134a_exv_orifice.json`.
|
||
|
||
### Échangeurs
|
||
|
||
| Type | Paramètres utiles |
|
||
|------|-------------------|
|
||
| `Condenser` / `Evaporator` | `ua`, `emergent_pressure`, `subcooling_k` / SH, `secondary_fluid`, ΔP secondaire |
|
||
| `FloodedEvaporator` | `ua`, `quality_control` |
|
||
| `HeatExchanger` | `ua`, `hot_fluid_id`, `cold_fluid_id` (4 ports) |
|
||
| `BphxEvaporator` / `BphxCondenser` | Géométrie plaques + corrélations |
|
||
| `AirCooledCondenser`, `FinCoilCondenser`, `MchxCondenserCoil` | Bobines air / MCHX |
|
||
| `FreeCoolingExchanger` | Free-cooling eau |
|
||
|
||
Secondaire 4 ports :
|
||
|
||
```text
|
||
BrineSource/AirSource → HX:secondary_inlet → HX:secondary_outlet → BrineSink/AirSink
|
||
```
|
||
|
||
ΔP secondaire de rating (optionnel) :
|
||
|
||
```json
|
||
"secondary_rated_pressure_drop_pa": 40000,
|
||
"secondary_rated_m_flow_kg_s": 0.5
|
||
```
|
||
|
||
### Tuyauterie / machines tournantes
|
||
|
||
| Type | Notes |
|
||
|------|-------|
|
||
| `Pipe` / `RefrigerantPipe` / `WaterPipe` / `AirDuct` | `length_m`, `diameter_m` ; `pressure_drop_pa = 0` → **Darcy** L/D ; `> 0` → ΔP imposé |
|
||
| `Pump`, `Fan` | Courbes + affinity laws |
|
||
| `FlowSplitter`, `FlowMerger`, `Drum` | Jonctions / séparateur |
|
||
|
||
### Frontières
|
||
|
||
| Type | Flags Fixed/Free |
|
||
|------|------------------|
|
||
| `BrineSource` / `BrineSink` | `fix_pressure`, `fix_temperature`, `fix_mass_flow` |
|
||
| `AirSource` / `AirSink` | idem (+ psychrométrie `t_dry_c`, `rh`) |
|
||
| `RefrigerantSource` / `RefrigerantSink` | P, qualité / h, ṁ |
|
||
|
||
**Défaut recommandé (Modelica MassFlowSource_T)** : source Fixed T + Fixed ṁ + Free P ; sink Fixed P.
|
||
|
||
Voir [`docs/modelica-boundary-proof.md`](../../docs/modelica-boundary-proof.md).
|
||
|
||
### Divers
|
||
|
||
`ThermalLoad`, `HeatSource`, `Anchor` / `RefrigerantNode`, `Placeholder`.
|
||
|
||
---
|
||
|
||
## Contrôles (régulation / calibration)
|
||
|
||
```json
|
||
"controls": [
|
||
{
|
||
"type": "SaturatedController",
|
||
"id": "sh_loop",
|
||
"measure": { "component": "evap", "output": "superheat" },
|
||
"actuator": {
|
||
"component": "exv",
|
||
"factor": "opening",
|
||
"initial": 0.5,
|
||
"min": 0.1,
|
||
"max": 1.0
|
||
},
|
||
"target": 5.0
|
||
}
|
||
]
|
||
```
|
||
|
||
Chaque boucle ajoute des inconnues d’actionneur + résidus de tracking. Le système doit rester DoF-carré (mesure FIX ↔ actionneur FREE).
|
||
|
||
---
|
||
|
||
## Stratégies solveur
|
||
|
||
| Valeur | Comportement |
|
||
|--------|--------------|
|
||
| `newton` | Newton–Raphson (défaut). Armijo activé si contrôles, orifice EXV, ou Free-P sur `BrineSource`. |
|
||
| `picard` | Substitution successive amortie (ω ≈ 0,5) |
|
||
| `fallback` | Newton → Picard si divergence → retour Newton si résidu bas |
|
||
|
||
```json
|
||
"solver": {
|
||
"strategy": "newton",
|
||
"max_iterations": 300,
|
||
"tolerance": 1e-6
|
||
}
|
||
```
|
||
|
||
Si le résidu décroît lentement (Jacobien partiellement numérique sur certains HX), augmenter `max_iterations` (ex. 1000).
|
||
|
||
---
|
||
|
||
## Sortie et codes de sortie
|
||
|
||
Sortie typique JSON (`--output`) :
|
||
|
||
- `status` : `converged` / `Error` / …
|
||
- `iterations`, `state` (arêtes : ṁ, P, h…)
|
||
- `performance` (puissances, COP…)
|
||
- `dof` (équations vs inconnues)
|
||
- `error`, `failure_diagnostics` si échec après itérations
|
||
|
||
| Code | Signification |
|
||
|------|----------------|
|
||
| 0 | Succès |
|
||
| 1 | Erreur de simulation / non-convergence |
|
||
| 2 | Erreur de configuration |
|
||
| 3 | Erreur I/O |
|
||
|
||
---
|
||
|
||
## Exemples fournis (`examples/`)
|
||
|
||
| Fichier | Intérêt |
|
||
|---------|---------|
|
||
| `chiller_aircooled_r134a.json` | Chiller air 4 ports, emergent |
|
||
| `chiller_watercooled_r410a.json` | Chiller eau R410A |
|
||
| `chiller_flooded_4port_watercooled.json` | FloodedEvaporator |
|
||
| `chiller_r134a_emergent_pressure.json` | Pressions émergentes |
|
||
| `chiller_r134a_exv_orifice.json` | EXV orifice (opening physique) |
|
||
| `chiller_r134a_superheat_control.json` | Boucle SH |
|
||
| `heatpump_airsource_r410a.json` | PAC air |
|
||
| `heatpump_r410a_reversing_valve.json` | Vanne 4 voies |
|
||
| `hx_air_water_4port.json` | HX isolé |
|
||
| `bphx_evaporator_condenser.json` | Plaques brasées |
|
||
| `capillary_tube_r134a.json` | Capillaire |
|
||
| `rate_chiller_iplv_ahri.json` | Rating IPLV |
|
||
| `scop_heatpump_r134a.json` | SCOP |
|
||
|
||
---
|
||
|
||
## Pièges fréquents
|
||
|
||
1. **EXV `opening` sans effet** → il manque `orifice_kv` (sinon isenthalpique seul ; ṁ = compresseur).
|
||
2. **DoF under-constrained** → source Free P sans fermeture P sur le HX/pipe ; ou oubli de brancher le secondaire 4 ports.
|
||
3. **DoF over-constrained** → Fixed ṁ **et** Fixed P sur la même frontière ; ou double Fixed-P sans ΔP.
|
||
4. **Pipe isobare** → avec l’ancien défaut mental « ΔP=0 = rien » : aujourd’hui `pressure_drop_pa = 0` déclenche **Darcy** depuis L/D.
|
||
5. **Exemples obsolètes** cités dans d’anciennes docs (`chiller_r410a_full.json`, etc.) → utiliser la table ci-dessus.
|
||
|
||
---
|
||
|
||
## Voir aussi
|
||
|
||
- [README racine](../../README.md) — architecture, composants, solveur
|
||
- [DOCUMENTATION.md](../../DOCUMENTATION.md) — manuel technique
|
||
- [docs/CLI_TUTORIAL.md](../../docs/CLI_TUTORIAL.md) — tutoriel pas à pas
|
||
- [docs/modelica-boundary-proof.md](../../docs/modelica-boundary-proof.md) — Fixed/Free
|
||
- [docs/rating-and-seasonal-metrics.md](../../docs/rating-and-seasonal-metrics.md) — IPLV / SCOP / SEER
|