Entropyk/DOCUMENTATION.md

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.
• Performance: Use TabularBackend for real-time HIL applications.
• Custom Physics: Implement the Component trait in Rust for specialized modeling.