ML_NOX::ML_Nox_Preconditioner Class Reference

ML_Nox_Preconditioner: a class to define a multilevel nonlinear preconditioner and solver. More...

#include <ml_nox_preconditioner.H>

Inheritance diagram for ML_NOX::ML_Nox_Preconditioner:

[legend]
Collaboration diagram for ML_NOX::ML_Nox_Preconditioner:
[legend]
List of all members.

Public Member Functions

 ML_Nox_Preconditioner (ML_NOX::Ml_Nox_Fineinterface &interface, const Epetra_Comm &comm)
 Constructs an ML_Nox_Preconditioner class with default values.
 ML_Nox_Preconditioner (ML_NOX::Ml_Nox_Fineinterface &interface, Teuchos::ParameterList &mlparams, const Epetra_Comm &comm)
 Constructs an ML_Nox_Preconditioner class with parameter list.
 ~ML_Nox_Preconditioner ()
 Destroys the preconditioner.
bool SetNonlinearMethod (bool islinPrec, int maxlevel, bool ismatrixfree, bool ismatfreelev0, bool fixdiagonal)
 Set the type of nonlinear method to be used.
bool SetCoarsenType (string coarsentype, int maxlevel, int maxcoarsesize, int nnodeperagg)
 Set type of coarsening algorithm to be used.
bool SetSmoothers (string finesmoothertype, string smoothertype, string coarsesolve)
 Set type of smoother.
bool SetNonlinearSolvers (bool usenlnCG_fine, bool usenlnCG, bool usenlnCG_coarse, bool useBroyden, int nitersCG_fine, int nitersCG, int nitersCG_coarse)
 Set type of nonlinear solver for each level.
bool SetSmootherSweeps (int nsmooth_fine, int nsmooth, int nsmooth_coarse)
 Set number of sweeps of smoother.
bool SetPrintLevel (int printlevel)
 Set the ML print level.
bool SetRecomputeOffset (int offset)
 Set the offset for recomputing this preconditioner.
bool SetRecomputeOffset (int offset, int recomputestep, double adaptrecompute, int adaptns)
 Set the offset for recomputing this preconditioner.
bool SetDimensions (int spatialDimension, int numPDE, int dimNS)
 Set dimensions for the PDE and the Nullspace.
bool SetConvergenceCriteria (double FAS_normF, double FAS_nupdate)
 Set convergence criteria for nonlinear preconditioner.
bool SetFAScycle (int prefsmooth, int presmooth, int coarsesmooth, int postsmooth, int postfsmooth, int maxcycle)
 Set cycle for nonlinear preconditioner.
bool SetFiniteDifferencing (bool centered, double alpha, double beta)
 Set finite differencing method.
bool set_nox_solver (NOX::Solver::Manager *noxsolver)
 Register the outer Nox iterative method with the nonlinear preconditioner.
const char * Label () const
 Returns the label of this class.
const Epetra_CommComm () const
 get Comm of this class
const Epetra_MapOperatorDomainMap () const
 Get fine level OperatorDomainMap.
const Epetra_MapOperatorRangeMap () const
 Get fine level OperatorRangeMap.
bool isinit () const
 Check initialization flag of the instant of this class.
bool setinit (bool flag)
 Set the initialization flag of the instant of this class.
int getoffset ()
 Get the offset to recompute this preconditioner.
virtual bool computePreconditioner (const Epetra_Vector &x, NOX::Parameter::List *precParams=0)
 Construct the preconditioner.
