SAMRAI::solv::SNES_SAMRAIContext< DIM > Class Template Reference

#include <source/solvers/packages/petsc/SNES_SAMRAIContext.h>

Inheritance diagram for SAMRAI::solv::SNES_SAMRAIContext< DIM >:

[legend]List of all members.

Public Member Functions
	SNES_SAMRAIContext (const string &object_name, tbox::Pointer< tbox::Database > input_db, SNESAbstractFunctions *my_functions)
	~SNES_SAMRAIContext ()
SNES	getSNESSolver () const
SNESAbstractFunctions *	getSNESFunctions () const
SLES	getSLESSolver () const
KSP	getKrylovSolver () const
Mat	getJacobianMatrix () const
double	getAbsoluteTolerance () const
void	setAbsoluteTolerance (double abs_tol)
double	getRelativeTolerance () const
void	setRelativeTolerance (double rel_tol)
double	getStepTolerance () const
void	setStepTolerance (double step_tol)
int	getMaxNonlinearIterations () const
void	setMaxNonlinearIterations (int max_nli)
int	getMaxFunctionEvaluations () const
void	setMaxFunctionEvaluations (int max_feval)
string	getForcingTermStrategy () const
void	setForcingTermStrategy (string &strategy)
double	getConstantForcingTerm () const
void	setConstantForcingTerm (double fixed_eta)
double	getInitialForcingTerm () const
void	setInitialForcingTerm (double initial_eta)
double	getMaximumForcingTerm () const
void	setMaximumForcingTerm (double max_eta)
double	getEWChoice2Exponent () const
void	setEWChoice2Exponent (double alpha)
double	getEWChoice2SafeguardExponent () const
void	setEWChoice2SafeguardExponent (double beta)
double	getEWChoice2ScaleFactor () const
void	setEWChoice2ScaleFactor (double gamma)
double	getEWSafeguardThreshold () const
void	setEWSafeguardThreshold (double threshold)
string	getLinearSolverType () const
void	setLinearSolverType (string &type)
bool	getUsesPreconditioner () const
void	setUsesPreconditioner (bool uses_preconditioner)
double	getLinearSolverAbsoluteTolerance () const
void	setLinearSolverAbsoluteTolerance (double abs_tol)
double	getLinearSolverDivergenceTolerance () const
void	setLinearSolverDivergenceTolerance (double div_tol)
int	getMaximumLinearIterations () const
void	setMaximumLinearIterations (int max_li)
int	getMaximumGMRESKrylovDimension () const
void	setMaximumGMRESKrylovDimension (int d)
string	getGMRESOrthogonalizationMethod () const
void	setGMRESOrthogonalizationMethod (string &method)
bool	getUsesExplicitJacobian () const
void	setUsesExplicitJacobian (bool use_jac)
string	getDifferencingParameterMethod () const
void	setDifferencingParameterMethod (string &method)
double	getFunctionEvaluationError () const
void	setFunctionEvaluationError (double evaluation_error)
void	initialize (tbox::Pointer< SAMRAIVectorReal< DIM, double > > solution)
void	resetSolver (const int coarsest_level, const int finest_level)
int	solve ()
int	getNonlinearIterationCount () const
int	getTotalLinearIterationCount () const
void	reportCompletionCode (ostream &os=tbox::plog) const
void	putToDatabase (tbox::Pointer< tbox::Database > db)
void	printClassData (ostream &os) const

---

Detailed Description

template<int DIM>
class SAMRAI::solv::SNES_SAMRAIContext< DIM >

Class SNES_SAMRAIContext<DIM> provides an interface to the SNES nonlinear solver capabilities in PETSc to facilitate their use with SAMRAI. While PETSc is implemented in an object-based manner, this class makes it easier to use PETSc's routines with SAMRAI data structures. In particular, it hides from the user some of the messy details required to link the C++ class library with PETSc which is written in C and to override PETSc objects, like vectors, with those found in SAMRAI.

This class declares five private static member functions to link user-defined routines for nonlinear residual calculation, Jacobian evaluation, preconditioner setup and solve, and Jacobian-vector product operations. The implementation of these functions is defined by the user in a subclass of the abstract base class SNESAbstractFunctions. The vector objects used within the solver are provided by the PETSc_SAMRAIVectorReal<DIM> wrapper class.

