# Entropyk: Technical Manual & Reference Guide

Entropyk is a high-performance thermodynamic simulation framework designed for precision modeling of HVAC/R systems. This manual provides exhaustive documentation of the physical models, solver mechanics, and multi-platform APIs.

---

## 1. Physical Foundations

### 1.1 Dimensional Analysis & Type Safety
Entropyk utilizes a "Type-Safe Dimension" pattern to eliminate unit errors. Every physical quantity is wrapped in a NewType that enforces SI base units internally.

| Quantity | Internal Unit (SI) | Documentation Symbol |
| :--- | :--- | :--- |
| Pressure | Pascal ($Pa$) | $P$ |
| Temperature | Kelvin ($K$) | $T$ |
| Enthalpy | Joule per kilogram ($J/kg$) | $h$ |
| Mass Flow | Kilogram per second ($kg/s$) | $\dot{m}$ |
| Density | Kilogram per cubic meter ($kg/m^3$) | $\rho$ |

### 1.2 Conservation Laws
The solver operates on the principle of local conservation at every node $i$:
- **Mass Conservation**: $\sum \dot{m}_{in} - \sum \dot{m}_{out} = 0$
- **Energy Conservation**: $\sum (\dot{m} \cdot h)_{in} - \sum (\dot{m} \cdot h)_{out} + \dot{Q} - \dot{W} = 0$

---

## 2. Fluid Physics (`entropyk-fluids`)

The `FluidBackend` trait provides thermodynamic properties $(T, \rho, c_p, s)$ as functions of state variables $(P, h)$.

### 2.1 Backend Implementations

#### A. CoolProp Backend
Utilizes full Helmholtz energy equations of state (EOS). 
- **Domain**: Precise research and steady-state validation.
- **Complexity**: $O(N)$ high overhead due to iterative property calls.

#### B. Tabular Backend (Bicubic)
Uses high-fidelity lookup tables with bicubic Hermite spline interpolation.
- **Equation**: $Z(P, h) = \sum_{i=0}^3 \sum_{j=0}^3 a_{ij} \cdot P^i \cdot h^j$
- **Performance**: $O(1)$ constant time with SIMD acceleration. Recommended for HIL.

#### C. Incompressible Backend (Linearized)
For water, glycols, and brines where $\rho$ is nearly constant.
- **Density**: $\rho(T) = \rho_0 \cdot [1 - \beta(T - T_0)]$
- **Enthalpy**: $h = c_p \cdot (T - T_0)$

### 2.2 Phase Change Logic
Fluid backends automatically identify the fluid phase:
1. **Subcooled**: $h < h_{sat,l}(P)$
2. **Two-Phase**: $h_{sat,l}(P) \le h \le h_{sat,v}(P)$
3. **Superheated**: $h > h_{sat,v}(P)$

For two-phase flow, quality $x$ is defined as:
$$x = \frac{h - h_{sat,l}}{h_{sat,v} - h_{sat,l}}$$


---

## 3. Component Technical Reference (`entropyk-components`)

### 3.1 Compressor (`Compressor`)

#### A. AHRI 540 (10-Coefficient)
Standard model for positive displacement compressors. Mass flow $\dot{m}$ and power $W$ are calculated using the 3rd-order polynomial:
$$X = C_1 + C_2 T_s + C_3 T_d + C_4 T_s^2 + C_5 T_s T_d + C_6 T_d^2 + C_7 T_s^3 + C_8 T_d T_s^2 + C_9 T_s T_d^2 + C_{10} T_d^3$$
*Note: $T_s$ is suction temperature and $T_d$ is discharge temperature in Fahrenheit or Celsius depending on coefficients.*

#### B. SST/SDT Polynomials
Used for variable speed compressors where coefficients are adjusted for RPM:
$$\dot{m} = \sum_{i=0}^3 \sum_{j=0}^3 A_{ij} \cdot SST^i \cdot SDT^j$$

