Pure Component Helmholtz EoS
============================
.. index::
pair: idaes.models.properties.general_helmholtz.helmholtz_state; HelmholtzStateBlock
.. module:: idaes.models.properties.general_helmholtz
The Helmholtz Equation of State (EoS) classes serve as a common core for pure
component property packages where accurate and thermodynamically consistent
pure component properties are required. New substances can be added by providing
parameter and expression files. The Helmholtz EoS functions use ExternalFunction,
so the IDAES binary extensions are required.
This page describes the standard HelmholtzParameterBlock and HelmholtzStateBlock. For
more information on accessing property expressions using a function-like interface,
or adding and modifying substance parameters see the following pages. There are also
two modules available for backward compatibility ``iapws95`` and ``swco2``, which are
the same as the general module, just with the pure component automatically set
to ``"h2o"`` or ``"co2"`` respectively.
.. toctree::
:maxdepth: 1
helmholtz_expressions
helmholtz_parameters
iapws95
swco2
Defined Components
------------------
If parameter and expression files are available for a component in the parameter file
directory, they will be registered automatically. IDAES comes with some defined components
and more can be added by users. Each component must have an equation of state model, while
transport models for viscosity, thermal conductivity and surface tension are optional.
Functions listed in this section allow you to discover what components and models are
available and get references for the models.
.. autofunction:: registered_components
.. autofunction:: viscosity_available
.. autofunction:: thermal_conductivity_available
.. autofunction:: surface_tension_available
.. autofunction:: component_registered
.. autofunction:: clear_component_registry
.. autofunction:: eos_reference
.. autofunction:: viscosity_reference
.. autofunction:: thermal_conductivity_reference
.. autofunction:: surface_tension_reference
Parameter File Location
-----------------------
You can get or set the parameter path with the functions described below. When
the parameter path is set components will automatically be registered based on the
available parameter files.
.. autofunction:: get_parameter_path
.. autofunction:: set_parameter_path
Classes
-------
The main class used to define a property method is the HelmholtzParameterBlock. Unit models
usually create their own state blocks, but it may be useful to create state block objects
apart from unit models.
.. autoclass:: HelmholtzParameterBlock
:members:
.. autoclass:: HelmholtzParameterBlockData
:members:
.. autoclass:: HelmholtzStateBlock
:members:
.. autoclass:: HelmholtzStateBlockData
:members:
.. autoclass:: StateVars
.. autoclass:: PhaseType
.. autoclass:: AmountBasis
Helper Function
---------------
Since conditions may be difficult to specify for some choices of state variables, for example,
fixing temperature and pressure of an inlet when the state variables are enthalpy and pressure,
helper methods are provided by the Parameter block class. See the ``htpx()``, ``stpx()``, or
``uptx()`` documentation in the parameter block class above.
Example
-------
The Heater unit model
:ref:`example `,
provides a simple example for using water properties.
.. testcode::
import pyomo.environ as pe # Pyomo environment
from idaes.core import FlowsheetBlock, MaterialBalanceType
from idaes.models.unit_models import Heater
from idaes.models.properties.general_helmholtz import (
HelmholtzParameterBlock,
PhaseType,
StateVars,
)
# Create an empty flowsheet and steam property parameter block.
model = pe.ConcreteModel()
model.fs = FlowsheetBlock(dynamic=False)
model.fs.properties = HelmholtzParameterBlock(
pure_component="h2o",
phase_presentation=PhaseType.LG,
state_vars=StateVars.PH
)
# Add a Heater model to the flowsheet.
model.fs.heater = Heater(
property_package=model.fs.properties,
material_balance_type=MaterialBalanceType.componentTotal
)
# Setup the heater model by fixing the inputs and heat duty
model.fs.heater.inlet[:].enth_mol.fix(4000)
model.fs.heater.inlet[:].flow_mol.fix(100)
model.fs.heater.inlet[:].pressure.fix(101325)
model.fs.heater.heat_duty[:].fix(100*20000)
# Initialize the model.
model.fs.heater.initialize()
Since all properties except the state variables are Pyomo Expressions in the
water properties module, after solving the problem any property can be
calculated in any state block. Continuing from the heater example, to get the
viscosity of both phases, the lines below could be added.
.. testcode::
mu_l = pe.value(model.fs.heater.control_volume.properties_out[0].visc_d_phase["Liq"])
mu_v = pe.value(model.fs.heater.control_volume.properties_out[0].visc_d_phase["Vap"])
For more information about how StateBlocks and PropertyParameterBlocks work see
the :ref:`StateBlock documentation `.
Units
-----
SI units are used for property variables and expressions (J, Pa, kg, mol, m, s, W).
Phase Presentation
------------------
The property package wrapper can present fluid phase information to the
IDAES framework in different ways. The ``PhaseType.MIX`` option causes
the modeling framework to view liquid and vapor as a single mixed liquid
and vapor phase. This generally reduces model complexity. Phase equilibrium
is still calculated and ``vapor_frac`` and individual phase properties are
available, just as they would be with the two-phase presentation. The
mixed-phase presentation can be used with most standard unit models that do
not provide phase separation. If phase separation is required, either use
the two-phase presentation or create a custom model.
.. warning::
The "has_phase_equilibrium" argument is ignored when constructing Helmholtz
property packages using mixed phase presentation. However, setting this to
`True` may cause errors in unit models as it is not possible to construct
phase equilibrium transfer terms with only one phase present.
The ``PhaseType.LG`` option appears to the IDAES framework to be two phases "Vap"
and "Liq". This option requires one of two unit model options to be set. You
can use the total material balance option for unit models, to specify that only
one material balance equation should be written not one per phase. The other
possible option is to specify ``has_phase_equlibrium=True``. This will
write a material balance per phase, but will add a phase generation term to the
model. For Helmholtz EoS packages, it is generally recommended that specifying
total material balances is best because it results in a problem with fewer
variables, and phase equilibrium is always calculated by the property package.
There are two single phase options ``PhaseType.L`` and ``PhaseType.G``; these
present a single phase "Liq" or "Vap" to the framework. The vapor fraction will
also always return 0 or 1 as appropriate. These options can be used when the phase
of a fluid is known for certain to only be liquid or only be vapor. For the
temperature-pressure-vapor fraction formulation, this eliminates the
complementarity constraint, but for the enthalpy-pressure formulation, where the
vapor fraction is always calculated, the single phase options probably do not
provide any real benefit over mixed phase.
State Variables
---------------
There is a choice of state variables, pressure-enthalpy, pressure-entropy,
pressure-internal energy and temperature-pressure-vapor fraction. In general
the enthalpy-pressure form is preferable. Both the pressure and enthalpy
variables are smooth and sufficient to define the fluid state. For systems
where two-phases may be present, it is expected that pressure-enthalpy is
the best choice of state variables.
The temperature-pressure-vapor fraction form is more convenient, since temperature
is directly measurable and more familiar than enthalpy. Complementarity
constraints are used to deal with the vapor fraction variable, but the additional
complimentary constraints may make the problem less robust. Temperature-pressure
is often a good choice of state variables where there is only a single known phase.
Pressure-Enthalpy, Entropy, or Internal Energy Formulation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The advantage of this choice of state variables is that it is more robust when
phase changes occur, and is especially useful when it is not known if a phase
change will occur. The disadvantage of this choice of state variables is that
for equations like heat transfer that are highly dependent on temperature, a
model could be harder to solve near regions with phase change. Temperature
is a non-smooth function with non-smoothness when transitioning from the
single-phase to the two-phase region. Temperature also has a zero derivative
with respect to enthalpy in the two-phase region, so near the two-phase region
solving a constraint that specifies a specific temperature may be difficult.
When a mass basis is used the variables in these forms are flow_mass (kg/s),
pressure (Pa), and one of ``enth_mass`` (J/kg), ``entr_mass`` (J/kg/K), or
``energy_ineternal_mass`` (J/kg).
When a mass basis is used the variables in these forms are flow_mol (mol/s),
pressure (Pa), and one of ``enth_mol`` (J/mol), ``entr_mol`` (J/mol/K), or
``energy_ineternal_mole`` (J/mol).
Since temperature and vapor fraction are not state variables in this formulation,
they are provided by expressions, and cannot be fixed. For example, to set a
temperature to a specific value, a constraint could be added which says the
temperature expression equals a fixed value.
Temperature-Pressure-Vapor Fraction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This formulation uses temperature (K), pressure (Pa), and vapor fraction as
state variables. When a single phase option is given, the vapor fraction does
not need to be specified and is instead an expression with the appropriate value.
A complementarity constraint is required for the T-P-x formulation when two-phases
may be present. First, two expressions are defined below where :math:`P^-` is
pressure under saturation pressure and :math:`P^+` is pressure over saturation
pressure. The :math:`\max()` function is provided as an IDAES utility which
provides a smooth max expression.
.. math::
P^- = \max(0, P_{\text{sat}} - P)
.. math::
P^+ = \max(0, P - P_{\text{sat}})
With the "pressure over" and "pressure under" expressions a complementarity
constraint can be written. If the pressure under saturation is more than zero,
only vapor exists. If the pressure over saturation is greater than zero only a
liquid exists. If both are about zero two phases can exist. The saturation
pressure function maxes out at the critical pressure and any temperature above
the critical temperature will yield a saturation pressure that is the critical
pressure, so supercritical fluids will be classified as liquids as is the
convention for this property package.
.. math::
0 = xP^+ - (1 - x)P^-
Assuming the vapor fraction (:math:`x`) is positive and noting that only one of
:math:`P^+` and :math:`P^-` can be nonzero (approximately), the complementarity
equation above requires :math:`x` to be 0 when :math:`P^+` is not zero (liquid)
or :math:`x` to be 1 when :math:`P^-`` is not zero (vapor). When both
:math:`P^+` and :math:`P^-`` are about 0, the complementarity constraint says
nothing about x, but it basically reduces another constraint, that
:math:`P=P_{\text{sat}}`. When two phases are present :math:`x` is found
by the unit model energy balance, where the temperature will be
:math:`T_{\text{sat}}` (because :math:`P=P_{\text{sat}}`).
An alternative approach is sometimes useful to simplify the problem when it is
certain that there are two phases. The complementarity constraint can be
deactivated and a :math:`P=P_{\text{sat}}` or :math:`T=T_{\text{sat}}` constraint
can be added.
Using the T-P-x formulation requires better initial guesses than the P-H form.
It is not strictly necessary but it is best to try to get an initial guess that
is in the correct phase region for the expected result.
Non-Existent Phases
~~~~~~~~~~~~~~~~~~~
This section describes the behavior of specific phase property calculations where that phase
does not exist.
Liquid phase properties calculated where a liquid does not exist will solve for the density root
smoothly extending from the saturation curve into the vapor region. Once the temperature
corresponding to the density root becomes higher than the critical temperature the vapor density
root is used.
Vapor phase properties calculated where a vapor does not exist will solve for the density root
smoothly extending from the saturation curve into the liquid region. Once the pressure
corresponding to the density root becomes higher than the critical pressure the liquid density
root is used.
This method for non-existing phase properties should provide a smooth buffer when solving
equations. It also returns properties for superheated liquids or sub-cooled vapor. It also
ensures that both the liquid and vapor phase properties are the same for the supercritical
region.
Variables
~~~~~~~~~
Variables are listed in the table below. What is a variable and what is an expression
depends on the selected state variables and amount basis. Pressure is always a variable.
========================================= ===============================================================================================
Variable Description
========================================= ===============================================================================================
``pressure`` Pressure (Pa)
``flow_mass`` Mass flow (kg/s), if ``amount_basis=AmountBasis.MASS``; otherwise, expression
``flow_mol`` Mole flow (mol/s) if ``amount_basis=AmountBasis.MOLE``; otherwise, expression
``temperature`` Temperature (K), is a variable in T-P-x formulation
``vapor_frac`` Vapor fraction (dimensionless), is a variable in T-P-x two phase formulation
``enth_mass`` Specific enthalpy (J/kg), is a variable in P-H formulation with mass basis
``enth_mol`` Molar enthalpy (J/mol), is a variable in P-H formulation with mole basis
``entr_mass`` Specific enthalpy (J/kg/K), is a variable in P-S formulation with mole basis
``entr_mol`` Molar enthalpy (J/mol/K), is a variable in P-S formulation with mole basis
``energy_internal_mass`` Specific internal energy (J/kg), is a variable in P-U formulation with mass basis
``energy_internal_mol`` Molar internal energy (J/mol), is a variable in P-U formulation with mole basis
========================================= ===============================================================================================
Expressions
~~~~~~~~~~~
Unless otherwise noted, the property expressions are common to both the
T-P-x and P-H formulations. For phase specific properties, valid phase indexes
are ``"Liq"`` and ``"Vap"``. Even when using the mixed phase version of the
property package, both liquid and vapor properties are available.
========================================= ===============================================================================================
Expression Description
========================================= ===============================================================================================
``flow_mass`` Mass flow (kg/s), variable if ``amount_basis=AmountBasis.MASS``
``flow_mol`` Mole flow (mol/s) variable if ``amount_basis=AmountBasis.MOLE``
``temperature`` Temperature (K), is a variable in T-P-x formulation
``vapor_frac`` Vapor fraction (dimensionless), is a variable in T-P-x two phase formulation
``enth_mass`` Specific enthalpy (J/kg), is a variable in P-H formulation with mass basis
``enth_mol`` Molar enthalpy (J/mol), is a variable in P-H formulation with mole basis
``entr_mass`` Specific enthalpy (J/kg/K), is a variable in P-S formulation with mole basis
``entr_mol`` Molar enthalpy (J/mol/K), is a variable in P-S formulation with mole basis
``energy_internal_mass`` Specific internal energy (J/kg), is a variable in P-U formulation with mass basis
``energy_internal_mol`` Molar internal energy (J/mol), is a variable in P-U formulation with mole basis
``mw`` Molecular weight (kg/mol)
``mole_frac_comp[comp]`` Mole fraction of component (dimensionless), since pure component, returns 1
``mole_frac_phase_comp[phase][comp]`` Mole fraction of component in phase (dimensionless), since pure component, returns 1
``temperature_crit`` Critical temperature (K)
``temperature_star`` Reducing temperature :math:`\tau=\frac{T^*}{T}` (K)
``pressure_crit`` Critical pressure (Pa)
``dens_mass_crit`` Critical mass density (kg/m\ :superscript:`3`)
``dens_mass_star`` Reducing mass density :math:`\delta=\frac{\rho}{\rho^*}` (kg/m\ :superscript:`3`)
``dens_mol_crit`` Critical mole density (mol/m\ :superscript:`3`)
``dens_mol_star`` Reducing mole density :math:`\delta=\frac{\rho}{\rho^*}` (kg/m\ :superscript:`3`)
``temperature_sat`` Saturation temperature (K), if supercritical, Tsat=Tcrit
``pressure_sat`` Saturation pressure (Pa), if supercritical, Psat=Pcrit
``enth_mass_sat_phase[phase]`` Saturation specific enthalpy of phase (J/kg)
``enth_mol_sat_phase[phase]`` Saturation molar enthalpy of phase (J/mol)
``entr_mass_sat_phase[phase]`` Saturation specific entropy of phase (J/kg/K)
``entr_mol_sat_phase[phase]`` Saturation molar entropy of phase (J/mol/K)
``energy_internal_mass_sat_phase[phase]`` Saturation specific internal energy of phase (J/kg)
``energy_internal_mol_sat_phase[phase]`` Saturation molar internal energy of phase (J/mol)
``volume_mass_sat_phase[phase]`` Saturation specific volume of phase (m\ :superscript:`3`/kg)
``volume_mol_sat_phase[phase]`` Saturation molar volume of phase (m\ :superscript:`3`/mol)
``dh_vap_mass`` Specific enthalpy of vaporization at P (J/kg)
``dh_vap_mol`` Molar enthalpy of vaporization at P (J/mol)
``ds_vap_mass`` Specific entropy of vaporization at P (J/kg/K)
``ds_vap_mol`` Molar entropy of vaporization at P (J/mol/K)
``du_vap_mass`` Specific internal energy of vaporization at P (J/kg)
``du_vap_mol`` Molar internal energy of vaporization at P (J/mol)
``phase_frac[phase]`` Phase fraction (dimensionless) mole and mass fraction same for pure
``enthalpy_mass_phase[phase]`` Specific enthalpy of phase (J/kg)
``enthalpy_mol_phase[phase]`` Molar enthalpy of phase (J/mol)
``entropy_mass_phase[phase]`` Specific entropy of phase (J/kg/K)
``entropy_mol_phase[phase]`` Molar entropy of phase (J/mol/K)
``energy_internal_mass_phase[phase]`` Specific internal energy of phase (J/kg)
``energy_internal_mol_phase[phase]`` Molar internal energy of phase (J/mol)
``cp_mass_phase[phase]`` Specific isobaric heat capacity for phase (J/kg)
``cp_mol_phase[phase]`` Molar isobaric heat capacity for phase (J/mol)
``cv_mass_phase[phase]`` Specific isochoric heat capacity for phase (J/kg)
``cv_mol_phase[phase]`` Molar isochoric heat capacity for phase (J/mol)
``speed_sound_phase[phase]`` Speed of sound in phase (m/s)
``vol_mass_phase[phase]`` Specific volume of phase (m\ :superscript:`3`/kg)
``vol_mol_phase[phase]`` Molar volume of phase (m\ :superscript:`3`/mol)
``dens_mass_phase[phase]`` Mass density of phase (kg/m\ :superscript:`3`)
``dens_mol_phase[phase]`` Mole density of phase (mol/m\ :superscript:`3`)
``flow_mass_comp[comp]`` Same as total mass flow since pure (kg/s)
``flow_mol_comp[comp]`` Same as total mole flow since pure (mol/s)
``cp_mass`` Specific isobaric heat capacity for mixed phase (J/kg)
``cp_mol`` Molar isobaric heat capacity for mixed phase (J/mol)
``cv_mass`` Specific isochoric heat capacity for mixed phase (J/kg)
``cv_mol`` Molar isochoric heat capacity for mixed phase (J/mol)
``dens_mass`` Mass density of mixed phase (kg/m\ :superscript:`3`)
``dens_mol`` Mole density of mixed phase (mol/m\ :superscript:`3`)
``flow_vol`` Total mixed phase volumetric flow (m\ :superscript:`3`/s)
``heat_capacity_ratio`` Mixed phase cp/cv (dimensionless)
``visc_d_phase[phase]`` Dynamic viscosity (Pa*s), depending on substance, may not be available
``visc_k_phase[phase]`` Kinematic viscosity (m\ :superscript:`2`/s), depending on substance, may not be available
``therm_cond_phase[phase]`` Thermal conductivity of phase (W/m/s), depending on substance, may not be available
``surface_tension`` Surface tension (N/m), depending on substance, may not be available
``P_under_sat`` Pressure under saturation pressure (Pa)
``P_over_sat`` Pressure over saturation pressure (Pa)
========================================= ===============================================================================================
Initialization
--------------
The Helmholtz EoS state blocks provide initialization functions for general
compatibility with the IDAES framework, but as long as the state variables are
specified to some reasonable value, initialization is not required. All required
solves are handled by external functions.
However, in order to support a general hierarchical initialization for unit models
which use Helmholtz equation of state properties, a custom ``Initializer`` for these
property packages is available.
.. module:: idaes.models.properties.general_helmholtz.helmholtz_state
.. autoclass:: HelmholtzEoSInitializer
:members: initialize