If no parameters are read from input, PETSc defaults are used. See the PETSc documentation (http://www-unix.mcs.anl.gov/petsc/). for more information on default parameters and SNES functionality.

Optional input keys and types that can be read by this class are:

• absolute_tolerance double value for absolute nonlinear convergence tolerance

• relative_tolerance double value for relative nonlinear convergence tolerance

• step_tolerance double value for minimum tolerance on change in solution norm between nonlinear iterates

• maximum_nonlinear_iterations integer value for maximum number of nonlinear iterations

• maximum_function_evals integer value for maximum number of nonlinear function evaluations

• forcing_term_strategy integer value for forcing term choice for linear solvers within the inexact Newton method. Choices are "CONSTANT" (default), "EWCHOICE1", and "EWCHOICE2".

• constant_forcing_term double value for constant relative convergence tolerance in Krylov solver (default case)

• initial_forcing_term double value for initial relative convergence tolerance in Krylov solver (used in Eisenstat-Walker case). Value must satisfy .

• maximum_forcing_term double value for maximum relative convergence tolerance in Krylov solver (used in Eisenstat-Walker case). Value must satisfy .

• EW_choice2_alpha double value for power used in Eisenstat-Walker choice 2 relative convergence tolerance computation. Value must satisfy .

• EW_safeguard_exponent double value for power for safeguard used in Eisenstat-Walker choice 2

• EW_choice2_gamma double value for multiplicative factor used in Eisenstat-Walker choice 2 relative convergence tolerance computation. Value must satisfy .

• EW_safeguard_disable_threshold double value for threshold for imposing safeguard in Eisenstat-Walker choice 2. Value must satisfy .

• linear_solver_type string value for type of linear solver. See the PETSc documentation for the valid types.

• uses_preconditioner boolean value for whether or not a preconditioner is used in the solution of the Newton equations.

• linear_solver_absolute_tolerance double value for absolute convergence tolerance in linear solver

• linear_solver_divergence_tolerance double value for amount linear solver residual can increase before solver concludes method is diverging

• maximum_linear_iterations integer value for maximum number of linear solver iterations

• maximum_gmres_krylov_dimension integer value for maximum dimension of Krylov subspace before restarting. Valid only if GMRES is used as the linear solver.

• gmres_orthogonalization_algorithm string value for algorithm used to incrementally construct the orthonormal basis of the Krylov subspace used by GMRES. Valid only if GMRES is used as the linear solver. See the PETSc documentation for valid values.

• uses_explicit_jacobian boolean value for whether or not the user provides code to explicitly calculate Jacobian-vector products.

• differencing_parameter_strategy string value indicating strategy used for computing the differencing parameter when Jacobian-vector products are approximated via finite differences. See the PETSc documentation for valid values.

• function_evaluation_error double value that is the square root of the estimated relative error in function evaluation.

Note that all input values may override values read in from restart. If no new input value is given, the restart value is used.

A sample input file entry might look like:

      absolute_tolerance             = 10.e-10
      relative_tolerance             = 10.e-6
      step_tolerance                 = 10.e-8
      maximum_nonlinear_iterations   = 200
      forcing_term_strategy          = "EWCHOICE1"

Note that input values can also be set using accessor functions. Values that are set via this mechanism will be cached both in the solver context as well as in the corresponding PETSc object. Thus values changed on-the-fly will be written to restart. These input values can also be changed by directly accessing the corresponding PETSc object and using native PETSc function calls; however such settings/changes will NOT be cached in the solver context, and so will not be written to restart.

See also:

solv::SNESAbstractFunctions

solv::NonlinearSolverStrategy

---

Constructor & Destructor Documentation

template<int DIM> SAMRAI::solv::SNES_SAMRAIContext< DIM >::SNES_SAMRAIContext (  const string &  object_name, tbox::Pointer< tbox::Database >  input_db, SNESAbstractFunctions *  my_functions )

Constructor for SNES_SAMRAIContext<DIM> allocates the SNES object and initializes rudimentary state associated with user-supplied solver components. Then, it reads solver parameter from input and restart which may override default values. When assertion checking is active, an unrecoverable exception will result if the name string is empty or the pointer to the user-defined SNES functions object is null.

template<int DIM> SAMRAI::solv::SNES_SAMRAIContext< DIM >::~SNES_SAMRAIContext (   )

Destructor for solve_SNES_SAMRAIContext destroys the SNES and the PETSc solution vector wrapper.

---

Member Function Documentation

template<int DIM> SNES SAMRAI::solv::SNES_SAMRAIContext< DIM >::getSNESSolver (   )  const

Return the PETSc nonlinear solver object.

template<int DIM> SNESAbstractFunctions * SAMRAI::solv::SNES_SAMRAIContext< DIM >::getSNESFunctions (   )  const

Return pointer to object providing user-defined functions for SNES.

template<int DIM> SLES SAMRAI::solv::SNES_SAMRAIContext< DIM >::getSLESSolver (   )  const

Return the PETSc linear solver object.

template<int DIM> KSP SAMRAI::solv::SNES_SAMRAIContext< DIM >::getKrylovSolver (   )  const

Return the PETSc Krylov solver object.

template<int DIM> Mat SAMRAI::solv::SNES_SAMRAIContext< DIM >::getJacobianMatrix (   )  const

Return the PETSc Mat object for the Jacobian.

template<int DIM> double SAMRAI::solv::SNES_SAMRAIContext< DIM >::getAbsoluteTolerance (   )  const

Get absolute tolerance for nonlinear solver.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setAbsoluteTolerance (  double  abs_tol  )

Set absolute tolerance for nonlinear solver.

template<int DIM> double SAMRAI::solv::SNES_SAMRAIContext< DIM >::getRelativeTolerance (   )  const

Get relative tolerance for nonlinear solver.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setRelativeTolerance (  double  rel_tol  )

Set relative tolerance for nonlinear solver.

template<int DIM> double SAMRAI::solv::SNES_SAMRAIContext< DIM >::getStepTolerance (   )  const

Get step tolerance for nonlinear solver.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setStepTolerance (  double  step_tol  )

Set step tolerance for nonlinear solver.

template<int DIM> int SAMRAI::solv::SNES_SAMRAIContext< DIM >::getMaxNonlinearIterations (   )  const

Get maximum iterations for nonlinear solver.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setMaxNonlinearIterations (  int  max_nli  )

Set maximum iterations for nonlinear solver.

template<int DIM> int SAMRAI::solv::SNES_SAMRAIContext< DIM >::getMaxFunctionEvaluations (   )  const

Get maximum function evaluations by nonlinear solver.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setMaxFunctionEvaluations (  int  max_feval  )

Set maximum function evaluations in nonlinear solver.

template<int DIM> string SAMRAI::solv::SNES_SAMRAIContext< DIM >::getForcingTermStrategy (   )  const

Get strategy for forcing term.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setForcingTermStrategy (  string &  strategy  )

Set strategy for forcing term.

template<int DIM> double SAMRAI::solv::SNES_SAMRAIContext< DIM >::getConstantForcingTerm (   )  const

Get value of constant forcing term.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setConstantForcingTerm (  double  fixed_eta  )

Set value of constant forcing term.

template<int DIM> double SAMRAI::solv::SNES_SAMRAIContext< DIM >::getInitialForcingTerm (   )  const

Get value of initial forcing term.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setInitialForcingTerm (  double  initial_eta  )

Set value of initial forcing term.

template<int DIM> double SAMRAI::solv::SNES_SAMRAIContext< DIM >::getMaximumForcingTerm (   )  const

Get value of maximum forcing term.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setMaximumForcingTerm (  double  max_eta  )

Set value of maximum forcing term.

template<int DIM> double SAMRAI::solv::SNES_SAMRAIContext< DIM >::getEWChoice2Exponent (   )  const

Get value of exponent in Eisenstat-Walker Choice 2 forcing term.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setEWChoice2Exponent (  double  alpha  )

Set value of exponent in Eisenstat-Walker Choice 2 forcing term.

template<int DIM> double SAMRAI::solv::SNES_SAMRAIContext< DIM >::getEWChoice2SafeguardExponent (   )  const

Get value of exponent in Eisenstat-Walker Choice 2 safeguard.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setEWChoice2SafeguardExponent (  double  beta  )

Set value of exponent in Eisenstat-Walker Choice 2 safeguard.

template<int DIM> double SAMRAI::solv::SNES_SAMRAIContext< DIM >::getEWChoice2ScaleFactor (   )  const

Get value of factor used to scale Eisenstat-Walker Choice 2 forcing term.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setEWChoice2ScaleFactor (  double  gamma  )

Set value of factor used to scale Eisenstat-Walker Choice 2 forcing term.

template<int DIM> double SAMRAI::solv::SNES_SAMRAIContext< DIM >::getEWSafeguardThreshold (   )  const

Get value of threshold to disable safeguard in Eisenstat-Walker forcing terms.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setEWSafeguardThreshold (  double  threshold  )

Set value of threshold to disable safeguard in Eisenstat-Walker forcing terms.

template<int DIM> string SAMRAI::solv::SNES_SAMRAIContext< DIM >::getLinearSolverType (   )  const

Get type of linear solver.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setLinearSolverType (  string &  type  )

Set type of linear solver.

template<int DIM> bool SAMRAI::solv::SNES_SAMRAIContext< DIM >::getUsesPreconditioner (   )  const

Get whether a preconditioner is used.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setUsesPreconditioner (  bool  uses_preconditioner  )

Set whether to use a preconditioner.

template<int DIM> double SAMRAI::solv::SNES_SAMRAIContext< DIM >::getLinearSolverAbsoluteTolerance (   )  const

Get absolute tolerance for linear solver.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setLinearSolverAbsoluteTolerance (  double  abs_tol  )

Set absolute tolerance for linear solver.

template<int DIM> double SAMRAI::solv::SNES_SAMRAIContext< DIM >::getLinearSolverDivergenceTolerance (   )  const

Get divergence tolerance for linear solver.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setLinearSolverDivergenceTolerance (  double  div_tol  )

Set divergence tolerance for linear solver.

template<int DIM> int SAMRAI::solv::SNES_SAMRAIContext< DIM >::getMaximumLinearIterations (   )  const

Get maximum linear iterations for linear solver.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setMaximumLinearIterations (  int  max_li  )

Set maximum linear iterations for linear solver.

template<int DIM> int SAMRAI::solv::SNES_SAMRAIContext< DIM >::getMaximumGMRESKrylovDimension (   )  const

Get maximum Krylov dimension in GMRES linear solver.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setMaximumGMRESKrylovDimension (  int  d  )

Set maximum Krylov dimension in GMRES linear solver.

template<int DIM> string SAMRAI::solv::SNES_SAMRAIContext< DIM >::getGMRESOrthogonalizationMethod (   )  const

Get orthogonalization method used in GMRES linear solver.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setGMRESOrthogonalizationMethod (  string &  method  )

Set orthogonalization method used in GMRES linear solver.

template<int DIM> bool SAMRAI::solv::SNES_SAMRAIContext< DIM >::getUsesExplicitJacobian (   )  const

Get whether a method for explicit Jacobian-vector products is provided.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setUsesExplicitJacobian (  bool  use_jac  )

Set whether a method for explicit Jacobian-vector products is provided.

template<int DIM> string SAMRAI::solv::SNES_SAMRAIContext< DIM >::getDifferencingParameterMethod (   )  const

Get method for computing differencing parameter.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setDifferencingParameterMethod (  string &  method  )

Set method for computing differencing parameter.

template<int DIM> double SAMRAI::solv::SNES_SAMRAIContext< DIM >::getFunctionEvaluationError (   )  const

Get estimate of error in function evaluation.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::setFunctionEvaluationError (  double  evaluation_error  )

Set estimate of error in function evaluation.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::initialize (  tbox::Pointer< SAMRAIVectorReal< DIM, double > >  solution  )  [virtual]

Initialize the state of the SNES solver based on vector argument representing the solution of the nonlinear system. In general, this routine must be called before the solve() routine is invoked. Implements SAMRAI::solv::NonlinearSolverStrategy< DIM >.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::resetSolver (  const int  coarsest_level, const int  finest_level )

Reset the state of the nonlinear solver after regridding.

template<int DIM> int SAMRAI::solv::SNES_SAMRAIContext< DIM >::solve (   )  [virtual]

Solve the nonlinear problem. In general, the initialize() routine must be called before this solve function to set up the solver. Returns 1 if successful, 0 otherwise. Implements SAMRAI::solv::NonlinearSolverStrategy< DIM >.

template<int DIM> int SAMRAI::solv::SNES_SAMRAIContext< DIM >::getNonlinearIterationCount (   )  const

Obtain number of nonlinear iterations.

template<int DIM> int SAMRAI::solv::SNES_SAMRAIContext< DIM >::getTotalLinearIterationCount (   )  const

Obtain total number of linear iterations accumulated over all nonlinear iterations.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::reportCompletionCode (  ostream &  os = tbox::plog  )  const

Report reason for termination.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::putToDatabase (  tbox::Pointer< tbox::Database >  db  )

Write solver parameters to restart database matching object name. When assertion checking is active, an unrecoverable exception will result if database pointer is null.

template<int DIM> void SAMRAI::solv::SNES_SAMRAIContext< DIM >::printClassData (  ostream &  os  )  const

Print out all members of integrator instance to given output stream.

---

The documentation for this class was generated from the following files:

• source/solvers/packages/petsc/SNES_SAMRAIContext.h
• source/solvers/packages/petsc/SNES_SAMRAIContext.C

---