Teuchos - Trilinos Tools Package  Version of the Day
Classes | Namespaces | Functions
Trilinos_Details_LinearSolverFactory.hpp File Reference

Declaration and definition of linear solver factory, and "factory of factories". More...

#include "Teuchos_RCP.hpp"
#include "TeuchosRemainder_config.h"
#include <map>
#include <stdexcept>
#include <sstream>
#include <string>

Go to the source code of this file.

Classes

class  Trilinos::Details::LinearSolver< MV, OP, NormType >
 Interface for a method for solving linear system(s) AX=B. More...
 
class  Trilinos::Details::LinearSolverFactory< MV, OP, NormType >
 Interface for a "factory" that creates solvers. More...
 
class  Trilinos::Details::Impl::LinearSolverFactoryRepository< MV, OP, NormType >
 Repository of solver factories. More...
 

Namespaces

 Trilinos
 Namespace of things generally useful to many Trilinos packages.
 
 Details
 Namespace of implementation details.
 
 Trilinos::Details::Impl
 Implementation details of implementation details.
 

Functions

template<class MV , class OP , class NormType >
Teuchos::RCP< LinearSolver< MV, OP, NormType > > Trilinos::Details::getLinearSolver (const std::string &packageName, const std::string &solverName)
 Get a LinearSolver instance. More...
 
template<class MV , class OP , class NormType >
void Trilinos::Details::registerLinearSolverFactory (const std::string &packageName, const Teuchos::RCP< LinearSolverFactory< MV, OP, NormType > > &factory)
 Called by a package to register its LinearSolverFactory. More...
 
bool Trilinos::Details::Impl::rememberRegisteredSomeLinearSolverFactory (const std::string &packageName)
 Remember which packages registered at least one LinearSolverFactory, with any template parameters. More...
 
bool Trilinos::Details::Impl::registeredSomeLinearSolverFactory (const std::string &packageName)
 Did the package with the given name register at least one LinearSolverFactory, with any template parameters? More...
 
bool Trilinos::Details::Impl::haveLinearSolverFactoryRunTimeRegistration ()
 Whether the CMake run-time registration option is ON. More...
 

Detailed Description

Declaration and definition of linear solver factory, and "factory of factories".

Warning
This header file is NOT currently part of the public interface of Trilinos. It or its contents may change or disappear at any time.

Tpetra::Details::getLinearSolver, Tpetra::Details::registerLinearSolverFactory, and Tpetra::Details::LinearSolverFactory implement the Dependency Inversion and Injection (DII) pattern, as applied to "linear solvers." A linear solver solves or helps solve linear system(s) AX=B. Examples include sparse direct solvers, iterative solvers, and preconditioners for iterative solvers.

DII naturally admits hierarchical run-time options, as in e.g., Teuchos::ParameterList. This lets solvers create inner solvers in an arbitrarily nested way, following the arbitrary nesting of the Teuchos::ParameterList.

DII works well when a ParameterList can express all the data that a solver might need. However, some solvers need or may benefit from additional data. For example, algebraic multigrid can use mesh coordinates, and a sparse factorization can use an initial permutation. Such data do not fit naturally in a Teuchos::ParameterList.

Note
To developers: The LinearSolver and LinearSolverFactory interfaces, and the LinearSolverFactoryRepository interface and implementation must live in the bottom-most (most upstream) package from all solvers that depend on it. Solver defines an interface for a solver, and LinearSolverFactory defines an interface for a "factory" that knows how to create solvers. Each solver package defines its own solvers, and its own factory that knows how to create all the solvers in a given package.

Definition in file Trilinos_Details_LinearSolverFactory.hpp.

Function Documentation

template<class MV , class OP , class NormType >
Teuchos::RCP< LinearSolver< MV, OP, NormType > > Trilinos::Details::getLinearSolver ( const std::string &  packageName,
const std::string &  solverName 
)

Get a LinearSolver instance.