int ApplyInverse (const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
 ApplyInverse the preconditioner.
int solve ()
 Apply the nonlinear multigrid FAS-solver.
int Apply (const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
 Apply the preconditioner, not implemented.
int SetUseTranspose (bool UseTranspose)
 SetUseTranspose, not implemented.
double NormInf () const
 NormInf, not implemented.
bool UseTranspose () const
 UseTranspose, not implemented.
bool HasNormInf () const
 HasNormInf, not implemented.

Detailed Description

ML_Nox_Preconditioner: a class to define a multilevel nonlinear preconditioner and solver.

Class ML_NOX::ML_Nox_Preconditioner defines an algebraic nonlinear preconditioner or solver that is based on a full approximation scheme (FAS) approach and is implemented making use of NOX' nonlinear solver capabilities. It operates on Epetra objects and implements an Epetra_Operator to be easily used as a preconditioner to some outer nonlinear iteration. It also implements the NOX::EpetraNew::Interface::Preconditioner from NOX so it can serve as it's own interface (see NOX documentation for details). In this class several methods and options can be chosen, which are described in the parameter set functions

To make use of the full functionality of this class it requires ML to be configured with the following options:

Warning:
Currently, using this class makes it necessary to configure and make install of Trilinos WITHOUT the --with-ml_nox, and then repeating the configure and make install process WITH the --with-ml_nox option to be able to resolve the dependencies of this class on NOX header files
Note:
an example is given in the directory ml/examples/NonlinML
Author:
Michael Gee, SNL 9214


Constructor & Destructor Documentation

ML_NOX::ML_Nox_Preconditioner::ML_Nox_Preconditioner ML_NOX::Ml_Nox_Fineinterface interface,
const Epetra_Comm comm
[explicit]
 

Constructs an ML_Nox_Preconditioner class with default values.

Constructs a ML_Nox_Preconditioner class and sets a set of default values. This constructor does NOT actually create the Multilevel hierarchy and the methods, this is done by a call to computePreconditioner.

Parameters:
interface (In) : ref to an ML_NOX::Ml_Nox_Fineinterface derived class
comm (In) : the Epetra_Comm to be used

ML_NOX::ML_Nox_Preconditioner::ML_Nox_Preconditioner ML_NOX::Ml_Nox_Fineinterface interface,
Teuchos::ParameterList mlparams,
const Epetra_Comm comm
[explicit]
 

Constructs an ML_Nox_Preconditioner class with parameter list.

Constructs a ML_Nox_Preconditioner class and sets a set of default values. This constructor does NOT actually create the Multilevel hierarchy and the methods, this is done by a call to computePreconditioner.

Teuchos parameters recognized and there default values:

   Teuchos::ParameterList mlparams;
   mlparams.set("nlnML output",6);                                        // Level of output to be generated (0-10), 6 recommended
   mlparams.set("nlnML max levels",10);                                   // Max # of levels to produce
   mlparams.set("nlnML coarse: max size",128);                            // Size of coarse grid where to stop coarsening
   mlparams.set("nlnML is linear preconditioner",false);                  // Act as linear preconditioner, else run FAS-cycle as nonlinear preconditioner
   mlparams.set("nlnML is matrixfree",true);                              // Finite difference for Jacobian
   mlparams.set("nlnML finite difference fine level",true);               // Finite difference for Jacobian on fine level only
   
   mlparams.set("nlnML finite difference alpha",1.0e-07);                 // Finite differencing perturbation parameter
   mlparams.set("nlnML finite difference beta",1.0e-06);                  // ---"---
   mlparams.set("nlnML finite difference centered",false);                // Finite differnencing scheme, true=centered, false=forward

   mlparams.set("nlnML absolute residual tolerance",1.0e-05);             // Internal absolute residual tolerance for FAS-cycle
   mlparams.set("nlnML max cycles",250);                                  // Max. # FAS-cycles before giving up
   mlparams.set("nlnML adaptive recompute",0.0);                          // Recompute preconditioner when outer residual is above this tolerance
   mlparams.set("nlnML offset recompute",0);                              // Recompute preconditioner every offset outer iterations
   mlparams.set("nlnML additional adaptive nullspace",0);                 // # additional adaptive nullspace candidates to compute
   
   mlparams.set("nlnML PDE equations",3);                                 // # PDE equations (degrees of freedom per node)
   mlparams.set("nlnML null space: dimension",3);                         // nullspace dimension
   mlparams.set("nlnML spatial dimension",3);                             // spatial dimension of problem
   
   mlparams.set("nlnML coarse: type","Uncoupled");                        // aggregation scheme: Uncoupled METIS VBMETIS
   mlparams.set("nlnML nodes per aggregate",27);                          // # nodes per aggregate for aggregation schemes "METIS" / "VBMETIS"

   mlparams.set("nlnML use nlncg on fine level",true);                    // use nonlinear CG as smoother on fine level, else use Newton-Krylov
   mlparams.set("nlnML use nlncg on medium level",true);                  // use nonlinear CG as smoother, else use Newton-Krylov
   mlparams.set("nlnML use nlncg on coarsest level",true);                // use nonlinear CG as smoother on coarsest level, else use Newton-Krylov
   
   mlparams.set("nlnML max iterations newton-krylov fine level",5);       // # iterations LINEAR CG in Newton-Krylov smoother fine level
   mlparams.set("nlnML max iterations newton-krylov medium level" ,5);    // # iterations LINEAR CG in Newton-Krylov smoother
   mlparams.set("nlnML max iterations newton-krylov coarsest level",5);   // # iterations LINEAR CG in Newton-Krylov smoother coarsest level 

   mlparams.set("nlnML linear smoother type fine level","SGS");           // type of linear fine smoother  : SGS BSGS Jacobi MLS Bcheby AmesosKLU
   mlparams.set("nlnML linear smoother type medium level","SGS");         // type of linear smoother       : SGS BSGS Jacobi MLS Bcheby AmesosKLU
   mlparams.set("nlnML linear smoother type coarsest level","AmesosKLU"); // type of linear coarse smoother: SGS BSGS Jacobi MLS Bcheby AmesosKLU 
   mlparams.set("nlnML linear smoother sweeps fine level",2);             // # of linear smoother sweeps/polynomial order for linear fine smoother
   mlparams.set("nlnML linear smoother sweeps medium level",2);           // # of linear smoother sweeps/polynomial order for linear smoother
   mlparams.set("nlnML linear smoother sweeps coarsest level",1);         // # of linear smoother sweeps/polynomial order for linear coarse smoother

   mlparams.set("nlnML nonlinear presmoothing sweeps fine level",0);      // # nonlinear presmoothing sweeps in FAS-cycle fine level
   mlparams.set("nlnML nonlinear presmoothing sweeps medium level",0);    // # nonlinear presmoothing sweeps in FAS-cycle
   mlparams.set("nlnML nonlinear smoothing sweeps coarse level",3);       // # nonlinear sweeps in FAS-cycle coarsest level
   mlparams.set("nlnML nonlinear postsmoothing sweeps medium level",3);   // # nonlinear postsmoothing sweeps in FAS-cycle
   mlparams.set("nlnML nonlinear postsmoothing sweeps fine level",3);     // # nonlinear postsmoothing sweeps in FAS-cycle fine level

Parameters:
interface (In) : ref to an ML_NOX::Ml_Nox_Fineinterface derived class
mlparams (In) : Teuchos parameter list
comm (In) : the Epetra_Comm to be used

ML_NOX::ML_Nox_Preconditioner::~ML_Nox_Preconditioner  ) 
 

Destroys the preconditioner.

Destroys the ML_Nox_Preconditioner.


Member Function Documentation

int ML_NOX::ML_Nox_Preconditioner::Apply const Epetra_MultiVector X,
Epetra_MultiVector Y
const [inline, virtual]
 

Apply the preconditioner, not implemented.

Derived from Epetra_Operator, not implemented.

Implements Epetra_Operator.

int ML_NOX::ML_Nox_Preconditioner::ApplyInverse const Epetra_MultiVector X,
Epetra_MultiVector Y
const [virtual]
 

ApplyInverse the preconditioner.

ApplyInverse the preconditioner. Method is derived from Epetra_Operator.

Parameters:
X (In) : Epetra_MultiVector matching the fine level map of this preconditioner
Y (Out) : Epetra_MultiVector containing the result on output

Implements Epetra_Operator.

const Epetra_Comm& ML_NOX::ML_Nox_Preconditioner::Comm  )  const [inline, virtual]
 

