Belos Version of the Day
|typedef SolverManager< Scalar, |
MV, OP >
|The type returned by |
|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 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.
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, 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 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.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 = 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 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.)
|Belos::SolverFactory< Scalar, MV, OP >::SolverFactory||(||)|
|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 GMRES-type 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 non-null 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.
|int Belos::SolverFactory< Scalar, MV, OP >::numSupportedSolvers||(||)||const|
|Teuchos::Array< std::string > Belos::SolverFactory< Scalar, MV, OP >::supportedSolverNames||(||)||const|
|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
|void Belos::SolverFactory< Scalar, MV, OP >::describe||(||Teuchos::FancyOStream &||out,|
|const Teuchos::EVerbosityLevel||verbLevel =
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
Reimplemented from Teuchos::Describable.