[doc][freeflow] Improve docu for freeflow tests

test/freeflow/navierstokes/angeli/main.cc

@@ -18,10 +18,10 @@
  *****************************************************************************/
 /*!
  * \file
- *
- * \brief Test for the instationary staggered grid Navier-Stokes model with analytical solution (Angeli et al., 2017)
- * The unsteady, 2D, incompressible Navier-Stokes equations for a zero source and a Newtonian flow is solved and compared to an analytical solution (sums/products of trigonometric functions). The velocities and pressures decay exponentially. The Dirichlet boundary conditions are time-dependent and consistent with the analytical solution.
+ * \ingroup NavierStokesTests
+ * \brief Test for the instationary staggered grid Navier-Stokes model with analytical solution (Angeli et al., 2017).
  */
+
 #include <config.h>
 
 #include <ctime>

test/freeflow/navierstokes/angeli/problem.hh

@@ -21,6 +21,7 @@
  * \ingroup NavierStokesTests
  * \brief Test for the instationary staggered grid Navier-Stokes model with analytical solution (Angeli et al., 2017)
  */
+
 #ifndef DUMUX_ANGELI_TEST_PROBLEM_HH
 #define DUMUX_ANGELI_TEST_PROBLEM_HH
 
@@ -34,13 +35,11 @@
 #include <dumux/freeflow/navierstokes/model.hh>
 #include "../l2error.hh"
 
-namespace Dumux
-{
+namespace Dumux {
 template <class TypeTag>
 class AngeliTestProblem;
 
-namespace Properties
-{
+namespace Properties {
 // Create new type tags
 namespace TTag {
 struct AngeliTest { using InheritsFrom = std::tuple<NavierStokes, StaggeredFreeFlowModel>; };
@@ -71,13 +70,16 @@ template<class TypeTag>
 struct EnableGridFluxVariablesCache<TypeTag, TTag::AngeliTest> { static constexpr bool value = true; };
 template<class TypeTag>
 struct EnableGridVolumeVariablesCache<TypeTag, TTag::AngeliTest> { static constexpr bool value = true; };
-
-}
+} // end namespace Properties
 
 /*!
  * \ingroup NavierStokesTests
- * \brief  Test problem for the staggered grid (Angeli 1947)
- * \todo doc me!
+ * \brief  Test problem for the staggered grid (Angeli 1947).
+ *
+ * The unsteady, 2D, incompressible Navier-Stokes equations for a zero source and a Newtonian
+ * flow is solved and compared to an analytical solution (sums/products of trigonometric functions).
+ * The velocities and pressures decay exponentially. The Dirichlet boundary conditions are
+ * time-dependent and consistent with the analytical solution.
  */
 template <class TypeTag>
 class AngeliTestProblem : public NavierStokesProblem<TypeTag>
@@ -136,7 +138,7 @@ public:
     }
 
    /*!
-     * \brief Return the temperature within the domain in [K].
+     * \brief Returns the temperature within the domain in [K].
      *
      * This problem assumes a temperature of 10 degrees Celsius.
      */
@@ -145,7 +147,7 @@ public:
 
 
    /*!
-     * \brief Return the sources within the domain.
+     * \brief Returns the sources within the domain.
      *
      * \param globalPos The global position
      */
@@ -199,7 +201,7 @@ public:
     }
 
    /*!
-     * \brief Return dirichlet boundary values at a given position
+     * \brief Returns Dirichlet boundary values at a given position.
      *
      * \param globalPos The global position
      */
@@ -210,7 +212,7 @@ public:
     }
 
     /*!
-     * \brief Return the analytical solution of the problem at a given position
+     * \brief Returns the analytical solution of the problem at a given position.
      *
      * \param globalPos The global position
      * \param time The current simulation time
@@ -239,7 +241,7 @@ public:
     // \{
 
    /*!
-     * \brief Evaluate the initial value for a control volume.
+     * \brief Evaluates the initial value for a control volume.
      *
      * \param globalPos The global position
      */
