de.jtem.jpetsc
Class SNES

java.lang.Object
  extended by de.jtem.jpetsc.PrimitivNative
      extended by de.jtem.jpetsc.Native
          extended by de.jtem.jpetsc.SNES

public class SNES
extends Native


Nested Class Summary
static interface SNES.Application
           
static interface SNES.FunctionEvaluator
           
static interface SNES.JacobianEvaluator
           
static class SNES.KSPGetParametersEWResult
          Result class for kSPGetParametersEW()
 
Field Summary
 
Fields inherited from class de.jtem.jpetsc.PrimitivNative
destroyNative
 
Constructor Summary
SNES()
           
 
Method Summary
 void appendOptionsPrefix(java.lang.String prefix)
          Appends to the prefix used for searching for all
SNES options in the database.
static SNES create()
           
static SNES create(int comm)
          Creates a nonlinear solver context.
 void defaultUpdate(int step)
          The default update function which does nothing.
 void destroy()
          Destroys the nonlinear solver context that was created
with SNESCreate().
 SNESConvergedReason getConvergedReason()
          Gets the reason the SNES iteration was stopped.
 double getFunctionNorm()
          Gets the norm of the current function that was set
with SNESSSetFunction().
 int getIterationNumber()
          Gets the number of nonlinear iterations completed
at this time.
 KSP getKSP()
          Returns the KSP context for a SNES solver.
 int getLinearSolveFailures()
          Gets the number of failed (non-converged)
linear solvers.
 int getLinearSolveIterations()
          Gets the total number of linear iterations
used by the nonlinear solver.
 int getMaxLinearSolveFailures()
          gets the maximum number of linear solve failures that
are allowed before SNES terminates
Not Collective
 int getMaxNonlinearStepFailures()
          Gets the maximum number of unsuccessful steps
attempted by the nonlinear solver before it gives up.
 int getNonlinearStepFailures()
          Gets the number of unsuccessful steps
attempted by the nonlinear solver.
 Vec getRhs()
          Gets the vector for solving F(x) = rhs.
 Vec getSolution()
          Returns the vector where the approximate solution is
stored.
 Vec getSolutionUpdate()
          Returns the vector where the solution update is
stored.
 void getTolerances(double[] abstol, double[] rtol, double[] stol, int[] maxit, int[] maxf)
          Gets various parameters used in convergence tests.
 java.lang.String getType()
          Gets the SNES method type and name (as a string).
 SNES.KSPGetParametersEWResult kSPGetParametersEW()
          Gets parameters for Eisenstat-Walker
convergence criteria for the linear solvers within an inexact
Newton method.
 boolean kSPGetUseEW()
          Gets if SNES is using Eisenstat-Walker method
for computing relative tolerance for linear solvers within an
inexact Newton method.
 void kSPSetParametersEW(int version, double rtol_0, double rtol_max, double gamma, double alpha, double alpha2, double threshold)
          Sets parameters for Eisenstat-Walker
convergence criteria for the linear solvers within an inexact
Newton method.
 void kSPSetUseEW(boolean flag)
          Sets SNES use Eisenstat-Walker method for
computing relative tolerance for linear solvers within an inexact
Newton method.
 void monitorCancel()
          Clears all the monitor functions for a SNES object.
protected  void nativeCreate()
           
static void registerDestroy()
          Frees the list of nonlinear solvers that were
registered by SNESRegisterDynamic().
 void setConvergenceHistory(double[] a, int[] its, int na, boolean reset)
          Sets the array used to hold the convergence history.
 void setFromOptions()
          Sets various SNES and KSP parameters from user options.
 void setFunction(SNES.FunctionEvaluator app, Vec f)
           
 void setJacobian(SNES.JacobianEvaluator app, Mat m, Mat pre)
           
 void setMaxLinearSolveFailures(int maxFails)
          the number of failed linear solve attempts
allowed before SNES returns with a diverged reason of SNES_DIVERGED_LINEAR_SOLVE
 void setMaxNonlinearStepFailures(int maxFails)
          Sets the maximum number of unsuccessful steps
attempted by the nonlinear solver before it gives up.
 void setOptionsPrefix(java.lang.String prefix)
          Sets the prefix used for searching for all
