inputs/dev/Solvers.tex

%%%%%%%%%%%%%%%%%%%
% XLiFE++ is an extended library of finite elements written in C++
%     Copyright (C) 2014  Lunéville, Eric; Kielbasiewicz, Nicolas; Lafranche, Yvon; Nguyen, Manh-Ha; Chambeyron, Colin
%
%     This program is free software: you can redistribute it and/or modify
%     it under the terms of the GNU General Public License as published by
%     the Free Software Foundation, either version 3 of the License, or
%     (at your option) any later version.
%     This program is distributed in the hope that it will be useful,
%     but WITHOUT ANY WARRANTY; without even the implied warranty of
%     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%     GNU General Public License for more details.
%     You should have received a copy of the GNU General Public License
%     along with this program.  If not, see <http://www.gnu.org/licenses/>.
%%%%%%%%%%%%%%%%%%%

\section{Solvers}

Each solver class in the {\lib solvers} library implements a specific iterative method to solve a linear system: \verb?A*X=B? in two cases: Real or Complex.  The algorithm of all solvers except Sor and Sor can work with and without a {\class Preconditioner}. Each solver takes {\class largeMatrix} \(matA\) and {\class Vector} \(vecB\) as inputs and a {\class Vector} \(vecX\) as output whose value is initialized with the input {\class Vector} \(vecX0\).\\
A solver without a preconditioner is invoked with the overloading operator():
\vspace{.1cm}
\begin{lstlisting}
template<class Mat, class VecB, class VecX>
VecX operator()(Mat& matA, VecB& vecB, VecX& vecX0, ValueType solType)
\end{lstlisting}
\vspace{.1cm}
Meanwhile, solver with a preconditioner \(pc\) can be used with the call
\vspace{.1cm}
\begin{lstlisting}
 template<class Mat, class VecB, class VecX, class Prec>
 VecX operator()(Mat& matA, VecB& vecB, VecX& vecX0, Prec& pc, ValueType solType)
\end{lstlisting}
\vspace{.1cm}
User must specify the type of solver \verb?solType?, which can be \verb?_real? or \verb?_complex?. \\
The algorithm corresponds to without-preconditioner solver
\vspace{.1cm}
\begin{lstlisting}
template<typename K, class Mat, class VecB, class VecX>
void algorithm(Mat& matA, VecB& vecB, VecX& vecX, VecX& vecR)
\end{lstlisting}
\vspace{.1cm}
and to a preconditioned one
\vspace{.1cm}
\begin{lstlisting}
 template<typename K, class Mat, class VecB, class VecX, class Prec>
 void algorithm(Mat& matA, VecB& vecB, VecX& vecX, VecX& vecR, Prec& pc)
\end{lstlisting}
\vspace{.1cm}

\subsection {The {\classtitle BicgSolver} class}

This class implements the Biconjugate Gradient method to solve a linear system.
There are several basic constructors calling {\class IterativeSolver} constructors
\vspace{.1cm}
\begin{lstlisting}
class BicgSolver : public IterativeSolver
{
  public:
    //! Default Constructor
    BicgSolver()
      : IterativeSolver("BiCG") {}

    //! Full constructor
    BicgSolver(const Real eps,
               const Number maxOfIt = defaultMaxIterations,
               const Number vb = 0)
      : IterativeSolver("BiCG", maxOfIt, eps, vb) {}
    ...
\end{lstlisting}
\vspace{.1cm}

\displayInfos{library=solvers, test={test\_BicgSolver.hpp}, header dep={IterativeSolver.hpp, Preconditioner.hpp}}

\subsection {The {\classtitle BicgStabSolver} class}

This class implements the Biconjugate Gradient Stabilized method to solve a linear system.
There are several basic constructors calling {\class IterativeSolver} constructors
\vspace{.1cm}
\begin{lstlisting}
class BicgStabSolver : public IterativeSolver
{
  public:
    //! Default Constructor
    BicgStabSolver() : IterativeSolver("BiCGStab") {}

    //! Full Constructor
    BicgStabSolver(const Real eps,
                   const Number maxOfIt = defaultMaxIterations,
                   const Number vb = 0)
      : IterativeSolver("BiCGStab", maxOfIt, eps, vb) {}
    ...
\end{lstlisting}
\vspace{.1cm}

\displayInfos{library=solvers, test={test\_BicgStabSolver.hpp}, header dep={IterativeSolver.hpp, Preconditioner.hpp}}

\subsection {The {\classtitle CgSolver} class}

This class implements the Conjugate Gradient method to solve a linear system.
There are several basic constructors calling {\class IterativeSolver} constructors
\vspace{.1cm}
\begin{lstlisting}
class CgSolver : public IterativeSolver
{
  public:
    //! Default constructor
    CgSolver(): IterativeSolver("CG") {}