Template Parameters
MVType of a (multi)vector, representing either the solution(s) X or the right-hand side(s) B of a linear system AX=B. For example, with Tpetra, use a Tpetra::MultiVector specialization. A multivector is a single data structure containing zero or more vectors with the same dimensions and layout.
OPType of a matrix or linear operator that this Solver understands. For example, for Tpetra, use a Tpetra::Operator specialization.
NormTypeType of the norm of the residual. See the documentation of LinearSolver for details.

Call this function to create a LinearSolver instance from a particular package. LinearSolvers may create LinearSolvers. The run-time registration system (see registerLinearSolverFactory() below) breaks software dependencies between packages. Thus, Package A may create a LinearSolver from Package B, even if Package B depends on Package A.

Parameters
packageName[in] Name of the package from which to get the solver. Names are case sensitive.
solverName[in] The solver's name. Names are case sensitive.

Definition at line 550 of file Trilinos_Details_LinearSolverFactory.hpp.

template<class MV , class OP , class NormType >
void Trilinos::Details::registerLinearSolverFactory ( const std::string &  packageName,
const Teuchos::RCP< LinearSolverFactory< MV, OP, NormType > > &  factory 
)

Called by a package to register its LinearSolverFactory.

registerLinearSolverFactory

Note
Most users do not need to call this function. This is mostly of interest to solver package developers. See below for details.
Template Parameters
MVType of a (multi)vector, representing either the solution(s) X or the right-hand side(s) B of a linear system AX=B. For example, with Tpetra, use a Tpetra::MultiVector specialization. A multivector is a single data structure containing zero or more vectors with the same dimensions and layout.
OPType of a matrix or linear operator that the LinearSolver instances to create understand. For example, for Tpetra, use a Tpetra::Operator specialization.
NormTypeType of the norm of the residual. See the documentation of LinearSolver for details.
Parameters
packageName[in] Name of the package registering the factory. Package names are case sensitive.
factory[in] That package's factory.

This function lets packages register themselves, so that getLinearSolver() (see above) can create solvers from that package. A package "registers itself" by doing the following:

  1. Defining a concrete LinearSolverFactory subclass, that knows how to create solvers from that package
  2. Calling registerLinearSolverFactory() (this function) with an instance of that LinearSolverFactory subclass

Packages may call this function before main() runs. In fact, we prefer that they do so. This ensures that any package will be able to create solvers from that package, without users or other packages needing to know about that package. When people talk about "dependency injection" or "dependency inversion," this is what they mean.

This function is templated with the same template parameters as LinearSolverFactory. This means that it must be called for every combination of types (MV, OP) for which code will instantiate a LinearSolverFactory<MV, OP, NormType>. Thus, if the solver package wants to do this before main() runs, it needs a list of all type combination in advance. If using explicit template instantiation (ETI), you may plug this into the ETI system. We thus recommend that packages that use ETI register a LinearSolverFactory instance for each ETI type combination. For example, Ifpack2 should iterate over all enabled combinations of the four template parameters S, LO, GO, NT of Ifpack2::Preconditioner, creating a LinearSolverFactory<MV, OP, NormType> instance for each combination, with MV = Tpetra::MultiVector<S, LO, GO, NT> and OP = Tpetra::Operator<S, LO, GO, NT>. Package developers may find it useful to write a macro that does this for that package's LinearSolverFactory subclass.

If packages do not register a factory for certain type combinations that users need, users may in rare instances need to call this function themselves. Avoid doing this, because it defeats dependency inversion.

It could very well be that some packages don't implement all desired type combinations MV, OP. In that case, those packages would not register a factory for those types. Users who request solvers from those packages for forbidden type combinations would get a run-time error.

Note
To developers: LinearSolverFactory returns LinearSolver by Teuchos::RCP because Trilinos' solvers tend to use Teuchos::RCP, and we don't want to break compatibility. However, if C++11 is enabled, we use std::shared_ptr to handle LinearSolverFactory instances. This is because that is an implementation detail that solvers themselves don't have to see, and because std::shared_ptr is thread safe.

Definition at line 537 of file Trilinos_Details_LinearSolverFactory.hpp.