PyTrilinos::NOX::Epetra::FiniteDifferenceColoring Class Reference

Inheritance diagram for PyTrilinos::NOX::Epetra::FiniteDifferenceColoring:

Inheritance graph
[legend]
Collaboration diagram for PyTrilinos::NOX::Epetra::FiniteDifferenceColoring:

Collaboration graph
[legend]

List of all members.

Public Member Functions

def computeJacobian
def createColorContainers
def __init__
def computeJacobian
def createColorContainers
def __init__

Public Attributes

 this


Detailed Description

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

The Jacobian entries are calculated via 1st or 2nd order finite
differencing. This requires $ N + 1 $ or $ 2N + 1 $ calls to
computeF(), respectively, where $ N $ is the number of colors.

\\[ 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.

Instead of perturbing each $ N_{dof} $ problem degrees of freedom
sequentially and then evaluating all $ N_{dof} $ functions for each
perturbation, coloring allows several degrees of freedom (all
belonging to the same color) to be perturbed at the same time. This
reduces the total number of function evaluations needed to compute
$\\mathbf{J}$ from $ N_{dof}^2 $ as is required using
FiniteDifference to $ N\\cdot N_{dof} $, often representing
substantial computational savings.

Coloring is based on a user-supplied color map generated using an
appropriate algorithm, eg greedy-algorithm - Y. Saad, "Iterative
Methods for Sparse Linear Systems, 2nd ed.," chp. 3, SIAM, 2003.. Use
can be made of the coloring algorithm provided by the EpetraExt
package in Trilinos. The 1Dfem_nonlinearColoring and Brusselator
example problems located in the nox/epetra-examples subdirectory
demonstrate use of the EpetraExt package, and the
1Dfem_nonlinearColoring directory also contains a stand-alone coloring
algorithm very similar to that in EpetraExt.

The perturbation, $ \\delta $, is calculated using the following
equation:

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

where $ \\alpha $ is a scalar value (defaults to 1.0e-4) and $
\\beta $ is another scalar (defaults to 1.0e-6).

Since both FiniteDifferenceColoring and FiniteDifference inherit from
the Epetra_RowMatrix class, they can be used as preconditioning
matrices for AztecOO preconditioners.

As for FiniteDifference, 1st order accurate Forward and Backward
differences as well as 2nd order accurate Centered difference can be
specified using setDifferenceMethod with the appropriate enumerated
type passed as the argument.

Using FiniteDifferenceColoring in Parallel

Two ways of using this class in a distributed parallel environment are
currently supported. From an application standpoint, the two
approaches differ only in the status of the solution iterate used in
the residual fill. If an object of this class is contructed with
parallelColoring = true the solution iterate will be passe back in a
non-ghosted form. On the contrary, setting this parameter to false in
the constructor will cause the solution iterate to be in a ghosted
form when calling back for a residual fill. When using the second
approach, the user should be aware that the perturbed vector used to
compute residuals has already been scattered to a form consistent with
the column space of the Epetra_CrsGraph. In practice, this means that
the perturbed vector used by computeF() has already been scattered to
a ghosted or overlapped state. The application should then not perform
this step but rather simply use the vector provided with the possible
exception of requiring a local index reordering to bring the column-
space based vector in sync with a potentially different ghosted index
ordering. See the Brusselator and 1Dfem_nonlinearColoring example
problems for details.

Special Case for Approximate Jacobian Construction

Provision is made for a simplified and cheaper use of coloring that
currently provides only for the diagonal of the Jacobian to be
computed. This is based on using a first-neighbors coloring of the
original Jacobian graph using the Epetra_Ext MapColoring class with
the distance1 argument set to true. This same argument should also be
set to true in the constructor to this class. The result will be a
diagonal Jacobian filled in a much more efficient manner.

C++ includes: NOX_Epetra_FiniteDifferenceColoring.H 

Member Function Documentation

def PyTrilinos::NOX::Epetra::FiniteDifferenceColoring::__init__ (   self,
  args 
)

__init__(self, ParameterList printingParams, Required i, Vector initialGuess, 
    Epetra_CrsGraph rawGraph, bool parallelColoring = False, 
    bool distance1 = False, 
    double beta = 1.0e-6, double alpha = 1.0e-4) -> FiniteDifferenceColoring

FiniteDifferenceColoring::FiniteDifferenceColoring(Teuchos::ParameterList
&printingParams, const Teuchos::RCP< Interface::Required > &i, const
NOX::Epetra::Vector &initialGuess, const Teuchos::RCP< Epetra_CrsGraph
> &rawGraph, const Teuchos::RCP< Epetra_MapColoring > &colorMap, const
Teuchos::RCP< vector< Epetra_IntVector > > &columns, bool
parallelColoring=false, bool distance1=false, double beta=1.0e-6,
double alpha=1.0e-4)

Constructor with output control. 

Reimplemented from PyTrilinos::NOX::Epetra::FiniteDifference.

def PyTrilinos::NOX::Epetra::FiniteDifferenceColoring::__init__ (   self,
  args 
)

__init__(self, ParameterList printingParams, Required i, Vector initialGuess, 
    Epetra_CrsGraph rawGraph, bool parallelColoring = False, 
    bool distance1 = False, 
    double beta = 1.0e-6, double alpha = 1.0e-4) -> FiniteDifferenceColoring

FiniteDifferenceColoring::FiniteDifferenceColoring(Teuchos::ParameterList
&printingParams, const Teuchos::RCP< Interface::Required > &i, const
NOX::Epetra::Vector &initialGuess, const Teuchos::RCP< Epetra_CrsGraph
> &rawGraph, const Teuchos::RCP< Epetra_MapColoring > &colorMap, const
Teuchos::RCP< vector< Epetra_IntVector > > &columns, bool
parallelColoring=false, bool distance1=false, double beta=1.0e-6,
double alpha=1.0e-4)

Constructor with output control. 

Reimplemented from PyTrilinos::NOX::Epetra::FiniteDifference.

def PyTrilinos::NOX::Epetra::FiniteDifferenceColoring::computeJacobian (   self,
  args 
)

computeJacobian(self, Epetra_Vector x, Epetra_Operator Jac) -> bool
computeJacobian(self, Epetra_Vector x) -> bool

bool
FiniteDifferenceColoring::computeJacobian(const Epetra_Vector &x)

Compute Jacobian given the specified input vector, x. Returns true if
computation was successful. 

Reimplemented from PyTrilinos::NOX::Epetra::FiniteDifference.

def PyTrilinos::NOX::Epetra::FiniteDifferenceColoring::computeJacobian (   self,
  args 
)

computeJacobian(self, Epetra_Vector x, Epetra_Operator Jac) -> bool
computeJacobian(self, Epetra_Vector x) -> bool

bool
FiniteDifferenceColoring::computeJacobian(const Epetra_Vector &x)

Compute Jacobian given the specified input vector, x. Returns true if
computation was successful. 

Reimplemented from PyTrilinos::NOX::Epetra::FiniteDifference.

def PyTrilinos::NOX::Epetra::FiniteDifferenceColoring::createColorContainers (   self,
  args 
)

createColorContainers(self)

void
FiniteDifferenceColoring::createColorContainers()

Create containers for using color and index maps in parallel coloring.

def PyTrilinos::NOX::Epetra::FiniteDifferenceColoring::createColorContainers (   self,
  args 
)

createColorContainers(self)

void
FiniteDifferenceColoring::createColorContainers()

Create containers for using color and index maps in parallel coloring.


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

Generated on Thu Dec 17 11:00:22 2009 for PyTrilinos by  doxygen 1.5.9