Belos Version of the Day

Factory for all solvers which Belos supports. More...
#include <BelosSolverFactory.hpp>
Public Types  
typedef SolverManager< Scalar, MV, OP >  solver_base_type 
The type returned by create() .  
Public Member Functions  
SolverFactory ()  
Constructor.  
Teuchos::RCP< solver_base_type >  create (const std::string &solverName, const Teuchos::RCP< Teuchos::ParameterList > &solverParams) 
Create, configure, and return the specified solver.  
int  numSupportedSolvers () const 
Number of supported solvers.  
Teuchos::Array< std::string >  supportedSolverNames () const 
List of supported solver names.  
bool  isSupported (const std::string &solverName) const 
Whether the given solver name names a supported solver.  
Implementation of Teuchos::Describable interface  
std::string  description () const 
A string description of this SolverFactory object.  
void  describe (Teuchos::FancyOStream &out, const Teuchos::EVerbosityLevel verbLevel=Teuchos::Describable::verbLevel_default) const 
Describe this SolverFactory object. 
Factory for all solvers which Belos supports.
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 onetoone 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.
This class' template parameters are the same as those of 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::parameterList; using Teuchos::RCP; using Teuchos::rcp; // Save some typing // The ellipses represent the code you would normally use to create // the sparse matrix, preconditioner, righthand 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 = ...; // Righthand side of AX=B RCP<MV> X = ...; // Initial guess for the solution Belos::SolverFactory<Scalar, MV, OP> factory; // 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.0e8); // 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 = rcp (new Belos::LinearProblem<Scalar, MV, OP> (A, X, B)); 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 switchcase 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 214 of file BelosSolverFactory.hpp.
Belos::SolverFactory< Scalar, MV, OP >::solver_base_type 
The type 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 222 of file BelosSolverFactory.hpp.
Belos::SolverFactory< Scalar, MV, OP >::SolverFactory  (  ) 
Constructor.
Definition at line 476 of file BelosSolverFactory.hpp.
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.
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 GMREStype solvers) may make this method set certain parameters in your parameter list.
The input parameter list is passed in as an RCP
because the factory passes it to the solver, and Belos solvers all keep a persisting reference to their input parameter lists. (This behavior differs from that of the AztecOO linear solver interface; AztecOO merely reads parameters from its input parameter list without modifying it.) We allow a null parameter list only for convenience, but we recommend that you provide a nonnull parameter list. If the list is not null, the solver will fill it in with any missing parameters and their default values. You can then inspect the parameter names, modify their default values, and change the returned solver's parameters by calling its setParameters()
method with the modified list.
Definition at line 530 of file BelosSolverFactory.hpp.
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 628 of file BelosSolverFactory.hpp.
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 663 of file BelosSolverFactory.hpp.
bool Belos::SolverFactory< Scalar, MV, OP >::isSupported  (  const std::string &  solverName  )  const 
Whether the given solver name names a supported solver.
std::string Belos::SolverFactory< Scalar, MV, OP >::description  (  )  const [virtual] 
A string description of this SolverFactory object.
Reimplemented from Teuchos::Describable.
Definition at line 573 of file BelosSolverFactory.hpp.
void Belos::SolverFactory< Scalar, MV, OP >::describe  (  Teuchos::FancyOStream &  out, 
const Teuchos::EVerbosityLevel  verbLevel = Teuchos::Describable::verbLevel_default 

)  const [virtual] 
Describe this SolverFactory 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 588 of file BelosSolverFactory.hpp.