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,12 +3,18 @@
#include <cstdint>
#include <vector>
namespace Dune {
template <class GridView, class Derived, class Partition>
class DataCollectorInterface
namespace Dune
{
public:
/// Base class for data collectors in a CRTP style.
/**
* \tparam GridView Model of Dune::GridView
* \tparam Derived Implementation of a concrete DataCollector.
* \tparam Partition Dune::PartitionType [Partitions::InteriorBorder]
**/
template <class GridView, class Derived, class Partition>
class DataCollectorInterface
{
public:
/// The partitionset to collect data from
static constexpr auto partition = Partition{};
......@@ -18,7 +24,7 @@ public:
/// The dimension of the world
enum { dow = GridView::dimensionworld };
public:
public:
/// Store a copy of the GridView
DataCollectorInterface (GridView const& gridView)
: gridView_(gridView)
......@@ -36,7 +42,7 @@ public:
return asDerived().ghostLevelImpl();
}
/// \brief Return the number of cells in (this partition of the) grid
/// Return the number of cells in (this partition of the) grid
std::uint64_t numCells () const
{
return asDerived().numCellsImpl();
......@@ -48,7 +54,7 @@ public:
return asDerived().numPointsImpl();
}
/// Return a flat vector of point coordinates
/// \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, ...]
......@@ -61,7 +67,7 @@ public:
return asDerived().template pointsImpl<T>();
}
/// Return a flat vector of function values evaluated at the points.
/// \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, ...]
......@@ -76,7 +82,7 @@ public:
return asDerived().template pointDataImpl<T>(fct);
}
/// Return a flat vector of function values evaluated at the cells in the order of traversal.
/// \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
......@@ -89,7 +95,7 @@ public:
return asDerived().template cellDataImpl<T>(fct);
}
protected: // cast to derived type
protected: // cast to derived type
Derived& asDerived ()
{
......@@ -101,7 +107,7 @@ protected: // cast to derived type
return static_cast<const Derived&>(*this);
}
public: // default implementations
public: // default implementations
void updateImpl ()
{
......@@ -117,9 +123,9 @@ public: // default implementations
template <class T, class VtkFunction>
std::vector<T> cellDataImpl (VtkFunction const& fct) const;
protected:
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,16 +9,25 @@
#include <dune/vtk/forward.hh>
namespace Dune {
template <class G, class Derived>
class GridCreatorInterface
namespace Dune
{
public:
/// 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
{
public:
using Grid = G;
using GlobalCoordinate = typename Grid::template Codim<0>::Entity::Geometry::GlobalCoordinate;
public:
public:
/// Constructor. Stores a reference to the passed GridFactory
GridCreatorInterface (GridFactory<Grid>& factory)
: factory_(&factory)
{}
......@@ -56,7 +65,7 @@ public:
return MPIHelper::getCollectiveCommunication();
}
protected: // cast to derived type
protected: // cast to derived type
Derived& asDerived ()
{
......@@ -68,7 +77,7 @@ protected: // cast to derived type
return static_cast<const Derived&>(*this);
}
public: // default implementations
public: // default implementations
void insertVerticesImpl (std::vector<GlobalCoordinate> const&,
std::vector<std::uint64_t> const&)
......@@ -88,8 +97,8 @@ public: // default implementations
/* do nothing */;
}
protected:
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.
*
* \param gridView Implementation of Dune::GridView
* \param format Format of the VTK file, either Vtk::BINARY, Vtk::ASCII, or Vtk::COMPRESSED
* \param datatype Output datatype used for coordinates and other global floating point values
**/
VtkWriterInterface (GridView const& gridView,
Vtk::FormatTypes format = Vtk::BINARY,
Vtk::DataTypes datatype = Vtk::FLOAT32)
......@@ -50,14 +63,21 @@ namespace Dune
#endif
}
/// Write the attached data to the file
/// \brief Write the attached data to the file
/**
* \param fn Filename of the VTK file. May contain a directory and any file extension.
* \param dir The optional parameter specifies the directory of the partition files.
* \param dir The optional parameter specifies the directory of the partition files for parallel writes.
**/
virtual void write (std::string const& fn, Std::optional<std::string> dir = {}) const override;
/// Attach point data to the writer, \see VtkFunction for possible arguments
/// \brief Attach point data to the writer
/**
* Attach a global function to the writer that will be evaluated at grid points
* (vertices and higher order points). The global function must be
* assignable to the function wrapper \ref VtkFunction. Additional argument
* for output datatype and number of components can be bassed. See \ref VtkFunction
* Constructor for possible arguments.
**/
template <class Function, class... Args>
VtkWriterInterface& addPointData (Function const& fct, Args&&... args)
{
......@@ -65,7 +85,13 @@ namespace Dune
return *this;
}
/// Attach cell data to the writer, \see VtkFunction for possible arguments
/// \brief Attach cell data to the writer
/**
* Attach a global function to the writer that will be evaluated at cell centers.
* The global function must be assignable to the function wrapper \ref VtkFunction.
* Additional argument for output datatype and number of components can be bassed.
* See \ref VtkFunction Constructor for possible arguments.
**/
template <class Function, class... Args>
VtkWriterInterface& addCellData (Function const& fct, Args&&... args)
{
......@@ -77,7 +103,7 @@ namespace Dune
/// Write a serial VTK file in Unstructured format
virtual void writeSerialFile (std::ofstream& out) const = 0;
/// Write a parallel VTK file `pfilename.pvtu` in Unstructured format,
/// Write a parallel VTK file `pfilename.pvtx` in XML format,
/// with `size` the number of pieces and serial files given by `pfilename_p[i].vtu`
/// for [i] in [0,...,size).
virtual void writeParallelFile (std::ofstream& out, std::string const& pfilename, int size) const = 0;
......@@ -90,19 +116,19 @@ namespace Dune
protected:
// Write the point or cell values given by the grid function `fct` to the
// output stream `out`. In case of binary format, stores the streampos of XML
// attributes "offset" in the vector `offsets`.
// output stream `out`. In case of binary format, append the streampos of XML
// attributes "offset" to the vector `offsets`.
void writeData (std::ofstream& out,
std::vector<pos_type>& offsets,
VtkFunction const& fct,
PositionTypes type,
Std::optional<std::size_t> timestep = {}) const;
// Write points-data and cell-data in raw/compressed format to output stream
// Write point-data and cell-data in raw/compressed format to output stream
void writeDataAppended (std::ofstream& out, std::vector<std::uint64_t>& blocks) const;
// Write the coordinates of the vertices to the output stream `out`. In case
// of binary format, stores the streampos of XML attributes "offset" in the
// of binary format, appends the streampos of XML attributes "offset" to the
// vector `offsets`.
void writePoints (std::ofstream& out,
std::vector<pos_type>& offsets,
......@@ -116,9 +142,12 @@ namespace Dune
template <class T>
std::uint64_t writeValuesAppended (std::ofstream& out, std::vector<T> const& values) const;
// Write the `values` in a space and newline separated list of ascii representations.
// The precision is controlled by the datatype and numerical_limits::digits10.
template <class T>
void writeValuesAscii (std::ofstream& out, std::vector<T> const& values) const;
// Write the XML file header of a VTK file `<VTKFile ...>`
void writeHeader (std::ofstream& out, std::string const& type) const;
/// Return PointData/CellData attributes for the name of the first scalar/vector/tensor DataArray
......@@ -137,16 +166,19 @@ namespace Dune
return fileExtension();
}
// Returns the VTK file format initialized in the constructor
Vtk::FormatTypes getFormat () const
{
return format_;
}
// Returns the global datatype used for coordinates and other global float values
Vtk::DataTypes getDatatype () const
{
return datatype_;
}
// Return the global MPI communicator.
auto comm () const
{
return MPIHelper::getCollectiveCommunication();
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment