Trilinos::Details Namespace Reference

Namespaces
	Impl
	Implementation details of implementation details.

Classes
class	LinearSolver
	Interface for a method for solving linear system(s) AX=B. More...
class	LinearSolverFactory
	Interface for a "factory" that creates solvers. More...

Functions
template<class MV , class OP , class NormType >
Teuchos::RCP< LinearSolver< MV, OP, NormType > >	getLinearSolver (const std::string &packageName, const std::string &solverName)
	Get a LinearSolver instance. More...
template<class MV , class OP , class NormType >
void	registerLinearSolverFactory (const std::string &packageName, const Teuchos::RCP< LinearSolverFactory< MV, OP, NormType > > &factory)
	Called by a package to register its LinearSolverFactory. More...

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

MV	Type 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.
OP	Type of a matrix or linear operator that this Solver understands. For example, for Tpetra, use a Tpetra::Operator specialization.
NormType	Type 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 519 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

MV	Type 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.
OP	Type of a matrix or linear operator that the LinearSolver instances to create understand. For example, for Tpetra, use a Tpetra::Operator specialization.
NormType	Type 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 506 of file Trilinos_Details_LinearSolverFactory.hpp.