Merge branch 'issue/add_documentation' into 'master'

added some comments to functions and classes

See merge request spraetor/dune-vtk!15

dune/vtk/datacollectorinterface.hh

@@ -3,123 +3,129 @@
 #include <cstdint>
 #include <vector>
 
-namespace Dune {
-
-template <class GridView, class Derived, class Partition>
-class DataCollectorInterface
+namespace Dune
 {
-public:
-  /// The partitionset to collect data from
-  static constexpr auto partition = Partition{};
-
-  /// The dimension of the grid
-  enum { dim = GridView::dimension };
-
-  /// The dimension of the world
-  enum { dow = GridView::dimensionworld };
-
-public:
-  /// Store a copy of the GridView
-  DataCollectorInterface (GridView const& gridView)
-    : gridView_(gridView)
-  {}
-
-  /// Update the DataCollector on the current GridView
-  void update ()
-  {
-    asDerived().updateImpl();
-  }
-
-  /// Return the number of ghost elements
-  int ghostLevel () const
-  {
-    return asDerived().ghostLevelImpl();
-  }
-
-  /// \brief Return the number of cells in (this partition of the) grid
-  std::uint64_t numCells () const
-  {
-    return asDerived().numCellsImpl();
-  }
-
-  /// Return the number of points in (this partition of the) grid
-  std::uint64_t numPoints () const
-  {
-    return asDerived().numPointsImpl();
-  }
-
-  /// Return a flat vector of point coordinates
-  /**
-   * All coordinates are extended to 3 components and concatenated.
-   * [p0_x, p0_y, p0_z, p1_x, p1_y, p1_z, ...]
-   * If the GridView::dimensionworld < 3, the remaining components are
-   * set to 0
-   **/
-  template <class T>
-  std::vector<T> points () const
-  {
-    return asDerived().template pointsImpl<T>();
-  }
-
-  /// Return a flat vector of function values evaluated at the points.
+  /// Base class for data collectors in a CRTP style.
   /**
-   * In case of a vector valued function, flat the vector entries:
-   * [fct(p0)_0, fct(p0)_1, fct(p0)_2, fct(p1)_0, ...]
-   * where the vector dimension must be 3 (possible extended by 0s)
-   * In case of tensor valued function, flat the tensor row-wise:
-   * [fct(p0)_00, fct(p0)_01, fct(p0)_02, fct(p0)_10, fct(p0)_11, fct(p0)_12, fct(p0)_20...]
-   * where the tensor dimension must be 3x3 (possible extended by 0s)
+   * \tparam GridView   Model of Dune::GridView
+   * \tparam Derived    Implementation of a concrete DataCollector.
+   * \tparam Partition  Dune::PartitionType [Partitions::InteriorBorder]
    **/
-  template <class T, class VtkFunction>
-  std::vector<T> pointData (VtkFunction const& fct) const
-  {
-    return asDerived().template pointDataImpl<T>(fct);
-  }
-
-  /// Return a flat vector of function values evaluated at the cells in the order of traversal.
-  /**
-   * \see pointData.
-   * Note: Cells might be descibred explicitly by connectivity, offsets, and types, e.g. in
-   * an UnstructuredGrid, or might be described implicitly by the grid type, e.g. in
-   * StructuredGrid.
-   */
-  template <class T, class VtkFunction>
-  std::vector<T> cellData (VtkFunction const& fct) const
-  {
-    return asDerived().template cellDataImpl<T>(fct);
-  }
-
-protected: // cast to derived type
-
-  Derived& asDerived ()
-  {
-    return static_cast<Derived&>(*this);
-  }
-
-  const Derived& asDerived () const
-  {
-    return static_cast<const Derived&>(*this);
-  }
-
-public: // default implementations
-
-  void updateImpl ()
+  template <class GridView, class Derived, class Partition>
+  class DataCollectorInterface
   {
-    /* do nothing */
-  }
-
-  int ghostLevelImpl () const
-  {
-    return gridView_.overlapSize(0);
-  }
-
-  // Evaluate `fct` in center of cell.
-  template <class T, class VtkFunction>
-  std::vector<T> cellDataImpl (VtkFunction const& fct) const;
-
-protected:
-  GridView gridView_;
-};
+  public:
+    /// The partitionset to collect data from
+    static constexpr auto partition = Partition{};
+
+    /// The dimension of the grid
+    enum { dim = GridView::dimension };
+
+    /// The dimension of the world
+    enum { dow = GridView::dimensionworld };
+
+  public:
+    /// Store a copy of the GridView
+    DataCollectorInterface (GridView const& gridView)
+      : gridView_(gridView)
+    {}
+
+    /// Update the DataCollector on the current GridView
+    void update ()
+    {
+      asDerived().updateImpl();
+    }
+
+    /// Return the number of ghost elements
+    int ghostLevel () const
+    {
+      return asDerived().ghostLevelImpl();
+    }
+
+    /// Return the number of cells in (this partition of the) grid
+    std::uint64_t numCells () const
+    {
+      return asDerived().numCellsImpl();
+    }
+
+    /// Return the number of points in (this partition of the) grid
+    std::uint64_t numPoints () const
+    {
+      return asDerived().numPointsImpl();
+    }
+
+    /// \brief Return a flat vector of point coordinates
+    /**
+    * All coordinates are extended to 3 components and concatenated.
+    * [p0_x, p0_y, p0_z, p1_x, p1_y, p1_z, ...]
+    * If the GridView::dimensionworld < 3, the remaining components are
+    * set to 0
+    **/
+    template <class T>
+    std::vector<T> points () const
+    {
+      return asDerived().template pointsImpl<T>();
+    }
+
+    /// \brief Return a flat vector of function values evaluated at the points.
+    /**
+    * In case of a vector valued function, flat the vector entries:
+    * [fct(p0)_0, fct(p0)_1, fct(p0)_2, fct(p1)_0, ...]
+    * where the vector dimension must be 3 (possible extended by 0s)
+    * In case of tensor valued function, flat the tensor row-wise:
+    * [fct(p0)_00, fct(p0)_01, fct(p0)_02, fct(p0)_10, fct(p0)_11, fct(p0)_12, fct(p0)_20...]
+    * where the tensor dimension must be 3x3 (possible extended by 0s)
+    **/
+    template <class T, class VtkFunction>
+    std::vector<T> pointData (VtkFunction const& fct) const
+    {
+      return asDerived().template pointDataImpl<T>(fct);
+    }
+
+    /// \brief Return a flat vector of function values evaluated at the cells in the order of traversal.
+    /**
+    * \see pointData.
+    * Note: Cells might be descibred explicitly by connectivity, offsets, and types, e.g. in
+    * an UnstructuredGrid, or might be described implicitly by the grid type, e.g. in
+    * StructuredGrid.
+    */
+    template <class T, class VtkFunction>
+    std::vector<T> cellData (VtkFunction const& fct) const
+    {
+      return asDerived().template cellDataImpl<T>(fct);
+    }
+
+  protected: // cast to derived type
+
+    Derived& asDerived ()
+    {
+      return static_cast<Derived&>(*this);
+    }
+
+    const Derived& asDerived () const
+    {
+      return static_cast<const Derived&>(*this);
+    }
+
+  public: // default implementations
+
+    void updateImpl ()
+    {
+      /* do nothing */
+    }
+
+    int ghostLevelImpl () const
+    {
+      return gridView_.overlapSize(0);
+    }
+
+    // Evaluate `fct` in center of cell.
+    template <class T, class VtkFunction>
+    std::vector<T> cellDataImpl (VtkFunction const& fct) const;
+
+  protected:
+    GridView gridView_;
+  };
 
 } // end namespace Dune
 

