chore: sync project state and current artifacts

2026-02-22 23:27:31 +01:00
parent 1b6415776e
commit dd77089b22
232 changed files with 37056 additions and 4296 deletions
--- a/crates/cli/README.md
+++ b/crates/cli/README.md
@@ -0,0 +1,169 @@
+# Entropyk CLI
+
+Command-line interface for batch thermodynamic simulations.
+
+## Installation
+
+```bash
+cargo build --release -p entropyk-cli
+```
+
+## Usage
+
+```bash
+# Single simulation
+./target/release/entropyk-cli run config.json -o result.json
+
+# Batch processing
+./target/release/entropyk-cli batch ./scenarios/ --parallel 4
+
+# Validate configuration
+./target/release/entropyk-cli validate config.json
+
+# Help
+./target/release/entropyk-cli --help
+```
+
+## Configuration Format
+
+### Complete Chiller Example (R410A + Water)
+
+```json
+{
+  "name": "Chiller eau glacée R410A",
+  "fluid": "R410A",
+  
+  "circuits": [
+    {
+      "id": 0,
+      "components": [
+        {
+          "type": "Compressor",
+          "name": "comp",
+          "fluid": "R410A",
+          "speed_rpm": 2900,
+          "displacement_m3": 0.000030,
+          "efficiency": 0.85,
+          "m1": 0.85, "m2": 2.5,
+          "m3": 500, "m4": 1500, "m5": -2.5, "m6": 1.8
+        },
+        {
+          "type": "HeatExchanger",
+          "name": "condenser",
+          "ua": 5000,
+          "hot_fluid": "R410A",
+          "hot_t_inlet_c": 45,
+          "hot_pressure_bar": 24,
+          "hot_mass_flow_kg_s": 0.05,
+          "cold_fluid": "Water",
+          "cold_t_inlet_c": 30,
+          "cold_pressure_bar": 1,
+          "cold_mass_flow_kg_s": 0.4
+        },
+        {
+          "type": "ExpansionValve",
+          "name": "exv",
+          "fluid": "R410A",
+          "opening": 1.0
+        },
+        {
+          "type": "Evaporator",
+          "name": "evaporator",
+          "ua": 6000,
+          "t_sat_k": 275.15,
+          "superheat_k": 5
+        }
+      ],
+      "edges": [
+        { "from": "comp:outlet", "to": "condenser:inlet" },
+        { "from": "condenser:outlet", "to": "exv:inlet" },
+        { "from": "exv:outlet", "to": "evaporator:inlet" },
+        { "from": "evaporator:outlet", "to": "comp:inlet" }
+      ]
+    },
+    {
+      "id": 1,
+      "components": [
+        { "type": "Pump", "name": "pump" },
+        { "type": "Placeholder", "name": "load", "n_equations": 0 }
+      ],
+      "edges": [
+        { "from": "pump:outlet", "to": "load:inlet" },
+        { "from": "load:outlet", "to": "pump:inlet" }
+      ]
+    }
+  ],
+  
+  "thermal_couplings": [
+    {
+      "hot_circuit": 0,
+      "cold_circuit": 1,
+      "ua": 6000,
+      "efficiency": 0.95
+    }
+  ],
+  
+  "solver": {
+    "strategy": "fallback",
+    "max_iterations": 100,
+    "tolerance": 1e-6
+  }
+}
+```
+
+## Component Types
+
+| Type | Required Parameters | Optional Parameters |
+|------|---------------------|---------------------|
+| `Compressor` | `fluid`, `speed_rpm`, `displacement_m3` | `efficiency`, `m1-m10` (AHRI 540) |
+| `HeatExchanger` | `ua`, `hot_fluid`, `cold_fluid`, `hot_t_inlet_c`, `cold_t_inlet_c` | `hot_pressure_bar`, `cold_pressure_bar`, `hot_mass_flow_kg_s`, `cold_mass_flow_kg_s` |
+| `Condenser` | `ua` | `t_sat_k` |
+| `CondenserCoil` | `ua` | `t_sat_k` |
+| `Evaporator` | `ua` | `t_sat_k`, `superheat_k` |
+| `EvaporatorCoil` | `ua` | `t_sat_k`, `superheat_k` |
+| `ExpansionValve` | `fluid` | `opening` |
+| `Pump` | - | `name` |
+| `Placeholder` | `name` | `n_equations` |
+
+## Thermal Couplings
+
+Thermal couplings define heat transfer between circuits:
+
+```json
+{
+  "hot_circuit": 0,
+  "cold_circuit": 1,
+  "ua": 5000,
+  "efficiency": 0.95
+}
+```
+
+- `hot_circuit`: Circuit ID providing heat
+- `cold_circuit`: Circuit ID receiving heat
+- `ua`: Thermal conductance (W/K)
+- `efficiency`: Heat exchanger efficiency (0.0-1.0)
+
+## Solver Strategies
+
+| Strategy | Description |
+|----------|-------------|
+| `newton` | Newton-Raphson solver |
+| `picard` | Sequential substitution (Picard iteration) |
+| `fallback` | Picard → Newton fallback (recommended) |
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Simulation error |
+| 2 | Configuration error |
+| 3 | I/O error |
+
+## Examples
+
+See `crates/cli/examples/` for complete configuration examples:
+
+- `chiller_r410a_full.json` - Water chiller with R410A
+- `heat_pump_r410a.json` - Air-to-water heat pump
+- `simple_cycle.json` - Simple heat exchanger cycle