Entropyk/docs/tutorial/03-components.md

# 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