feat(python): implement python bindings for all components and solvers

crates/entropyk/src/lib.rs

@@ -0,0 +1,172 @@
+//! # Entropyk
+//!
+//! A thermodynamic cycle simulation library with type-safe APIs and idiomatic Rust design.
+//!
+//! Entropyk provides a complete toolkit for simulating refrigeration cycles, heat pumps,
+//! and other thermodynamic systems. Built with a focus on type safety, performance, and
+//! developer ergonomics.
+//!
+//! ## Features
+//!
+//! - **Type-safe physical quantities**: Never mix up units with NewType wrappers
+//! - **Component-based modeling**: Build complex systems from reusable blocks
+//! - **Multiple solver strategies**: Newton-Raphson with automatic fallback
+//! - **Multi-fluid support**: CoolProp, tabular interpolation, incompressible fluids
+//! - **Zero-panic policy**: All errors return `Result<T, E>`
+//!
+//! ## Quick Start
+//!
+//! The [`SystemBuilder`] provides an ergonomic way to construct thermodynamic systems:
+//!
+//! ```
+//! use entropyk::SystemBuilder;
+//!
+//! let builder = SystemBuilder::new();
+//! assert_eq!(builder.component_count(), 0);
+//! ```
+//!
+//! For a complete refrigeration cycle example with real components:
+//!
+//! ```ignore
+//! use entropyk::{
+//!     System, Solver, NewtonConfig,
+//!     Compressor, Condenser, Evaporator, ExpansionValve,
+//!     Pressure, Temperature,
+//! };
+//!
+//! // Build a simple refrigeration cycle
+//! let mut system = System::new();
+//!
+//! // Add components
+//! let comp = system.add_component(Box::new(Compressor::new(coeffs)));
+//! let cond = system.add_component(Box::new(Condenser::new(ua)));
+//! let evap = system.add_component(Box::new(Evaporator::new(ua)));
+//! let valve = system.add_component(Box::new(ExpansionValve::new()));
+//!
+//! // Connect components
+//! system.add_edge(comp, cond)?;
+//! system.add_edge(cond, valve)?;
+//! system.add_edge(valve, evap)?;
+//! system.add_edge(evap, comp)?;
+//!
+//! // Finalize and solve
+//! system.finalize()?;
+//!
+//! let solver = NewtonConfig::default();
+//! let result = solver.solve(&system)?;
+//! ```
+//!
+//! ## Architecture
+//!
+//! The library re-exports types from these source crates:
+//!
+//! - **Core types**: [`Pressure`], [`Temperature`], [`Enthalpy`], [`MassFlow`], [`Power`]
+//! - **Components**: [`Component`], [`Compressor`], [`Condenser`], [`Evaporator`], etc.
+//! - **Fluids**: [`FluidBackend`], [`CoolPropBackend`], [`TabularBackend`]
+//! - **Solver**: [`System`], [`Solver`], [`NewtonConfig`], [`PicardConfig`]
+//!
+//! ## Error Handling
+//!
+//! All operations return `Result<T, ThermoError>` with comprehensive error types.
+//! The library follows a zero-panic policy - no operation should ever panic.
+//!
+//! ## Documentation
+//!
+//! Mathematical formulas in the documentation use LaTeX notation:
+//!
+//! $$ W = \dot{m} \cdot (h_{out} - h_{in}) $$
+//!
+//! where $W$ is work, $\dot{m}$ is mass flow rate, and $h$ is specific enthalpy.
+
+#![deny(unsafe_code)]
+#![warn(missing_docs)]
+#![warn(rust_2018_idioms)]
+
+// =============================================================================
+// Core Types Re-exports
+// =============================================================================
+
+pub use entropyk_core::{
+    Calib, CalibIndices, CalibValidationError, Enthalpy, MassFlow, Power, Pressure, Temperature,
+    ThermalConductance, MIN_MASS_FLOW_REGULARIZATION_KG_S,
+};
+
+// =============================================================================
+// Components Re-exports
+// =============================================================================
+
+pub use entropyk_components::{
+    friction_factor, roughness, AffinityLaws, Ahri540Coefficients, CircuitId, Component,
+    ComponentError, CompressibleMerger, CompressibleSink, CompressibleSource, CompressibleSplitter,
+    Compressor, CompressorModel, Condenser, CondenserCoil, ConnectedPort, ConnectionError,
+    Economizer, EpsNtuModel, Evaporator, EvaporatorCoil, ExchangerType, ExpansionValve,
+    ExternalModel, ExternalModelConfig, ExternalModelError, ExternalModelMetadata,
+    ExternalModelType, Fan, FanCurves, FlowConfiguration, FlowMerger, FlowSink, FlowSource,
+    FlowSplitter, FluidKind, HeatExchanger, HeatExchangerBuilder, HeatTransferModel,
+    HxSideConditions, IncompressibleMerger, IncompressibleSink, IncompressibleSource,
+    IncompressibleSplitter, JacobianBuilder, LmtdModel, MockExternalModel, OperationalState,
+    PerformanceCurves, PhaseRegion, Pipe, PipeGeometry, Polynomial1D, Polynomial2D, Pump,
+    PumpCurves, ResidualVector, SstSdtCoefficients, StateHistory, StateManageable,
+    StateTransitionError, SystemState, ThreadSafeExternalModel,
+};
+
+pub use entropyk_components::port::{Connected, Disconnected, FluidId as ComponentFluidId, Port};
+
+// =============================================================================
+// Fluids Re-exports
+// =============================================================================
+
+pub use entropyk_fluids::{
+    CachedBackend, CoolPropBackend, CriticalPoint, DampedBackend, DampingParams, DampingState,
+    Entropy, FluidBackend, FluidError, FluidId, FluidResult, FluidState, IncompFluid,
+    IncompressibleBackend, Mixture, MixtureError, Phase, Property, Quality, TabularBackend,
+    TestBackend, ThermoState, ValidRange,
+};
+
+// =============================================================================
+// Solver Re-exports
+// =============================================================================
+
+pub use entropyk_solver::{
+    antoine_pressure, compute_coupling_heat, coupling_groups, has_circular_dependencies,
+    AddEdgeError, AntoineCoefficients, CircuitConvergence, CircuitId as SolverCircuitId,
+    ComponentOutput, Constraint, ConstraintError, ConstraintId, ConvergedState,
+    ConvergenceCriteria, ConvergenceReport, ConvergenceStatus, FallbackConfig, FallbackSolver,
+    FlowEdge, InitializerConfig, InitializerError, JacobianFreezingConfig, JacobianMatrix,
+    MacroComponent, MacroComponentSnapshot, NewtonConfig, PicardConfig, PortMapping,
+    SmartInitializer, Solver, SolverError, SolverStrategy, System, ThermalCoupling, TimeoutConfig,
+    TopologyError,
+};
+
+// =============================================================================
+// Error Types (must come before builder)
+// =============================================================================
+
+mod error;
+pub use error::{ThermoError, ThermoResult};
+
+// =============================================================================
+// Builder Pattern
+// =============================================================================
+
+mod builder;
+pub use builder::{SystemBuilder, SystemBuilderError};
+
+// =============================================================================
+// Prelude
+// =============================================================================
+
+/// Common imports for Entropyk users.
+///
+/// This module re-exports the most commonly used types and traits
+/// for convenience. Import it with:
+///
+/// ```
+/// use entropyk::prelude::*;
+/// ```
+pub mod prelude {
+    pub use crate::ThermoError;
+    pub use entropyk_components::Component;
+    pub use entropyk_core::{Enthalpy, MassFlow, Power, Pressure, Temperature};
+    pub use entropyk_solver::{NewtonConfig, Solver, System};
+}