Fix open WaterPropsIAPWS issues / add WaterSSTP as alternative Water backend

data/liquidvapor.yaml

@@ -25,6 +25,18 @@ phases:
     T: 300.0
     P: 1.01325e+05
   pure-fluid-name: water
+- name: liquid-water-IAPWS95
+  elements: [O, H]
+  species: [H2O]
+  thermo: liquid-water-IAPWS95
+  state:
+    T: 300.0
+    P: 1.01325e+05
+  note: >-
+    Equation of state is based on W. Wagner, A. Pruss, "The IAPWS Formulation
+    1995 for the Thermodynamic Properties of Ordinary Water Substance for
+    General and Scientific Use," J. Phys. Chem. Ref. Dat, 31, 387, 2002.
+    Important: Only liquid and supercritical states are currently implemented
 - name: nitrogen
   thermo: pure-fluid
   elements: [N]
@@ -92,6 +104,12 @@ phases:
     T: 300.0
     P: 1.01325e+05
   pure-fluid-name: HFC-134a
+  note: >-
+    Equation of state is based on R. Tillner-Roth and H. D. Baehr, "An
+    International Standard Formulation for The Thermodynamic Properties of
+    1,1,1,2-Tetrafluoroethane (HFC-134a) for Temperatures From 170 K to 455 K
+    and Pressures up to 70 MPa". J. Phys. Chem. Ref. Data, Vol. 23, No. 5, 1994.
+    pp. 657--729.
 - name: hfc134a
   thermo: pure-fluid
   elements: [C, F, H]

include/cantera/thermo/WaterProps.h

@@ -83,6 +83,11 @@ class PDSS_Water;
 //! The WaterProps class is used to house several approximation routines for
 //! properties of water.
 /*!
+ * This is a helper class for WaterSSTP and PDSS_Water and does not constitute
+ * a complete implementation of a thermo phase by itself (see \ref thermoprops
+ * and classes \link Cantera::WaterSSTP WaterSSTP\endlink and
+ * \link Cantera::PDSS_Water PDSS_Water\endlink).
+ *
  * The class is also a wrapper around the WaterPropsIAPWS class which provides
  * the calculations for the equation of state properties for water.
  *

include/cantera/thermo/WaterPropsIAPWS.h

@@ -37,6 +37,11 @@ namespace Cantera
 
 //! Class for calculating the equation of state of water.
 /*!
+ * This is a helper class for WaterSSTP and PDSS_Water and does not constitute
+ * a complete implementation of a thermo phase by itself (see \ref thermoprops
+ * and classes \link Cantera::WaterSSTP WaterSSTP\endlink and
+ * \link Cantera::PDSS_Water PDSS_Water\endlink).
+ *
  * The reference is W. Wagner, A. Pruss, "The IAPWS Formulation 1995 for the
  * Thermodynamic Properties of Ordinary Water Substance for General and
  * Scientific Use," J. Phys. Chem. Ref. Dat, 31, 387, 2002.

include/cantera/thermo/WaterPropsIAPWSphi.h

@@ -20,6 +20,11 @@ namespace Cantera
 
 //! Low level class for the real description of water.
 /*!
+ * This is a helper class for WaterSSTP and PDSS_Water and does not constitute
+ * a complete implementation of a thermo phase by itself (see \ref thermoprops
+ * and classes \link Cantera::WaterSSTP WaterSSTP\endlink and
+ * \link Cantera::PDSS_Water PDSS_Water\endlink).
+ *
  * The reference is W. Wagner, A. Pruss, "The IAPWS Formulation 1995 for the
  * Thermodynamic Properties of Ordinary Water Substance for General and
  * Scientific Use," J. Phys. Chem. Ref. Dat, 31, 387, 2002.

include/cantera/thermo/WaterSSTP.h

@@ -20,7 +20,7 @@ namespace Cantera
 class WaterPropsIAPWS;
 class WaterProps;
 //! Class for single-component water. This is designed to cover just the liquid
-//! part of water.
+//! and supercritical phases of water.
 /*!
  * The reference is W. Wagner, A. Pruss, "The IAPWS Formulation 1995 for the
  * Thermodynamic Properties of Ordinary Water Substance for General and
@@ -140,9 +140,11 @@ class WaterSSTP : public SingleSpeciesTP
     explicit WaterSSTP(XML_Node& phaseRef, const std::string& id = "");
 
     virtual std::string type() const {
-        return "Water";
+        return "liquid-water-IAPWS95";
     }
 
+    virtual std::string phaseOfMatter() const;
+
     //! @name  Molar Thermodynamic Properties of the Solution
     //! @{
 
@@ -238,6 +240,15 @@ class WaterSSTP : public SingleSpeciesTP
         return m_waterProps.get();
     }
 
+    //! Switch that enables calculations in the gas phase
+    /**
+     *  Since this phase represents a liquid (or supercritical) phase, it is an
+     *  error to return a gas-phase answer. The sole intended use for this
+     *  member function is to check the thermodynamic consistency of the
+     *  underlying WaterProps class with ideal-gas thermo functions.
+     */
+    void _allowGasPhase(bool flag) { m_allowGasPhase = flag; }
+
 protected:
     /**
      * @internal This internal routine must be overridden because it is not
@@ -278,8 +289,8 @@ class WaterSSTP : public SingleSpeciesTP
     bool m_ready;
 
     /**
-     *  Since this phase represents a liquid phase, it's an error to
-     *  return a gas-phase answer. However, if the below is true, then
+     *  Since this phase represents a liquid (or supercritical) phase, it is an
+     *  error to return a gas-phase answer. However, if the below is true, then
      *  a gas-phase answer is allowed. This is used to check the thermodynamic
      *  consistency with ideal-gas thermo functions for example.
      */