SNES options in the database.
 void setRhs(Vec rhs)
          Sets the vector for solving F(x) = rhs.
 void setSolution(Vec x)
          Sets the vector where the approximate solution is stored.
 void setTolerances(double abstol, double rtol, double stol, int maxit, int maxf)
          Sets various parameters used in convergence tests.
 void setTrustRegionTolerance(double tol)
          Sets the trust region parameter tolerance.
 void setType(java.lang.String type)
          Sets the method for the nonlinear solver.
 void setUp()
          Sets up the internal data structures for the later use
of a nonlinear solver.
 void solve(Vec b, Vec x)
          Solves a nonlinear system F(x) = b.
static boolean testJacobian(SNES.FunctionEvaluator funcApp, Mat m, Vec x, Vec f)
           
 void view()
          Prints the SNES data structure.
 
Methods inherited from class de.jtem.jpetsc.PrimitivNative
finalize, getNativeObjectToString, load, toString
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

SNES

public SNES()
Method Detail

nativeCreate

protected void nativeCreate()
Specified by:
nativeCreate in class Native

setFunction

public void setFunction(SNES.FunctionEvaluator app,
                        Vec f)

setJacobian

public void setJacobian(SNES.JacobianEvaluator app,
                        Mat m,
                        Mat pre)

testJacobian

public static boolean testJacobian(SNES.FunctionEvaluator funcApp,
                                   Mat m,
                                   Vec x,
                                   Vec f)

create

public static SNES create()

view

public void view()
Prints the SNES data structure.

See Also:
#PetscViewerASCIIOpen

setFromOptions

public void setFromOptions()
Sets various SNES and KSP parameters from user options.

See Also:
setOptionsPrefix(java.lang.String)

getIterationNumber

public int getIterationNumber()
Gets the number of nonlinear iterations completed
at this time.
Not Collective

Returns:
iteration number
See Also:
getFunctionNorm(), getLinearSolveIterations()

getFunctionNorm

public double getFunctionNorm()
Gets the norm of the current function that was set
with SNESSSetFunction().

Returns:
2-norm of function
See Also:
#getFunction, getIterationNumber(), getLinearSolveIterations()

getNonlinearStepFailures

public int getNonlinearStepFailures()
Gets the number of unsuccessful steps
attempted by the nonlinear solver.
Not Collective

Returns:
number of unsuccessful steps attempted

setMaxNonlinearStepFailures

public void setMaxNonlinearStepFailures(int maxFails)
Sets the maximum number of unsuccessful steps
attempted by the nonlinear solver before it gives up.
Not Collective

Parameters:
maxFails - maximum of unsuccessful steps

getMaxNonlinearStepFailures

public int getMaxNonlinearStepFailures()
Gets the maximum number of unsuccessful steps
attempted by the nonlinear solver before it gives up.
Not Collective

Returns:
maximum of unsuccessful steps

getLinearSolveFailures

public int getLinearSolveFailures()
Gets the number of failed (non-converged)
linear solvers.
Not Collective

Returns:
number of failed solves

setMaxLinearSolveFailures

public void setMaxLinearSolveFailures(int maxFails)
the number of failed linear solve attempts
allowed before SNES returns with a diverged reason of SNES_DIVERGED_LINEAR_SOLVE

Parameters:
maxFails - maximum allowed linear solve failures
See Also:
getLinearSolveFailures(), getMaxLinearSolveFailures()

getMaxLinearSolveFailures

public int getMaxLinearSolveFailures()
gets the maximum number of linear solve failures that
are allowed before SNES terminates
Not Collective

Returns:
maximum of unsuccessful solves allowed
See Also:
getLinearSolveFailures(), getMaxLinearSolveFailures()

getLinearSolveIterations

public int getLinearSolveIterations()
Gets the total number of linear iterations
used by the nonlinear solver.
Not Collective

Returns:
number of linear iterations
See Also:
getIterationNumber(), getFunctionNorm()

getKSP

public KSP getKSP()
Returns the KSP context for a SNES solver.
Not Collective, but if SNES object is parallel, then KSP object is parallel

Returns:
the KSP context
See Also:
#KSPGetPC, create(), #KSPCreate, #setKSP

create

public static SNES create(int comm)
Creates a nonlinear solver context.

Parameters:
comm - MPI communicator
Returns:
the new SNES context
See Also:
solve(de.jtem.jpetsc.Vec, de.jtem.jpetsc.Vec), destroy(), SNES()

