Fix changes suggested by @bangerth.

+ Add explanations for CGS,FCG and IR.
+ Fix the doxygen @param with [in,out] qualifications.
+ Add empty lines and fix a typo.
+ Change cerr to Assert.

diff --git a/include/deal.II/lac/ginkgo_solver.h b/include/deal.II/lac/ginkgo_solver.h
index 9f4116d0d9a3ae14b683c80fa194903e28be3396..a0e428d0505f99242c870a1ad939afab811b02a1 100644 (file)
--- a/include/deal.II/lac/ginkgo_solver.h
+++ b/include/deal.II/lac/ginkgo_solver.h
@@ -198,7 +198,7 @@ namespace GinkgoWrappers
     std::shared_ptr<gko::matrix::Csr<ValueType, IndexType>> system_matrix;
 
     /**
-     * The execution paradigm as a string to be set by the user . The choices
+     * The execution paradigm as a string to be set by the user. The choices
      * are between `omp`, `cuda` and `reference` and more details can be found
      * in Ginkgo's documentation.
      */
@@ -224,11 +224,13 @@ namespace GinkgoWrappers
     /**
      * Constructor.
      *
-     * @p solver_control The solver control object is then used to set the
-     * parameters and setup the CG solver from the CG factory which solves the
-     * linear system.
+     * @param[in,out] solver_control The solver control object is then used to
+     * set the parameters and setup the CG solver from the CG factory which
+     * solves the linear system.
+     *
+     * @param[in] exec_type The execution paradigm for the CG solver.
      *
-     * @p exec_type The execution paradigm for the CG solver.
+     * @param[in] data The additional data required by the solver.
      */
     SolverCG(SolverControl &       solver_control,
              const std::string &   exec_type,
@@ -237,13 +239,15 @@ namespace GinkgoWrappers
     /**
      * Constructor.
      *
-     * @p solver_control The solver control object is then used to set the
-     * parameters and setup the CG solver from the CG factory which solves the
-     * linear system.
+     * @param[in,out] solver_control The solver control object is then used to
+     * set the parameters and setup the CG solver from the CG factory which
+     * solves the linear system.
+     *
+     * @param[in] exec_type The execution paradigm for the CG solver.
      *
-     * @p exec_type The execution paradigm for the CG solver.
+     * @param[in] preconditioner The preconditioner for the solver.
      *
-     * @p preconditioner The preconditioner for the solver.
+     * @param[in] data The additional data required by the solver.
      */
     SolverCG(SolverControl &                           solver_control,
              const std::string &                       exec_type,
@@ -276,11 +280,13 @@ namespace GinkgoWrappers
     /**
      * Constructor.
      *
-     * @p solver_control The solver control object is then used to set the
-     * parameters and setup the Bicgstab solver from the Bicgstab factory which
-     * solves the linear system.
+     * @param[in,out] solver_control The solver control object is then used to
+     * set the parameters and setup the Bicgstab solver from the Bicgstab
+     * factory which solves the linear system.
+     *
+     * @param[in] exec_type The execution paradigm for the Bicgstab solver.
      *
-     * @p exec_type The execution paradigm for the Bicgstab solver.
+     * @param[in] data The additional data required by the solver.
      */
     SolverBicgstab(SolverControl &       solver_control,
                    const std::string &   exec_type,
@@ -289,13 +295,15 @@ namespace GinkgoWrappers
     /**
      * Constructor.
      *
-     * @p solver_control The solver control object is then used to set the
-     * parameters and setup the Bicgstab solver from the Bicgstab factory which
-     * solves the linear system.
+     * @param[in,out] solver_control The solver control object is then used to
+     * set the parameters and setup the Bicgstab solver from the Bicgstab
+     * factory which solves the linear system.
      *
-     * @p exec_type The execution paradigm for the Bicgstab solver.
+     * @param[in] exec_type The execution paradigm for the Bicgstab solver.
      *
-     * @p preconditioner The preconditioner for the solver.
+     * @param[in] preconditioner The preconditioner for the solver.
+     *
+     * @param[in] data The additional data required by the solver.
      */
     SolverBicgstab(SolverControl &                           solver_control,
                    const std::string &                       exec_type,
@@ -312,6 +320,9 @@ namespace GinkgoWrappers
   /**
    * An implementation of the solver interface using the Ginkgo CGS solver.
    *
+   * CGS or the conjugate gradient square method is an iterative type Krylov
+   * subspace method which is suitable for general systems.
+   *
    * @ingroup GinkgoWrappers
    */
   template <typename ValueType = double, typename IndexType = int32_t>
@@ -327,11 +338,13 @@ namespace GinkgoWrappers
     /**
      * Constructor.
      *
-     * @p solver_control The solver control object is then used to set the
-     * parameters and setup the CGS solver from the CGS factory which solves the
-     * linear system.
+     * @param[in,out] solver_control The solver control object is then used to
+     * set the parameters and setup the CGS solver from the CGS factory which
+     * solves the linear system.
+     *
+     * @param[in] exec_type The execution paradigm for the CGS solver.
      *
-     * @p exec_type The execution paradigm for the CGS solver.
+     * @param[in] data The additional data required by the solver.
      */
     SolverCGS(SolverControl &       solver_control,
               const std::string &   exec_type,
@@ -340,13 +353,15 @@ namespace GinkgoWrappers
     /**
      * Constructor.
      *
-     * @p solver_control The solver control object is then used to set the
-     * parameters and setup the CGS solver from the CGS factory which solves the
-     * linear system.
+     * @param[in,out] solver_control The solver control object is then used to
+     * set the parameters and setup the CGS solver from the CGS factory which
+     * solves the linear system.
+     *
+     * @param[in] exec_type The execution paradigm for the CGS solver.
      *
-     * @p exec_type The execution paradigm for the CGS solver.
+     * @param[in] preconditioner The preconditioner for the solver.
      *
-     * @p preconditioner The preconditioner for the solver.
+     * @param[in] data The additional data required by the solver.
      */
     SolverCGS(SolverControl &                           solver_control,
               const std::string &                       exec_type,
@@ -363,6 +378,18 @@ namespace GinkgoWrappers
   /**
    * An implementation of the solver interface using the Ginkgo FCG solver.
    *
+   * FCG or the flexible conjugate gradient method is an iterative type Krylov
+   * subspace method which is suitable for symmetric positive definite methods.
+   *
+   * Though this method performs very well for symmetric positive definite
+   * matrices, it is in general not suitable for general matrices.
+   *
+   * In contrast to the standard CG based on the Polack-Ribiere formula, the
+   * flexible CG uses the Fletcher-Reeves formula for creating the orthonormal
+   * vectors spanning the Krylov subspace. This increases the computational cost
+   * of every Krylov solver iteration but allows for non-constant
+   * preconditioners.
+   *
    * @ingroup GinkgoWrappers
    */
   template <typename ValueType = double, typename IndexType = int32_t>
@@ -378,11 +405,13 @@ namespace GinkgoWrappers
     /**
      * Constructor.
      *
-     * @p solver_control The solver control object is then used to set the
-     * parameters and setup the FCG solver from the FCG factory which solves the
-     * linear system.
+     * @param[in,out] solver_control The solver control object is then used to
+     * set the parameters and setup the FCG solver from the FCG factory which
+     * solves the linear system.
+     *
+     * @param[in] exec_type The execution paradigm for the FCG solver.
      *
-     * @p exec_type The execution paradigm for the FCG solver.
+     * @param[in] data The additional data required by the solver.
      */
     SolverFCG(SolverControl &       solver_control,
               const std::string &   exec_type,
@@ -391,13 +420,15 @@ namespace GinkgoWrappers
     /**
      * Constructor.
      *
-     * @p solver_control The solver control object is then used to set the
-     * parameters and setup the FCG solver from the FCG factory which solves the
-     * linear system.
+     * @param[in,out] solver_control The solver control object is then used to
+     * set the parameters and setup the FCG solver from the FCG factory which
+     * solves the linear system.
+     *
+     * @param[in] exec_type The execution paradigm for the FCG solver.
      *
-     * @p exec_type The execution paradigm for the FCG solver.
+     * @param[in] preconditioner The preconditioner for the solver.
      *
-     * @p preconditioner The preconditioner for the solver.
+     * @param[in] data The additional data required by the solver.
      */
     SolverFCG(SolverControl &                           solver_control,
               const std::string &                       exec_type,
@@ -440,11 +471,13 @@ namespace GinkgoWrappers
     /**
      * Constructor.
      *
-     * @p solver_control The solver control object is then used to set the
-     * parameters and setup the GMRES solver from the GMRES factory which solves
-     * the linear system.
+     * @param[in,out] solver_control The solver control object is then used to
+     * set the parameters and setup the GMRES solver from the GMRES factory
+     * which solves the linear system.
+     *
+     * @param[in] exec_type The execution paradigm for the GMRES solver.
      *
-     * @p exec_type The execution paradigm for the GMRES solver.
+     * @param[in] data The additional data required by the solver.
      */
     SolverGMRES(SolverControl &       solver_control,
                 const std::string &   exec_type,
@@ -453,13 +486,15 @@ namespace GinkgoWrappers
     /**
      * Constructor.
      *
-     * @p solver_control The solver control object is then used to set the
-     * parameters and setup the GMRES solver from the GMRES factory which solves
-     * the linear system.
+     * @param[in,out] solver_control The solver control object is then used to
+     * set the parameters and setup the GMRES solver from the GMRES factory
+     * which solves the linear system.
      *
-     * @p exec_type The execution paradigm for the GMRES solver.
+     * @param[in] exec_type The execution paradigm for the GMRES solver.
      *
-     * @p preconditioner The preconditioner for the solver.
+     * @param[in] preconditioner The preconditioner for the solver.
+     *
+     * @param[in] data The additional data required by the solver.
      */
     SolverGMRES(SolverControl &                           solver_control,
                 const std::string &                       exec_type,
@@ -476,6 +511,10 @@ namespace GinkgoWrappers
   /**
    * An implementation of the solver interface using the Ginkgo IR solver.
    *
+   * Iterative refinement (IR) is an iterative method that uses another coarse
+   * method to approximate the error of the current solution via the current
+   * residual.
+   *
    * @ingroup GinkgoWrappers
    */
   template <typename ValueType = double, typename IndexType = int32_t>
@@ -491,11 +530,13 @@ namespace GinkgoWrappers
     /**
      * Constructor.
      *
-     * @p solver_control The solver control object is then used to set the
-     * parameters and setup the IR solver from the IR factory which solves the
-     * linear system.
+     * @param[in,out] solver_control The solver control object is then used to
+     * set the parameters and setup the IR solver from the IR factory which
+     * solves the linear system.
+     *
+     * @param[in] exec_type The execution paradigm for the IR solver.
      *
-     * @p exec_type The execution paradigm for the IR solver.
+     * @param[in] data The additional data required by the solver.
      */
     SolverIR(SolverControl &       solver_control,
              const std::string &   exec_type,
@@ -504,13 +545,15 @@ namespace GinkgoWrappers
     /**
      * Constructor.
      *
-     * @p solver_control The solver control object is then used to set the
-     * parameters and setup the IR solver from the IR factory which solves the
-     * linear system.
+     * @param[in,out] solver_control The solver control object is then used to
+     * set the parameters and setup the IR solver from the IR factory which
+     * solves the linear system.
+     *
+     * @param[in] exec_type The execution paradigm for the IR solver.
      *
-     * @p exec_type The execution paradigm for the IR solver.
+     * @param[in] inner_solver The Inner solver for the IR solver.
      *
-     * @p inner_solver The Inner solver for the IR solver.
+     * @param[in] data The additional data required by the solver.
      */
     SolverIR(SolverControl &                           solver_control,
              const std::string &                       exec_type,

diff --git a/source/lac/ginkgo_solver.cc b/source/lac/ginkgo_solver.cc
index f79e10d29bd4032e87634fbcc6e4ccb07ec08424..4415c83d764a6e477a8fa55efe06045228ca0359 100644 (file)
--- a/source/lac/ginkgo_solver.cc
+++ b/source/lac/ginkgo_solver.cc
@@ -50,10 +50,10 @@ namespace GinkgoWrappers
       }
     else
       {
-        std::cerr
-          << "exec_type needs to be one of the three strings: \"reference\", \"cuda\" or \"omp\", but provided with"
-          << exec_type << std::endl;
-        std::exit(-1);
+        Assert(
+          false,
+          ExcMessage(
+            " exec_type needs to be one of the three strings: \"reference\", \"cuda\" or \"omp\" "));
       }
     using ResidualCriterionFactory = gko::stop::ResidualNormReduction<>;
     residual_criterion             = ResidualCriterionFactory::build()
@@ -69,6 +69,8 @@ namespace GinkgoWrappers
         .on(executor);
   }
 
+
+
   template <typename ValueType, typename IndexType>
   void
   SolverBase<ValueType, IndexType>::initialize_ginkgo_log()
@@ -79,6 +81,8 @@ namespace GinkgoWrappers
       executor, gko::log::Logger::criterion_check_completed_mask);
   }
 
+
+
   template <typename ValueType, typename IndexType>
   void
   SolverBase<ValueType, IndexType>::apply(Vector<ValueType> &      solution,
@@ -199,6 +203,7 @@ namespace GinkgoWrappers
   }
 
 
+
   template <typename ValueType, typename IndexType>
   SolverControl &
   SolverBase<ValueType, IndexType>::control() const
@@ -207,6 +212,7 @@ namespace GinkgoWrappers
   }
 
 
+
   template <typename ValueType, typename IndexType>
   void
   SolverBase<ValueType, IndexType>::initialize(
@@ -280,6 +286,7 @@ namespace GinkgoWrappers
   }
 
 
+
   template <typename ValueType, typename IndexType>
   void
   SolverBase<ValueType, IndexType>::solve(const SparseMatrix<ValueType> &matrix,
@@ -291,8 +298,8 @@ namespace GinkgoWrappers
   }
 
 
-  /* ---------------------- SolverCG ------------------------ */
 
+  /* ---------------------- SolverCG ------------------------ */
   template <typename ValueType, typename IndexType>
   SolverCG<ValueType, IndexType>::SolverCG(SolverControl &       solver_control,
                                            const std::string &   exec_type,
@@ -305,6 +312,8 @@ namespace GinkgoWrappers
       cg::build().with_criteria(this->combined_factory).on(this->executor);
   }
 
+
+
   template <typename ValueType, typename IndexType>
   SolverCG<ValueType, IndexType>::SolverCG(
     SolverControl &                           solver_control,
@@ -322,8 +331,8 @@ namespace GinkgoWrappers
   }
 
 
-  /* ---------------------- SolverBicgstab ------------------------ */
 
+  /* ---------------------- SolverBicgstab ------------------------ */
   template <typename ValueType, typename IndexType>
   SolverBicgstab<ValueType, IndexType>::SolverBicgstab(
     SolverControl &       solver_control,
@@ -338,6 +347,8 @@ namespace GinkgoWrappers
                          .on(this->executor);
   }
 
+
+
   template <typename ValueType, typename IndexType>
   SolverBicgstab<ValueType, IndexType>::SolverBicgstab(
     SolverControl &                           solver_control,
@@ -354,8 +365,9 @@ namespace GinkgoWrappers
                          .on(this->executor);
   }
 
-  /* ---------------------- SolverCGS ------------------------ */
 
+
+  /* ---------------------- SolverCGS ------------------------ */
   template <typename ValueType, typename IndexType>
   SolverCGS<ValueType, IndexType>::SolverCGS(SolverControl &    solver_control,
                                              const std::string &exec_type,
@@ -368,6 +380,8 @@ namespace GinkgoWrappers
       cgs::build().with_criteria(this->combined_factory).on(this->executor);
   }
 
+
+
   template <typename ValueType, typename IndexType>
   SolverCGS<ValueType, IndexType>::SolverCGS(
     SolverControl &                           solver_control,
@@ -384,8 +398,9 @@ namespace GinkgoWrappers
                          .on(this->executor);
   }
 
-  /* ---------------------- SolverFCG ------------------------ */
 
+
+  /* ---------------------- SolverFCG ------------------------ */
   template <typename ValueType, typename IndexType>
   SolverFCG<ValueType, IndexType>::SolverFCG(SolverControl &    solver_control,
                                              const std::string &exec_type,
@@ -398,6 +413,8 @@ namespace GinkgoWrappers
       fcg::build().with_criteria(this->combined_factory).on(this->executor);
   }
 
+
+
   template <typename ValueType, typename IndexType>
   SolverFCG<ValueType, IndexType>::SolverFCG(
     SolverControl &                           solver_control,
@@ -414,14 +431,17 @@ namespace GinkgoWrappers
                          .on(this->executor);
   }
 
-  /* ---------------------- SolverGMRES ------------------------ */
 
+
+  /* ---------------------- SolverGMRES ------------------------ */
   template <typename ValueType, typename IndexType>
   SolverGMRES<ValueType, IndexType>::AdditionalData::AdditionalData(
     const unsigned int restart_parameter)
     : restart_parameter(restart_parameter)
   {}
 
+
+
   template <typename ValueType, typename IndexType>
   SolverGMRES<ValueType, IndexType>::SolverGMRES(SolverControl &solver_control,
                                                  const std::string &exec_type,
@@ -436,6 +456,8 @@ namespace GinkgoWrappers
                          .on(this->executor);
   }
 
+
+
   template <typename ValueType, typename IndexType>
   SolverGMRES<ValueType, IndexType>::SolverGMRES(
     SolverControl &                           solver_control,
@@ -453,8 +475,9 @@ namespace GinkgoWrappers
                          .on(this->executor);
   }
 
-  /* ---------------------- SolverIR ------------------------ */
 
+
+  /* ---------------------- SolverIR ------------------------ */
   template <typename ValueType, typename IndexType>
   SolverIR<ValueType, IndexType>::SolverIR(SolverControl &       solver_control,
                                            const std::string &   exec_type,
@@ -467,6 +490,8 @@ namespace GinkgoWrappers
       ir::build().with_criteria(this->combined_factory).on(this->executor);
   }
 
+
+
   template <typename ValueType, typename IndexType>
   SolverIR<ValueType, IndexType>::SolverIR(
     SolverControl &                           solver_control,
@@ -483,6 +508,8 @@ namespace GinkgoWrappers
                          .on(this->executor);
   }
 
+
+
   // Explicit instantiations in GinkgoWrappers
 #  define DEALII_INSTANTIATE_FOR_EACH_VALUE_AND_INDEX_TYPE(_macro) \
     template _macro(float, int32_t);                               \