56df96ed9e
- Created DOCUMENTATION.md covering core philosophy, modules, and platform specifics. - Created EXAMPLES_FULL.md with complex multi-platform usage scenarios. - Updated README.md and docs/index.md to centralize documentation links.
98 lines
4.6 KiB
Markdown
98 lines
4.6 KiB
Markdown
# 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.
|