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/docs/tutorial/03-components.md
+++ b/docs/tutorial/03-components.md
@@ -0,0 +1,412 @@
+# Components Reference
+
+This document describes all available thermodynamic components in Entropyk, their equations, and usage examples.
+
+## Component Categories
+
+| Category | Purpose | Components |
+|----------|---------|------------|
+| **Active** | Add work to fluid | Compressor, Pump, Fan |
+| **Passive** | Pressure drop, no work | Pipe, ExpansionValve |
+| **Heat Transfer** | Exchange heat between fluids | Evaporator, Condenser, Economizer, HeatExchanger |
+| **Boundary** | Fixed conditions | FlowSource, FlowSink |
+| **Junction** | Flow splitting/merging | FlowSplitter, FlowMerger |
+
+---
+
+## Active Components
+
+### Compressor
+
+A positive displacement compressor using the AHRI 540 performance model.
+
+**Equations (2)**:
+- Mass flow: `ṁ = M1 × (1 - (P_suc/P_dis)^(1/M2)) × ρ_suc × V_disp × N/60`
+- Power: `Ẇ = M3 + M4 × (P_dis/P_suc) + M5 × T_suc + M6 × T_dis`
+
+**Ports**: 2 (inlet, outlet)
+
+```rust
+use entropyk_components::compressor::{Compressor, Ahri540Coefficients};
+use entropyk_components::port::{FluidId, Port};
+use entropyk_core::{Pressure, Enthalpy};
+
+// Create with AHRI 540 coefficients
+let coeffs = Ahri540Coefficients::new(
+    0.85, 2.5,      // M1, M2 (flow)
+    500.0, 1500.0, -2.5, 1.8,  // M3-M6 (cooling power)
+    600.0, 1600.0, -3.0, 2.0   // M7-M10 (heating power)
+);
+
+// Create disconnected ports
+let inlet = Port::new(
+    FluidId::new("R134a"),
+    Pressure::from_bar(3.5),
+    Enthalpy::from_kj_per_kg(405.0),
+);
+let outlet = Port::new(
+    FluidId::new("R134a"),
+    Pressure::from_bar(12.0),
+    Enthalpy::from_kj_per_kg(440.0),
+);
+
+// Build compressor
+let compressor = Compressor::new(
+    coeffs,
+    2900.0,    // speed_rpm
+    0.0001,    // displacement m³/rev
+    inlet,
+    outlet,
+)?;
+```
+
+**Calibration**: `f_m` (mass flow), `f_power` (power), `f_etav` (volumetric efficiency)
+
+---
+
+### Pump
+
+A centrifugal pump for incompressible fluids (water, brine, glycol).
+
+**Equations (2)**:
+- Pressure rise: `ΔP = f_head × ρ × g × H_curve(Q)`
+- Power: `Ẇ = ρ × g × Q × H / η`
+
+**Ports**: 2 (inlet, outlet)
+
+```rust
+use entropyk_components::pump::Pump;
+use entropyk_components::port::{FluidId, Port};
+use entropyk_core::{Pressure, Enthalpy};
+
+let inlet = Port::new(
+    FluidId::new("Water"),
+    Pressure::from_bar(1.0),
+    Enthalpy::from_kj_per_kg(63.0),  // ~15°C
+);
+let outlet = Port::new(
+    FluidId::new("Water"),
+    Pressure::from_bar(3.0),
+    Enthalpy::from_kj_per_kg(63.0),
+);
+
+let pump = Pump::new(
+    "Chilled Water Pump",
+    inlet,
+    outlet,
+    0.5,    // design flow rate kg/s
+    200.0,  // design head kPa
+)?;
+```
+
+---
+
+### Fan
+
+An air-moving device for condenser cooling or ventilation.
+
+**Equations (2)**:
+- Pressure rise: `ΔP = fan_curve(Q, N)`
+- Power: `Ẇ = Q × ΔP / η`
+
+**Ports**: 2 (inlet, outlet)
+
+```rust
+use entropyk_components::fan::Fan;
+
+let fan = Fan::new(
+    "Condenser Fan",
+    inlet_port,
+    outlet_port,
+    2.0,    // design flow m³/s
+    150.0,  // design static pressure Pa
+)?;
+```
+
+---
+
+## Passive Components
+
+### Pipe
+
+A fluid transport pipe with Darcy-Weisbach pressure drop.
+
+**Equations (1)**:
+- Pressure drop: `ΔP = f × (L/D) × (ρ × v² / 2)`
+
+**Ports**: 2 (inlet, outlet)
+
+```rust
+use entropyk_components::pipe::{Pipe, PipeGeometry, roughness};
+
+let geometry = PipeGeometry::new(
+    10.0,              // length m
+    0.025,             // inner diameter m
+    roughness::SMOOTH, // roughness m
+)?;
+
+let pipe = Pipe::for_incompressible(
+    geometry,
+    inlet_port,
+    outlet_port,
+    998.0,    // density kg/m³
+    0.001,    // viscosity Pa·s
+)?;
+```
+
+---
+
+### Expansion Valve
+
+A thermostatic or electronic expansion valve for refrigerant systems.
+
+**Equations (1)**:
+- Mass flow: `ṁ = C_v × opening × √(ρ × ΔP)`
+
+**Ports**: 2 (inlet, outlet)
+
+```rust
+use entropyk_components::expansion_valve::ExpansionValve;
+
+let valve = ExpansionValve::new(
+    FluidId::new("R134a"),
+    0.8,    // opening (0-1)
+    inlet_port,
+    outlet_port,
+)?;
+```
+
+---
+
+## Heat Transfer Components
+
+### Heat Exchanger Architecture
+
+All heat exchangers have **4 ports**:
+
+```
+   Hot Side:
+   Inlet ─────►┌──────────┐──────► Outlet
+               │   HX     │
+   Cold Side:  │          │
+   Inlet ─────►└──────────┘──────► Outlet
+```
+
+| Component | Hot Side | Cold Side | Model |
+|-----------|----------|-----------|-------|
+| Condenser | Refrigerant (condensing) | Water/Air | LMTD |
+| Evaporator | Water/Air | Refrigerant (evaporating) | ε-NTU |
+| Economizer | Hot refrigerant | Cold refrigerant | ε-NTU |
+
+---
+
+### Condenser
+
+A heat exchanger where refrigerant condenses from vapor to liquid.
+
+**Equations (3)**:
+- Hot side energy: `Q_hot = ṁ_hot × (h_in - h_out)`
+- Cold side energy: `Q_cold = ṁ_cold × Cp × (T_out - T_in)`
+- Heat transfer: `Q = UA × LMTD`
+
+**Ports**: 4 (hot_in, hot_out, cold_in, cold_out)
+
+```rust
+use entropyk_components::heat_exchanger::Condenser;
+
+let condenser = Condenser::new(10_000.0);  // UA = 10 kW/K
+
+// Set saturation temperature for condensation
+condenser.set_saturation_temp(323.15);  // 50°C
+
+// Calibration for matching real data
+condenser.set_calib(Calib { f_ua: 1.1, ..Default::default() });
+```
+
+**Thermodynamic Notes**:
+- Refrigerant enters as superheated vapor
+- Refrigerant exits as subcooled liquid
+- Typical subcooling: 3-10 K
+
+---
+
+### Evaporator
+
+A heat exchanger where refrigerant evaporates from liquid to vapor.
+
+**Equations (3)**:
+- Hot side energy: `Q_hot = ṁ_hot × Cp × (T_in - T_out)`
+- Cold side energy: `Q_cold = ṁ_cold × (h_out - h_in)`
+- Heat transfer: `Q = ε × ṁ_cold × Cp_cold × (T_hot_in - T_cold_in)`
+
+**Ports**: 4 (hot_in, hot_out, cold_in, cold_out)
+
+```rust
+use entropyk_components::heat_exchanger::Evaporator;
+
+let evaporator = Evaporator::new(8_000.0);  // UA = 8 kW/K
+
+// Set saturation temperature and superheat target
+evaporator.set_saturation_temp(278.15);  // 5°C
+evaporator.set_superheat_target(5.0);    // 5 K superheat
+```
+
+**Thermodynamic Notes**:
+- Refrigerant enters as two-phase mixture (after expansion valve)
+- Refrigerant exits as superheated vapor
+- Typical superheat: 5-10 K
+
+---
+
+### Economizer
+
+A heat exchanger for subcooling liquid refrigerant using expanded vapor.
+
+**Equations (3)**: Same as generic heat exchanger
+
+**Ports**: 4 (hot_in, hot_out, cold_in, cold_out)
+
+```rust
+use entropyk_components::heat_exchanger::Economizer;
+
+let economizer = Economizer::new(2_000.0);  // UA = 2 kW/K
+```
+
+---
+
+## Boundary Components
+
+### FlowSource
+
+Imposes fixed pressure and enthalpy at circuit inlet.
+
+**Equations (2)**:
+- `r_P = P_edge - P_set = 0`
+- `r_h = h_edge - h_set = 0`
+
+**Ports**: 1 (outlet only)
+
+```rust
+use entropyk_components::flow_boundary::FlowSource;
+
+// City water supply: 3 bar, 15°C
+let source = FlowSource::incompressible(
+    "Water",
+    3.0e5,      // pressure Pa
+    63_000.0,   // enthalpy J/kg (~15°C)
+    connected_port,
+)?;
+
+// Refrigerant reservoir: 12 bar, 40°C subcooled
+let source = FlowSource::compressible(
+    "R134a",
+    12.0e5,     // pressure Pa
+    250_000.0,  // enthalpy J/kg (subcooled liquid)
+    connected_port,
+)?;
+```
+
+---
+
+### FlowSink
+
+Imposes back-pressure at circuit outlet.
+
+**Equations (1-2)**:
+- `r_P = P_edge - P_back = 0`
+- Optional: `r_h = h_edge - h_back = 0`
+
+**Ports**: 1 (inlet only)
+
+```rust
+use entropyk_components::flow_boundary::FlowSink;
+
+// Return header with back-pressure
+let sink = FlowSink::incompressible(
+    "Water",
+    1.5e5,      // back-pressure Pa
+    None,       // no fixed enthalpy
+    connected_port,
+)?;
+
+// With fixed return temperature
+let sink = FlowSink::incompressible(
+    "Water",
+    1.5e5,
+    Some(84_000.0),  // fixed enthalpy (~20°C)
+    connected_port,
+)?;
+```
+
+---
+
+## Junction Components
+
+### FlowSplitter
+
+Divides one inlet flow into multiple outlets.
+
+**Equations (N_outlets)**:
+- Mass conservation: `ṁ_in = Σ ṁ_out`
+- Pressure equality at all outlets
+
+**Ports**: 1 inlet + N outlets
+
+```rust
+use entropyk_components::flow_junction::FlowSplitter;
+
+let splitter = FlowSplitter::new(
+    "Chilled Water Splitter",
+    inlet_port,
+    vec![outlet1, outlet2, outlet3],
+)?;
+```
+
+---
+
+### FlowMerger
+
+Combines multiple inlet flows into one outlet.
+
+**Equations (N_inlets)**:
+- Mass conservation: `Σ ṁ_in = ṁ_out`
+- Enthalpy mixing: `h_out = Σ(ṁ_in × h_in) / ṁ_out`
+
+**Ports**: N inlets + 1 outlet
+
+```rust
+use entropyk_components::flow_junction::FlowMerger;
+
+let merger = FlowMerger::new(
+    "Return Water Merger",
+    vec![inlet1, inlet2, inlet3],
+    outlet_port,
+)?;
+```
+
+---
+
+## Component Summary Table
+
+| Component | Equations | Ports | Calibration |
+|-----------|-----------|-------|-------------|
+| Compressor | 2 | 2 | f_m, f_power, f_etav |
+| Pump | 2 | 2 | f_m, f_power |
+| Fan | 2 | 2 | f_m, f_power |
+| Pipe | 1 | 2 | f_dp |
+| ExpansionValve | 1 | 2 | f_m |
+| Condenser | 3 | 4 | f_ua, f_dp |
+| Evaporator | 3 | 4 | f_ua, f_dp |
+| Economizer | 3 | 4 | f_ua, f_dp |
+| FlowSource | 2 | 1 | - |
+| FlowSink | 1-2 | 1 | - |
+| FlowSplitter | N | 1+N | - |
+| FlowMerger | N | N+1 | - |
+
+---
+
+## Next Steps
+
+- See [Building Systems](./04-building-systems.md) for connecting components
+- Learn about [Refrigeration Cycles](./06-refrigeration-cycles.md) for complete examples
+- Explore [Calibration](./10-calibration.md) for matching real data