setRhs

public void setRhs(Vec rhs)
Sets the vector for solving F(x) = rhs. If rhs is not set
it assumes a zero right hand side.

Parameters:
rhs - the right hand side vector or PETSC_NULL for a zero right hand side
See Also:
getRhs(), #getFunction, #computeFunction, setJacobian(de.jtem.jpetsc.SNES.JacobianEvaluator, de.jtem.jpetsc.Mat, de.jtem.jpetsc.Mat), setFunction(de.jtem.jpetsc.SNES.FunctionEvaluator, de.jtem.jpetsc.Vec)

getRhs

public Vec getRhs()
Gets the vector for solving F(x) = rhs. If rhs is not set
it assumes a zero right hand side.

Returns:
the right hand side vector or PETSC_NULL for a zero right hand side
See Also:
setRhs(de.jtem.jpetsc.Vec), #getFunction, #computeFunction, setJacobian(de.jtem.jpetsc.SNES.JacobianEvaluator, de.jtem.jpetsc.Mat, de.jtem.jpetsc.Mat), setFunction(de.jtem.jpetsc.SNES.FunctionEvaluator, de.jtem.jpetsc.Vec)

setUp

public void setUp()
Sets up the internal data structures for the later use
of a nonlinear solver.

See Also:
create(), solve(de.jtem.jpetsc.Vec, de.jtem.jpetsc.Vec), destroy()

destroy

public void destroy()
Destroys the nonlinear solver context that was created
with SNESCreate().

See Also:
create(), solve(de.jtem.jpetsc.Vec, de.jtem.jpetsc.Vec)

setTolerances

public void setTolerances(double abstol,
                          double rtol,
                          double stol,
                          int maxit,
                          int maxf)
Sets various parameters used in convergence tests.

Parameters:
abstol - absolute convergence tolerance
rtol - relative convergence tolerance
stol - convergence tolerance in terms of the norm
of the change in the solution between steps
maxit - maximum number of iterations
maxf - maximum number of function evaluations
See Also:
setTrustRegionTolerance(double)

getTolerances

public void getTolerances(double[] abstol,
                          double[] rtol,
                          double[] stol,
                          int[] maxit,
                          int[] maxf)
Gets various parameters used in convergence tests.
Not Collective

Parameters:
abstol - absolute convergence tolerance
rtol - relative convergence tolerance
stol - convergence tolerance in terms of the norm
of the change in the solution between steps
maxit - maximum number of iterations
maxf - maximum number of function evaluations
See Also:
setTolerances(double, double, double, int, int)

setTrustRegionTolerance

public void setTrustRegionTolerance(double tol)
Sets the trust region parameter tolerance.

Parameters:
tol - tolerance
See Also:
setTolerances(double, double, double, int, int)

monitorCancel

public void monitorCancel()
Clears all the monitor functions for a SNES object.

See Also:
#monitorDefault, #monitorSet

getConvergedReason

public SNESConvergedReason getConvergedReason()
Gets the reason the SNES iteration was stopped.
Not Collective

Returns:
negative value indicates diverged, positive value converged, see petscsnes.h or the manual pages for the individual convergence tests for complete lists
See Also:
#setConvergenceTest, #convergedLS, #convergedTR, #convergedReason

setConvergenceHistory

public void setConvergenceHistory(double[] a,
                                  int[] its,
                                  int na,
                                  boolean reset)
Sets the array used to hold the convergence history.

Parameters:
a - array to hold history
its - integer array holds the number of linear iterations for each solve.
na - size of a and its
reset - PETSC_TRUE indicates each new nonlinear solve resets the history counter to zero,
else it continues storing new values for new nonlinear solves after the old ones
See Also:
#getConvergenceHistory

defaultUpdate

public void defaultUpdate(int step)
The default update function which does nothing.
Not collective

Parameters:
step - The current step of the iteration
See Also:
#setUpdate, #defaultRhsBC, #defaultShortolutionBC

solve

public void solve(Vec b,
                  Vec x)
Solves a nonlinear system F(x) = b.
Call SNESSolve() after calling SNESCreate() and optional routines of the form SNESSetXXX().

