Commit 69cdf2d9 authored by Praetorius, Simon's avatar Praetorius, Simon
Browse files

Merge branch 'issue/add_documentation' into 'master'

added some comments to functions and classes

See merge request spraetor/dune-vtk!15
parents 583c7476 865b9180
......@@ -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
......
......@@ -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));
......
......@@ -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
......@@ -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>>
......
......@@ -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);
......
......@@ -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
......
......@@ -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)
......
......@@ -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
{
......
......@@ -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.
*
......
......@@ -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;
......
......@@ -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.
*