Entropyk/DOCUMENTATION.md

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 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.