Concrete implementation of NOX::Epetra::LinearSolver for AztecOO.
This solver provides the linear algebra services provided through the
AztecOO parallel iterative linear solver.
The NOX::Epetra::LinearSystemAztecOO object provides a flexible and
efficient way to interface an Epetra based application code to the
Aztec linear solver. This class handles construction of both the
preconditioners and AztecOO solver. All options are determined through
parameter lists and the basic constructors.
Constructing a Linear System
There are four different constructors that can be used. The difference
between constructors is based on whether the user supplies a Jacobian,
a preconditioner, neither or both.
If a Jacobian is not supplied then this object can create an
internally constructed Jacobian based on a Finite Difference or
Matrif-Free object. The user can specify which type of object to use
by setting the parameter "Jacobian Operator" in the parameter list.
The choices are "Matrix-Free" or "Finite Difference".
The user can supply their own preconditioner as an Epetra_Operator, or
they can supply their own matrix (an Epetra_RowMatrix derived object)
that can be used by one of the internal preconditioner libraries
(currently aztecoo or ifpack). If they supply their own preconditioner
the object must implement the Epetra_Operator::ApplyInverse method.
This is the method called during the linear solve to introduce
preconditoning into aztecoo. If the user supplies a matrix to be used
with an internal preconditioner, it must be derived from the
Epetra_RowMatrix class and must implement all functionality in the
Epetra_RowMatrix. If a Preconditioner is not supplied, then this
object can create an internal preconditioner matrix by finite
differencing or it can use the Jacobian operator if the Jacobian
derives from the Epetra_RowMatrix class. The user can specify which
type of object to use by setting the parameter "Preconditioner
Operator" in the parameter list. The choices are "Use Jacobian" or
"Finite Difference".
The Jacobian and preconditioner each require an interface to update
the state of the operator with respect to the solution vector and any
other parameters. There are three interfaces that can be implemented,
NOX::Epetra::Interface::Required, NOX::Epetra::Interface::Jacobian,
and NOX::Epetra::Interface::Preconditioner.
NOX::Epetra::Interface::Required supplies the computeF() function so
codes can tell NOX what the nonlinear equations are. This is the
minimum requirement to run nox through the epetra interface.
LinearSolverAztecOO requires this in some constructors so that if a
Jacobian or preconditoner is not supplied, it will use computeF from
the Required interface to estimate the Jacobian or preconditioner via
finite differences or directional derivatives.
NOX::Epetra::Interface::Jacobian is used for updating a user supplied
Jacobian opertor with respect to the solution vector and any other
parameters. It is required only in constructors in which a user
supplies a Jacobian operator.
NOX::Epetra::Interface::Preconditioner is used for updating a user
supplied preconditioner opertor/matrix with respect to the solution
vector and any other parameters. It is required only in constructors
in which a user supplies a preconditioner operator.
"Linear Solver" sublist parameters
A Teuchos::ParameterList called linearSolverParams is required in the
various constructors and during some method calls such as
applyJacobianInverse() and applyRightPreconditioning(). Typically,
this list is the "Linear Solver" sublist found in the nox parameter
list. The following parameters can be set in the linear solver sublist
and are vaild for the NOX::Epetra::LinearSolverAztecOO object: "Aztec
Solver" - Determine the iterative technique used in the solve. The
following options are valid:
"GMRES" - Restarted generalized minimal residual (default).
"CG" - Conjugate gradient.
"CGS" - Conjugate gradient squared.
"TFQMR" - Transpose-free quasi-minimal reasidual.
"BiCGStab" - Bi-conjugate gradient with stabilization.
"LU" - Sparse direct solve (single processor only).
"Size of Krylov Subspace" - When using restarted GMRES this sets the
maximum size of the Krylov subspace (defaults to 300).
"Orthogonalization" - The orthogonalization routine used for the
Gram-Schmidt orthogonalization procedure in Aztec. The following
options are valid:
"Classical" - (default).
"Modified"
"Convergence Test" - Algorithm used to calculate the residual that
is used for determining the convergence of the linear solver. See the
Aztec 2.1 manual for more information. The following options are
valid:
"r0" - (default)
"rhs"
"norm"
"no scaling"
"sol"
"Tolerance" - Tolerance used by AztecOO to determine if an iterative
linear solve has converged.
"Ill-Conditioning Threshold" - If the upper hessenberg matrix during
GMRES generates a condition number greater than this parameter value,
aztec will exit the linear solve returning the it's current solution.
The default is 1.0e11.
"Preconditioner Iterations" - Number of iterations an
AztecOO_Operator should take when solving the preconditioner. This is
only used if an AztecOO preconditioner is used and the solver makes a
call to NOX::Epetra::Group::applyRightPreconditioning(). This is NOT a
recomended approach.
"Max Iterations" - maximum number of iterations in the linear solve.
Default is 400.
"Zero Initial Guess" - boolean. Zero out the initial guess for
linear solves performed through applyJacobianInverse calls (i.e. zero
out the result vector before the linear solve). Defaults to false.
"Throw Error on Prec Failure" - boolean. If set to true, an
exception will be thrown if the preconditioner fails to initialize or
recompute/refactor. If set to false, a warning will br printed if the
NOX::Utils::Warning is enabled in the printing utilities (
NOX::Utils). Defaults to true.
"Output Frequency" - number of linear solve iterations between
output of the linear solve residual. Takes an integer, or one of the
AztecOO flags: AZ_none, AZ_last, or AZ_all as a value. Defaults to
AZ_last.
"Jacobian Operator" - When a constructor does not require a Jacobian
operator, the linear system will create a default operator using:
"Matrix-Free" (default)
"Finite Difference"
"Preconditioner" - Sets the choice of the preconditioner to use
during linear solves. The validity of the choice of preconditioner
will depend on the types of operators that are available for the
Jacobian and preconditioner. NOTE: This flag will override any
constructor details. For example, if you supply a preconditioner
operator in the constructor, it will not be used if this flag is set
to "None". If you supply an Epetra_Operator for the preconditioner
but the "Preconditioner" flag is set to "AztecOO" (this requires
an Epetra_RowMatrix for the preconditioner operator), this object will
exit with a failure. The valid options and any requirements on the
operator type are listed below:
"None" - No preconditioning. (default)
"AztecOO" - AztecOO internal preconditioner. This requires a
preconditioner operator that derives from the Epetra_RowMatrix class.
"Ifpack" - Ifpack internal preconditioner. This requires a
preconditioner object that derives from the Epetra_RowMatrix class or
it can use a Jacobian if the Jacobian derives from an
Epetra_RowMatrix. This option is deprecated. Please use "New
Ifpack".
"New Ifpack" - Ifpack internal preconditioner. This requires a
preconditioner object that derives from the Epetra_RowMatrix class or
it can use a Jacobian if the Jacobian derives from an
Epetra_RowMatrix.
"User Defined" - The user supplies an Epetra_Operator derived class.
Users must implement at a minimum the ApplyInverse() function of the
Epetra_Operator class since preconditioning of vectors is accomplished
through calls to this method.
"Jacobian Operator" - If a constructor is used that does not supply
a Jacobian operator, nox will create an internal Jacobian operator.
This flag is ONLY valid in such cases. This will determine which
Operator is used: "Matrix-Free" - Create a NOX::Epetra::MatrixFree
object.
"Finite Difference" - Create a NOX::Epetra::FiniteDifference object.
"Preconditioner Operator" - If a constructor is used that does not
supply a preconditioner operator, nox will create an internal
preconditioner operator. This flag is ONLY valid in such cases. This
will determine which Operator is used: "Use Jacobian" - Use the
Jacobian Operator (it must be an Epetra_RowMatrix derived object).
"Finite Difference" - Create a NOX::Epetra::FiniteDifference object.
"Aztec Preconditioner" - If the "Preconditioner" flag is set to
"AztecOO" then the specific AztecOO preconditioner is specified with
this flag. Currently supported preconditioners and their corresponding
parameters that can be set are shown below (See the Aztec 2.1 manual
for more information):
"ilu" - ilu preconditioning. This choice allows the following
additional parameters to be specified: "Overlap" - defaults to 0
"Graph Fill" - defaults to 0
"ilut" - ilut preconditioning. This choice allows the following
additional parameters to be specified: "Overlap" - defaults to 0
"Fill Factor" - defaults to 1.0
"Drop Tolerance" - defaults to 1.0e-12
"Jacobi" - k step Jacobi where k is set by the "Steps" flag:
"Steps" - defaults to 3.
"Symmetric Gauss-Siedel" - Non-overlapping domain decomposition k
step symmetric Gauss-Siedel where k is set by the "Steps" flag:
"Steps" - defaults to 3.
"Polynomial" - Neumann polynomial with order set by the parameter:
"Polynomial Order" - defaults to 3.
"Least-squares Polynomial" - Least-squares polynomial with order set
by the parameter: "Polynomial Order" - defaults to 3.
"Ifpack" - If the "Preconditioner" flag is set to "New Ifpack"
then any of the options supported by the Ifpack Create factory can be
specified using a Teuchos::ParameterList containing the Ifpack options
and then setting this as a parameter named "Ifpack" in the "Linear
Solver" sublist.
"ML" - If the "Preconditioner" flag is set to "ML" then any of
the options supported by the ML factory can be specified using a
Teuchos::ParameterList containing the ML options and then setting this
as a parameter named "ML" in the "Linear Solver" sublist.
"Preconditioner Reuse Policy" - (string) Allows the user to set how
and when the preconditioner should be computed. This flag supports
native Aztec, Ifpack and ML preconditioners. There are three options:
"Rebuild" - The "Rebuild" option always completely destroys and
then rebuilds the preconditioner each time a linear solve is
requested.
"Reuse" - The group/linear solver will not recompute the
preconditioner even if the group's solution vector changes. It just
blindly reuses what has been constructed. This turns off control of
preconditioner recalculation. This is a dangerous condition but can
really speed up the computations if the user knows what they are
doing. We don't recommend users trying this.
"Recompute" - Recomputes the preconditioner, but will try to
efficiently reuse any objects that don't need to be destroyed. How
efficient the "Recompute" option is depends on the type of
preconditioner. For example if we are using ILU from the Ifpack
library, we would like to not destroy and reallocate the graph each
solve. With this option, we tell Ifpack to reuse the graph from last
time - e.g the sparisty pattern has not changed between applications
of the preconditioner.
"Max Age Of Prec" - (int) If the "Preconditioner Reuse Policy" is
set to "Reuse", this integer tells the linear system how many times
to reuse the preconditioner before rebuilding it. Defaults to 1.
"RCM Reordering" - Enables RCM reordering in conjunction with domain
decomp incomplete factorization preconditioning. The following options
are valid:
"Disabled" - (default).
"Enabled"
"Use Adaptive Linear Solve" - Enables the use of AztecOO's
AdaptiveIterate() method instead of calling the Iterate() method. This
causes the preconditioning matrix to be modified to make the linear
solves easier. AztecOO will attempt to solve the linear system
multiple times now and if the solves are failing it will modify the
preconditioner and try again. Boolean value, defaults to false. NOTE:
This only works for internal Aztec preconditioners! The
"Preconditioning" parameter must be set to "AztecOO: Jacobian
Matrix" or "AztecOO: User RowMatrix". (NOTE: This parameter is
currently NOT supported)
"Max Adaptive Solve Iterations" - (integer) Maximum number of
attempts that the linear solver will make when trying to solve a
linear system. Defaults to 5. (NOTE: This parameter is currently NOT
supported)
"Compute Scaling Manually" - (boolean) The linear system can be
scaled if a NOX::Epetra::Scaling object is supplied to
LinearSystemAztecOO. When to compute the scaling can be handled either
manually by the user, or this object can automatically compute the
scaling prior to a linear solve. By setting this flag to true, the
user will call NOX::Epetra::Scaling::computeScaling() manually - on
their own! Setting this to false means the LinearSystemAztecOO object
will call the computeScaling function right before it applies the
scaling to the matrix in the applyJacobianInverse function. Default is
true (user will call compute scaling).
"Output Solver Details" - (boolean) Write the output sublist below
to the parameter list after each linear solve. default is true.
"Write Linear System" - (boolean) If set to true, the linear system
(Epetra_Map, Jacobian, LHS and RHS) is printed to a set of files in
matrix market format. This option requires building nox with the flag
--enable-nox-debug and building the EpetraExt library.
"Write Linear System File Prefix" - (string) If writing of the
linear system is enabled (see above parameter) users can change the
name of the output file prefix. The default is "NOX_LinSys". This
option requires building nox with the flag --enable-nox-debug and
building the EpetraExt library.
"Output" sublist
The parameter list passed in during calls to ApplyJacobianInverse()
will have an "Output" sublist created that contains the following
parameters if the flag "Output Solver Details" is set to true:
"Acheived Tolerance" - Actual tolerance achieved by the linear
solver computed via the convergence test requested.
"Number of Linear Iterations" - Number of iterations used by the
linear solver in the last call to applyJacobianInverse
"Total Number of Linear Iterations" - Total number of linear solve
iterations performed by groups that have used this input list
C++ includes: NOX_Epetra_LinearSystem_AztecOO.H
1.7.6.1