INIT File: Add Support for Writing Saturation Function Tables

This commit extends the INIT file Table writing to also output the
saturation function tables in normalised form.  We support
generating the INIT file's SGFN, SOFN, and SWFN tables--including
the derivative information--for both two and three phases from both
families of saturation function keywords (S{G,W}OF and S{G,W}FN +
SOF{2,3}).  We do not yet support generating the appropriate tables
from input keyword SLGOF.

We leverage the LinearisedOutputTable to abstract away some of the
details of indexing into the linear 'tab' array and create a helper
function to loop across saturation function regions whence each
table generator need only be concerned about the specific data
pertaining to that region's saturation function (i.e., the values of
independent and dependent variates and number of active rows).  We
allocate the output tables according to information in the TABDIMS
keyword, notably the number of saturation nodes (item 3 of TABDIMS).

Generating the three-phase SOFN table, which has the same columns as
the input table SOF3, in the case of family One (SGOF and SWOF) is
slightly involved.  In particular we need to join the SGOF and SWOF
tables on common oil saturation values and derive/insert missing
KroX data through piecewise linear interpolation in the appropriate
input table.  We defer the details of merging on common (and uniqe)
oil saturation values to the standard library routine 'set_union()'
which outputs repeated saturation values exactly once rather than
for each occurrence.  That way we only need to wrap the input tables
in a simple class to facilitate look-up of oil saturation values and
the mechanics of piecewise linear interpolation of the relative
permeability column for oil.  Due to this merging process, the
number of rows in SOFN is twice the number of saturation nodes in
this case.

Since this support depends on being able to determine which phases
are active in a particular run, what table sizes to use for the
output and which keywords are being used to represent the saturation
function tables we introduce a single new public member function

    void Tables::addSatFunc(const EclipseState& es)

This function determines the run's active phases and dispatches to
the new helper functions

    void Tables::addSatFunc_FamilyOne()
    void Tables::addSatFunc_FamilyTwo()

according to which keyword family exists in the input deck.  These
functions in turn call additional helper functions to handle each
phase table separately.  For instance addSatFunc_FamilyOne() uses
the helper function

    SatFunc::Oil::ThreePhase::fromSGOFandSWOF()

to generate a three-phase SOFN table based on the information in the
SGOF and SWOF tables.

Information about slopes/derivatives for the piecewise interpolants
of the dependent variates is computed through the helper function

    DifferentiateOutputTable::calcSlopes()

whence the first entry of each derivative column is undefined (i.e.,
assigned the sentinel value 1e+20).  This should arguably be zero
instead.  Further testing and comparison with INIT result sets
generated by ECL will inform the decision here.

We add unit tests for all combinations of number of active phases
(two or three) and which saturation function keyword family is
present in the simulation case.  The unit tests use the tables from
SPE 9 for keyword family One and the tables from SPE 1 for keyword
family Two.  Comparison data is extracted directly from the ECL INIT
file in the case of the SPE 9 tables and derived from independent
calculation for the SPE 1 tables.

opm/output/eclipse/Tables.hpp

@@ -29,9 +29,9 @@
 #include <opm/parser/eclipse/EclipseState/Tables/PvtgTable.hpp>
 #include <opm/parser/eclipse/EclipseState/Tables/FlatTable.hpp>
 
-
 namespace Opm {
     class UnitSystem;
+    class EclipseState;
 
     class Tables {
     public:
@@ -42,6 +42,13 @@ namespace Opm {
         void addPVTW(const PvtwTable& pvtwTable);
         void addDensity(const DensityTable& density);
 
+        /// Add normalised saturation function tables to INIT file's TAB
+        /// vector.
+        ///
+        /// \param[in] es Valid \c EclipseState object with accurate RUNSPEC
+        ///    information on active phases and table dimensions ("TABDIMS").
+        void addSatFunc(const EclipseState& es);
+
         /// Acquire read-only reference to internal TABDIMS vector.
         const std::vector<int>& tabdims() const;
 
@@ -55,6 +62,40 @@ namespace Opm {
 
         void addData(const std::size_t          offset_index,
                      const std::vector<double>& new_data);
+
+        /// Add saturation function tables corresponding to family I (SGOF,
+        /// SWOF) to the tabular data (TABDIMS and TAB vectors).
+        ///
+        /// \param[in] es Valid \c EclipseState object with accurate table
+        ///    dimensions ("TABDIMS" keyword) and an initialised \c
+        ///    TableManager sub-object.
+        ///
+        /// \param[in] gas Whether or not gas is active the current run.
+        ///
+        /// \param[in] oil Whether or not oil is active the current run.
+        ///
+        /// \param[in] wat Whether or not water is active the current run.
+        void addSatFunc_FamilyOne(const EclipseState& es,
+                                  const bool          gas,
+                                  const bool          oil,
+                                  const bool          wat);
+
+        /// Add saturation function tables corresponding to family II (SGFN,
+        /// SOF{2,3}, SWFN) to the tabular data (TABDIMS and TAB vectors).
+        ///
+        /// \param[in] es Valid \c EclipseState object with accurate table
+        ///    dimensions ("TABDIMS" keyword) and an initialised \c
+        ///    TableManager sub-object.
+        ///
+        /// \param[in] gas Whether or not gas is active the current run.
+        ///
+        /// \param[in] oil Whether or not oil is active the current run.
+        ///
+        /// \param[in] wat Whether or not water is active the current run.
+        void addSatFunc_FamilyTwo(const EclipseState& es,
+                                  const bool          gas,
+                                  const bool          oil,
+                                  const bool          wat);
     };
 
     /// Emit normalised tabular information (TABDIMS and TAB vectors) to