get Comm of this class

Derived from Epetra_Operator, returns ref to the Epetra_Comm of this class

Implements Epetra_Operator.

bool ML_NOX::ML_Nox_Preconditioner::computePreconditioner const Epetra_Vector x,
NOX::Parameter::List *  precParams = 0
[virtual]
 

Construct the preconditioner.

Construct the preconditioner. This is derived from the NOX::EpetraNew::Interface::Preconditioner class. Nox will use this to (re)compute the preconditioner.

Parameters:
x (In) : Vector of the current solution
precParams (In) : ignored

int ML_NOX::ML_Nox_Preconditioner::getoffset  )  [inline]
 

Get the offset to recompute this preconditioner.

Get the offset to recompute this preconditioner.

bool ML_NOX::ML_Nox_Preconditioner::HasNormInf  )  const [inline, virtual]
 

HasNormInf, not implemented.

Derived from Epetra_Operator, always returns false.

Implements Epetra_Operator.

bool ML_NOX::ML_Nox_Preconditioner::isinit  )  const [inline]
 

Check initialization flag of the instant of this class.

check the init-flag of this instant, if false, ApplyInverse will throw an error.

const char* ML_NOX::ML_Nox_Preconditioner::Label  )  const [inline, virtual]
 

Returns the label of this class.

