# Entropyk: The Definitive Guide

Entropyk is a high-performance thermodynamic simulation framework designed for precision modeling of HVAC/R systems. It combines deep physical principles with modern software engineering patterns to provide a robust, scalable, and cross-platform simulation engine.

## 1. Core Philosophy

### Physics First (Type-Safe Units)
Entropyk eliminates unit errors at the compiler level. Instead of using `f64` for all physical values, we use strong types:
- `Pressure` (Pascals, bar, psi)
- `Temperature` (Kelvin, Celsius, Fahrenheit)
- `Enthalpy` (J/kg, kJ/kg)
- `MassFlow` (kg/s, g/s)

These types prevent accidents like adding Celsius to Kelvin or confusing bar with Pascals.

### Topology Safety (Type-State Connections)
Using Rust's type system, ports transition from `Disconnected` to `Connected`. A `Connected` port is guaranteed to have the same fluid, pressure, and enthalpy as its peer. The solver only accepts systems with fully connected and validated topologies.

---

## 2. Core Modules

### 💧 Fluids (`entropyk-fluids`)
The thermodynamic property backbone.
- **CoolProp Backend**: Full Equation of State (EOS) for hundreds of fluids and mixtures.
- **Tabular Backend**: High-performance bicubic interpolation for real-time applications (HIL).
- **Caching Layer**: Intelligent LRU caching and SIMD-optimized lookups.

### 🧱 Components (`entropyk-components`)
Highly modular building blocks.
- **Compressor**: AHRI 540 10-coefficient and SST/SDT polynomial models.
- **Heat Exchangers**: ε-NTU and LMTD models with support for phase changes.
- **Advanced Topology**: `FlowSplitter`, `FlowMerger`, `FlowSource`, and `FlowSink`.
- **Customizable**: Implement the `Component` trait to add your own physics.

### 🔄 Solver (`entropyk-solver`)
The convergence engine.
- **Newton-Raphson**: Fast, quadratic convergence with line search and step clipping.
- **Picard (Sequential Substitution)**: Robust fallback for systems with high non-linearity.
- **Jacobian Freezing**: Performance optimization that skips expensive derivative calculations when appropriate.

---

## 3. Advanced Modeling

### Multi-Circuit Brilliance
Entropyk naturally supports systems with multiple independent circuits (e.g., a Chiller with a refrigerant loop and a water loop) through thermal coupling via Heat Exchangers.

### Inverse Control & Parameter Estimation
Go beyond "What happens if...?" to "What must I do to...?"
- **Bounded Control**: Set limits on control variables (e.g., valve opening 0.0-1.0).
- **Constraint Solver**: Target specific outputs (e.g., "Set speed to achieve 7°C water exit").
- **Inverse Calibration**: Estimate physical parameters (like UA or efficiency) from experimental data using the one-shot solver.

### Physical Validation
Every solution is automatically validated for:
- **Mass Balance**: Σ ṁ_in = Σ ṁ_out within 1e-9 kg/s.
- **Energy Balance**: (Planned) Conservation of enthalpy across joints.

---

## 4. Multi-Platform Ecosystem

### 🐍 Python
Mirroring the Rust API, our Python bindings offer the same speed and safety with the flexibility of data science tools (NumPy, Pandas, Jupyter).

### 🛠️ C / FFI
Integrate Entropyk into PLC controllers, HIL systems (dSPACE, Speedgoat), or legacy C++ codebases with our zero-allocation C header.

### 🌐 WebAssembly
The same Rust physics engine running in your browser for interactive design tools and client-side simulations.

---

## 5. Developer Ecosystem & Platform Specifics

### 🐍 Python: Integration & Data Science
- **Performance**: Rust-native speed with zero-copy data passing for large state vectors.
- **Exception Hierarchy**: Specific catchable exceptions like `SolverError`, `FluidError`, and `ValidationError`.
- **Interchange**: System states can be exported to NumPy arrays for analysis.

### 🛠️ C / FFI: HIL & Real-Time
- **Ownership**: Explicit `create`/`free` patterns. Adding a component to a `System` transfers ownership to Rust.
- **Real-Time Ready**: No dynamic allocations in the `solve` hot path when using the C FFI.
- **Header**: Single `entropyk.h` required for integration.

### 🌐 WebAssembly: Client-Side Physics
- **Initialization**: Must call `await init()` before use.
- **Fluid Tables**: Uses `TabularBackend`. Custom fluids loaded via `load_fluid_table(json_string)`.
- **JSON First**: Optimized for passing system definitions and results as JSON objects.

---

## 7. Getting Started
- **Basic Example**: See [EXAMPLES_FULL.md](./EXAMPLES_FULL.md) for a "Simple Cycle" walkthrough.
- **Performance Tuning**: Use `JacobianBuilder` for custom components to maximize sparse matrix efficiency.
- **API Reference**: `cargo doc --open` for the full technical API.