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

Getting Started - Installation, first simulation, basic concepts
Physical Types - Type-safe units (Pressure, Temperature, Enthalpy, MassFlow)
Components Reference - All available components with examples
Building Systems - Creating system topology, connecting components
Solver Configuration - Newton, Picard, Fallback strategies

Additional Resources

Main Documentation - Project overview and API reference
Python Bindings - Python API documentation
Examples - Example scripts

Quick Start

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

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

cargo run --bin macro-chiller

Shows hierarchical system composition with MacroComponent pattern.

Next Steps

Start with Getting Started to set up your environment.

5.4 KiB Raw Permalink Blame History