Entropyk/apps/web/public/docs/components/README.md

# Entropyk Component Documentation / Documentation des composants Entropyk

> Bilingual reference (EN + FR) for every component usable from the CLI JSON config and the web UI.  
> Référence bilingue (EN + FR) pour chaque composant CLI / UI.
>
> Each page documents: physical model, correlations (if any), residual equations, `n_equations()`,
> ports, system vs rating secondary, calibration Z-factors, and JSON parameters with defaults.
>
> Chaque fiche documente : modèle, corrélations, résidus, ports, modes système/rating, facteurs Z, paramètres JSON.

**Last major doc refresh:** 2026-07-17 — dual-mode HX Newton, compressor maps (AHRI / SST–SDT), correlation inventory, UI Fixed/Free, fallback solver.

### Full correlation & map inventory

→ **[correlations-and-maps.md](./correlations-and-maps.md)** — AHRI 540, screw bilinear presets, Longo/Shah/…, ε-NTU, pumps/fans, ΔP.

---

## Conventions

### State / État

- **State per edge:** `(ṁ, P, h)`. Series branches share one ṁ unknown (`same_branch_m`, CM1.4).  
- **État par arête :** `(ṁ, P, h)`. Branches en série → un seul ṁ.

### DoF (degrees of freedom)

A real-machine solve requires **`n_equations = n_unknowns`**.

- **FIX** = impose a quantity (boundary T/P/ṁ, outlet SH/SC, quality residual, measured calib target…) → +equation or pin.  
- **FREE** = solver unknown (emergent pressure, free opening, free `z_ua`, …).  

CLI hard-fails on imbalance (`validate_system_dof`). Web UI: Fixed checkboxes + balance bar.

### System vs rating secondary (HX)

| Mode | Secondary definition | Secondary unknowns | Newton duty |
|------|----------------------|--------------------|-------------|
| **System** | Live ports `secondary_inlet` / `secondary_outlet` + Source/Sink | yes | ε-NTU Q from edge state |
| **Rating** | Scalars `secondary_inlet_temp_*` + ṁ·cp or `C_sec` | no | ε-NTU Q from scalars **in residuals** |

Both modes are first-class for Condenser / Evaporator / FloodedEvaporator.  
Scalars are **not** limited to offline `rate()` only.

### Zero flow

Valid state. HX use `flow_regularization` (smooth `|ṁ|`, activity, Δh hold). See [flow-regularization.md](./flow-regularization.md).

### Emergent pressure

`emergent_pressure: true` lets condensing/evaporating pressure float from HX ↔ secondary energy balance instead of a fixed design pin.

### Calibration Z-factors (BOLT)

Default **1.0** = no correction. Typical range ~0.2–3 for inverse calib; production often ~0.8–1.2.

| Entropyk | BOLT | Effect |
|----------|------|--------|
| `z_flow` | `Z_flow_suc`, … | ṁ_eff = z_flow × ṁ_nom |
| `z_dp` | `Z_dpc`, … | ΔP_eff = z_dp × ΔP_nom |
| `z_ua` | `Z_UA`, `Z_Uev`, `Z_Ucd` | UA_eff = z_ua × UA_nom |
| `z_power` | `Z_power` | Ẇ_eff = z_power × Ẇ_nom |
| `z_etav` | — | η_v scale |

Legacy `f_*` and BOLT `Z_*` spellings accepted in JSON.  
Recommended order: `z_flow → z_dp → z_ua → z_power → z_etav`.

**UI calibration pattern:** Fixed on measure (SST/SDT) + Free on `z_ua` (do **not** require the Advanced “Regulation loop” node for simple Z_UA calib).

### Solver strategies (CLI)

| `solver.strategy` | Behaviour |
|-------------------|-----------|
| `newton` | Newton–Raphson |
| `picard` | Sequential substitution |
| `fallback` | Intelligent Newton → Picard (`FallbackSolver`) |

---

## Compressors / Compresseurs

- [IsentropicCompressor](./isentropic-compressor.md)
- [ScrewEconomizerCompressor / ScrewCompressor](./screw-economizer-compressor.md)
- [Compressor (AHRI 540)](./compressor-ahri540.md)

## Heat exchangers / Échangeurs

| Component | Model / correlations | Notes |
|-----------|----------------------|--------|
| [Condenser](./condenser.md) | ε-NTU phase-change | dual secondary modes |
| [Evaporator](./evaporator.md) | ε-NTU DX + SH | dual secondary modes |
| [FloodedEvaporator](./flooded-evaporator.md) | ε-NTU + sat-vapor / quality | dual secondary modes |
| [FloodedCondenser](./flooded-condenser.md) | inner ε-NTU + SC control | prefer Condenser in production |
| [BphxEvaporator / BphxCondenser](./bphx.md) | **Longo / Shah** → UA + ε-NTU | geometry + correlation |
| [AirCooledCondenser](./air-cooled-condenser.md) | air-side coil | |
| [FinCoilCondenser](./fin-coil-condenser.md) | finned coil | |
| [MchxCondenserCoil](./mchx-condenser-coil.md) | microchannel | |
| [HeatExchanger (generic)](./heat-exchanger-generic.md) | generic ε-NTU / LMTD | |
| [FreeCoolingExchanger](./free-cooling-exchanger.md) | free cooling | |
| [Economizer](./economizer.md) | internal LMTD HX | not always a CLI leaf |
| [MovingBoundaryHX](./moving-boundary-hx.md) | multi-zone UA ID | research path |
| [Flow regularization](./flow-regularization.md) | zero-flow helpers | shared |

## Valves & expansion

- [IsenthalpicExpansionValve / EXV](./isenthalpic-expansion-valve.md)
- [ExpansionValve](./expansion-valve.md)
- [ReversingValve](./reversing-valve.md)
- [BypassValve](./bypass-valve.md)

## Flow network

- [FlowSplitter](./flow-splitter.md)
- [FlowMerger](./flow-merger.md)
- [Pipe](./pipe.md)
- [Drum](./drum.md)

## Rotating machines

- [Fan](./fan.md)
- [Pump](./pump.md)

## Boundaries

- [Refrigerant / Brine / Air Sources & Sinks](./boundaries.md)

## Inline nodes

- [Anchor & HeatSource](./anchor-heat-source.md)

## Inter-circuit coupling

- [ThermalLoad](./thermal-load.md)

---

See also: system capability notes under `docs/` and example machines in `crates/cli/examples/`.