diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md new file mode 100644 index 0000000..b24680e --- /dev/null +++ b/DOCUMENTATION.md @@ -0,0 +1,97 @@ +# 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. diff --git a/EXAMPLES_FULL.md b/EXAMPLES_FULL.md new file mode 100644 index 0000000..c1993f7 --- /dev/null +++ b/EXAMPLES_FULL.md @@ -0,0 +1,106 @@ +# Entropyk: Comprehensive Examples + +This document provides deep-dive examples for various Entropyk features across different platforms. + +## 1. Simple Refrigeration Cycle (Rust) +The "Hello World" of thermodynamics. + +```rust +use entropyk_components::compressor::{Compressor, Ahri540Coefficients}; +use entropyk_components::heat_exchanger::{Condenser, Evaporator}; +use entropyk_components::expansion_valve::ExpansionValve; +use entropyk_solver::{System, FallbackConfig}; + +fn main() -> Result<(), Box> { + let mut system = System::new(); + + // 1. Create Components + let comp = Compressor::new(Ahri540Coefficients::typical(), ...)?; + let cond = Condenser::new(5000.0); + let valve = ExpansionValve::new(...)?; + let evap = Evaporator::new(3000.0); + + // 2. Add to System & Connect + let n1 = system.add_component(Box::new(comp)); + let n2 = system.add_component(Box::new(cond)); + let n3 = system.add_component(Box::new(valve)); + let n4 = system.add_component(Box::new(evap)); + + system.add_edge(n1, n2)?; // Comp -> Cond + system.add_edge(n2, n3)?; // Cond -> Valve + system.add_edge(n3, n4)?; // Valve -> Evap + system.add_edge(n4, n1)?; // Evap -> Comp + + // 3. Finalize & Solve + system.finalize()?; + let config = FallbackConfig::default(); + let result = config.solve(&system)?; + + println!("Cycle COP: {}", result.cop()); + Ok(()) +} +``` + +## 2. Parameter Estimation in Python +Estimating fouling (UA reduction) from sensor data. + +```python +import entropyk as ek + +# Setup system with experimental targets +system = ek.System() +comp = system.add_component(ek.Compressor(...)) +cond = system.add_component(ek.Condenser(ua=5000.0)) # Initial guess + +# Add Inverse Control target: Discharge temperature must match sensor +system.add_constraint(target_node=cond, target_value=325.15, ... ) + +# Solve for the UA that makes the physics match the sensor +solver = ek.NewtonConfig(inverse_mode=True) +result = solver.solve(system) + +print(f"Calculated UA: {result.component_params[cond].ua} W/K") +``` + +## 3. Custom Component Implementation +How to add a new physical model. + +```rust +use entropyk_components::{Component, SystemState, ResidualVector, JacobianBuilder, ConnectedPort}; + +struct BypassValve { + opening: f64, +} + +impl Component for BypassValve { + fn compute_residuals(&self, state: &SystemState, residuals: &mut ResidualVector) -> Result<(), ComponentError> { + // P_out = P_in - (k * opening^2 * flow^2) + residuals[0] = state[1] - (state[0] - self.calc_dp(state)); + Ok(()) + } + + fn jacobian_entries(&self, state: &SystemState, jacobian: &mut JacobianBuilder) -> Result<(), ComponentError> { + // Provide partial derivatives for fast convergence + jacobian.add_entry(0, 0, self.dp_dm(state)); + jacobian.add_entry(0, 1, 1.0); + Ok(()) + } + + fn n_equations(&self) -> usize { 1 } + fn get_ports(&self) -> &[ConnectedPort] { &self.ports } +} +``` + +## 4. Multi-Circuit Coupling +Bridging a Chiller to a Water loop. + +```rust +// Evaporator acts as a bridge +let evaporator = HeatExchanger::new_bridge(ua); + +system.add_edge(refrigerant_valve, evaporator.side_a_in)?; +system.add_edge(evaporator.side_a_out, refrigerant_comp)?; + +system.add_edge(water_pump, evaporator.side_b_in)?; +system.add_edge(evaporator.side_b_out, water_building)?; +``` diff --git a/README.md b/README.md index 3ae14d9..4584ea4 100644 --- a/README.md +++ b/README.md @@ -37,10 +37,9 @@ Then visit [http://localhost:3030](http://localhost:3030) in your browser. - `ui/`: Web-based interface for visual modeling. - `docs/`: Technical documentation and tutorials. -## Documentation - +- **[Comprehensive Documentation](./DOCUMENTATION.md)**: The definitive guide to Entropyk features and architecture. +- **[Exhaustive Examples](./EXAMPLES_FULL.md)**: Deep-dive code samples for all platforms (Rust, Python, C). - **[Tutorial](./docs/TUTORIAL.md)**: Step-by-step guide to using the library and UI. -- **[Examples](./EXAMPLES.md)**: Detailed code snippets for each component. - **[Full Index](./docs/index.md)**: Directory of all project documentation. ## License diff --git a/docs/index.md b/docs/index.md index b0c04e0..e3edacd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,9 +2,11 @@ ## General Documentation +- **[DOCUMENTATION.md](../DOCUMENTATION.md)** - The definitive guide to Entropyk. +- **[EXAMPLES_FULL.md](../EXAMPLES_FULL.md)** - Deep-dive usage examples for all platforms. - **[README.md](../README.md)** - Main project overview and getting started guide. - **[TUTORIAL.md](./TUTORIAL.md)** - Step-by-step guide to using Entropyk (CLI & UI). -- **[EXAMPLES.md](../EXAMPLES.md)** - Comprehensive usage examples for all library components. +- **[EXAMPLES.md](../EXAMPLES.md)** - Component-level usage snippets (Legacy). - **[README_STORY_1_3.md](../README_STORY_1_3.md)** - Technical details of Port and Connection system implementation. ## Project Subdirectories