Belos  Version of the Day
Public Types | Public Member Functions | List of all members
Belos::SolverFactory< Scalar, MV, OP > Class Template Reference

Factory for all solvers which Belos supports. More...

#include <BelosSolverFactory.hpp>

Inheritance diagram for Belos::SolverFactory< Scalar, MV, OP >:
Inheritance graph
[legend]

Public Types

typedef SolverManager< Scalar, MV, OP > solver_base_type
 The type of the solver returned by create(). More...
 

Public Member Functions

 SolverFactory ()
 Default constructor. More...
 
Teuchos::RCP< solver_base_typecreate (const std::string &solverName, const Teuchos::RCP< Teuchos::ParameterList > &solverParams)
 Create, configure, and return the specified solver. More...
 
int numSupportedSolvers () const
 Number of supported solvers. More...
 
Teuchos::Array< std::string > supportedSolverNames () const
 List of supported solver names. More...
 
bool isSupported (const std::string &solverName) const
 Whether the given solver name names a supported solver. More...
 
Implementation of Teuchos::Describable interface
std::string description () const
 A string description of this object. More...
 
void describe (Teuchos::FancyOStream &out, const Teuchos::EVerbosityLevel verbLevel=Teuchos::Describable::verbLevel_default) const
 Describe this object. More...
 
- Public Member Functions inherited from Teuchos::Describable
void describe (std::ostream &out, const EVerbosityLevel verbLevel=verbLevel_default) const
 
virtual ~Describable ()
 
DescribableStreamManipulatorState describe (const Describable &describable, const EVerbosityLevel verbLevel=Describable::verbLevel_default)
 
std::ostream & operator<< (std::ostream &os, const DescribableStreamManipulatorState &d)
 
void describe (std::ostream &out, const EVerbosityLevel verbLevel=verbLevel_default) const
 
virtual ~Describable ()
 
- Public Member Functions inherited from Teuchos::LabeledObject
 LabeledObject ()
 
virtual ~LabeledObject ()
 
virtual void setObjectLabel (const std::string &objectLabel)
 
virtual std::string getObjectLabel () const
 

Additional Inherited Members

- Static Public Attributes inherited from Teuchos::Describable
static const EVerbosityLevel verbLevel_default
 

Detailed Description

template<class Scalar, class MV, class OP>
class Belos::SolverFactory< Scalar, MV, OP >

Factory for all solvers which Belos supports.

Author
Mark Hoemmen

New Belos users should start by creating an instance of this class, and using it to create the solver they want.

Belos implements several different iterative solvers. The usual way in which users interact with these solvers is through appropriately named subclasses of SolverManager. This factory class tells users which solvers are supported. It can initialize and return any supported subclass of SolverManager, given a short name of the subclass (such as "GMRES" or "CG").

Users ask for the solver they want by a string name, and supply an optional (but recommended) list of parameters (Teuchos::ParameterList) for the solver. The solver may fill in the parameter list with all the valid parameters and their default values, which users may later inspect and modify. Valid solver names include both "canonical names" (each maps one-to-one to a specific SolverManager subclass) and "aliases." Some aliases are short nicknames for canonical names, like "GMRES" for "Pseudoblock GMRES". Other aliases refer to a canonical solver name, but also modify the user's parameter list. For example, "Flexible GMRES" is an alias for "Block GMRES", and also sets the "Flexible Gmres" parameter to true in the input parameter list.

 Solver name | Aliases | Solver Manager Class

--------— | ----— | -------— Pseudoblock GMRES | GMRES, Pseudo Block GMRES, PseudoBlockGMRES, PseudoBlockGmres | PseudoBlockGmresSolMgr Block GMRES | Flexible GMRES | BlockGmresSolMgr Block CG | | BlockCGSolMgr Pseudoblock CG | PseudoBlockCG, Pseudo Block CG | PseudoBlockCGSolMgr Pseudoblock Stochastic CG | Stochastic CG | PseudoBlockStochasticCGSolMgr GCRODR | Recycling GMRES | GCRODRSolMgr RCG | Recycling CG | RCGSolMgr MINRES | | MinresSolMgr LSQR | | LSQRSolMgr TFQMR | Transpose-Free QMR | TFQMRSolMgr Pseudoblock TFQMR | Pseudo Block Transpose-Free QMR | PseudoBlockTFQMRSolMgr Hybrid Block GMRES | GmresPoly, Seed GMRES | GmresPolySolMgr PCPG | CGPoly, Seed CG | PCPGSolMgr

This class' template parameters are the same as those of Belos::SolverManager. Scalar is the scalar type (of entries in the multivector), MV is the multivector type, and OP is the operator type. For example: Scalar=double, MV=Epetra_MultiVector, and OP=Epetra_Operator will access the Epetra specialization of the Belos solvers.

Here is a simple example of how to use SolverFactory to create a GMRES solver for your linear system. Your code needs to include BelosSolverFactory.hpp and whatever linear algebra library header files you would normally use. Suppose that Scalar, MV, and OP have been previously typedef'd to the scalar resp. multivector resp. operator type in your application.

using Teuchos::parameterList;
using Teuchos::rcp; // Save some typing
// The ellipses represent the code you would normally use to create
// the sparse matrix, preconditioner, right-hand side, and initial
// guess for the linear system AX=B you want to solve.
RCP<OP> A = ...; // The sparse matrix / operator A
RCP<OP> M = ...; // The (right) preconditioner M
RCP<MV> B = ...; // Right-hand side of AX=B
RCP<MV> X = ...; // Initial guess for the solution
// Make an empty new parameter list.
RCP<ParameterList> solverParams = parameterList();
// Set some GMRES parameters.
//
// "Num Blocks" = Maximum number of Krylov vectors to store. This
// is also the restart length. "Block" here refers to the ability
// of this particular solver (and many other Belos solvers) to solve
// multiple linear systems at a time, even though we are only solving
// one linear system in this example.
solverParams->set ("Num Blocks", 40);
solverParams->set ("Maximum Iterations", 400);
solverParams->set ("Convergence Tolerance", 1.0e-8);
// Create the GMRES solver.
RCP<Belos::SolverManager<Scalar, MV, OP> > solver =
factory.create ("GMRES", solverParams);
// Create a LinearProblem struct with the problem to solve.
// A, X, B, and M are passed by (smart) pointer, not copied.
RCP<Belos::LinearProblem<Scalar, MV, OP> > problem =
problem->setRightPrec (M);
// Tell the solver what problem you want to solve.
solver->setProblem (problem);
// Attempt to solve the linear system. result == Belos::Converged
// means that it was solved to the desired tolerance. This call
// overwrites X with the computed approximate solution.
Belos::ReturnType result = solver->solve();
// Ask the solver how many iterations the last solve() took.
const int numIters = solver->getNumIters();

Belos developers who have implemented a new solver (i.e., a new subclass of SolverManager) and who want to make the solver available through the factory should do the following:

  1. Add a new symbol corresponding to their solver to the details::EBelosSolverType enum.
  2. If necessary, specialize details::makeSolverManagerTmpl for their SolverManager subclass. In most cases, the default implementation suffices.
  3. Add a case for their enum symbol that instantiates their solver to the long switch-case statement in details::makeSolverManagerFromEnum.
  4. In the SolverFactory constructor, define a canonical string name for their solver and its mapping to the corresponding enum value, following the examples and comments there. (This takes one line of code.)

Definition at line 246 of file BelosSolverFactory.hpp.

Member Typedef Documentation

◆ solver_base_type

template<class Scalar, class MV, class OP>
typedef SolverManager<Scalar, MV, OP> Belos::SolverFactory< Scalar, MV, OP >::solver_base_type

The type of the solver returned by create().

This is a specialization of SolverManager for the same scalar, multivector, and operator types as the template parameters of this factory.

Definition at line 253 of file BelosSolverFactory.hpp.

Constructor & Destructor Documentation

◆ SolverFactory()

template<class Scalar , class MV , class OP >
Belos::SolverFactory< Scalar, MV, OP >::SolverFactory ( )

Default constructor.

Definition at line 537 of file BelosSolverFactory.hpp.

Member Function Documentation

◆ create()

template<class Scalar , class MV , class OP >
Teuchos::RCP< typename SolverFactory< Scalar, MV, OP >::solver_base_type > Belos::SolverFactory< Scalar, MV, OP >::create ( const std::string &  solverName,
const Teuchos::RCP< Teuchos::ParameterList > &  solverParams 
)

Create, configure, and return the specified solver.

Parameters
solverName[in] Name of the solver.
solverParams[in/out] List of parameters with which to configure the solver. If null, we configure the solver with default parameters. If nonnull, the solver may modify the list by filling in missing parameters with default values. You can then inspect the resulting list to learn what parameters the solver accepts.

Some solvers may be accessed by multiple names ("aliases"). Each solver has a canonical name, and zero or more aliases. Using some aliases (such as those that access Flexible GMRES capability in GMRES-type solvers) may make this method set certain parameters in your parameter list.

The input parameter list is passed in as a Teuchos::RCP because the factory passes it to the solver, and Belos solvers want their input parameter list as a Teuchos::RCP<Teuchos::ParameterList>. We allow a null parameter list only for convenience, and will use default parameter values in that case.

Definition at line 610 of file BelosSolverFactory.hpp.

◆ numSupportedSolvers()

template<class Scalar , class MV , class OP >
int Belos::SolverFactory< Scalar, MV, OP >::numSupportedSolvers ( ) const

Number of supported solvers.

This may differ from the number of supported solver names, since we may accept multiple names ("aliases") for some solvers.

Definition at line 738 of file BelosSolverFactory.hpp.

◆ supportedSolverNames()

template<class Scalar , class MV , class OP >
Teuchos::Array< std::string > Belos::SolverFactory< Scalar, MV, OP >::supportedSolverNames ( ) const

List of supported solver names.

The length of this list may differ from the number of supported solvers, since we may accept multiple names ("aliases") for some solvers.

Definition at line 773 of file BelosSolverFactory.hpp.

◆ isSupported()

template<class Scalar, class MV, class OP>
bool Belos::SolverFactory< Scalar, MV, OP >::isSupported ( const std::string &  solverName) const

Whether the given solver name names a supported solver.

◆ description()

template<class Scalar , class MV , class OP >
std::string Belos::SolverFactory< Scalar, MV, OP >::description ( ) const
virtual

A string description of this object.

Reimplemented from Teuchos::Describable.

Definition at line 670 of file BelosSolverFactory.hpp.

◆ describe()

template<class Scalar , class MV , class OP >
void Belos::SolverFactory< Scalar, MV, OP >::describe ( Teuchos::FancyOStream out,
const Teuchos::EVerbosityLevel  verbLevel = Teuchos::Describable::verbLevel_default 
) const
virtual

Describe this object.

At higher verbosity levels, this method will print out the list of names of supported solvers. You can also get this list directly by using the supportedSolverNames() method.

Reimplemented from Teuchos::Describable.

Definition at line 690 of file BelosSolverFactory.hpp.


The documentation for this class was generated from the following file:

Generated for Belos by doxygen 1.8.14