interfaces/cython/cantera/liquidvapor.py

@@ -4,47 +4,186 @@
 from . import PureFluid, _cantera
 
 
-def Water():
+def Water(backend='Reynolds'):
     """
     Create a `PureFluid` object using the equation of state for water and the
     `WaterTransport` class for viscosity and thermal conductivity.
+
+    The object returned by this method implements an accurate equation of state
+    for water, where implementations are selected using the *backend* switch.
+
+    For the ``Reynolds`` backend, the equation of state is taken from
+
+        W. C. Reynolds, *Thermodynamic Properties in SI: graphs, tables, and
+        computational equations for forty substances.* Stanford: Stanford
+        University, 1979. Print.
+
+    which can be used in the liquid, vapor, saturated liquid/vapor, and
+    supercritical regions of the phase diagram.
+
+    The ``IAPWS95`` backend implements an IAPWS (International Association for
+    the Properties of Water and Steam) formulation for thermodynamic properties
+    taken from
+
+        W. Wagner, A. Pruss, *The IAPWS Formulation 1995 for the Thermodynamic
+        Properties of Ordinary Water Substance for General and Scientific Use,*
+        J. Phys. Chem. Ref. Dat, 31, 387, 2002.
+
+    which currently only implements liquid and supercritical regions.
+
+    In both cases, formulas for transport are taken from
+
+        J. V. Sengers, J. T. R. Watson, *Improved International Formulations for
+        the Viscosity and Thermal Conductivity of Water Substance,* J. Phys.
+        Chem. Ref. Data, 15, 1291, 1986.
+
+    For more details, see classes :ct:PureFluid, tpx::water,
+    :ct:WaterSSTP and :ct:WaterTransport in the Cantera C++ source
+    code documentation.
     """
     class WaterWithTransport(PureFluid, _cantera.Transport):
         __slots__ = ()
 
-    return WaterWithTransport('liquidvapor.yaml', 'water', transport_model='Water')
+    if backend == 'Reynolds':
+        return WaterWithTransport('liquidvapor.yaml', 'water',
+                                  transport_model='Water')
+    if backend == 'IAPWS95':
+        return WaterWithTransport('liquidvapor.yaml', 'liquid-water-IAPWS95',
+                                  transport_model='Water')
+
+    raise KeyError("Unknown backend '{}'".format(backend))
 
 
 def Nitrogen():
-    """Create a `PureFluid` object using the equation of state for nitrogen."""
+    """
+    Create a `PureFluid` object using the equation of state for nitrogen.
+
+    The object returned by this method implements an accurate equation of
+    state for nitrogen that can be used in the liquid, vapor, saturated
+    liquid/vapor, and supercritical regions of the phase diagram. The
+    equation of state is taken from
+
+        W. C. Reynolds, *Thermodynamic Properties in SI: graphs, tables, and
+        computational equations for forty substances* Stanford: Stanford
+        University, 1979. Print.
+
+    For more details, see classes :ct:PureFluid and tpx::nitrogen in the
+    Cantera C++ source code documentation.
+    """
     return PureFluid('liquidvapor.yaml', 'nitrogen')
 
 
 def Methane():
