139 lines
6.1 KiB
Markdown
139 lines
6.1 KiB
Markdown
# 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.
|