NOX::Epetra::FiniteDifference Class Reference

Concrete implementation for creating an Epetra_RowMatrix Jacobian via finite differencing of the residual. More...

#include <NOX_Epetra_FiniteDifference.H>

Inheritance diagram for NOX::Epetra::FiniteDifference:

[legend]
Collaboration diagram for NOX::Epetra::FiniteDifference:
[legend]
List of all members.

Public Types

enum  DifferenceType { Forward, Backward, Centered }
 Define types for use of the perturbation parameter $ \delta$.

Public Member Functions

 FiniteDifference (Interface &i, const Epetra_Vector &initialGuess, double beta=1.0e-6, double alpha=1.0e-4)
 Constructor.
 FiniteDifference (Interface &i, const Epetra_Vector &initialGuess, const Epetra_Vector &beta, double alpha=1.0e-4)
 Constructor.
 FiniteDifference (Interface &i, const Epetra_Vector &initialGuess, const Epetra_CrsGraph &g, double beta=1.0e-6, double alpha=1.0e-4)
 Constructor that takes a pre-constructed Epetra_CrsGraph so it does not have to determine the non-zero entries in the matrix.
 FiniteDifference (Interface &i, const Epetra_Vector &initialGuess, const Epetra_CrsGraph &g, const Epetra_Vector &beta, double alpha=1.0e-4)
 Constructor that takes a pre-constructed Epetra_CrsGraph so it does not have to determine the non-zero entries in the matrix.
virtual ~FiniteDifference ()
 Pure virtual destructor.
virtual const char * Label () const
 Returns a character string describing the name of the operator.
virtual int SetUseTranspose (bool UseTranspose)
 If set true, the transpose of this operator will be applied.