@@ -249,7 +251,7 @@ public:
     }
 
    /*!
-     * \brief Returns the analytical solution for the pressure
+     * \brief Returns the analytical solution for the pressure.
      */
     auto& getAnalyticalPressureSolution() const
     {
@@ -257,7 +259,7 @@ public:
     }
 
    /*!
-     * \brief Returns the analytical solution for the velocity
+     * \brief Returns the analytical solution for the velocity.
      */
     auto& getAnalyticalVelocitySolution() const
     {
@@ -265,7 +267,7 @@ public:
     }
 
    /*!
-     * \brief Returns the analytical solution for the velocity at the faces
+     * \brief Returns the analytical solution for the velocity at the faces.
      */
     auto& getAnalyticalVelocitySolutionOnFace() const
     {
@@ -284,7 +286,9 @@ public:
     }
 
    /*!
-     * \brief Adds additional VTK output data to the VTKWriter. Function is called by the output module on every write.
+     * \brief Adds additional VTK output data to the VTKWriter.
+     *
+     * Function is called by the output module on every write.
      */
     void createAnalyticalSolution()
     {
@@ -331,6 +335,6 @@ private:
     std::vector<VelocityVector> analyticalVelocity_;
     std::vector<VelocityVector> analyticalVelocityOnFace_;
 };
-} //end namespace
+} // end namespace Dumux
 
 #endif

test/freeflow/navierstokes/channel/1d/main.cc

@@ -18,9 +18,10 @@
  *****************************************************************************/
 /*!
  * \file
- *
- * \brief Test for a 1-D staggered grid Navier-Stokes model
+ * \ingroup NavierStokesTests
+ * \brief Test for a 1-D staggered grid Navier-Stokes model.
  */
+
 #include <config.h>
 
 #include <ctime>

test/freeflow/navierstokes/channel/1d/problem.hh

@@ -19,7 +19,7 @@
 /*!
  * \file
  * \ingroup NavierStokesTests
- * \brief Test for the 1-D Navier-Stokes model with an analytical solution
+ * \brief Test for the 1-D Navier-Stokes model with an analytical solution.
  *
  * \copydoc Dumux::NavierStokesAnalyticProblem
  */
@@ -38,13 +38,11 @@
 #include "../../l2error.hh"
 
 
-namespace Dumux
-{
+namespace Dumux {
 template <class TypeTag>
 class NavierStokesAnalyticProblem;
 
-namespace Properties
-{
+namespace Properties {
 // Create new type tags
 namespace TTag {
 struct NavierStokesAnalytic { using InheritsFrom = std::tuple<NavierStokes, StaggeredFreeFlowModel>; };
@@ -76,15 +74,15 @@ struct EnableGridVolumeVariablesCache<TypeTag, TTag::NavierStokesAnalytic> { sta
 
 template<class TypeTag>
 struct NormalizePressure<TypeTag, TTag::NavierStokesAnalytic> { static constexpr bool value = false; };
-}
+} // end namespace Properties
 
 /*!
  * \ingroup NavierStokesTests
- * \brief Test for the 1-D Navier-Stokes model with an analytical solution
+ * \brief Test for the 1-D Navier-Stokes model with an analytical solution.
  *
  * The 1-D analytic solution is given by
  * \f[ p = 2 - 2 \cdot x \f]
- * \f[ v_\text{x} = 2 \cdot x^3 \f]
+ * \f[ v_\text{x} = 2 \cdot x^3 \f].
  */
 template <class TypeTag>
 class NavierStokesAnalyticProblem : public NavierStokesProblem<TypeTag>
@@ -144,7 +142,7 @@ public:
     }
 
    /*!
-     * \brief Return the temperature within the domain in [K].
+     * \brief Returns the temperature within the domain in [K].
      *
      * This problem assumes a temperature of 10 degrees Celsius.
      */
@@ -152,7 +150,7 @@ public:
     { return 298.0; }
 
    /*!
-     * \brief Return the sources within the domain.
+     * \brief Returns the sources within the domain.
      *
      * \param globalPos The global position
      */
@@ -239,7 +237,7 @@ public:
     }
 
    /*!
-     * \brief Return dirichlet boundary values at a given position
+     * \brief Returns Dirichlet boundary values at a given position
      *
      * \param globalPos The global position
      */
@@ -250,7 +248,7 @@ public:
     }
 
     /*!
-     * \brief Return the analytical solution of the problem at a given position
+     * \brief Returns the analytical solution of the problem at a given position
      *
      * \param globalPos The global position
      */
@@ -321,7 +319,7 @@ public:
     // \{
 
    /*!
-     * \brief Evaluate the initial value for a control volume.
+     * \brief Evaluates the initial value for a control volume.
      *
      * \param globalPos The global position
      */
@@ -339,7 +337,7 @@ public:
     }
 
    /*!
-     * \brief Returns the analytical solution for the velocity
+     * \brief Returns the analytical solution for the velocity.
      */
     auto& getAnalyticalVelocitySolution() const
     {
@@ -347,7 +345,7 @@ public:
     }
 
    /*!
-     * \brief Returns the analytical solution for the velocity at the faces
+     * \brief Returns the analytical solution for the velocity at the faces.
      */
     auto& getAnalyticalVelocitySolutionOnFace() const
     {
@@ -357,7 +355,9 @@ public:
 private:
 
    /*!
-     * \brief Adds additional VTK output data to the VTKWriter. Function is called by the output module on every write.
+     * \brief Adds additional VTK output data to the VTKWriter.
+     *
+     * Function is called by the output module on every write.
      */
     void createAnalyticalSolution_()
     {
@@ -401,6 +401,6 @@ private:
     std::vector<GlobalPosition> analyticalVelocity_;
     std::vector<GlobalPosition> analyticalVelocityOnFace_;
 };
-} //end namespace
+} // end namespace Dumux
 
 #endif

