.. Thermofluids documentation master file, created by
   sphinx-quickstart on Thu Oct  8 13:47:07 2026.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

***************
Getting Started
***************

Thermofluids makes modeling thermofluid systems easier. The essential element is the ``statepoint``. ``statepoint``
objects work like physical statepoints: they have two independent variables, many dependent variables, and sometimes
extensive variables. You can use them like this::

   sp = Statepoint(fluid='water',  # define a fluid
                   t=25.0,         # define one independent variable
                   p=1.0,          # define a second independent variable
                   m=0.1)          # define extensive variable

   print(sp.rho, sp.h, sp.visc)


   >>> (<Quantity(997.047039, 'kilogram / meter ** 3')>, <Quantity(104.918893, 'kilojoule / kilogram')>, <Quantity(0.000890022674, 'kilogram / meter / second')>)

Representing statepoints this way makes it easy to model thermodynamic cycles. The module includes some common
thermodynamic unit processes to manipulate statepoints in physically meaningful ways. For example, we can model a
refrigeration cycle::

   from thermofluids import Statepoint, Quantity
   from thermofluids.ProcessEquipment import Compressor


   # Select a refrigerant
   REFR = 'R134A'

   # Find the saturation pressures of the refrigerant
   ssp = Statepoint(fluid=REFR, t=-10, x=1.).p
   scp = Statepoint(fluid=REFR, t=25., x=1.).p

   # Define a statepoint representing the state between the evaporator and compressor
   evap_to_comp = Statepoint(fluid=REFR, t=-5., p=ssp, m=0.1)

   # Use the built in compressor object to calculate the statepoint at the compressor outlet
   comp = Compressor(inlet=evap_to_comp,
                     eta=0.7,
                     Pout=scp)
   comp_to_cond = comp.get_outlet()
   print(f'Compressor work: {comp.work.to("kW")}')

   # Derive the statepoint representing the condensed state between the condenser and expansion valve
   cond_to_exp = Statepoint(fluid=REFR, t=20., p=scp, m=evap_to_comp.m)
   q_cond = cond_to_exp.m * (comp_to_cond.h - cond_to_exp.h)
   print(f'Condenser heat: {q_cond.to("kW")}')

   # Derive the statepoint representing the isenthalpically expanded refrigerant
   exp_to_evap = Statepoint(fluid=REFR, p=ssp, h=cond_to_exp.h, m=cond_to_exp.m)
   q_evap = evap_to_comp.m * (evap_to_comp.h - exp_to_evap.h)
   print(f'Evaporator heat: {q_evap.to("kW")}')
   cop = q_evap / comp.work
   print(f'Coefficient of performance: {cop.to("")}')


   >>> Compressor work: 3.637 kW
   >>> Condenser heat: 20.58 kW
   >>> Evaporator heat: 16.95 kW
   >>> Coefficient of performance: 4.659

Installation
____________
Thermofluids is installable using standard python tools such as ``pip install python``. See https://pypi.org/project/thermofluids/

Acknowledgement of CoolProp and Pint
____________________________________
Statepoints are, at a basic level, a nice looking wrapper around `CoolProp <https://pypi.org/project/thermofluids/>`__
property lookups and `Pint <https://pint.readthedocs.io/en/stable/>`__ Quantity for unit management. We're grateful to those projects!

*********
Code Docs
*********

.. toctree::
   :maxdepth: 2
   :caption: Contents:

Essential Functionality
_______________________
.. autoclass:: thermofluids.Base.Statepoint.Statepoint
   :members: __add__, __div__
.. autoclass:: ...src.Base.Quantity

Fluids
______
The Fluids submodule supplies functions to perform common fluids calculations including non-dimensional characterization
and pressure drops in various situations.

.. automodule:: thermofluids.Fluids.Drag
   :members: f_drag, settling_vel
.. automodule:: thermofluids.Fluids.Moody
   :members: frictionfactor
.. automodule:: thermofluids.Fluids.Re
   :members: Re, Re_ext
.. automodule:: thermofluids.Fluids.PressureDrop
   :members: pressure_drop, pressure_drop_fitting, pressure_drop_packed_bed, pressure_drop_corrugated_plates, flow_at_dp

Heat Transfer
_____________
The Heat Transfer module supplies functions to perform common heat transfer calculations including non-dimensional
characterization, effective temperature differences, two-phase flow regime prediction, and heat transfer coefficients.

.. automodule:: thermofluids.HeatTransfer.lmtd
   :members: lmtd
.. automodule:: thermofluids.HeatTransfer.Nusselt
   :members: Nu, Nu_natural
.. automodule:: thermofluids.HeatTransfer.Ra
   :members: Ra
.. automodule:: thermofluids.HeatTransfer.Gr
   :members: Gr
.. automodule:: thermofluids.HeatTransfer.NTU
   :members: NTU
.. automodule:: thermofluids.HeatTransfer.TwoPhase
   :members: Co, Bo, Fr_le, crit_heat_flux, heat_flux_nucleate_boiling, htc_conv_boil

Special Properties
__________________
Special properties are a handful of properties we've needed over time that aren't available in CoolProp.

.. automodule:: thermofluids.Properties
.. automodule:: thermofluids.Properties.BrineProps
   :members: get_c_freeze, get_T_liq_sat, get_T_vap_sat, get_P_liq_sat, get_P_vap_sat, get_h_mix, get_C_vap_sat, get_C_liq_sat

Process Equipment
_________________
The Process Equipment supplies classes and functions that represent unit functions that take and produce thermodynamic
statepoints. The performance/outputs are mostly theoretically derived as opposed to empirically derived from specific
implementations of these types of process equipment.

.. automodule:: thermofluids.ProcessEquipment
.. automodule:: thermofluids.ProcessEquipment.Column
   :members: Column
.. automodule:: thermofluids.ProcessEquipment.Compressor
   :members: Compressor
.. automodule:: thermofluids.ProcessEquipment.HeatExchanger
   :members: HX_Energy
.. automodule:: thermofluids.ProcessEquipment.IsoCompressor
   :members: IsoCompressor
.. automodule:: thermofluids.ProcessEquipment.Pump
   :members: Pump
.. automodule:: thermofluids.ProcessEquipment.Turbine
   :members: Turbine
.. automodule:: thermofluids.ProcessEquipment.Valve
   :members: get_valve_flow_rate, get_valve_dP, get_valve_C_v