Returns the label of this class.

Implements Epetra_Operator.

double ML_NOX::ML_Nox_Preconditioner::NormInf  )  const [inline, virtual]
 

NormInf, not implemented.

Derived from Epetra_Operator, not implemented.

Implements Epetra_Operator.

const Epetra_Map& ML_NOX::ML_Nox_Preconditioner::OperatorDomainMap  )  const [inline, virtual]
 

Get fine level OperatorDomainMap.

Derived from Epetra_Operator, get fine level OperatorDomainMap.

Implements Epetra_Operator.

const Epetra_Map& ML_NOX::ML_Nox_Preconditioner::OperatorRangeMap  )  const [inline, virtual]
 

Get fine level OperatorRangeMap.

Derived from Epetra_Operator, get fine level OperatorRangeMap.

Implements Epetra_Operator.

bool ML_NOX::ML_Nox_Preconditioner::set_nox_solver NOX::Solver::Manager *  noxsolver  )  [inline]
 

Register the outer Nox iterative method with the nonlinear preconditioner.

Register the outer Nox iterative method with the nonlinear preconditioner. This is necessary, because the outer NOX iterative method will provide the nonlinear preconditioner with current solution and residual. Necessary only in the islinearPrec==false case and when used as a preconditioner. If used as stand-alone solver, this is not necessary.

Parameters:
noxsolver (In) : ptr to the NOX::Solver::Manager of the outer Nox iterative method.

bool ML_NOX::ML_Nox_Preconditioner::SetCoarsenType string  coarsentype,
int  maxlevel,
int  maxcoarsesize,
int  nnodeperagg
 

Set type of coarsening algorithm to be used.

Set type of coarsening algorithm to be used. Currently, this class recognizes the ML-coarsening schemes Uncoupled, METIS and VBMETIS.

Parameters:
coarsentype (In) : string giving the coarsening scheme, currently "Uncoupled", "METIS" and "VBMETIS" are recognized
maxlevel (In) : maximum number of levels to generate
maxcoarsesize (In) : coarse grid size to stop coarsening when reached
nnodeperagg (In) : objective how many nodes to put in one aggregate for coarsening schemes "METIS" and "VBMETIS".

bool ML_NOX::ML_Nox_Preconditioner::SetConvergenceCriteria double  FAS_normF,
double  FAS_nupdate
 

Set convergence criteria for nonlinear preconditioner.

Set convergence criteria for nonlinear preconditioner. Takes effect for islinPrec==false only.

Parameters:
FAS_normF (In) : Residual norm a nonlinear iteration on some level is considered converged.
FAS_nupdate (In) : Norm of stepsize a nonlinear iteration on some level is considered converged.

bool ML_NOX::ML_Nox_Preconditioner::SetDimensions int  spatialDimension,
int  numPDE,
int  dimNS
 

Set dimensions for the PDE and the Nullspace.

Set dimensions for the PDE and the Nullspace.