-    """Create a `PureFluid` object using the equation of state for methane."""
+    """
+    Create a `PureFluid` object using the equation of state for methane.
+
+    The object returned by this method implements an accurate equation of
+    state for methane that can be used in the liquid, vapor, saturated
+    liquid/vapor, and supercritical regions of the phase diagram.  The
+    equation of state is taken from
+
+        W. C. Reynolds, *Thermodynamic Properties in SI: graphs, tables, and
+        computational equations for forty substances* Stanford: Stanford
+        University, 1979. Print.
+
+    For more details, see classes :ct:PureFluid and tpx::methane in the
+    Cantera C++ source code documentation.
+    """
     return PureFluid('liquidvapor.yaml', 'methane')
 
 
 def Hydrogen():
-    """Create a `PureFluid` object using the equation of state for hydrogen."""
+    """
+    Create a `PureFluid` object using the equation of state for hydrogen.
+
+    The object returned by this method implements an accurate equation of
+    state for hydrogen that can be used in the liquid, vapor, saturated
+    liquid/vapor, and supercritical regions of the phase diagram. The
+    equation of state is taken from
+
+        W. C. Reynolds, *Thermodynamic Properties in SI: graphs, tables, and
+        computational equations for forty substances* Stanford: Stanford
+        University, 1979. Print.
+
+    For more details, see classes :ct:PureFluid and tpx::hydrogen in the
+    Cantera C++ source code documentation.
+    """
     return PureFluid('liquidvapor.yaml', 'hydrogen')
 
 
 def Oxygen():
-    """Create a `PureFluid` object using the equation of state for oxygen."""
+    """
+    Create a `PureFluid` object using the equation of state for oxygen.
+
+    The object returned by this method implements an accurate equation of
+    state for oxygen that can be used in the liquid, vapor, saturated
+    liquid/vapor, and supercritical regions of the phase diagram.  The
+    equation of state is taken from
+
+        W. C. Reynolds, *Thermodynamic Properties in SI: graphs, tables, and
+        computational equations for forty substances* Stanford: Stanford
+        University, 1979. Print.
+
+    For more details, see classes :ct:PureFluid and tpx::oxygen in the
+    Cantera C++ source code documentation.
+    """
     return PureFluid('liquidvapor.yaml', 'oxygen')
 
 
 def Hfc134a():
-    """Create a `PureFluid` object using the equation of state for HFC-134a."""
+    """
+    Create a `PureFluid` object using the equation of state for HFC-134a.
+
+    The object returned by this method implements an accurate equation of
+    state for refrigerant HFC134a (R134a) that can be used in the liquid,
+    vapor, saturated liquid/vapor, and supercritical regions of the phase
+    diagram. Implements the equation of state given in:
+
+        R. Tillner-Roth, H. D. Baehr. *An International Standard Formulation for
+        The Thermodynamic Properties of 1,1,1,2-Tetrafluoroethane (HFC-134a) for
+        Temperatures From 170 K to 455 K and Pressures up to 70 MPa.* J. Phys.
+        Chem. Ref. Data, Vol. 23, No. 5, 1994. pp. 657--729.
+        http://dx.doi.org/10.1063/1.555958
+
+    For more details, see classes :ct:PureFluid and tpx::HFC134a in the
+    Cantera C++ source code documentation.
+    """
     return PureFluid('liquidvapor.yaml', 'HFC-134a')
 
 
 def CarbonDioxide():
-    """Create a `PureFluid` object using the equation of state for carbon dioxide."""
+    """
+    Create a `PureFluid` object using the equation of state for carbon dioxide.
+
+    The object returned by this method implements an accurate equation of
+    state for carbon dioxide that can be used in the liquid, vapor, saturated
+    liquid/vapor, and supercritical regions of the phase diagram. The
+    equation of state is taken from
+
+        W. C. Reynolds, *Thermodynamic Properties in SI: graphs, tables, and
+        computational equations for forty substances.* Stanford: Stanford
+        University, 1979. Print.
+
+    For more details, see classes :ct:PureFluid and tpx::CarbonDioxide in
+    the Cantera C++ source code documentation.
+    """
     return PureFluid('liquidvapor.yaml', 'carbon-dioxide')
 
 
 def Heptane():
-    """Create a `PureFluid` object using the equation of state for heptane."""
+    """
+    Create a `PureFluid` object using the equation of state for heptane.
+
+    The object returned by this method implements an accurate equation of
+    state for n-heptane that can be used in the liquid, vapor, saturated
+    liquid/vapor, and supercritical regions of the phase diagram. The
+    equation of state is taken from
+
+        W. C. Reynolds, *Thermodynamic Properties in SI: graphs, tables, and
+        computational equations for forty substances.* Stanford: Stanford
+        University, 1979. Print.
+
+    For more details, see classes :ct:PureFluid and tpx::Heptane in the
+    Cantera C++ source code documentation.
+    """
     return PureFluid('liquidvapor.yaml', 'heptane')