dune/vtk/defaultvtkfunction.hh

@@ -25,21 +25,25 @@ namespace Dune
     using Range = std::decay_t<decltype(std::declval<F>()(std::declval<D>()))>;
 
   public:
+    /// Constructor. Stores a copy of the passed `localFct` in a local variable.
     template <class LocalFct, disableCopyMove<Self, LocalFct> = 0>
     LocalFunctionWrapper (LocalFct&& localFct)
       : localFct_(std::forward<LocalFct>(localFct))
     {}
 
+    /// Bind the LocalFunction to the Entity
     virtual void bind (Entity const& entity) override
     {
       localFct_.bind(entity);
     }
 
+    /// Unbind the LocalFunction from the Entity
     virtual void unbind () override
     {
       localFct_.unbind();
     }
 
+    /// Evaluate the LocalFunction in LocalCoordinates
     virtual double evaluate (int comp, LocalCoordinate const& xi) const override
     {
       return evaluateImpl(comp, localFct_(xi));

dune/vtk/gridcreatorinterface.hh

@@ -9,87 +9,96 @@
 
 #include <dune/vtk/forward.hh>
 
-namespace Dune {
-
-template <class G, class Derived>
-class GridCreatorInterface
+namespace Dune
 {
-public:
-  using Grid = G;
-  using GlobalCoordinate = typename Grid::template Codim<0>::Entity::Geometry::GlobalCoordinate;
-
-public:
-  GridCreatorInterface (GridFactory<Grid>& factory)
-    : factory_(&factory)
-  {}
-
-  /// Insert all points as vertices into the factory
-  void insertVertices (std::vector<GlobalCoordinate> const& points,
-                       std::vector<std::uint64_t> const& point_ids)
-  {
-    asDerived().insertVerticesImpl(points, point_ids);
-  }
-
-  /// Create elements based on type and connectivity description
-  void insertElements (std::vector<std::uint8_t> const& types,
-                       std::vector<std::int64_t> const& offsets,
-                       std::vector<std::int64_t> const& connectivity)
-  {
-    asDerived().insertElementsImpl(types, offsets, connectivity);
-  }
-
-  /// Insert part of a grid stored in file into factory
-  void insertPieces (std::vector<std::string> const& pieces)
-  {
-    asDerived().insertPiecesImpl(pieces);
-  }
-
-  /// Return the associated GridFactory
-  GridFactory<Grid>& factory ()
-  {
-    return *factory_;
-  }
-
-  /// Return the mpi collective communicator
-  auto comm () const
-  {
-    return MPIHelper::getCollectiveCommunication();
-  }
-
-protected: // cast to derived type
 
-  Derived& asDerived ()
+  /// Base class for grid creators in a CRTP style.
+  /**
+   * Construct a grid from data read from VTK files.
+   *
+   * \tparam GridView   Model of Dune::GridView
+   * \tparam Derived    Implementation of a concrete GridCreator.
+   **/
+  template <class G, class Derived>
+  class GridCreatorInterface
   {
-    return static_cast<Derived&>(*this);
-  }
-
-  const Derived& asDerived () const
-  {
-    return static_cast<const Derived&>(*this);
-  }
-
-public: // default implementations
-
-  void insertVerticesImpl (std::vector<GlobalCoordinate> const&,
-                           std::vector<std::uint64_t> const&)
-  {
-    /* do nothing */
-  }
-
-  void insertElementsImpl (std::vector<std::uint8_t> const&,
-                           std::vector<std::int64_t> const&,
-                           std::vector<std::int64_t> const&)
-  {
-    /* do nothing */
-  }
-
-  void insertPiecesImpl (std::vector<std::string> const&)
-  {
-    /* do nothing */;
-  }
-
-protected:
-  GridFactory<Grid>* factory_;
-};
+  public:
+    using Grid = G;
+    using GlobalCoordinate = typename Grid::template Codim<0>::Entity::Geometry::GlobalCoordinate;
+
+  public:
+    /// Constructor. Stores a reference to the passed GridFactory
+    GridCreatorInterface (GridFactory<Grid>& factory)
+      : factory_(&factory)
+    {}
+
+    /// Insert all points as vertices into the factory
+    void insertVertices (std::vector<GlobalCoordinate> const& points,
+                        std::vector<std::uint64_t> const& point_ids)
+    {
+      asDerived().insertVerticesImpl(points, point_ids);
+    }
+
+    /// Create elements based on type and connectivity description
+    void insertElements (std::vector<std::uint8_t> const& types,
+                        std::vector<std::int64_t> const& offsets,
+                        std::vector<std::int64_t> const& connectivity)
+    {
+      asDerived().insertElementsImpl(types, offsets, connectivity);
+    }
+
+    /// Insert part of a grid stored in file into factory
+    void insertPieces (std::vector<std::string> const& pieces)
+    {
+      asDerived().insertPiecesImpl(pieces);
+    }
+
+    /// Return the associated GridFactory
+    GridFactory<Grid>& factory ()
+    {
+      return *factory_;
+    }
+
+    /// Return the mpi collective communicator
+    auto comm () const
+    {
+      return MPIHelper::getCollectiveCommunication();
+    }
+
+  protected: // cast to derived type
+
+    Derived& asDerived ()
+    {
+      return static_cast<Derived&>(*this);
+    }
+
+    const Derived& asDerived () const
+    {
+      return static_cast<const Derived&>(*this);
+    }
+
+  public: // default implementations
+
+    void insertVerticesImpl (std::vector<GlobalCoordinate> const&,
+                            std::vector<std::uint64_t> const&)
+    {
+      /* do nothing */
+    }
+
+    void insertElementsImpl (std::vector<std::uint8_t> const&,
+                            std::vector<std::int64_t> const&,
+                            std::vector<std::int64_t> const&)
+    {
+      /* do nothing */
+    }
+
+    void insertPiecesImpl (std::vector<std::string> const&)
+    {
+      /* do nothing */;
+    }
+
+  protected:
+    GridFactory<Grid>* factory_;
+  };
 
 } // end namespace Dune

