chore: sync project state and current artifacts

docs/tutorial/README.md

@@ -0,0 +1,137 @@
+# 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.