Parameters:
spatialDimension (In) : spatial dimension of the problem.
numPDE (In) : Number of PDE equations, normally number of dofs per node.
dimNS (In) : Dimension of the nullspace. The preconditioner will ask for the Nullspace through the fine level interface. If know Nullspace is supplied there, the default Nullspace is used and a warning is printed.

bool ML_NOX::ML_Nox_Preconditioner::SetFAScycle int  prefsmooth,
int  presmooth,
int  coarsesmooth,
int  postsmooth,
int  postfsmooth,
int  maxcycle
 

Set cycle for nonlinear preconditioner.

Set cycle for nonlinear preconditioner. Takes effect for islinPrec==false only.

Parameters:
prefsmooth (In) : maximum number of nonlinear iterations to take as a presmoothing step on finest level
presmooth (In) : maximum number of nonlinear iterations to take as a presmoothing step on coarse levels
coarsesmooth (In) : maximum number of nonlinear iterations to take on coarsest level
postsmooth (In) : maximum number of nonlinear iterations to take as a postsmoothing step on coarse levels
postfsmooth (In) : maximum number of nonlinear iterations to take as a postsmoothing step on finest level
maxcycle (In) : maximum number of nonlinear MG cycles to take before we give up

bool ML_NOX::ML_Nox_Preconditioner::SetFiniteDifferencing bool  centered,
double  alpha,
double  beta
 

Set finite differencing method.

Set finite differencing method. Takes effect for ismatrixfree==true only.

Parameters:
centered (In) : if true, use centered finite differencing, else use forward finite differencing (true is twice the cost)
alpha (In) : perturbation parameter, see EpetraExt manual
beta (In) : perturbation parameter, see EpetraExt manual

bool ML_NOX::ML_Nox_Preconditioner::setinit bool  flag  )  [inline]
 

Set the initialization flag of the instant of this class.

Set the init-flag of this instant.

bool ML_NOX::ML_Nox_Preconditioner::SetNonlinearMethod bool  islinPrec,
int  maxlevel,
bool  ismatrixfree,
bool  ismatfreelev0,
bool  fixdiagonal
 

Set the type of nonlinear method to be used.

Set the type of nonlinear method to be used on each level of the hierarchy

Parameters:
islinPrec (In) : if true, compute a linear multigrid operator, if false, create a FAS multilevel hierarchy
maxlevel (In) : maximum number of levels.
ismatrixfree (In) : if true, use Finite Differencing to construct the Jacobians on all levels. In this case, the preconditioner will ask for a Epetra_CrsGraph through the fine level interface and will build a plain aggregation hierarchy based on it. If Jacobi is chosen as a smoother on any level, on that level only the main diagonal of the Jacobian will be computed. If false, the preconditioner will ask for an Epetra_CrsMatrix and an Epetra_CrsGraph through the fine level interface and will construct a smoothed aggregation MG hierarchy based on it. Coarse level operators will then be Galerkin.
ismatfreelev0 (In) : if true AND ismatrixfree==true, the preconditioner will construct a finite difference Jacobian on the fine level and then will use it to construct a smoothed aggregation hierarchy. Coarse level operators will be Galerkin. Option has no effect when ismatrixfree==false.

bool ML_NOX::ML_Nox_Preconditioner::SetNonlinearSolvers bool  usenlnCG_fine,
bool  usenlnCG,
bool  usenlnCG_coarse,
bool  useBroyden,
int  nitersCG_fine,
int  nitersCG,
int  nitersCG_coarse
 

Set type of nonlinear solver for each level.

Set type of nonlinear solver for each level and number of LINEAR CG-iterations allowed inside Newton's method.

Parameters:
usenlnCG_fine (In) : If true, use nlnCG on finest level, if false, use Newton's method.
usenlnCG (In) : If true, use nlnCG on all intermediate levels, if false use Newton's method.
usenlnCG_coarse (In) : If true, use nlnCG on coarsest level, if false, use Newton's method.
useBroyden (In) : If true, use Broyden update for Jacobian, will only affect levels on which Newton's method is used.
nitersCG_fine (In) : If Newton's method is used on finest level, this is the max. number of LINEAR CG iterations allowed for the linear solve inside.
nitersCG (In) : If Newton's method is used on intermediate levels, this is the max. number of LINEAR CG iterations allowed for the linear solve inside.
nitersCG_fine (In) : If Newton's method is used on coarsest level, this is the max. number of LINEAR CG iterations allowed for the linear solve inside.
Note:
When using Newton's method with or without Broyden update, Aztec's PCG will be used as linear solver inside. The preconditioner to this LINEAR CG will then be the smoother chosen via the method SetSmoothers.

