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_Comm &	Comm () const
	get Comm of this class
const Epetra_Map &	OperatorDomainMap () const
	Get fine level OperatorDomainMap.
const Epetra_Map &	OperatorRangeMap () 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:

• --with-ml_nox
• --enable-epetra
• --enable-epetraext
• --enable-nox
• --enable-nox-epetra
• --enable-prerelease
• --enable-aztecoo
• --enable-amesos

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:

• ml_nox_preconditioner.H
• ml_nox_preconditioner1.cpp
• ml_nox_preconditioner2.cpp

---