test/freeflow/navierstokes/channel/2d/main.cc

@@ -18,9 +18,10 @@
  *****************************************************************************/
 /*!
  * \file
- *
- * \brief Channel flow test for the staggered grid (Navier-)Stokes model
+ * \ingroup NavierStokesTests
+ * \brief Channel flow test for the staggered grid (Navier-)Stokes model.
  */
+
 #include <config.h>
 
 #include <ctime>

test/freeflow/navierstokes/channel/2d/problem.hh

@@ -19,8 +19,9 @@
 /*!
  * \file
  * \ingroup NavierStokesTests
- * \brief Channel flow test for the staggered grid (Navier-)Stokes model
+ * \brief Channel flow test for the staggered grid (Navier-)Stokes model.
  */
+
 #ifndef DUMUX_CHANNEL_TEST_PROBLEM_HH
 #define DUMUX_CHANNEL_TEST_PROBLEM_HH
 
@@ -34,13 +35,11 @@
 #include <dumux/discretization/staggered/freeflow/properties.hh>
 #include <dumux/freeflow/navierstokes/model.hh>
 
-namespace Dumux
-{
+namespace Dumux {
 template <class TypeTag>
 class ChannelTestProblem;
 
-namespace Properties
-{
+namespace Properties {
 // Create new type tags
 namespace TTag {
 #if !NONISOTHERMAL
@@ -77,12 +76,18 @@ template<class TypeTag>
 struct EnableGridFluxVariablesCache<TypeTag, TTag::ChannelTest> { static constexpr bool value = true; };
 template<class TypeTag>
 struct EnableGridVolumeVariablesCache<TypeTag, TTag::ChannelTest> { static constexpr bool value = true; };
-}
+} // end namespace Properties
 
 /*!
  * \ingroup NavierStokesTests
  * \brief  Test problem for the one-phase (Navier-) Stokes problem in a channel.
- * \todo doc me!
+ *
+ * Flow from left to right in a two-dimensional channel is considered. At the inlet (left),
+ * fixed values for velocity are set, while at the outlet (right), a fixed pressure
+ * boundary condition is used. The channel is confined by solid walls at the top and bottom
+ * of the domain which corresponds to no-slip/no-flow conditions.
+ * For the non-isothermal test, water of increased temperature is injected at the inlet
+ * while the walls are fully isolating.
  */
 template <class TypeTag>
 class ChannelTestProblem : public NavierStokesProblem<TypeTag>
@@ -122,7 +127,7 @@ public:
     }
 
    /*!
-     * \brief Return the temperature within the domain in [K].
+     * \brief Returns the temperature within the domain in [K].
      *
      * This problem assumes a temperature of 10 degrees Celsius.
      */
@@ -130,7 +135,7 @@ public:
     { return 273.15 + 10; } // 10C
 
    /*!
-     * \brief Return the sources within the domain.
+     * \brief Returns the sources within the domain.
      *
      * \param globalPos The global position
      */
@@ -182,8 +187,7 @@ public:
     }
 
    /*!
-     * \brief Evaluate the boundary conditions for a dirichlet
-     *        control volume.
+     * \brief Evaluates the boundary conditions for a Dirichlet control volume.
      *
      * \param globalPos The center of the finite volume which ought to be set.
      */
@@ -212,7 +216,7 @@ public:
     // \{
 
    /*!
-     * \brief Evaluate the initial value for a control volume.
+     * \brief Evaluates the initial value for a control volume.
      *
      * \param globalPos The global position
      */
@@ -259,6 +263,6 @@ private:
     Scalar inletVelocity_;
     TimeLoopPtr timeLoop_;
 };