### 3.2 Pipe (`Pipe`)
- **Pressure Drop**: $\Delta P = f \cdot \frac{L}{D} \cdot \frac{\rho v^2}{2}$
- **Haaland Approximation** (Friction Factor $f$):
$$\frac{1}{\sqrt{f}} \approx -1.8 \log_{10} \left[ \left(\frac{\epsilon/D}{3.7}\right)^{1.11} + \frac{6.9}{Re} \right]$$
*Where $Re = \frac{\rho v D}{\mu}$ is the Reynolds number.*

### 3.3 Heat Exchanger (`HeatExchanger`)
Single-phase and phase-change modeling via the $\varepsilon$-NTU method.

- **Heat Transfer**: $\dot{Q} = \varepsilon \cdot C_{min} \cdot (T_{h,in} - T_{c,in})$
- **Effectiveness ($\varepsilon$)**:
    - **Counter-Flow**: $\varepsilon = \frac{1 - \exp(-NTU(1 - C^*))}{1 - C^* \exp(-NTU(1 - C^*))}$
    - **Evaporator/Condenser**: $\varepsilon = 1 - \exp(-NTU)$ (since $C^* \to 0$ during phase change)

---

## 4. Solver Engine (`entropyk-solver`)

The engine solves $\mathbf{F}(\mathbf{x}) = \mathbf{0}$ where $\mathbf{x}$ is the state vector $[P, h]$ for all edges.

### 4.1 Newton-Raphson Solver
Primary strategy for fast, quadratic convergence.
$$\mathbf{J}(\mathbf{x}_k) \Delta \mathbf{x} = -\mathbf{F}(\mathbf{x}_k)$$
$$\mathbf{x}_{k+1} = \mathbf{x}_k + \alpha \Delta \mathbf{x}$$

- **Armijo Line Search**: Dynamically adjusts $\alpha$ to ensure steady residual reduction.
- **Step Clipping**: Hard bounds on $\Delta P$ and $\Delta h$ to maintain physical sanity (e.g., $P > 0$).
- **Jacobian Freezing**: Reuses $\mathbf{J}$ for $N$ steps if convergence is stable, improving speed by ~40%.

### 4.2 Sequential Substitution (Picard)
Fixed-point iteration for robust initialization:
$$\mathbf{x}_{k+1} = \mathbf{x}_k - \omega \cdot \mathbf{F}(\mathbf{x}_k)$$
*Where $\omega \in (0, 1]$ is the relaxation factor (default 0.5).*

---

## 5. Advanced Features

### 5.1 Inverse Control
Swaps independent variables for targets.
- **Constraints**: Force specific outputs (e.g., Exit Superheat $= 5K$).
- **Bounded Variables**: Physical limits on inputs (e.g., Valve Opening $0 \le x \le 1$).

### 5.2 Multi-Circuit Coupling
Modeled via bridge components (typically `HeatExchanger`). The solver constructs a unified Jacobian for both circuits to handle thermal feedback loops in a single pass.

---

## 6. Multi-Platform API Reference

Entropyk provides high-fidelity bindings with near-perfect parity.

| Feature | Rust (`-core`) | Python (`entropyk`) | C / FFI | WASM |
| :--- | :--- | :--- | :--- | :--- |
| **Component Creation** | `Compressor::new()` | `ek.Compressor()` | `ek_compressor_create()` | `new Compressor()` |
| **System Finalization** | `system.finalize()` | `system.finalize()` | `ek_system_finalize()` | `system.finalize()` |
| **Solving** | `config.solve(&sys)` | `config.solve(sys)` | `ek_solve(sys, cfg)` | `await config.solve(sys)` |
| **Inverse Control** | `sys.add_constraint()` | `sys.add_constraint()` | `ek_sys_add_constraint()` | `sys.addConstraint()` |
| **Memory Management** | RAII (Automatic) | Ref-Counted (PyO3) | Manual Free (`_free`) | JS Garbage Collected |

---

## 7. Getting Started
- **Step-by-Step Instructions**: Refer to [EXAMPLES_FULL.md](./EXAMPLES_FULL.md).
- **Performance**: Use `TabularBackend` for real-time HIL applications.
- **Custom Physics**: Implement the `Component` trait in Rust for specialized modeling.