Generalise Restart Representation of UDQs

This commit reimplements the RestartIO::RstUDQ type with a view
towards introducing support for restarting simulation runs
containing user defined quantities (UDQs) associated to the segments
of multi-segmented wells.  In particular, we replace the current
value container with a back-end based on the CSRGraphFromCoordinates
helper class.  This, in turn, enables supporting UDQ values at the
sub-entity level of a top-level entity such as the segments of a
multi-segmented well.

We more clearly distinguish the producing side--i.e., the layer
which loads information from a restart file--from the consuming
side--i.e., the client code which forms UDQConfig and UDQState
objects based on the restart file information, and require the
producing side to signal when the restart information has been fully
loaded.  To this end, the producing side is expected to

  1. Call member function prepareValues() to signal that new values
     are being loaded
  2. Call member function addValue(), typically in a loop, to
     include new UDQ values from the restart file
  3. Call member function commitValues() to signal that all values
     have been loaded.

As an alternative to step 2, the producing side may call member
function addScalarValue() if the quantity in question is
scalar--typically a field level UDQ.

The producing should also include any relevant entity names, usually
well or group names, by calling the addEntityName() member function.

The consuming side is expected to interact with the information
through operator[]() which returns a specialised ValueRange type
that supports forward iteration, for instance in a range-for() loop.

This new interface begets a significant update to the UDQAssign
class.  In particular, we no longer need the 'rst_selector' and
instead add new constructor and add_record interfaces which take a
RestartIO::RstUDQ object and a report step index.  The previous
interface based on the 'rst_selector' implicitly assumed that all
assignment statements applied a constant value to a collection of
wells or groups, but this assumption does not generally hold when we
load information from a restart file.  The new interface removes
this assumption.  While here, also make the AssignRecord into a
private data type since client code does not generally need to know
how we represent the assignment information.

Finally, add Doxygen-style documentation to the types

  * RestartIO::RstUDQ
  * UDQAssign
  * UDQConfig
  * UDQState

While not much, this may help future maintainers understand the
relationships between these types a little better.

opm/input/eclipse/Schedule/UDQ/UDQConfig.cpp

@@ -588,12 +588,6 @@ namespace Opm {
         }
     }
 
-    UDQAction UDQConfig::action_type(const std::string& udq_key) const
-    {
-        auto action_iter = this->input_index.find(udq_key);
-        return action_iter->second.action;
-    }
-
     void UDQConfig::add_assign(const RestartIO::RstUDQ& udq,
                                const std::size_t        report_step)
     {

opm/input/eclipse/Schedule/UDQ/UDQConfig.hpp

@@ -246,7 +246,7 @@ namespace Opm {
         /// \param[in] create_segment_matcher Factory function for
         /// constructing segment set matchers.
         ///
-        /// \param[in,out] st Summary vectors.  For output and evaulating
+        /// \param[in,out] st Summary vectors.  For output and evaluating
         /// ACTION condition purposes.  Values pertaining to UDQs being
         /// assigned here will be updated.
         ///
@@ -277,7 +277,7 @@ namespace Opm {
         /// \param[in] create_region_matcher Factory function for
         /// constructing region set matchers.
         ///
-        /// \param[in,out] st Summary vectors.  For output and evaulating
+        /// \param[in,out] st Summary vectors.  For output and evaluating
         /// ACTION condition purposes.  Values pertaining to UDQs being
         /// assigned here will be updated.
         ///
@@ -307,7 +307,7 @@ namespace Opm {
         /// \param[in] key Unqualified UDQ name such as FUNNY, GUITAR,
         /// WURST, or SUSHI.
         ///
-        /// \return Pending assingment object for \p key.  Throws an
+        /// \return Pending assignment object for \p key.  Throws an
         /// exception of type \code std::out_of_range \endcode if no such
         /// object exists for the UDQ \p key.
         const UDQAssign& assign(const std::string& key) const;
@@ -433,7 +433,7 @@ namespace Opm {
         UDQFunctionTable udqft;
 
         // The following data structures are constrained by compatibility
-        // requirements in our simulation restart files.  In particuar we
+        // requirements in our simulation restart files.  In particular we
         // need to control the keyword ordering.  In this class the ordering
         // is maintained mainly by the input_index map which tracks the
         // insertion order of each keyword and whether the keyword (UDQ
@@ -465,7 +465,7 @@ namespace Opm {
 
         /// Ordered set of DEFINE statements.
         ///
-        /// Mostly unused and should probably be removed.
+        /// TODO: Mostly unused and should probably be removed.
         IOrderSet<std::string> define_order;
 
         /// Ordered set of UDQ inputs.
@@ -491,16 +491,6 @@ namespace Opm {
         /// \param[in] action Kind of operation.
         void add_node(const std::string& quantity, UDQAction action);
 
-        /// Retrieve operation currently associated a UDQ
-        ///
-        /// \param[in] udq_key Unqualified UDQ name such as FUNNY, GUITAR,
-        /// WURST, or SUSHI.  Shall be the name of an existing UDQ since
-        /// this function otherwise will dereference \code input_index.end()
-        /// \endcode.
-        ///
-        /// \return Operation currently associated to \p udq_key.
-        UDQAction action_type(const std::string& udq_key) const;
-
         /// Reconstitute an assignment statement from restart file information.
         ///
         /// \param[in] udq Restart file representation of an assignment statement.

opm/io/eclipse/rst/udq.cpp

@@ -19,6 +19,8 @@
 
 #include <opm/io/eclipse/rst/udq.hpp>
 
+#include <opm/common/utility/Visitor.hpp>
+
 #include <opm/output/eclipse/UDQDims.hpp>
 
 #include <algorithm>
@@ -35,20 +37,12 @@
 
 #include <fmt/format.h>
 
-namespace detail {
-    template <typename... Ts>
-    struct Overloaded : public Ts... { using Ts::operator()...; };
-
-    template <typename... Ts>
-    Overloaded(Ts...) -> Overloaded<Ts...>;
-}
-
 void Opm::RestartIO::RstUDQ::ValueRange::Iterator::setValue()
 {
     this->deref_value_.first = this->i_[this->ix_];
 
     this->deref_value_.second =
-        std::visit(detail::Overloaded {
+        std::visit(VisitorOverloadSet {
             []              (const double  v) { return v; },
             [ix = this->ix_](const double* v) { return v[ix]; }
         }, this->value_);

opm/io/eclipse/rst/udq.hpp

@@ -263,7 +263,7 @@ class RstUDQ
 
     /// UDQ's category, i.e., which level this UDQ applies to.
     ///
-    /// Exmples include, the FIELD (FU*), group (GU*), well (WU*), or well
+    /// Examples include, the FIELD (FU*), group (GU*), well (WU*), or well
     /// segments (SU*).
     UDQVarType category{UDQVarType::NONE};