138 lines
5.4 KiB
Markdown
138 lines
5.4 KiB
Markdown
# Entropyk Tutorial
|
|
|
|
Welcome to the Entropyk tutorial! This guide covers the thermodynamic simulation library.
|
|
|
|
## Current Status
|
|
|
|
**Important**: The library is under active development. Key points:
|
|
|
|
- ✅ **Rust API**: Full component library with real thermodynamic equations
|
|
- ✅ **System topology**: Graph-based component connection works
|
|
- ✅ **Solver infrastructure**: Newton, Picard, and Fallback solvers implemented
|
|
- ⚠️ **Python bindings**: Use placeholder adapters (no real physics equations)
|
|
- ⚠️ **Convergence**: Requires proper initialization and boundary conditions
|
|
|
|
## Table of Contents
|
|
|
|
1. **[Getting Started](./01-getting-started.md)** - Installation, first simulation, basic concepts
|
|
2. **[Physical Types](./02-physical-types.md)** - Type-safe units (Pressure, Temperature, Enthalpy, MassFlow)
|
|
3. **[Components Reference](./03-components.md)** - All available components with examples
|
|
4. **[Building Systems](./04-building-systems.md)** - Creating system topology, connecting components
|
|
5. **[Solver Configuration](./05-solver-configuration.md)** - Newton, Picard, Fallback strategies
|
|
|
|
## Additional Resources
|
|
|
|
- **[Main Documentation](../README.md)** - Project overview and API reference
|
|
- **[Python Bindings](../../bindings/python/README.md)** - Python API documentation
|
|
- **[Examples](../../bindings/python/examples/)** - Example scripts
|
|
|
|
## Quick Start
|
|
|
|
### Rust
|
|
|
|
```rust
|
|
use entropyk_solver::System;
|
|
use entropyk_components::{Component, ComponentError, ConnectedPort,
|
|
JacobianBuilder, ResidualVector, SystemState};
|
|
|
|
// Create a simple component
|
|
struct MyComponent { n_eq: usize }
|
|
|
|
impl Component for MyComponent {
|
|
fn compute_residuals(&self, _state: &SystemState, residuals: &mut ResidualVector)
|
|
-> Result<(), ComponentError> {
|
|
for r in residuals.iter_mut().take(self.n_eq) { *r = 0.0; }
|
|
Ok(())
|
|
}
|
|
fn jacobian_entries(&self, _state: &SystemState, jacobian: &mut JacobianBuilder)
|
|
-> Result<(), ComponentError> {
|
|
for i in 0..self.n_eq { jacobian.add_entry(i, i, 1.0); }
|
|
Ok(())
|
|
}
|
|
fn n_equations(&self) -> usize { self.n_eq }
|
|
fn get_ports(&self) -> &[ConnectedPort] { &[] }
|
|
}
|
|
|
|
fn main() {
|
|
let mut system = System::new();
|
|
let n1 = system.add_component(Box::new(MyComponent { n_eq: 2 }));
|
|
let n2 = system.add_component(Box::new(MyComponent { n_eq: 2 }));
|
|
system.add_edge(n1, n2).unwrap();
|
|
system.finalize().unwrap();
|
|
println!("State vector length: {}", system.state_vector_len());
|
|
}
|
|
```
|
|
|
|
### Python
|
|
|
|
```python
|
|
import entropyk
|
|
|
|
# Note: Python bindings use placeholder adapters
|
|
# The solver won't converge because there are no real physics equations
|
|
|
|
system = entropyk.System()
|
|
comp = entropyk.Compressor(speed_rpm=2900.0, displacement=0.0001,
|
|
efficiency=0.85, fluid="R134a")
|
|
cond = entropyk.Condenser(ua=5000.0)
|
|
valve = entropyk.ExpansionValve(fluid="R134a", opening=0.8)
|
|
evap = entropyk.Evaporator(ua=3000.0)
|
|
|
|
c = system.add_component(comp)
|
|
d = system.add_component(cond)
|
|
v = system.add_component(valve)
|
|
e = system.add_component(evap)
|
|
|
|
system.add_edge(c, d)
|
|
system.add_edge(d, v)
|
|
system.add_edge(v, e)
|
|
system.add_edge(e, c)
|
|
|
|
system.finalize()
|
|
print(f"State vector length: {system.state_vector_len}")
|
|
```
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ System (Graph) │
|
|
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
|
│ │Compress.├────►│Condenser├────►│ Valve ├────►│Evaporat.│ │
|
|
│ └────▲────┘ └─────────┘ └─────────┘ └────┬────┘ │
|
|
│ │ │ │
|
|
│ └───────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ Each edge carries: P (pressure), h (enthalpy) │
|
|
│ Each node has: n_equations(), compute_residuals() │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Thermodynamic Conventions
|
|
|
|
### Refrigerant Circuits
|
|
- **Flow direction**: Compressor → Condenser → Expansion Valve → Evaporator → Compressor
|
|
- **Pressure levels**: High pressure (condensing) → Low pressure (evaporating)
|
|
- **State points**: Superheated vapor at compressor inlet, subcooled liquid at expansion valve inlet
|
|
|
|
### Heat Exchangers (4 Ports)
|
|
```
|
|
Hot Side: Inlet ──►│ HX │──► Outlet
|
|
Cold Side: Inlet ──►│ │──► Outlet
|
|
```
|
|
|
|
- **Evaporator**: Refrigerant (cold) evaporates, water/air (hot) provides heat
|
|
- **Condenser**: Refrigerant (hot) condenses, water/air (cold) absorbs heat
|
|
|
|
## Running the Demo
|
|
|
|
```bash
|
|
cargo run --bin macro-chiller
|
|
```
|
|
|
|
Shows hierarchical system composition with MacroComponent pattern.
|
|
|
|
## Next Steps
|
|
|
|
Start with [Getting Started](./01-getting-started.md) to set up your environment.
|