interfaces/cython/cantera/test/test_composite.py

@@ -87,6 +87,9 @@ def check(a, b):
             try:
                 sol = ct.Solution(self.yml_file, ph_name)
                 a = ct.SolutionArray(sol, 10)
+                if ph['thermo'] == 'liquid-water-IAPWS95':
+                    # ensure that phase remains liquid
+                    a.TP = sol.T, sol.critical_pressure
 
                 # assign some state
                 T = 373.15 + 100*np.random.rand(10)

interfaces/cython/cantera/test/test_convert.py

@@ -841,10 +841,10 @@ def checkConversion(self, basename, cls=ct.Solution, ctmlphases=(),
 
         return ctmlPhase, yamlPhase
 
-    def checkThermo(self, ctmlPhase, yamlPhase, temperatures, tol=1e-7):
+    def checkThermo(self, ctmlPhase, yamlPhase, temperatures, pressure=ct.one_atm, tol=1e-7):
         for T in temperatures:
-            ctmlPhase.TP = T, ct.one_atm
-            yamlPhase.TP = T, ct.one_atm
+            ctmlPhase.TP = T, pressure
+            yamlPhase.TP = T, pressure
             cp_ctml = ctmlPhase.partial_molar_cp
             cp_yaml = yamlPhase.partial_molar_cp
             h_ctml = ctmlPhase.partial_molar_enthalpies
@@ -1134,7 +1134,7 @@ def test_water_IAPWS95_thermo(self):
             Path(self.test_work_dir).joinpath("liquid-water.yaml"),
         )
         ctmlWater, yamlWater = self.checkConversion("liquid-water")
-        self.checkThermo(ctmlWater, yamlWater, [300, 500, 1300, 2000])
+        self.checkThermo(ctmlWater, yamlWater, [300, 500, 1300, 2000], pressure=22064000.0)
         self.assertEqual(ctmlWater.transport_model, yamlWater.transport_model)
         dens = ctmlWater.density
         for T in [298, 1001, 2400]:

interfaces/cython/cantera/test/test_purefluid.py

@@ -357,6 +357,44 @@ def test_phase_of_matter(self):
         co2 = ct.CarbonDioxide()
         self.assertEqual(co2.phase_of_matter, "gas")
 
+    def test_water_backends(self):
+        w = ct.Water(backend='Reynolds')
+        self.assertEqual(w.thermo_model, 'PureFluid')
+        w = ct.Water(backend='IAPWS95')
+        self.assertEqual(w.thermo_model, 'liquid-water-IAPWS95')
+        with self.assertRaisesRegex(KeyError, 'Unknown backend'):
+            ct.Water('foobar')
+
+    def test_water_iapws(self):
+        w = ct.Water(backend='IAPWS95')
+        self.assertNear(w.critical_density, 322.)
+        self.assertNear(w.critical_temperature, 647.096)
+        self.assertNear(w.critical_pressure, 22064000.0)
+
+        # test internal TP setters (setters update temperature at constant
+        # density before updating pressure)
+        w.TP = 300, ct.one_atm
+        dens = w.density
+        w.TP = 2000, ct.one_atm # supercritical
+        self.assertEqual(w.phase_of_matter, "supercritical")
+        w.TP = 300, ct.one_atm # state goes from supercritical -> gas -> liquid
+        self.assertNear(w.density, dens)
+        self.assertEqual(w.phase_of_matter, "liquid")
+
+        # test setters for critical conditions
+        w.TP = w.critical_temperature, w.critical_pressure
+        self.assertNear(w.density, 322.)
+        w.TP = 2000, ct.one_atm # uses current density as initial guess
+        w.TP = 273.16, ct.one_atm # uses fixed density as initial guess
+        self.assertNear(w.density, 999.84376)
+        self.assertEqual(w.phase_of_matter, "liquid")
+        w.TP = w.T, w.P_sat
+        self.assertEqual(w.phase_of_matter, "liquid")
+        with self.assertRaisesRegex(ct.CanteraError, "assumes liquid phase"):
+            w.TP = 273.1599999, ct.one_atm
+        with self.assertRaisesRegex(ct.CanteraError, "assumes liquid phase"):
+            w.TP = 500, ct.one_atm
+
 
 # To minimize errors when transcribing tabulated data, the input units here are:
 # T: K, P: MPa, rho: kg/m3, v: m3/kg, (u,h): kJ/kg, s: kJ/kg-K