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