virtual int Apply (const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
 Return the result on an Epetra_Operator applied to an Epetra_MultiVector X in Y.
virtual int ApplyInverse (const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
 Return the result on an Epetra_Operator inverse applied to an Epetra_MultiVector X in Y.
virtual bool UseTranspose () const
 Returns the current use transpose setting.
virtual bool HasNormInf () const
 Returns true if the this object can provide an approximate Inf-norm, false otherwise.
virtual const Epetra_MapOperatorDomainMap () const
 Returns the Epetra_BlockMap object associated with the domain of this matrix operator.
virtual const Epetra_MapOperatorRangeMap () const
 Returns the Epetra_BlockMap object associated with the range of this matrix operator.
virtual bool Filled () const
 See Epetra_RowMatrix documentation.
virtual int NumMyRowEntries (int MyRow, int &NumEntries) const
 See Epetra_RowMatrix documentation.
virtual int MaxNumEntries () const
 See Epetra_RowMatrix documentation.
virtual int ExtractMyRowCopy (int MyRow, int Length, int &NumEntries, double *Values, int *Indices) const
 See Epetra_RowMatrix documentation.
virtual int ExtractDiagonalCopy (Epetra_Vector &Diagonal) const
 See Epetra_RowMatrix documentation.
virtual int Multiply (bool TransA, const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
 See Epetra_RowMatrix documentation.
virtual int Solve (bool Upper, bool Trans, bool UnitDiagonal, const Epetra_MultiVector &X, Epetra_MultiVector &Y) const
 See Epetra_RowMatrix documentation.
virtual int InvRowSums (Epetra_Vector &x) const
 See Epetra_RowMatrix documentation.
virtual int LeftScale (const Epetra_Vector &x)
 See Epetra_RowMatrix documentation.
virtual int InvColSums (Epetra_Vector &x) const
 See Epetra_RowMatrix documentation.
virtual int RightScale (const Epetra_Vector &x)
 See Epetra_RowMatrix documentation.
virtual double NormInf () const
 See Epetra_RowMatrix documentation.
virtual double NormOne () const
 See Epetra_RowMatrix documentation.
virtual int NumGlobalNonzeros () const
 See Epetra_RowMatrix documentation.
virtual int NumGlobalRows () const
 See Epetra_RowMatrix documentation.
virtual int NumGlobalCols () const
 See Epetra_RowMatrix documentation.
virtual int NumGlobalDiagonals () const
 See Epetra_RowMatrix documentation.
virtual int NumMyNonzeros () const
 See Epetra_RowMatrix documentation.
virtual int NumMyRows () const
 See Epetra_RowMatrix documentation.
virtual int NumMyCols () const
 See Epetra_RowMatrix documentation.
virtual int NumMyDiagonals () const
 See Epetra_RowMatrix documentation.
virtual bool LowerTriangular () const
 See Epetra_RowMatrix documentation.
virtual bool UpperTriangular () const
 See Epetra_RowMatrix documentation.
virtual const Epetra_CommComm () const
 See Epetra_RowMatrix documentation.
virtual const Epetra_MapRowMatrixRowMap () const
 See Epetra_RowMatrix documentation.
virtual const Epetra_MapRowMatrixColMap () const
 See Epetra_RowMatrix documentation.
virtual const Epetra_ImportRowMatrixImporter () const
 See Epetra_RowMatrix documentation.
virtual const Epetra_BlockMapMap () const
 See Epetra_SrcDistObj documentation.
virtual bool computeJacobian (const Epetra_Vector &x, Epetra_Operator &Jac)
 Compute Jacobian given the specified input vector, x. Returns true if computation was successful.
virtual bool computeJacobian (const Epetra_Vector &x)
 Compute Jacobian given the specified input vector, x. Returns true if computation was successful.
virtual bool computePreconditioner (const Epetra_Vector &x, Epetra_RowMatrix &M)
 Compute an Epetra_RowMatrix to be used by Aztec preconditioners given the specified input vector, x. Returns true if computation was successful.
virtual void setDifferenceMethod (DifferenceType type)
 Set the type of perturbation method used (default is Forward).
virtual Epetra_CrsMatrixgetUnderlyingMatrix () const
 An accessor method for the underlying Epetra_CrsMatrix.
virtual void Print (ostream &) const
 Output the underlying matrix.

Protected Types

enum  BetaType { Scalar, Vector }
 Define types for the $ \beta $ parameter during the computation of the perturbation parameter $ \delta$.

Protected Member Functions

Epetra_CrsMatrixcreateGraphAndJacobian (Interface &i, const Epetra_Vector &x)
 Constructs an Epetra_CrsGraph and Epetra_RowMatrix for the Jacobian. This is only called if the user does not supply an Epetra_CrsGraph.

Protected Attributes

const Epetra_BlockMapmap
 Map that contains element distribution data.
Epetra_CrsGraphgraph
 Pointer to the Jacobian graph.
Epetra_CrsMatrixjacobian
 Pointer to the Jacobian.
Interfaceinterface
 User provided interface function.
Epetra_Vector x_perturb
 Perturbed solution vector - a work array that needs to be mutable.
Epetra_Vector fo
 Function evaluation at currentX - a work array that needs to be mutable.
Epetra_Vector fp
 Function evaluation at perturbX - a work array that needs to be mutable.
Epetra_VectorfmPtr
 Optional pointer to function evaluation at -perturbX - needed only for centered finite differencing.
Epetra_Vector Jc
 Column vector of the jacobian - a work array that needs to be mutable.
double alpha
 Constant for the perturbation calculation.
double beta
 Constant for the perturbation calculation.
const Epetra_VectorbetaVector
 Vector for the perturbation calculation.
BetaType betaType
 Flag that sets whether $ \beta $ is a scalar or a vector.
DifferenceType diffType
 Define types for use of the perturbation parameter $ \delta$.
string label
 label for the Epetra_RowMatrix

Detailed Description

Concrete implementation for creating an Epetra_RowMatrix Jacobian via finite differencing of the residual.

The Jacobian entries are calculated via 1st order finite differencing. This requires $ N + 1 $ calls to computeF() where $ N $ is the number of unknowns in the problem.

\[ J_{ij} = \frac{\partial F_i}{\partial x_j} = \frac{F_i(x+\delta\mathbf{e}_j) - F_i(x)}{\delta} \]

where $J$ is the Jacobian, $F$ is the function evaluation, $x$ is the solution vector, and $\delta$ is a small perturbation to the $x_j$ entry.

The perturbation, $ \delta $, is calculated based on one of the following equations:

\[ \delta = \alpha * | x_j | + \beta \]

\[ \delta = \alpha * | x_j | + \beta_j \]

where $ \alpha $ is a scalar value (defaults to 1.0e-4) and $ \beta $ can be either a scalar or a vector (defaults to a scalar value of 1.0e-6). The choice is defined by the type of constructor used. All parameters are supplied in the constructor. In addition to the forward difference derivative approximation, backward or centered differences can be used via the setDifferenceMethod function. Note that centered difference provides second order spatial accuracy but at the cost of twice as many function evaluations.

Since this inherits from the Epetra_RowMatrix class, it can be used as the preconditioning matrix for AztecOO preconditioners. This method is very inefficient when computing the Jacobian and is not recommended for large-scale systems but only for debugging purposes.


The documentation for this class was generated from the following files:
Generated on Thu Sep 18 12:42:27 2008 for NOX by doxygen 1.3.9.1