Parameters:
b - the constant part of the equation, or PETSC_NULL to use zero.
x - the solution vector, or PETSC_NULL if it was set with SNESSetSolution()
See Also:
create(), destroy(), setFunction(de.jtem.jpetsc.SNES.FunctionEvaluator, de.jtem.jpetsc.Vec), setJacobian(de.jtem.jpetsc.SNES.JacobianEvaluator, de.jtem.jpetsc.Mat, de.jtem.jpetsc.Mat), setRhs(de.jtem.jpetsc.Vec), setSolution(de.jtem.jpetsc.Vec)

setType

public void setType(java.lang.String type)
Sets the method for the nonlinear solver.

Parameters:
type - a known method
See Also:
#type, create()

registerDestroy

public static void registerDestroy()
Frees the list of nonlinear solvers that were
registered by SNESRegisterDynamic().
Not Collective

See Also:
#registerAll, #registerAll

getType

public java.lang.String getType()
Gets the SNES method type and name (as a string).
Not Collective

Returns:
SNES method (a character string)

getSolution

public Vec getSolution()
Returns the vector where the approximate solution is
stored.
Not Collective, but Vec is parallel if SNES is parallel

Returns:
the solution
See Also:
setSolution(de.jtem.jpetsc.Vec), #getFunction, getSolutionUpdate()

setSolution

public void setSolution(Vec x)
Sets the vector where the approximate solution is stored.
Not Collective, but Vec is parallel if SNES is parallel

Parameters:
x - the solution
See Also:
getSolution(), #getFunction, getSolutionUpdate()

getSolutionUpdate

public Vec getSolutionUpdate()
Returns the vector where the solution update is
stored.
Not Collective, but Vec is parallel if SNES is parallel

Returns:
the solution update
See Also:
getSolution(), #getFunction

setOptionsPrefix

public void setOptionsPrefix(java.lang.String prefix)
Sets the prefix used for searching for all
SNES options in the database.

Parameters:
prefix - the prefix to prepend to all option names
See Also:
setFromOptions()

appendOptionsPrefix

public void appendOptionsPrefix(java.lang.String prefix)
Appends to the prefix used for searching for all
SNES options in the database.

Parameters:
prefix - the prefix to prepend to all option names
See Also:
#getOptionsPrefix

kSPSetUseEW

public void kSPSetUseEW(boolean flag)
Sets SNES use Eisenstat-Walker method for
computing relative tolerance for linear solvers within an inexact
Newton method.

Parameters:
flag - PETSC_TRUE or PETSC_FALSE
See Also:
kSPGetUseEW(), kSPGetParametersEW(), kSPSetParametersEW(int, double, double, double, double, double, double)

kSPGetUseEW

public boolean kSPGetUseEW()
Gets if SNES is using Eisenstat-Walker method
for computing relative tolerance for linear solvers within an
inexact Newton method.
Not Collective

Returns:
PETSC_TRUE or PETSC_FALSE
See Also:
kSPSetUseEW(boolean), kSPGetParametersEW(), kSPSetParametersEW(int, double, double, double, double, double, double)

kSPSetParametersEW

public void kSPSetParametersEW(int version,
                               double rtol_0,
                               double rtol_max,
                               double gamma,
                               double alpha,
                               double alpha2,
                               double threshold)
Sets parameters for Eisenstat-Walker
convergence criteria for the linear solvers within an inexact
Newton method.

Parameters:
version - version 1, 2 (default is 2) or 3
rtol_0 - initial relative tolerance (0 <= rtol_0 < 1)
rtol_max - maximum relative tolerance (0 <= rtol_max < 1)
gamma - multiplicative factor for version 2 rtol computation
(0 <= gamma2 <= 1)
alpha - power for version 2 rtol computation (1 < alpha <= 2)
alpha2 - power for safeguard
threshold - threshold for imposing safeguard (0 < threshold < 1)
See Also:
kSPSetUseEW(boolean), kSPGetUseEW(), kSPGetParametersEW()

kSPGetParametersEW

public SNES.KSPGetParametersEWResult kSPGetParametersEW()
Gets parameters for Eisenstat-Walker
convergence criteria for the linear solvers within an inexact
Newton method.
Not Collective

Returns:
SNES.KSPGetParametersEWResult
See Also:
kSPSetUseEW(boolean), kSPGetUseEW(), kSPSetParametersEW(int, double, double, double, double, double, double)