-} //end namespace
+} // end namespace Dumux
 
 #endif

test/freeflow/navierstokes/channel/3d/main.cc

@@ -16,11 +16,12 @@
  *   You should have received a copy of the GNU General Public License       *
  *   along with this program.  If not, see <http://www.gnu.org/licenses/>.   *
  *****************************************************************************/
- /*!
-  * \file
-  *
-  * \brief 3D Channel flow test for the staggered grid (Navier-)Stokes model
-  */
+/*!
+ * \file
+ * \ingroup NavierStokesTests
+ * \brief 3D Channel flow test for the staggered grid (Navier-)Stokes model
+ */
+
 #include <config.h>
 
 #include <ctime>

test/freeflow/navierstokes/channel/3d/problem.hh

@@ -18,13 +18,13 @@
  *****************************************************************************/
 /*!
  * \file
- *
+ * \ingroup NavierStokesTests
  * \brief Channel flow test for the staggered grid (Navier-)Stokes model.
  *
  * The channel is either modeled in 3D or in 2D, using an additional wall friction term
  * to mimic the 3D behavior of the flow.
- *
  */
+
 #ifndef DUMUX_3D_CHANNEL_PROBLEM_HH
 #define DUMUX_3D_CHANNEL_PROBLEM_HH
 
@@ -42,15 +42,12 @@
 #define DIM_3D 0
 #endif
 
-namespace Dumux
-{
-
+namespace Dumux {
 
 template <class TypeTag>
 class ThreeDChannelTestProblem;
 
-namespace Properties
-{
+namespace Properties {
 // Create new type tags
 namespace TTag {
 struct ThreeDChannelTest { using InheritsFrom = std::tuple<NavierStokes, StaggeredFreeFlowModel>; };
@@ -83,11 +80,18 @@ template<class TypeTag>
 struct EnableGridFluxVariablesCache<TypeTag, TTag::ThreeDChannelTest> { static constexpr bool value = true; };
 template<class TypeTag>
 struct EnableGridVolumeVariablesCache<TypeTag, TTag::ThreeDChannelTest> { static constexpr bool value = true; };
-}
+} // end namespace Properties
 
 /*!
- * \brief  Test problem for the one-phase model:
-   \todo doc me!
+ * \brief Test problem for the one-phase (Navier-) Stokes model in a 3D or pseudo 3D channel.
+ *
+ * Flow from left to right in a three-dimensional channel is considered. At the inlet (left)
+ * and outlet (right) fixed values for pressure are set.
+ * The channel is confined by solid walls at all other sides of the domain which corresponds
+ * to no-slip/no-flow conditions.
+ * The value of an analytical solution for the given flow configuration is furthermore provided.
+ * For sake of efficiency, the 3D problem can be reduced to a two-dimensional one by including
+ * an additional wall friction term to the momentum balance (Flekkoy et al., 1995 \cite flekkoy1995a).
  */
 template <class TypeTag>
 class ThreeDChannelTestProblem : public NavierStokesProblem<TypeTag>
@@ -142,7 +146,7 @@ public:
     // \{
 
     /*!
-     * \brief Return the temperature within the domain in [K].
+     * \brief Returns the temperature within the domain in [K].
      *
      * This problem assumes a temperature of 10 degrees Celsius.
      */
@@ -151,8 +155,8 @@ public:
 
 
     /*!
-     * \brief Evaluate the source term for all phases within a given
-     *        sub-control-volume face.
+     * \brief Evaluates the source term for all phases within a given
+     *        sub-control volume face.
      */
     using ParentType::source;
     template<class ElementVolumeVariables, class ElementFaceVariables>
@@ -208,8 +212,7 @@ public:
     }
 
     /*!
-     * \brief Evaluate the boundary conditions for a dirichlet
-     *        control volume.
+     * \brief Evaluates the boundary conditions for a Dirichlet control volume.
      *
      * \param globalPos The center of the finite volume which ought to be set.
      */
@@ -229,7 +232,7 @@ public:
     // \}
 
     /*!
-     * \brief Evaluate the initial value for a control volume.
+     * \brief Evaluates the initial value for a control volume.
      *
      * \param globalPos The global position
      */
@@ -270,6 +273,6 @@ private:
     Scalar rho_;
     Scalar nu_;
 };
-} //end namespace
+} // end namespace Dumux
 
 #endif

test/freeflow/navierstokes/closedsystem/main.cc