    //! Full constructor
    CgSolver(const Real eps,
             const Number maxOfIt = defaultMaxIterations,
             const Number vb = 0)
      : IterativeSolver("CG", maxOfIt, eps, vb) {}
    ...
\end{lstlisting}
\vspace{.1cm}

\displayInfos{library=solvers, test={test\_CgSolver.hpp}, header dep={IterativeSolver.hpp, Preconditioner.hpp}}

\subsection {The {\classtitle CgsSolver} class}

This class implements the Conjugate Gradient Squared method to solve a linear system.
There are several basic constructors calling {\class IterativeSolver} constructors
\vspace{.1cm}
\begin{lstlisting}
class CgsSolver : public IterativeSolver
{
  public:
    //! Default constructor
    CgsSolver()
      : IterativeSolver("CGS") {}

    //! Full constructor
    CgsSolver(const Real eps,
              const Number maxOfIt = defaultMaxIterations,
              const Number vb = 0)
      : IterativeSolver("CGS", maxOfIt, eps, vb) {}
    ...
\end{lstlisting}
\vspace{.1cm}

\displayInfos{library=solvers, test={test\_CgsSolver.hpp}, header dep={IterativeSolver.hpp, Preconditioner.hpp}}

\subsection {The {\classtitle GmresSolver} class}

This class implements the Generalized Minimal Residual method to solve a linear system.
Different from other solvers, the {\class GmresSolver} has more constructors: user can specify the Krylov dimension in the constructor.
\vspace{.1cm}
\begin{lstlisting}
class GmresSolver : public IterativeSolver
{
  private:
    Number krylovDim_;  // << Dimension of Krylov space

  public:
    //! Default Constructor
    GmresSolver()
      : IterativeSolver("GMRes"), krylovDim_(defaultKrylovDimension) {}

    //! Constructor with Krylov dimension
    GmresSolver(const Number kd)
      : IterativeSolver("GMRes", defaultMaxIterations, theDefaultConvergenceThreshold),
        krylovDim_(kd) {}

    //! Full constructor
    GmresSolver(const Number kd, const Real eps,
                const Number maxOfIt = defaultMaxIterations,
                const Number vb = 0)
      : IterativeSolver("GMRes", maxOfIt, eps, vb), krylovDim_(kd) {}
    ...
\end{lstlisting}
\vspace{.1cm}

\displayInfos{library=solvers, test={test\_GmresSolver.hpp}, header dep={IterativeSolver.hpp, Preconditioner.hpp}}

\subsection {The {\classtitle QmrSolver} class}

This class implements the Quasi-Minimal Residual method to solve a linear system.
There are several basic constructors calling {\class IterativeSolver} constructors
\vspace{.1cm}
\begin{lstlisting}
class QmrSolver : public IterativeSolver
{
  public:
    //! Constructor
    QmrSolver()
      : IterativeSolver("QMR") {}

    //! Full Constructor
    QmrSolver(const Real eps,
              const Number maxOfIt = defaultMaxIterations,
              const Number vb = 0)
      : IterativeSolver("QMR", maxOfIt, eps, vb) {}
    ...
\end{lstlisting}
\vspace{.1cm}

\displayInfos{library=solvers, test={test\_QmrSolver.hpp}, header dep={IterativeSolver.hpp, Preconditioner.hpp}}

\subsection {The {\classtitle SorSolver} class}

This class implements the Successive Over Relaxation method to solve a linear system.
For this solver, user can have more choices to specify the relaxation factor \(omega\) in the constructor.
Different from other solvers above, {\class SorSolver} doesn't work with a preconditioner.
\vspace{.1cm}
\begin{lstlisting}
class SorSolver : public IterativeSolver
{
  private:
    Real omega_;  // relaxation factor of SOR method

  public:
    //! Default Constructor
    SorSolver()
      : IterativeSolver("SOR"), omega_(1.) {}

    //! Constructor with omege
    SorSolver(const Real w)
      : IterativeSolver("SOR"), omega_(w) {}

    //! Full constructor
    SorSolver(const Real w, const Real eps,
              const Number maxOfIt = defaultMaxIterations,
              const Number vb = 0)
      : IterativeSolver("SOR", maxOfIt, eps, vb), omega_(w) {}
    ...
\end{lstlisting}
\vspace{.1cm}

\displayInfos{library=solvers, test={test\_SorSolver.hpp}, header dep={IterativeSolver.hpp, Preconditioner.hpp}}

\subsection {The {\classtitle SsorSolver} class}

This class implements the Symmetric Successive Over Relaxation method to solve a linear system.
Like {\class SorSolver}, the {\class SsorSolver} only works without a preconditioner and user can specify the relaxation factor \(omega\) in the constructor.
\vspace{.1cm}
\begin{lstlisting}
class SsorSolver : public IterativeSolver
{
  private:
    Real omega_;  //relaxation factor of SOR method

  public:
    //! Default Constructors
    SsorSolver() : IterativeSolver("SSOR"), omega_(1.) {}

    //! Constructor with omega
    SsorSolver(const Real w) : IterativeSolver("SSOR"), omega_(w) {}

    //! Full constructor
    SsorSolver(const Real w, const Real eps,
               const Number maxOfIt = defaultMaxIterations,
               const Number vb = 0)
      : IterativeSolver("SSOR", maxOfIt, eps, vb), omega_(w) {}
    ...
\end{lstlisting}
\vspace{.1cm}

\displayInfos{library=solvers, test={test\_SsorSolver.hpp}, header dep={IterativeSolver.hpp, Preconditioner.hpp}}