Entropyk/crates/entropyk/src/lib.rs

//! # 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::{
    id_ends_with_calib_suffix, normalize_factor_name, Calib, CalibIndices, CalibValidationError,
    Concentration, Enthalpy, MassFlow, Power, Pressure, RelativeHumidity, Temperature,
    ThermalConductance, VaporQuality, VolumeFlow, MIN_MASS_FLOW_REGULARIZATION_KG_S, Z_DP, Z_ETAV,
    Z_FLOW, Z_POWER, Z_UA,
};

// =============================================================================
// Components Re-exports
// =============================================================================

pub use entropyk_components::{
    create_component, friction_factor, roughness, AffinityLaws, Ahri540Coefficients,
    AirCooledCondenser, AirSink, AirSource, Anchor, AnchorConstraint, BoundedCurve, BrineSink,
    BrineSource, BypassValve, BypassValveConfig, CapillaryGeometry, CapillaryTube,
    CentrifugalCompressor, CentrifugalMap, CentrifugalMapPoint, CircuitId, CoilGeometry, Component,
    ComponentError, CompressibleMerger, CompressibleSplitter, Compressor, CompressorModel,
    Condenser, CondenserCoil, CondenserRating, ConnectedPort, ConnectionError, CurveEngine,
    CurveEval, CurveResult, CurveSet, CurveWarning, Drum, Economizer, EpsNtuModel, Evaporator,
    EvaporatorCoil, EvaporatorRating, ExchangerType, ExpansionValve, ExternalModel,
    ExternalModelConfig, ExternalModelError, ExternalModelMetadata, ExternalModelType, Fan,
    FanCoilUnit, FanCurves, FinCoilCondenser, FinType, FloodedEvaporator, FloodedPoolBoilingConfig,
    FlowConfiguration, FlowMerger, FlowSplitter, FluidKind, FreeCoolingConfig,
    FreeCoolingControlMode, FreeCoolingExchanger, FreeCoolingMode, GasCooler, HeatExchanger,
    HeatExchangerBuilder, HeatSource, HeatTransferModel, HxSideConditions, IncompressibleMerger,
    IncompressibleSplitter, IsenthalpicExpansionValve, IsentropicCompressor, JacobianBuilder,
    LmtdModel, MchxCondenserCoil, MockExternalModel, Node, NodeMeasurements, NodePhase,
    OperationalState, PerformanceCurves, PhaseRegion, Pipe, PipeGeometry, Polynomial1D,
    Polynomial2D, Pump, PumpCurves, RefrigerantSink, RefrigerantSource, RegistryError,
    ResidualVector, ScrewEconomizerCompressor, ScrewPerformanceCurves, ShellAndTubeHx,
    SstSdtCoefficients, StateHistory, StateManageable, StateTransitionError, SystemState,
    ThermalLoad, ThreadSafeExternalModel, UaMode, ValveCharacteristics, ValveFlowModel,
};
pub use entropyk_components::{ReversingMode, ReversingValve};

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::inverse::{
    BoundedVariable, BoundedVariableError, BoundedVariableId, DoFError,
};
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, CyclePerformance, FallbackConfig,
    FallbackSolver, FlowEdge, HomotopyConfig, 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};

// =============================================================================
// Structured Results
// =============================================================================

mod result;
pub use result::{
    extract_simulation_result, ComponentResult, ConvergenceSummary, EdgeResult, EnergyResult,
    PortState, SimulationOutcome, SimulationResult, SystemSummary,
};

// =============================================================================
// Standardized ratings (IPLV / ESEER / SCOP)
// =============================================================================

pub mod rating;
pub use rating::{
    BinClimateStandard, BinPerformance, PartLoadEfficiencies, PartLoadStandard, RatingCondition,
    RatingError, TemperatureBin,
};

// =============================================================================
// 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::result::SimulationResult;
    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};
}