dune/vtk/gridcreators/parallelgridcreator.hh

@@ -13,6 +13,7 @@
 
 namespace Dune
 {
+  // create a distributed grid in parallel. Currently only supported by ALUGrid
   template <class Grid>
   struct ParallelGridCreator
       : public DerivedGridCreator<ContinuousGridCreator<Grid>, ParallelGridCreator<Grid>>

dune/vtk/legacyvtkfunction.hh

@@ -18,20 +18,24 @@ namespace Dune
     using LocalCoordinate = typename Interface::LocalCoordinate;
 
   public:
+    /// Constructor. Stores a shared pointer to the passed Dune::VTKFunction
     VTKLocalFunctionWrapper (std::shared_ptr<VTKFunction<GridView> const> const& fct)
       : fct_(fct)
     {}
 
+    /// Stores a pointer to the passed entity
     virtual void bind (Entity const& entity) override
     {
       entity_ = &entity;
     }
 
+    /// Unsets the stored entity pointer
     virtual void unbind () override
     {
       entity_ = nullptr;
     }
 
+    /// Evaluate the Dune::VTKFunction in LocalCoordinates on the stored Entity
     virtual double evaluate (int comp, LocalCoordinate const& xi) const override
     {
       return fct_->evaluate(comp, *entity_, xi);

dune/vtk/pvdwriter.hh

@@ -18,8 +18,6 @@ namespace Dune
   {
     using Self = PvdWriter;
 
-    // static_assert(IsVtkWriter<VtkWriter>::value, "Writer must implement the VtkWriterInterface.");
-
   public:
     /// Constructor, creates a VtkWriter with constructor arguments forwarded
     template <class... Args, disableCopyMove<Self,Args...> = 0>
@@ -30,7 +28,7 @@ namespace Dune
       datatype_ = vtkWriter_.getDatatype();
     }
 
-    /// Write the attached data to the file
+    /// \brief Write the attached data to the file
     /**
      * Create timestep files for the data associated to the current timestep `time`.
      *
@@ -44,8 +42,8 @@ namespace Dune
     void writeTimestep (double time, std::string const& fn, Std::optional<std::string> dir = {},
                         bool writeCollection = true) const;
 
-    /// Writes collection of timesteps to .pvd file.
-    // NOTE: requires an aforging call to \ref writeTimestep
+    /// \brief Writes collection of timesteps to .pvd file.
+    // NOTE: requires an aforgoing call to \ref writeTimestep
     /**
      * \param fn  The filename of the PVD file. May contain directory and any filename extension.
      * \param dir (Ignored) Timestep files are already written and their filenames are

dune/vtk/vtkfunction.hh

@@ -35,6 +35,7 @@ namespace Dune
   constexpr int sizeOf () { return Impl::SizeImpl<std::decay_t<T>>::value; }
 
 
+  /// Wrapper class for functions allowing local evaluations.
   template <class GridView>
   class VtkFunction
   {
@@ -48,6 +49,10 @@ namespace Dune
 
   public:
     /// Constructor VtkFunction from legacy VTKFunction
+    /**
+     * \param fct   The VTKFunction to wrap
+     * \param type  The VTK datatype how to write the function values to the output [Vtk::FLOAT64]
+     **/
     VtkFunction (std::shared_ptr<VTKFunction<GridView> const> const& fct,
                  Std::optional<Vtk::DataTypes> type = {})
       : localFct_(fct)

dune/vtk/vtkreader.hh

@@ -52,15 +52,19 @@ namespace Dune
       : creator_(creator)
     {}
 
+    // disable copy and move operations
+    VtkReader(VtkReader const&) = delete;
+    VtkReader(VtkReader&&) = delete;
+    VtkReader& operator=(VtkReader const&) = delete;
+    VtkReader& operator=(VtkReader&&) = delete;
+
     /// Read the grid from file with `filename` into the GridFactory \ref factory_
+    /**
+     * \param filename  The name of the input file
+     * \param create    If `false`, only fill internal data structures, if `true`, also create the grid. [true]
+     **/
     void readFromFile (std::string const& filename, bool create = true);
 
-    /// Read the grid from and input stream into the GridFactory \ref factory_
-    void readSerialFileFromStream (std::ifstream& input, bool create = true);
-
-    /// Read the grid from and input stream into the GridFactory \ref factory_
-    void readParallelFileFromStream (std::ifstream& input, int rank, int size, bool create = true);
-
     /// Implementation of \ref FileReader interface
     static void readFactoryImpl (GridFactory<Grid>& factory, std::string const& filename)
     {
@@ -68,9 +72,29 @@ namespace Dune
       reader.readFromFile(filename);
     }
 
+    /// Advanced read methods
+    /// @{
+
+    /// Read the grid from an input stream, referring to a .vtu file, into the GridFactory \ref factory_
+    /**
+     * \param input   A STL input stream to read the VTK file from.
+     * \param create  If `false`, only fill internal data structures, if `true`, also create the grid. [true]
+     **/
+    void readSerialFileFromStream (std::ifstream& input, bool create = true);
+
+    /// Read the grid from and input stream, referring to a .pvtu file, into the GridFactory \ref factory_
+    /**
+     * \param input   A STL input stream to read the VTK file from.
+     * \param create  If `false`, only fill internal data structures, if `true`, also create the grid. [true]
+     **/
+    void readParallelFileFromStream (std::ifstream& input, int rank, int size, bool create = true);
+
     /// Construct a grid using the GridCreator
+    // NOTE: requires the internal data structures to be filled by an aforgoing call to readFromFile
     void createGrid(bool insertPieces = true);
 
+    /// @}
+
     /// Return the filenames of parallel pieces
     std::vector<std::string> const& pieces () const
     {

dune/vtk/vtktimeserieswriter.hh

@@ -67,7 +67,7 @@ namespace Dune
                         bool writeCollection = true) const;
 
     /// Writes all timesteps to single timeseries file.
-    // NOTE: requires an aforging call to \ref writeTimestep
+    // NOTE: requires an aforgoing call to \ref writeTimestep
     /**
      * Create a timeseries file with all timesteps written by \ref writeTimestep.
      *

dune/vtk/vtkwriter.hh

@@ -33,7 +33,7 @@ namespace Dune
    * are provided, like YaspGrid and GeometrGrid.
    *
    * Note: Uses the default data-collector. If you want to choose a special data-collector, use
-   * the concrete write Implementation instead.
+   * the concrete writer Implementation instead. \see VtkWriterInterface
    **/
   template <class GridView>
   using VtkWriter = typename Impl::VtkWriterImpl<GridView, typename GridView::Grid>::type;

dune/vtk/vtkwriterinterface.hh

@@ -14,6 +14,10 @@
 namespace Dune
 {
   /// Interface for file writers for the Vtk XML file formats
+  /**
+   * \tparam GridView       Model of Dune::GridView
+   * \tparam DataCollector  Model of \ref DataCollectorInterface
+   **/
   template <class GridView, class DataCollector>
   class VtkWriterInterface
       : public FileWriter
@@ -34,7 +38,16 @@ namespace Dune
     };
 
   public:
-    /// Constructor, stores the gridView
+    /// \brief Constructor, passes the gridView to the DataCollector
+    /**
+     * Creates a new VtkWriterInterface for the provided GridView. Initializes a
+     * DataCollector that is used to collect point coordinates, cell connectivity and
+     * data values.
+     *