bool ML_NOX::ML_Nox_Preconditioner::SetPrintLevel int  printlevel  ) 
 

Set the ML print level.

Set the ML print level between 0 and 10.

Parameters:
printlevel (In) : (0-10), amount of output generated by NOX/ML

bool ML_NOX::ML_Nox_Preconditioner::SetRecomputeOffset int  offset,
int  recomputestep,
double  adaptrecompute,
int  adaptns
 

Set the offset for recomputing this preconditioner.

Set the offset for recomputing this preconditioner. Every offset times, the preconditioner is applied it will recreate itself and will use the fine level interface to obtain either a new fine level Jacobian or to compute a Finite Differencing - Jacobian. Optionally, the MG hierarchy and Jacobian can be recomputed after the recomputestep iteration

Parameters:
offset (In) : How often to apply this preconditioner before recomputing it.

bool ML_NOX::ML_Nox_Preconditioner::SetRecomputeOffset int  offset  ) 
 

Set the offset for recomputing this preconditioner.

Set the offset for recomputing this preconditioner. Every offset times, the preconditioner is applied it will recreate itself and will use the fine level interface to obtain either a new fine level Jacobian or to compute a Finite Differencing - Jacobian.

Parameters:
offset (In) : How often to apply this preconditioner before recomputing it.

bool ML_NOX::ML_Nox_Preconditioner::SetSmoothers string  finesmoothertype,
string  smoothertype,
string  coarsesolve
 

Set type of smoother.

Set type of smoother. Currently, this class recognizes the ML-smoothers Jacobi, SGS and AmesosKLU.

Parameters:
finesmoothertype (In) : string giving the fine level smoother, currently "Jacobi", "SGS" and "AmesosKLU" are recognized.
smoothertype (In) : string giving the smoother on all intermediate levels, currently "Jacobi", "SGS" and "AmesosKLU" are recognized.
coarsesolve (In) : string giving the smoother on the coarsest level, currently "Jacobi", "SGS" and "AmesosKLU" are recognized.

bool ML_NOX::ML_Nox_Preconditioner::SetSmootherSweeps int  nsmooth_fine,
int  nsmooth,
int  nsmooth_coarse
 

Set number of sweeps of smoother.

Set number of sweeps of smoother.

Parameters:
nsmooth_fine (In) : Number of smoothing sweeps on fine level
nsmooth (In) : Number of smoothing sweeps on intermediate levels
nsmooth_coarse (In) : Number of smoothing sweeps on coarsest level
Note:
When using nlnCG on a level, this is the number of sweeps of the preconditioner to nlnCG. When using Newton's method on a level, this is the number of sweeps of the preconditioner to the LINEAR CG inside the Newton iteration on that level.

int ML_NOX::ML_Nox_Preconditioner::SetUseTranspose bool  UseTranspose  )  [virtual]
 

SetUseTranspose, not implemented.

Derived from Epetra_Operator, not implemented.

Implements Epetra_Operator.

int ML_NOX::ML_Nox_Preconditioner::solve  ) 
 

Apply the nonlinear multigrid FAS-solver.

Apply the nonlinear multigrid FAS-solver. This preconditioner can act as a stand-alone FAS-Solver. Will throw an error, if islinearPrec==true;

bool ML_NOX::ML_Nox_Preconditioner::UseTranspose  )  const [inline, virtual]
 

UseTranspose, not implemented.

Derived from Epetra_Operator, not implemented.

Implements Epetra_Operator.


The documentation for this class was generated from the following files:
Generated on Thu Sep 18 12:40:58 2008 for ML by doxygen 1.3.9.1