SAMRAI::solv::KINSOLAbstractFunctions Class Reference

#include <source/solvers/packages/sundials/kinsol/KINSOLAbstractFunctions.h>

List of all members.

Public Member Functions
	KINSOLAbstractFunctions ()
virtual	~KINSOLAbstractFunctions ()
virtual void	evaluateNonlinearFunction (SundialsAbstractVector *soln, SundialsAbstractVector *fval)=0
virtual int	precondSetup (SundialsAbstractVector *soln, SundialsAbstractVector *soln_scale, SundialsAbstractVector *fval, SundialsAbstractVector *fval_scale, SundialsAbstractVector *vtemp1, SundialsAbstractVector *vtemp2, int &num_feval)=0
virtual int	precondSolve (SundialsAbstractVector *soln, SundialsAbstractVector *soln_scale, SundialsAbstractVector *fval, SundialsAbstractVector *fval_scale, SundialsAbstractVector *rhs, SundialsAbstractVector *vtemp, int &num_feval)=0
virtual int	jacobianTimesVector (SundialsAbstractVector *vector, SundialsAbstractVector *product, const bool soln_changed, SundialsAbstractVector *soln)=0

---

Detailed Description

Class KINSOLAbstractFunctions is an abstract base class that defines an interface for user-supplied functions to be used with KINSOL via the C++ wrapper class KINSOLSolver. To use KINSOL with the C++ wrapper one must derive a subclass of this base class and pass it into the KINSOLSolver constructor. The pure virtual member functions in this interface are used by KINSOL during the nonlinear system solution process. The complete argument lists in the function signatures defined by KINSOL have been preserved for the user-supplied routines have been preserved for the most part. In a few cases, some arguments do not appear in the function signatures below since they are superfluous via this interface.

KINSOL only requires that the function evaluateNonlinearFunction() be supplied. The other virtual functions are optional in KINSOL. Note that the use of the optional functions may be turned on and off via boolean arguments to the constructor of the KINSOLSolver class, or using the setKINSOLFunctions() member function of that class.

See also:

solv::KINSOLSolver

solv::SundialsAbstractVector

---

Constructor & Destructor Documentation

SAMRAI::solv::KINSOLAbstractFunctions::KINSOLAbstractFunctions

(

)

Uninteresting constructor destructor for KINSOLAbstractFunctions.

SAMRAI::solv::KINSOLAbstractFunctions::~KINSOLAbstractFunctions

(

)

[virtual]

---

Member Function Documentation

virtual void SAMRAI::solv::KINSOLAbstractFunctions::evaluateNonlinearFunction	(	SundialsAbstractVector *	soln,
		SundialsAbstractVector *	fval
	)			[pure virtual]

User-supplied nonlinear residual function evaluation.

The function arguments are:

• soln (INPUT) {current iterate for the nonlinear solution.}
• fval (OUTPUT){current value of residual function.}

IMPORTANT: This function must not modify the vector soln.

virtual int SAMRAI::solv::KINSOLAbstractFunctions::precondSetup	(	SundialsAbstractVector *	soln,
		SundialsAbstractVector *	soln_scale,
		SundialsAbstractVector *	fval,
		SundialsAbstractVector *	fval_scale,
		SundialsAbstractVector *	vtemp1,
		SundialsAbstractVector *	vtemp2,
		int &	num_feval
	)			[pure virtual]

User-supplied preconditioner setup function. The setup function is called to provide matrix data for the subsequent call(s) to precondSolve(). That is, this preconditioner setup function is used to evaluate and preprocess any Jacobian-related data needed by the preconditioner solve function. The integer return value is a flag indicating success if 0 is returned, and failure otherwise. If a non-zero value is returned, KINSOL stops. Together precondSetup() and precondSolve() form a right preconditoner for the KINSOL Krylov solver. This function will not be called prior to every call of precondSolve(), but instead will be called only as often as needed to achieve convergence within the Newton iteration.

The function arguments are:

• soln (INPUT) {current iterate for the nonlinear solution}
• fval (INPUT) {current values of the nonlinear residual}
• soln_scale (INPUT) {diagonal entries of the nonlinear solution scaling matrix}
• fval_scale (INPUT) {diagonal entries of the nonlinear residual scaling matrix}
• vtemp1 (INOUT) {temporary vector managed by KINSOL}
• vtemp2 (INOUT) {temporary vector managed by KINSOL}
• num_feval (OUTPUT){number of nonlinear function evaluations made to approximate the Jacobian, if any. For example, if the routine evaluates the function twice, num_feval is set to 2}

The scaling vectors are provided for possible use in approximating Jacobian data; e.g., uing difference quotients. The

IMPORTANT: This function must not modify the vector arguments.

virtual int SAMRAI::solv::KINSOLAbstractFunctions::precondSolve	(	SundialsAbstractVector *	soln,
		SundialsAbstractVector *	soln_scale,
		SundialsAbstractVector *	fval,
		SundialsAbstractVector *	fval_scale,
		SundialsAbstractVector *	rhs,
		SundialsAbstractVector *	vtemp,
		int &	num_feval
	)			[pure virtual]

User-supplied preconditioner solve function. This function must solve , where is the right preconditioner matrix formed by precondSetup(). The integer return value is a flag indicating success if 0 is returned, and failure otherwise. If a non-zero value is returned, KINSOL stops.

The function arguments are:

• soln (INPUT) {current iterate for the nonlinear solution}
• fval (INPUT) {current iterate for the nonlinear residual}
• soln_scale (INPUT) {diagonal entries of the nonlinear solution scaling matrix}
• fval_scale (INPUT) {diagonal entries of the nonlinear residual scaling matrix}
• rhs (OUTPUT){rhs-side (r) on input and must be set to preconditioner solution (i.e., x) on output}
• vtemp1 (INOUT) {temporary vector managed by KINSOL}
• num_feval (OUTPUT){number of nonlinear function evaluations made to approximate the Jacobian, if any. For example, if the routine evaluates the function twice, num_feval is set to 2}

IMPORTANT: This function must not modify soln, fval, or the scaling vectors.

virtual int SAMRAI::solv::KINSOLAbstractFunctions::jacobianTimesVector	(	SundialsAbstractVector *	vector,
		SundialsAbstractVector *	product,
		const bool	soln_changed,
		SundialsAbstractVector *	soln
	)			[pure virtual]

Optional user-supplied A times x routine, where A is an approximation to the Jacobian matrix and v is some vector. product = (A * vector) is computed.

The function arguments are:

• vector (INPUT) {the vector multiplied by the Jacobian}
• product (OUTPUT){product of the Jacobian and vector; )}
• new_soln (INPUT) {flag indicating whether solution has changed since last call to this routine. For example, if this routine computes and saves the Jacobian, then the Jacobian does not require computation if flag is false.}
• soln (INPUT) {current iterate for the nonlinear solution}

IMPORTANT: This function must not modify soln vector.

---

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

• source/solvers/packages/sundials/kinsol/KINSOLAbstractFunctions.h
• source/solvers/packages/sundials/kinsol/KINSOLAbstractFunctions.C

---