@@ -18,9 +18,10 @@
  *****************************************************************************/
 /*!
  * \file
- *
- * \brief Test for the staggered grid Stokes model in a closed domain
+ * \ingroup NavierStokesTests
+ * \brief Test for the staggered grid Stokes model in a closed domain.
  */
+
 #include <config.h>
 
 #include <ctime>

test/freeflow/navierstokes/closedsystem/problem.hh

@@ -19,8 +19,9 @@
 /*!
  * \file
  * \ingroup NavierStokesTests
- * \brief A test problem for the staggered (Navier-) Stokes model
+ * \brief A test problem for the staggered (Navier-) Stokes model.
  */
+
 #ifndef DUMUX_CLOSEDSYSTEM_TEST_PROBLEM_HH
 #define DUMUX_CLOSEDSYSTEM_TEST_PROBLEM_HH
 
@@ -33,13 +34,11 @@
 #include <dumux/discretization/staggered/freeflow/properties.hh>
 #include <dumux/freeflow/navierstokes/model.hh>
 
-namespace Dumux
-{
+namespace Dumux {
 template <class TypeTag>
 class ClosedSystemTestProblem;
 
-namespace Properties
-{
+namespace Properties {
 // Create new type tags
 namespace TTag {
 struct ClosedSystemTest { using InheritsFrom = std::tuple<NavierStokes, StaggeredFreeFlowModel>; };
@@ -68,13 +67,16 @@ template<class TypeTag>
 struct EnableGridFluxVariablesCache<TypeTag, TTag::ClosedSystemTest> { static constexpr bool value = true; };
 template<class TypeTag>
 struct EnableGridVolumeVariablesCache<TypeTag, TTag::ClosedSystemTest> { static constexpr bool value = true; };
-
-}
+} // end namespace Properties
 
 /*!
  * \ingroup NavierStokesTests
- * \brief  Test problem for the one-phase model.
- * \todo doc me!
+ * \brief Test problem for the one-phase (Navier-) Stokes model.
+ *
+ * Here, a quadratic two-dimensional domain with closed walls at all sides is considered.
+ * If all walls are immobile and gravity is switched on, a hydrostatic pressure
+ * gradient will develop. When assigning a fixed velocity to the top wall (without gravity),
+ * this test corresponds to a lid-driven cavity problem.
  */
 template <class TypeTag>
 class ClosedSystemTestProblem : public NavierStokesProblem<TypeTag>
@@ -113,7 +115,7 @@ public:
     }
 
    /*!
-     * \brief Return the temperature within the domain in [K].
+     * \brief Returns the temperature within the domain in [K].
      *
      * This problem assumes a temperature of 10 degrees Celsius.
      */
@@ -121,7 +123,7 @@ public:
     { return 273.15 + 10; } // 10C
 
    /*!
-     * \brief Return the sources within the domain.
+     * \brief Returns the sources within the domain.
      *
      * \param globalPos The global position
      */
@@ -173,7 +175,7 @@ public:
     }
 
    /*!
-     * \brief Return dirichlet boundary values at a given position
+     * \brief Returns Dirichlet boundary values at a given position.
      *
      * \param globalPos The global position
      */
@@ -191,7 +193,7 @@ public:
     }
 
    /*!
-     * \brief Evaluate the initial value for a control volume.
+     * \brief Evaluates the initial value for a control volume.
      *
      * \param globalPos The global position
      */
@@ -212,6 +214,6 @@ private:
     Scalar eps_;
     Scalar lidVelocity_;
 };
-} //end namespace
+} // end namespace Dumux
 
 #endif

test/freeflow/navierstokes/donea/main.cc

@@ -18,9 +18,10 @@
  *****************************************************************************/
 /*!
  * \file
- *
- * \brief Test for the staggered grid Navier-Stokes model (Kovasznay 1947)
+ * \ingroup NavierStokesTests
+ * \brief Test for the staggered grid Navier-Stokes model (Kovasznay 1947).
  */
+
 #include <config.h>
 
 #include <ctime>

test/freeflow/navierstokes/kovasznay/main.cc

@@ -18,9 +18,10 @@
  *****************************************************************************/
 /*!
  * \file
- *
- * \brief Stationary test for the staggered grid Navier-Stokes model (Kovasznay 1947)
+ * \ingroup NavierStokesTests
+ * \brief Stationary test for the staggered grid Navier-Stokes model (Kovasznay 1947).
  */
+
 #include <config.h>
 
 #include <ctime>