Belos Package Browser (Single Doxygen Collection) Development
Public Types | Public Member Functions | Private Member Functions | Private Attributes
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]

List of all members.

Public Types

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

Public Member Functions

 SolverFactory ()
 Constructor.
Teuchos::RCP< solver_base_typecreate (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.

Private Member Functions

void reviseParameterListForAlias (const std::string &aliasName, const Teuchos::RCP< Teuchos::ParameterList > &solverParams)
 Modify the input ParameterList appropriately for the given alias.
Teuchos::Array< std::string > canonicalSolverNames () const
 List of canonical solver names.
Teuchos::Array< std::string > solverNameAliases () const
 List of supported aliases (to canonical solver names).

Private Attributes

std::map< std::string,
std::string > 
aliasToCanonicalName_
 Map from solver name alias to canonical solver name.
std::map< std::string,
details::EBelosSolverType
canonicalNameToEnum_
 Map from canonical solver name to solver enum value.

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.

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.

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.)

Definition at line 220 of file BelosSolverFactory.hpp.


Member Typedef Documentation

template<class Scalar, class MV, class OP>
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 228 of file BelosSolverFactory.hpp.


Constructor & Destructor Documentation

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

Constructor.

Definition at line 517 of file BelosSolverFactory.hpp.


Member Function Documentation

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 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.

Definition at line 583 of file BelosSolverFactory.hpp.

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 694 of file BelosSolverFactory.hpp.

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 729 of file BelosSolverFactory.hpp.

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.

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

A string description of this SolverFactory object.

Reimplemented from Teuchos::Describable.

Definition at line 626 of file BelosSolverFactory.hpp.

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 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 646 of file BelosSolverFactory.hpp.

template<class Scalar , class MV , class OP >
void Belos::SolverFactory< Scalar, MV, OP >::reviseParameterListForAlias ( const std::string &  aliasName,
const Teuchos::RCP< Teuchos::ParameterList > &  solverParams 
) [private]

Modify the input ParameterList appropriately for the given alias.

Some aliases include modifications or special checking of the input ParameterList. All alias-related ParameterList revision happens in this method.

Definition at line 564 of file BelosSolverFactory.hpp.

template<class Scalar , class MV , class OP >
Teuchos::Array< std::string > Belos::SolverFactory< Scalar, MV, OP >::canonicalSolverNames ( ) const [private]

List of canonical solver names.

Definition at line 701 of file BelosSolverFactory.hpp.

template<class Scalar , class MV , class OP >
Teuchos::Array< std::string > Belos::SolverFactory< Scalar, MV, OP >::solverNameAliases ( ) const [private]

List of supported aliases (to canonical solver names).

Definition at line 714 of file BelosSolverFactory.hpp.


Member Data Documentation

template<class Scalar, class MV, class OP>
std::map<std::string, std::string> Belos::SolverFactory< Scalar, MV, OP >::aliasToCanonicalName_ [private]

Map from solver name alias to canonical solver name.

The keys of this map do not necessarily include canonical solver names. If a candidate name isn't a key in this map, then it must be a canonical name in order to be valid. There doesn't need to be an alias for each solver.

Note to Belos developers: If you want to add a new alias, first add the mapping from alias to canonical solver name in the SolverFactory constructor. Then, edit reviseParameterListForAlias() to do any modifications of the input ParameterList associated with that alias.

Definition at line 311 of file BelosSolverFactory.hpp.

template<class Scalar, class MV, class OP>
std::map<std::string, details::EBelosSolverType> Belos::SolverFactory< Scalar, MV, OP >::canonicalNameToEnum_ [private]

Map from canonical solver name to solver enum value.

Access the keys to get the list of canonical solver names.

Note to Belos developers: If you add a new solver, start with the documentation of details::EBelosSolverType for instructions. Each new solver needs a canonical name (a string), which is a key into this map. The map from canonical name to enum value is set up in the SolverFactory constructor. The details::makeSolverManagerFromEnum() function in turn takes the enum value and parameter list, and returns an instance of the appropriate subclass of SolverManager.

Definition at line 326 of file BelosSolverFactory.hpp.


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines