[doc][style] Add doxygen documentation and fix code formatting

.clang-format

 ---
 Language:        Cpp
 # BasedOnStyle:  Chromium
-AccessModifierOffset: -1
+AccessModifierOffset: -4
 AlignAfterOpenBracket: Align
 AlignConsecutiveMacros: false
 AlignConsecutiveAssignments: false

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Not released yet
 
+- 2022-01-26: Renamed `dumupreciceindexwrapper.[hh|cc]` to `dumupreciceindexmapper.[hh|cc]` to be consistent with the class name.
+- 2022-01-26: Made sure all private member of the adapter are prefixed with an underscore.
+- 2022-01-26: Add and configure Doxygen code documentation of coupling adapter.
+- 2022-01-25: Fix code formatting configuration to be close to the original DuMuX code formatting configuration.
 - 2022-01-25: Added [description templates](https://docs.gitlab.com/ee/user/project/description_templates.html) for merge requests and issues.
 - 2022-01-12: The repository has been restructured. The main changes are:
 

doc/doxygen/Doxylocal

 # This file contains local changes to the doxygen configuration
 # please use '+=' to add files/directories to the lists
 
+PROJECT_NAME          = "DuMuX-preCICE"
+PROJECT_BRIEF         = "Adapter to couple DuMuX to other solver via preCICE"
+PROJECT_NUMBER        = @DUNE_MOD_VERSION@
+
 # The INPUT tag can be used to specify the files and/or directories that contain
 # documented source files. You may enter file names like "myfile.cpp" or
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                 += @top_srcdir@/dune/
+INPUT                 += @top_srcdir@/dumux-precice/ \
+                         @top_srcdir@/doc/doxygen \
 # see e.g. dune-grid for the examples of mainpage and modules
 # INPUT                 += @srcdir@/mainpage \
 #                          @srcdir@/modules
@@ -15,7 +20,7 @@ INPUT                 += @top_srcdir@/dune/
 # excluded from the INPUT source files. This way you can easily exclude a
 # subdirectory from a directory tree whose root is specified with the INPUT tag.
 
-# EXCLUDE               += @top_srcdir@/dune/dumux-precice/test
+EXCLUDE               += @top_srcdir@/dumux-precice/dumux-addon/
 
 # The EXAMPLE_PATH tag can be used to specify one or more files or
 # directories that contain example code fragments that are included (see
@@ -28,3 +33,6 @@ INPUT                 += @top_srcdir@/dune/
 # the \image command).
 
 # IMAGE_PATH            += @top_srcdir@/dune/dumux-precice/pics
+
+
+FILE_PATTERNS += *.hh *.dox

doc/doxygen/main.dox

+/*! \mainpage DuMuX-preCICE adapter
+ *
+ * This project helps with coupling DuMuX-based solvers
+ * with other solvers via the coupling library preCICE.
+ *
+ */
\ No newline at end of file

dumux-precice/CMakeLists.txt

@@ -2,7 +2,7 @@ install(FILES
 	couplingadapter.hh
 	DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/dumux-precice)
 
-add_library(dumux-precice STATIC couplingadapter.cc dumuxpreciceindexwrapper.cc)
+add_library(dumux-precice STATIC couplingadapter.cc dumuxpreciceindexmapper.cc)
 target_link_libraries(dumux-precice PRIVATE precice::precice)
 
 add_subdirectory(dumux-addon)

dumux-precice/couplingadapter.cc

@@ -7,17 +7,17 @@
 using namespace Dumux::Precice;
 
 CouplingAdapter::CouplingAdapter()
-    : wasCreated_(false),
-      precice_(nullptr),
-      meshWasCreated_(false),
-      preciceWasInitialized_(false),
-      hasIndexMapper_(false),
-      meshID_(0),
-      timeStepSize_(0.)
+    : _wasCreated(false),
+      _precice(nullptr),
+      _meshWasCreated(false),
+      _preciceWasInitialized(false),
+      _hasIndexMapper(false),
+      _meshID(0),
+      _timeStepSize(0.)
 {
-    preciceDataID_.reserve(reserveSize_);
-    dataNames_.reserve(reserveSize_);
-    dataVectors_.reserve(reserveSize_);
+    _preciceDataID.reserve(_reserveSize);
+    _dataNames.reserve(_reserveSize);
+    _dataVectors.reserve(_reserveSize);
 }
 
 CouplingAdapter &CouplingAdapter::getInstance()
@@ -27,79 +27,79 @@ CouplingAdapter &CouplingAdapter::getInstance()
 }
 
 void CouplingAdapter::announceSolver(const std::string &name,
-                                    const std::string configurationFileName,
-                                    const int rank,
-                                    const int size)
+                                     const std::string configurationFileName,
+                                     const int rank,
+                                     const int size)
 {
-    assert(precice_ == nullptr);
-    precice_ = std::make_unique<precice::SolverInterface>(
+    assert(_precice == nullptr);
+    _precice = std::make_unique<precice::SolverInterface>(
         name, configurationFileName, rank, size);
-    wasCreated_ = true;
+    _wasCreated = true;
 }
 
 size_t CouplingAdapter::announceQuantity(const std::string &name)
 {
-    assert(meshWasCreated_);
-    auto it = std::find(dataNames_.begin(), dataNames_.end(), name);
-    if (it != dataNames_.end()) {
+    assert(_meshWasCreated);
+    auto it = std::find(_dataNames.begin(), _dataNames.end(), name);
+    if (it != _dataNames.end()) {
         throw(std::runtime_error(" Error! Duplicate quantity announced! "));
     }
-    dataNames_.push_back(name);
-    preciceDataID_.push_back(precice_->getDataID(name, meshID_));
-    dataVectors_.push_back(std::vector<double>(vertexIDs_.size()));
+    _dataNames.push_back(name);
+    _preciceDataID.push_back(_precice->getDataID(name, _meshID));
+    _dataVectors.push_back(std::vector<double>(_vertexIDs.size()));
 
     return getNumberOfQuantities() - 1;
 }
 
 int CouplingAdapter::getDimensions() const
 {
-    assert(wasCreated_);
-    return precice_->getDimensions();
+    assert(_wasCreated);
+    return _precice->getDimensions();
 }
 /*
 void CouplingAdapter::setMeshName(const std::string& meshName)
 {
-  assert( wasCreated_ );
-  meshID_ = precice_->getMeshID(meshName);
+  assert( _wasCreated );
+  _meshID = _precice->getMeshID(meshName);
 }
 */
 
 void CouplingAdapter::setMesh(const std::string &meshName,
-                             const size_t numPoints,
-                             std::vector<double> &coordinates)
+                              const size_t numPoints,
+                              std::vector<double> &coordinates)
 {
-    assert(wasCreated_);
+    assert(_wasCreated);
     assert(numPoints == coordinates.size() / getDimensions());
-    meshID_ = precice_->getMeshID(meshName);
-    vertexIDs_.resize(numPoints);
-    precice_->setMeshVertices(meshID_, numPoints, coordinates.data(),
-                              vertexIDs_.data());
-    meshWasCreated_ = true;
+    _meshID = _precice->getMeshID(meshName);
+    _vertexIDs.resize(numPoints);
+    _precice->setMeshVertices(_meshID, numPoints, coordinates.data(),
+                              _vertexIDs.data());
+    _meshWasCreated = true;
 }
 
 double CouplingAdapter::initialize()
 {
-    assert(wasCreated_);
-    assert(meshWasCreated_);
-    assert(!preciceWasInitialized_);
+    assert(_wasCreated);
+    assert(_meshWasCreated);
+    assert(!_preciceWasInitialized);
 
-    timeStepSize_ = precice_->initialize();
-    assert(timeStepSize_ > 0);
+    _timeStepSize = _precice->initialize();
+    assert(_timeStepSize > 0);
 
-    preciceWasInitialized_ = true;
-    return timeStepSize_;
+    _preciceWasInitialized = true;
+    return _timeStepSize;
 }
 
 void CouplingAdapter::createIndexMapping(const std::vector<int> &dumuxFaceIDs)
 {
-    assert(meshWasCreated_);
-    indexMapper_.createMapping(dumuxFaceIDs, vertexIDs_);
-    hasIndexMapper_ = true;
+    assert(_meshWasCreated);
+    _indexMapper.createMapping(dumuxFaceIDs, _vertexIDs);
+    _hasIndexMapper = true;
 }
 
 double CouplingAdapter::setMeshAndInitialize(const std::string &meshName,
-                                            const size_t numPoints,
-                                            std::vector<double> &coordinates)
+                                             const size_t numPoints,
+                                             std::vector<double> &coordinates)
 {
     setMesh(meshName, numPoints, coordinates);
     return initialize();
@@ -107,66 +107,66 @@ double CouplingAdapter::setMeshAndInitialize(const std::string &meshName,
 
 void CouplingAdapter::initializeData()
 {
-    assert(preciceWasInitialized_);
-    precice_->initializeData();
+    assert(_preciceWasInitialized);
+    _precice->initializeData();
 }
 
 void CouplingAdapter::finalize()
 {
-    assert(wasCreated_);
-    if (preciceWasInitialized_)
-        precice_->finalize();
+    assert(_wasCreated);
+    if (_preciceWasInitialized)
+        _precice->finalize();
 }
 
 double CouplingAdapter::advance(const double computedTimeStepLength)
 {
-    assert(wasCreated_);
-    return precice_->advance(computedTimeStepLength);
+    assert(_wasCreated);
+    return _precice->advance(computedTimeStepLength);
 }
 
 bool CouplingAdapter::isCouplingOngoing()
 {
-    assert(wasCreated_);
-    return precice_->isCouplingOngoing();
+    assert(_wasCreated);
+    return _precice->isCouplingOngoing();
 }
 
 size_t CouplingAdapter::getNumberOfVertices()
 {
-    assert(wasCreated_);
-    return vertexIDs_.size();
+    assert(_wasCreated);
+    return _vertexIDs.size();
 }
 
 double CouplingAdapter::getScalarQuantityOnFace(const size_t dataID,
-                                               const int faceID) const
+                                                const int faceID) const
 {
-    assert(wasCreated_);
-    assert(hasIndexMapper_);
-    if (!hasIndexMapper_) {
+    assert(_wasCreated);
+    assert(_hasIndexMapper);
+    if (!_hasIndexMapper) {
         throw std::runtime_error(
             "Reading quantity using faceID, but index mapping was not "
             "created!");
     }
-    const auto idx = indexMapper_.getPreciceId(faceID);
-    assert(dataID < dataVectors_.size());
-    const std::vector<double> &quantityVector = dataVectors_[dataID];
+    const auto idx = _indexMapper.getPreciceId(faceID);
+    assert(dataID < _dataVectors.size());
+    const std::vector<double> &quantityVector = _dataVectors[dataID];
     assert(idx < quantityVector.size());
     return quantityVector[idx];
 }
 
 void CouplingAdapter::writeScalarQuantityOnFace(const size_t dataID,
-                                               const int faceID,
-                                               const double value)
+                                                const int faceID,
+                                                const double value)
 {
-    assert(wasCreated_);
-    assert(hasIndexMapper_);
-    if (!hasIndexMapper_) {
+    assert(_wasCreated);
+    assert(_hasIndexMapper);
+    if (!_hasIndexMapper) {
         throw std::runtime_error(
             "Writing quantity using faceID, but index mapping was not "
             "created!");
     }
-    const auto idx = indexMapper_.getPreciceId(faceID);
-    assert(dataID < dataVectors_.size());
-    std::vector<double> &quantityVector = dataVectors_[dataID];
+    const auto idx = _indexMapper.getPreciceId(faceID);
+    assert(dataID < _dataVectors.size());
+    std::vector<double> &quantityVector = _dataVectors[dataID];
     assert(idx < quantityVector.size());
     quantityVector[idx] = value;
 }
@@ -176,16 +176,16 @@ void CouplingAdapter::writeScalarQuantityOnFace(const size_t dataID,
 //                                               const double* value,
 //                                               const size_t size)
 //{
-//  assert( wasCreated_ );
-//  assert( hasIndexMapper_ );
+//  assert( _wasCreated );
+//  assert( _hasIndexMapper );
 //  assert( size == getDimensions() );
-//  if ( !hasIndexMapper_ )
+//  if ( !_hasIndexMapper )
 //  {
 //    throw std::runtime_error("Writing quantity using faceID, but index mapping was not created!");
 //  }
-//  const auto idx = indexMapper_.getPreciceId( faceID ) * size;
-//  assert( dataID < dataVectors_.size() );
-//  std::vector<double>& quantityVector = dataVectors_[ dataID ];
+//  const auto idx = _indexMapper.getPreciceId( faceID ) * size;
+//  assert( dataID < _dataVectors.size() );
+//  std::vector<double>& quantityVector = _dataVectors[ dataID ];
 //  assert( idx < quantityVector.size() );
 //  //quantityVector[idx] = value;
 //  std::copy_n( value, size, quantityVector[idx] );
@@ -193,142 +193,142 @@ void CouplingAdapter::writeScalarQuantityOnFace(const size_t dataID,
 
 std::vector<double> &CouplingAdapter::getQuantityVector(const size_t dataID)
 {
-    assert(wasCreated_);
-    assert(dataID < dataVectors_.size());
-    return dataVectors_[dataID];
+    assert(_wasCreated);
+    assert(dataID < _dataVectors.size());
+    return _dataVectors[dataID];
 }
 
 const std::vector<double> &CouplingAdapter::getQuantityVector(
     const size_t dataID) const
 {
-    assert(wasCreated_);
+    assert(_wasCreated);
     return getQuantityVector(dataID);
 }
 
 void CouplingAdapter::writeScalarQuantityVector(const size_t dataID,
-                                               std::vector<double> &values)
+                                                std::vector<double> &values)
 {
-    assert(wasCreated_);
-    assert(dataID < dataVectors_.size());
-    assert(dataVectors_[dataID].size() == values.size());
-    dataVectors_[dataID] = values;
+    assert(_wasCreated);
+    assert(dataID < _dataVectors.size());
+    assert(_dataVectors[dataID].size() == values.size());
+    _dataVectors[dataID] = values;
 }
 
 void CouplingAdapter::writeScalarQuantityToOtherSolver(const size_t dataID)
 {
-    assert(wasCreated_);
-    assert(dataID < dataVectors_.size());
-    assert(dataID < preciceDataID_.size());
+    assert(_wasCreated);
+    assert(dataID < _dataVectors.size());
+    assert(dataID < _preciceDataID.size());
     assert(dataID < std::numeric_limits<int>::max());
-    writeBlockScalarDataToPrecice(preciceDataID_[dataID], dataVectors_[dataID]);
+    writeBlockScalarDataToPrecice(_preciceDataID[dataID], _dataVectors[dataID]);
 }
 
 void CouplingAdapter::readScalarQuantityFromOtherSolver(const size_t dataID)
 {
-    assert(wasCreated_);
-    assert(dataID < dataVectors_.size());
-    assert(dataID < preciceDataID_.size());
+    assert(_wasCreated);
+    assert(dataID < _dataVectors.size());
+    assert(dataID < _preciceDataID.size());
     assert(dataID < std::numeric_limits<int>::max());
-    readBlockScalarDataFromPrecice(preciceDataID_[dataID],
-                                   dataVectors_[dataID]);
+    readBlockScalarDataFromPrecice(_preciceDataID[dataID],
+                                   _dataVectors[dataID]);
 }
 
 bool CouplingAdapter::isCoupledEntity(const int faceID) const
 {
-    assert(wasCreated_);
-    return indexMapper_.isDumuxIdMapped(faceID);
+    assert(_wasCreated);
+    return _indexMapper.isDumuxIdMapped(faceID);
 }
 
 size_t CouplingAdapter::getIdFromName(const std::string &dataName) const
 {
-    assert(wasCreated_);
-    const auto it = std::find(dataNames_.begin(), dataNames_.end(), dataName);
-    if (it == dataNames_.end()) {
+    assert(_wasCreated);
+    const auto it = std::find(_dataNames.begin(), _dataNames.end(), dataName);
+    if (it == _dataNames.end()) {
         throw(std::runtime_error(" Error! Name of data not found! "));
     }
-    const auto idx = std::distance(dataNames_.begin(), it);
+    const auto idx = std::distance(_dataNames.begin(), it);
     assert(idx > -1);
     return size_t(idx);
 }
 
 std::string CouplingAdapter::getNameFromId(const size_t dataID) const
 {
-    assert(wasCreated_);
-    assert(dataID < dataNames_.size());
-    return dataNames_[dataID];
+    assert(_wasCreated);
+    assert(dataID < _dataNames.size());
+    return _dataNames[dataID];
 }
 
 void CouplingAdapter::print(std::ostream &os)
 {
-    os << indexMapper_;
+    os << _indexMapper;
 }
 
 bool CouplingAdapter::checkIfActionIsRequired(const std::string &condition)
 {
-    assert(wasCreated_);
-    return precice_->isActionRequired(condition);
+    assert(_wasCreated);
+    return _precice->isActionRequired(condition);
 }
 
 void CouplingAdapter::actionIsFulfilled(const std::string &condition)
 {
-    assert(wasCreated_);
-    precice_->markActionFulfilled(condition);
+    assert(_wasCreated);
+    _precice->markActionFulfilled(condition);
 }
 
 void CouplingAdapter::readBlockScalarDataFromPrecice(const int dataID,
-                                                    std::vector<double> &data)
+                                                     std::vector<double> &data)
 {
-    assert(wasCreated_);
-    assert(vertexIDs_.size() == data.size());
-    precice_->readBlockScalarData(dataID, vertexIDs_.size(), vertexIDs_.data(),
+    assert(_wasCreated);
+    assert(_vertexIDs.size() == data.size());
+    _precice->readBlockScalarData(dataID, _vertexIDs.size(), _vertexIDs.data(),
                                   data.data());
 }
 
 void CouplingAdapter::writeBlockScalarDataToPrecice(const int dataID,
-                                                   std::vector<double> &data)
+                                                    std::vector<double> &data)
 {
-    assert(wasCreated_);
-    assert(vertexIDs_.size() == data.size());
-    precice_->writeBlockScalarData(dataID, vertexIDs_.size(), vertexIDs_.data(),
+    assert(_wasCreated);
+    assert(_vertexIDs.size() == data.size());
+    _precice->writeBlockScalarData(dataID, _vertexIDs.size(), _vertexIDs.data(),
                                    data.data());
 }
 
 bool CouplingAdapter::hasToWriteInitialData()
 {
-    assert(wasCreated_);
+    assert(_wasCreated);
     return checkIfActionIsRequired(
         precice::constants::actionWriteInitialData());
 }
 
 void CouplingAdapter::announceInitialDataWritten()
 {
-    assert(wasCreated_);
-    precice_->markActionFulfilled(precice::constants::actionWriteInitialData());
+    assert(_wasCreated);
+    _precice->markActionFulfilled(precice::constants::actionWriteInitialData());
 }
 
 bool CouplingAdapter::hasToReadIterationCheckpoint()
 {
-    assert(wasCreated_);
+    assert(_wasCreated);
     return checkIfActionIsRequired(
         precice::constants::actionReadIterationCheckpoint());
 }
 
 void CouplingAdapter::announceIterationCheckpointRead()
 {
-    assert(wasCreated_);
+    assert(_wasCreated);
     actionIsFulfilled(precice::constants::actionReadIterationCheckpoint());
 }
 
 bool CouplingAdapter::hasToWriteIterationCheckpoint()
 {
-    assert(wasCreated_);
+    assert(_wasCreated);
     return checkIfActionIsRequired(
         precice::constants::actionWriteIterationCheckpoint());
 }
 
 void CouplingAdapter::announceIterationCheckpointWritten()
 {
-    assert(wasCreated_);
+    assert(_wasCreated);
     actionIsFulfilled(precice::constants::actionWriteIterationCheckpoint());
 }
 

dumux-precice/couplingadapter.hh

@@ -5,125 +5,353 @@
 #include <precice/SolverInterface.hpp>
 #include <string>
 
-#include "dumuxpreciceindexwrapper.hh"
+#include "dumuxpreciceindexmapper.hh"
 
+/*!
+ * @brief Namespace of dumux-precice
+ *
+ */
 namespace Dumux::Precice
 {
+/*!
+ * @brief A DuMuX-preCICE coupling adapter class
+ *
+ * The class provides an interface to DuMuX to couple simulations
+ * via the coupling tool preCICE. The class aims to provide an
+ * easy-to-use interface that is reasonably close to the coupling
+ * interface for monolithic couplings that is integrated into DuMuX.
+ *
+ * \note The coupling adapter is currently implemented as a Singleton.
+ *
+ */
 class CouplingAdapter
 {
-   private:
-    bool wasCreated_;
-    std::unique_ptr<precice::SolverInterface> precice_;
-
+private:
+    //! True if preCICE instance was initiated
+    bool _wasCreated;
+    //! Pointer to preCICE instance
+    std::unique_ptr<precice::SolverInterface> _precice;
+    //! Constructor
     CouplingAdapter();
-
+    /*!
+     * @brief Checks whether an action predefined by preCICE
+     *        needs to be carried out.
+     *
+     * @param[in] condition Name of the action.
+     * @return true Action must be carried out.
+     * @return false Action must not be carried out.
+     */
     bool checkIfActionIsRequired(const std::string &condition);
+    /*!
+     * @brief Announce to preCICE that an action was carried out.
+     *
+     * @param[in] condition Name of the action.
+     */
     void actionIsFulfilled(const std::string &condition);
-
+    /*!
+     * @brief Reads full block of data from preCICE.
+     *
+     * @param[in] dataID Identifier of dataset to read.
+     * @param[out] data Vector to store the read data to.
+     */
     void readBlockScalarDataFromPrecice(const int dataID,
                                         std::vector<double> &data);
+    /*!
+     * @brief Writes full block of data to preCICE.
+     *
+     * @param[in] dataID Identifier of dataset to read.
+     * @param[in] data Vector containing data to write into preCICE's buffer.
+     */
     void writeBlockScalarDataToPrecice(const int dataID,
                                        std::vector<double> &data);
-
-    size_t numberOfQuantities() const { return dataNames_.size(); }
-
-    bool meshWasCreated_;
-    bool preciceWasInitialized_;
-    bool hasIndexMapper_;
-    int meshID_;
-
-    double timeStepSize_;
-
-    std::vector<std::string> dataNames_;