xref: /petsc/include/petscsnes.h (revision c2fc9fa91a764ea1bc445c5db6fc55248852cdef)
1f26ada1bSBarry Smith /*
2eef9c623SLois Curfman McInnes     User interface for the nonlinear solvers package.
3f26ada1bSBarry Smith */
40a835dfdSSatish Balay #if !defined(__PETSCSNES_H)
50a835dfdSSatish Balay #define __PETSCSNES_H
694b7f48cSBarry Smith #include "petscksp.h"
7e9fa29b7SSatish Balay PETSC_EXTERN_CXX_BEGIN
8b1f5cb9dSBarry Smith 
9435da068SBarry Smith /*S
10435da068SBarry Smith      SNES - Abstract PETSc object that manages all nonlinear solves
11435da068SBarry Smith 
12435da068SBarry Smith    Level: beginner
13435da068SBarry Smith 
14435da068SBarry Smith   Concepts: nonlinear solvers
15435da068SBarry Smith 
1694b7f48cSBarry Smith .seealso:  SNESCreate(), SNESSetType(), SNESType, TS, KSP, KSP, PC
17435da068SBarry Smith S*/
18f09e8eb9SSatish Balay typedef struct _p_SNES* SNES;
19435da068SBarry Smith 
2076bdecfbSBarry Smith /*J
21435da068SBarry Smith     SNESType - String with the name of a PETSc SNES method or the creation function
22435da068SBarry Smith        with an optional dynamic library name, for example
23435da068SBarry Smith        http://www.mcs.anl.gov/petsc/lib.a:mysnescreate()
24435da068SBarry Smith 
25435da068SBarry Smith    Level: beginner
26435da068SBarry Smith 
27435da068SBarry Smith .seealso: SNESSetType(), SNES
2876bdecfbSBarry Smith J*/
29a313700dSBarry Smith #define SNESType char*
30eef9c623SLois Curfman McInnes #define SNESLS           "ls"
31eef9c623SLois Curfman McInnes #define SNESTR           "tr"
321d6018f0SLisandro Dalcin #define SNESPYTHON       "python"
33eef9c623SLois Curfman McInnes #define SNESTEST         "test"
34d5c3842bSBarry Smith #define SNESNRICHARDSON  "nrichardson"
35b79b07cfSJed Brown #define SNESKSPONLY      "ksponly"
36*c2fc9fa9SBarry Smith #define SNESVIRS         "virs"
37*c2fc9fa9SBarry Smith #define SNESVISS         "viss"
384a0c5b0cSMatthew G Knepley #define SNESNGMRES       "ngmres"
394b11644fSPeter Brune #define SNESQN           "qn"
40c5ae4b9aSBarry Smith #define SNESSHELL        "shell"
41fef7b6d8SPeter Brune #define SNESNCG          "ncg"
42d5c3842bSBarry Smith #define SNESSORQN        "sorqn"
43421d9b32SPeter Brune #define SNESFAS          "fas"
44d5c3842bSBarry Smith 
45deeb6e72SMatthew Knepley /* Logging support */
467087cfbeSBarry Smith extern PetscClassId  SNES_CLASSID;
47deeb6e72SMatthew Knepley 
487087cfbeSBarry Smith extern PetscErrorCode  SNESInitializePackage(const char[]);
49deeb6e72SMatthew Knepley 
507087cfbeSBarry Smith extern PetscErrorCode  SNESCreate(MPI_Comm,SNES*);
5137596af1SLisandro Dalcin extern PetscErrorCode  SNESReset(SNES);
52fcfd50ebSBarry Smith extern PetscErrorCode  SNESDestroy(SNES*);
537087cfbeSBarry Smith extern PetscErrorCode  SNESSetType(SNES,const SNESType);
54228d79bcSJed Brown extern PetscErrorCode  SNESMonitor(SNES,PetscInt,PetscReal);
55c2efdce3SBarry Smith extern PetscErrorCode  SNESMonitorSet(SNES,PetscErrorCode(*)(SNES,PetscInt,PetscReal,void*),void *,PetscErrorCode (*)(void**));
567087cfbeSBarry Smith extern PetscErrorCode  SNESMonitorCancel(SNES);
577087cfbeSBarry Smith extern PetscErrorCode  SNESSetConvergenceHistory(SNES,PetscReal[],PetscInt[],PetscInt,PetscBool );
587087cfbeSBarry Smith extern PetscErrorCode  SNESGetConvergenceHistory(SNES,PetscReal*[],PetscInt *[],PetscInt *);
597087cfbeSBarry Smith extern PetscErrorCode  SNESSetUp(SNES);
607087cfbeSBarry Smith extern PetscErrorCode  SNESSolve(SNES,Vec,Vec);
617087cfbeSBarry Smith extern PetscErrorCode  SNESSetErrorIfNotConverged(SNES,PetscBool );
627087cfbeSBarry Smith extern PetscErrorCode  SNESGetErrorIfNotConverged(SNES,PetscBool  *);
63e113a28aSBarry Smith 
6484cb2905SBarry Smith 
657087cfbeSBarry Smith extern PetscErrorCode  SNESAddOptionsChecker(PetscErrorCode (*)(SNES));
664d8f6ca9SMatthew Knepley 
677087cfbeSBarry Smith extern PetscErrorCode  SNESSetUpdate(SNES, PetscErrorCode (*)(SNES, PetscInt));
687087cfbeSBarry Smith extern PetscErrorCode  SNESDefaultUpdate(SNES, PetscInt);
694d8f6ca9SMatthew Knepley 
70b0a32e0cSBarry Smith extern PetscFList SNESList;
717087cfbeSBarry Smith extern PetscErrorCode  SNESRegisterDestroy(void);
727087cfbeSBarry Smith extern PetscErrorCode  SNESRegisterAll(const char[]);
7384cb2905SBarry Smith 
747087cfbeSBarry Smith extern PetscErrorCode  SNESRegister(const char[],const char[],const char[],PetscErrorCode (*)(SNES));
7530de9b25SBarry Smith 
7630de9b25SBarry Smith /*MC
7730de9b25SBarry Smith    SNESRegisterDynamic - Adds a method to the nonlinear solver package.
7830de9b25SBarry Smith 
7930de9b25SBarry Smith    Synopsis:
801890ba74SBarry Smith    PetscErrorCode SNESRegisterDynamic(const char *name_solver,const char *path,const char *name_create,PetscErrorCode (*routine_create)(SNES))
8130de9b25SBarry Smith 
8230de9b25SBarry Smith    Not collective
8330de9b25SBarry Smith 
8430de9b25SBarry Smith    Input Parameters:
8530de9b25SBarry Smith +  name_solver - name of a new user-defined solver
8630de9b25SBarry Smith .  path - path (either absolute or relative) the library containing this solver
8730de9b25SBarry Smith .  name_create - name of routine to create method context
8830de9b25SBarry Smith -  routine_create - routine to create method context
8930de9b25SBarry Smith 
9030de9b25SBarry Smith    Notes:
9130de9b25SBarry Smith    SNESRegisterDynamic() may be called multiple times to add several user-defined solvers.
9230de9b25SBarry Smith 
9330de9b25SBarry Smith    If dynamic libraries are used, then the fourth input argument (routine_create)
9430de9b25SBarry Smith    is ignored.
9530de9b25SBarry Smith 
96ab901514SBarry Smith    Environmental variables such as ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR},
9730de9b25SBarry Smith    and others of the form ${any_environmental_variable} occuring in pathname will be
9830de9b25SBarry Smith    replaced with appropriate values.
9930de9b25SBarry Smith 
10030de9b25SBarry Smith    Sample usage:
10130de9b25SBarry Smith .vb
10230de9b25SBarry Smith    SNESRegisterDynamic("my_solver",/home/username/my_lib/lib/libg/solaris/mylib.a,
10330de9b25SBarry Smith                 "MySolverCreate",MySolverCreate);
10430de9b25SBarry Smith .ve
10530de9b25SBarry Smith 
10630de9b25SBarry Smith    Then, your solver can be chosen with the procedural interface via
10730de9b25SBarry Smith $     SNESSetType(snes,"my_solver")
10830de9b25SBarry Smith    or at runtime via the option
10930de9b25SBarry Smith $     -snes_type my_solver
11030de9b25SBarry Smith 
11130de9b25SBarry Smith    Level: advanced
11230de9b25SBarry Smith 
11330de9b25SBarry Smith     Note: If your function is not being put into a shared library then use SNESRegister() instead
11430de9b25SBarry Smith 
11530de9b25SBarry Smith .keywords: SNES, nonlinear, register
11630de9b25SBarry Smith 
11730de9b25SBarry Smith .seealso: SNESRegisterAll(), SNESRegisterDestroy()
11830de9b25SBarry Smith M*/
119aa482453SBarry Smith #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
120f1af5d2fSBarry Smith #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,0)
121b2002411SLois Curfman McInnes #else
122f1af5d2fSBarry Smith #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,d)
123b2002411SLois Curfman McInnes #endif
124b2002411SLois Curfman McInnes 
1257087cfbeSBarry Smith extern PetscErrorCode  SNESGetKSP(SNES,KSP*);
1267087cfbeSBarry Smith extern PetscErrorCode  SNESSetKSP(SNES,KSP);
1277087cfbeSBarry Smith extern PetscErrorCode  SNESGetSolution(SNES,Vec*);
1287087cfbeSBarry Smith extern PetscErrorCode  SNESGetSolutionUpdate(SNES,Vec*);
1292d4b5aceSLisandro Dalcin extern PetscErrorCode  SNESGetRhs(SNES,Vec*);
1307087cfbeSBarry Smith extern PetscErrorCode  SNESView(SNES,PetscViewer);
1317bc3d0afSSatish Balay 
1327087cfbeSBarry Smith extern PetscErrorCode  SNESSetOptionsPrefix(SNES,const char[]);
1337087cfbeSBarry Smith extern PetscErrorCode  SNESAppendOptionsPrefix(SNES,const char[]);
1347087cfbeSBarry Smith extern PetscErrorCode  SNESGetOptionsPrefix(SNES,const char*[]);
1357087cfbeSBarry Smith extern PetscErrorCode  SNESSetFromOptions(SNES);
136c699ede6SMatthew G Knepley extern PetscErrorCode  SNESDefaultGetWork(SNES,PetscInt);
13740191667SLois Curfman McInnes 
1387087cfbeSBarry Smith extern PetscErrorCode  MatCreateSNESMF(SNES,Mat*);
1397087cfbeSBarry Smith extern PetscErrorCode  MatMFFDComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
1408f6e3e37SBarry Smith 
1417087cfbeSBarry Smith extern PetscErrorCode  MatDAADSetSNES(Mat,SNES);
1423a7fca6bSBarry Smith 
1437087cfbeSBarry Smith extern PetscErrorCode  SNESGetType(SNES,const SNESType*);
1447087cfbeSBarry Smith extern PetscErrorCode  SNESMonitorDefault(SNES,PetscInt,PetscReal,void *);
1457087cfbeSBarry Smith extern PetscErrorCode  SNESMonitorRange(SNES,PetscInt,PetscReal,void *);
1467087cfbeSBarry Smith extern PetscErrorCode  SNESMonitorRatio(SNES,PetscInt,PetscReal,void *);
147649052a6SBarry Smith extern PetscErrorCode  SNESMonitorSetRatio(SNES,PetscViewer);
1487087cfbeSBarry Smith extern PetscErrorCode  SNESMonitorSolution(SNES,PetscInt,PetscReal,void *);
1497087cfbeSBarry Smith extern PetscErrorCode  SNESMonitorResidual(SNES,PetscInt,PetscReal,void *);
1507087cfbeSBarry Smith extern PetscErrorCode  SNESMonitorSolutionUpdate(SNES,PetscInt,PetscReal,void *);
1517087cfbeSBarry Smith extern PetscErrorCode  SNESMonitorDefaultShort(SNES,PetscInt,PetscReal,void *);
1527087cfbeSBarry Smith extern PetscErrorCode  SNESSetTolerances(SNES,PetscReal,PetscReal,PetscReal,PetscInt,PetscInt);
1537087cfbeSBarry Smith extern PetscErrorCode  SNESGetTolerances(SNES,PetscReal*,PetscReal*,PetscReal*,PetscInt*,PetscInt*);
1547087cfbeSBarry Smith extern PetscErrorCode  SNESSetTrustRegionTolerance(SNES,PetscReal);
1557087cfbeSBarry Smith extern PetscErrorCode  SNESGetFunctionNorm(SNES,PetscReal*);
1567087cfbeSBarry Smith extern PetscErrorCode  SNESGetIterationNumber(SNES,PetscInt*);
1573d4c4710SBarry Smith 
1587087cfbeSBarry Smith extern PetscErrorCode  SNESGetNonlinearStepFailures(SNES,PetscInt*);
1597087cfbeSBarry Smith extern PetscErrorCode  SNESSetMaxNonlinearStepFailures(SNES,PetscInt);
1607087cfbeSBarry Smith extern PetscErrorCode  SNESGetMaxNonlinearStepFailures(SNES,PetscInt*);
1617087cfbeSBarry Smith extern PetscErrorCode  SNESGetNumberFunctionEvals(SNES,PetscInt*);
162b850b91aSLisandro Dalcin 
1637087cfbeSBarry Smith extern PetscErrorCode  SNESSetLagPreconditioner(SNES,PetscInt);
1647087cfbeSBarry Smith extern PetscErrorCode  SNESGetLagPreconditioner(SNES,PetscInt*);
1657087cfbeSBarry Smith extern PetscErrorCode  SNESSetLagJacobian(SNES,PetscInt);
1667087cfbeSBarry Smith extern PetscErrorCode  SNESGetLagJacobian(SNES,PetscInt*);
167efd51863SBarry Smith extern PetscErrorCode  SNESSetGridSequence(SNES,PetscInt);
168a8054027SBarry Smith 
1697087cfbeSBarry Smith extern PetscErrorCode  SNESGetLinearSolveIterations(SNES,PetscInt*);
1707087cfbeSBarry Smith extern PetscErrorCode  SNESGetLinearSolveFailures(SNES,PetscInt*);
1717087cfbeSBarry Smith extern PetscErrorCode  SNESSetMaxLinearSolveFailures(SNES,PetscInt);
1727087cfbeSBarry Smith extern PetscErrorCode  SNESGetMaxLinearSolveFailures(SNES,PetscInt*);
1733d4c4710SBarry Smith 
1747087cfbeSBarry Smith extern PetscErrorCode  SNESKSPSetUseEW(SNES,PetscBool );
1757087cfbeSBarry Smith extern PetscErrorCode  SNESKSPGetUseEW(SNES,PetscBool *);
1767087cfbeSBarry Smith extern PetscErrorCode  SNESKSPSetParametersEW(SNES,PetscInt,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal);
1777087cfbeSBarry Smith extern PetscErrorCode  SNESKSPGetParametersEW(SNES,PetscInt*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*);
178eafb4bcbSBarry Smith 
1797087cfbeSBarry Smith extern PetscErrorCode  SNESMonitorLGCreate(const char[],const char[],int,int,int,int,PetscDrawLG*);
1807087cfbeSBarry Smith extern PetscErrorCode  SNESMonitorLG(SNES,PetscInt,PetscReal,void*);
181fcfd50ebSBarry Smith extern PetscErrorCode  SNESMonitorLGDestroy(PetscDrawLG*);
1827087cfbeSBarry Smith extern PetscErrorCode  SNESMonitorLGRangeCreate(const char[],const char[],int,int,int,int,PetscDrawLG*);
1837087cfbeSBarry Smith extern PetscErrorCode  SNESMonitorLGRange(SNES,PetscInt,PetscReal,void*);
184fcfd50ebSBarry Smith extern PetscErrorCode  SNESMonitorLGRangeDestroy(PetscDrawLG*);
185eafb4bcbSBarry Smith 
1867087cfbeSBarry Smith extern PetscErrorCode  SNESSetApplicationContext(SNES,void *);
187e71120c6SJed Brown extern PetscErrorCode  SNESGetApplicationContext(SNES,void *);
188d25893d9SBarry Smith extern PetscErrorCode  SNESSetComputeApplicationContext(SNES,PetscErrorCode (*)(SNES,void**),PetscErrorCode (*)(void**));
189184914b5SBarry Smith 
1907087cfbeSBarry Smith extern PetscErrorCode  SNESPythonSetType(SNES,const char[]);
1911d6018f0SLisandro Dalcin 
1927087cfbeSBarry Smith extern PetscErrorCode  SNESSetFunctionDomainError(SNES);
193435da068SBarry Smith /*E
194435da068SBarry Smith     SNESConvergedReason - reason a SNES method was said to
195435da068SBarry Smith          have converged or diverged
196435da068SBarry Smith 
197435da068SBarry Smith    Level: beginner
198435da068SBarry Smith 
199f203c74bSBarry Smith    The two most common reasons for divergence are
200f203c74bSBarry Smith $   1) an incorrectly coded or computed Jacobian or
201f203c74bSBarry Smith $   2) failure or lack of convergence in the linear system (in this case we recommend
202f203c74bSBarry Smith $      testing with -pc_type lu to eliminate the linear solver as the cause of the problem).
203f203c74bSBarry Smith 
204f203c74bSBarry Smith    Diverged Reasons:
205f203c74bSBarry Smith .    SNES_DIVERGED_LOCAL_MIN - this can only occur when using the line-search variant of SNES.
206f203c74bSBarry Smith        The line search wants to minimize Q(alpha) = 1/2 || F(x + alpha s) ||^2_2  this occurs
207f203c74bSBarry Smith        at Q'(alpha) = s^T F'(x+alpha s)^T F(x+alpha s) = 0. If s is the Newton direction - F'(x)^(-1)F(x) then
208f203c74bSBarry Smith        you get Q'(alpha) = -F(x)^T F'(x)^(-1)^T F'(x+alpha s)F(x+alpha s); when alpha = 0
209f203c74bSBarry Smith        Q'(0) = - ||F(x)||^2_2 which is always NEGATIVE if F'(x) is invertible. This means the Newton
210f203c74bSBarry Smith        direction is a descent direction and the line search should succeed if alpha is small enough.
211f203c74bSBarry Smith 
212f203c74bSBarry Smith        If F'(x) is NOT invertible AND F'(x)^T F(x) = 0 then Q'(0) = 0 and the Newton direction
213f203c74bSBarry Smith        is NOT a descent direction so the line search will fail. All one can do at this point
214f203c74bSBarry Smith        is change the initial guess and try again.
215f203c74bSBarry Smith 
216f203c74bSBarry Smith        An alternative explanation: Newton's method can be regarded as replacing the function with
217f203c74bSBarry Smith        its linear approximation and minimizing the 2-norm of that. That is F(x+s) approx F(x) + F'(x)s
218f203c74bSBarry Smith        so we minimize || F(x) + F'(x) s ||^2_2; do this using Least Squares. If F'(x) is invertible then
219f203c74bSBarry Smith        s = - F'(x)^(-1)F(x) otherwise F'(x)^T F'(x) s = -F'(x)^T F(x). If F'(x)^T F(x) is NOT zero then there
220f203c74bSBarry Smith        exists a nontrival (that is F'(x)s != 0) solution to the equation and this direction is
221f203c74bSBarry Smith        s = - [F'(x)^T F'(x)]^(-1) F'(x)^T F(x) so Q'(0) = - F(x)^T F'(x) [F'(x)^T F'(x)]^(-T) F'(x)^T F(x)
222f203c74bSBarry Smith        = - (F'(x)^T F(x)) [F'(x)^T F'(x)]^(-T) (F'(x)^T F(x)). Since we are assuming (F'(x)^T F(x)) != 0
223f203c74bSBarry Smith        and F'(x)^T F'(x) has no negative eigenvalues Q'(0) < 0 so s is a descent direction and the line
224f203c74bSBarry Smith        search should succeed for small enough alpha.
225f203c74bSBarry Smith 
226f203c74bSBarry Smith        Note that this RARELY happens in practice. Far more likely the linear system is not being solved
227f203c74bSBarry Smith        (well enough?) or the Jacobian is wrong.
228f203c74bSBarry Smith 
2294d0a8057SBarry Smith    SNES_DIVERGED_MAX_IT means that the solver reached the maximum number of iterations without satisfying any
2304d0a8057SBarry Smith    convergence criteria. SNES_CONVERGED_ITS means that SNESSkipConverged() was chosen as the convergence test;
2314d0a8057SBarry Smith    thus the usual convergence criteria have not been checked and may or may not be satisfied.
232f203c74bSBarry Smith 
2334d0a8057SBarry Smith    Developer Notes: this must match finclude/petscsnes.h
2344d0a8057SBarry Smith 
2354d0a8057SBarry Smith        The string versions of these are in SNESConvergedReason, if you change any value here you must
2364d0a8057SBarry Smith      also adjust that array.
2375968eb51SBarry Smith 
23846a9e3ceSBarry Smith    Each reason has its own manual page.
23946a9e3ceSBarry Smith 
240435da068SBarry Smith .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest()
241435da068SBarry Smith E*/
242184914b5SBarry Smith typedef enum {/* converged */
24301b82886SBarry Smith               SNES_CONVERGED_FNORM_ABS         =  2, /* ||F|| < atol */
24401b82886SBarry Smith               SNES_CONVERGED_FNORM_RELATIVE    =  3, /* ||F|| < rtol*||F_initial|| */
24546a9e3ceSBarry Smith               SNES_CONVERGED_PNORM_RELATIVE    =  4, /* Newton computed step size small; || delta x || < stol */
2463f149594SLisandro Dalcin               SNES_CONVERGED_ITS               =  5, /* maximum iterations reached */
247184914b5SBarry Smith               SNES_CONVERGED_TR_DELTA          =  7,
248184914b5SBarry Smith               /* diverged */
24946a9e3ceSBarry Smith               SNES_DIVERGED_FUNCTION_DOMAIN     = -1, /* the new x location passed the function is not in the domain of F */
250184914b5SBarry Smith               SNES_DIVERGED_FUNCTION_COUNT      = -2,
25146a9e3ceSBarry Smith               SNES_DIVERGED_LINEAR_SOLVE        = -3, /* the linear solve failed */
252184914b5SBarry Smith               SNES_DIVERGED_FNORM_NAN           = -4,
253184914b5SBarry Smith               SNES_DIVERGED_MAX_IT              = -5,
254647a2e1fSBarry Smith               SNES_DIVERGED_LINE_SEARCH         = -6, /* the line search failed */
2551e633543SBarry Smith               SNES_DIVERGED_INNER               = -7, /* inner solve failed */
25658c775ebSBarry Smith               SNES_DIVERGED_LOCAL_MIN           = -8, /* || J^T b || is small, implies converged to local minimum of F() */
257184914b5SBarry Smith               SNES_CONVERGED_ITERATING          =  0} SNESConvergedReason;
2587935a769SJed Brown extern const char *const*SNESConvergedReasons;
259184914b5SBarry Smith 
260c838673bSBarry Smith /*MC
261c838673bSBarry Smith      SNES_CONVERGED_FNORM_ABS - 2-norm(F) <= abstol
262c838673bSBarry Smith 
263c838673bSBarry Smith    Level: beginner
264c838673bSBarry Smith 
265c838673bSBarry Smith .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
266c838673bSBarry Smith 
267c838673bSBarry Smith M*/
268c838673bSBarry Smith 
269c838673bSBarry Smith /*MC
270c838673bSBarry Smith      SNES_CONVERGED_FNORM_RELATIVE - 2-norm(F) <= rtol*2-norm(F(x_0)) where x_0 is the initial guess
271c838673bSBarry Smith 
272c838673bSBarry Smith    Level: beginner
273c838673bSBarry Smith 
274c838673bSBarry Smith .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
275c838673bSBarry Smith 
276c838673bSBarry Smith M*/
277c838673bSBarry Smith 
278c838673bSBarry Smith /*MC
27946a9e3ceSBarry Smith      SNES_CONVERGED_PNORM_RELATIVE - The 2-norm of the last step <= stol * 2-norm(x) where x is the current
28046a9e3ceSBarry Smith           solution and stol is the 4th argument to SNESSetTolerances()
281c838673bSBarry Smith 
282c838673bSBarry Smith    Level: beginner
283c838673bSBarry Smith 
284c838673bSBarry Smith .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
285c838673bSBarry Smith 
286c838673bSBarry Smith M*/
287c838673bSBarry Smith 
288c838673bSBarry Smith /*MC
289c838673bSBarry Smith      SNES_DIVERGED_FUNCTION_COUNT - The user provided function has been called more times then the final
290c838673bSBarry Smith          argument to SNESSetTolerances()
291c838673bSBarry Smith 
292c838673bSBarry Smith    Level: beginner
293c838673bSBarry Smith 
294c838673bSBarry Smith .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
295c838673bSBarry Smith 
296c838673bSBarry Smith M*/
297c838673bSBarry Smith 
298c838673bSBarry Smith /*MC
299c838673bSBarry Smith      SNES_DIVERGED_FNORM_NAN - the 2-norm of the current function evaluation is not-a-number (NaN), this
300c838673bSBarry Smith       is usually caused by a division of 0 by 0.
301c838673bSBarry Smith 
302c838673bSBarry Smith    Level: beginner
303c838673bSBarry Smith 
304c838673bSBarry Smith .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
305c838673bSBarry Smith 
306c838673bSBarry Smith M*/
307c838673bSBarry Smith 
308c838673bSBarry Smith /*MC
309c838673bSBarry Smith      SNES_DIVERGED_MAX_IT - SNESSolve() has reached the maximum number of iterations requested
310c838673bSBarry Smith 
311c838673bSBarry Smith    Level: beginner
312c838673bSBarry Smith 
313c838673bSBarry Smith .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
314c838673bSBarry Smith 
315c838673bSBarry Smith M*/
316c838673bSBarry Smith 
317c838673bSBarry Smith /*MC
318647a2e1fSBarry Smith      SNES_DIVERGED_LINE_SEARCH - The line search has failed. This only occurs for a SNESType of SNESLS
319c838673bSBarry Smith 
320c838673bSBarry Smith    Level: beginner
321c838673bSBarry Smith 
322c838673bSBarry Smith .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
323c838673bSBarry Smith 
324c838673bSBarry Smith M*/
325c838673bSBarry Smith 
326c838673bSBarry Smith /*MC
32746a9e3ceSBarry Smith      SNES_DIVERGED_LOCAL_MIN - the algorithm seems to have stagnated at a local minimum that is not zero.
32846a9e3ceSBarry Smith         See the manual page for SNESConvergedReason for more details
329c838673bSBarry Smith 
330c838673bSBarry Smith    Level: beginner
331c838673bSBarry Smith 
332c838673bSBarry Smith .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
333c838673bSBarry Smith 
334c838673bSBarry Smith M*/
335c838673bSBarry Smith 
336c838673bSBarry Smith /*MC
337c838673bSBarry Smith      SNES_CONERGED_ITERATING - this only occurs if SNESGetConvergedReason() is called during the SNESSolve()
338c838673bSBarry Smith 
339c838673bSBarry Smith    Level: beginner
340c838673bSBarry Smith 
341c838673bSBarry Smith .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
342c838673bSBarry Smith 
343c838673bSBarry Smith M*/
344c838673bSBarry Smith 
3457087cfbeSBarry Smith extern PetscErrorCode  SNESSetConvergenceTest(SNES,PetscErrorCode (*)(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*),void*,PetscErrorCode (*)(void*));
3467087cfbeSBarry Smith extern PetscErrorCode  SNESDefaultConverged(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
3477087cfbeSBarry Smith extern PetscErrorCode  SNESSkipConverged(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
3487087cfbeSBarry Smith extern PetscErrorCode  SNESGetConvergedReason(SNES,SNESConvergedReason*);
349ddbbdb52SLois Curfman McInnes 
3507087cfbeSBarry Smith extern PetscErrorCode  SNESDAFormFunction(SNES,Vec,Vec,void*);
3517087cfbeSBarry Smith extern PetscErrorCode  SNESDAComputeJacobianWithAdic(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
3527087cfbeSBarry Smith extern PetscErrorCode  SNESDAComputeJacobianWithAdifor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
3537087cfbeSBarry Smith extern PetscErrorCode  SNESDAComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
3543a7fca6bSBarry Smith 
35511f088b5SMatthew G Knepley extern PetscErrorCode  SNESMeshFormFunction(SNES,Vec,Vec,void*);
35611f088b5SMatthew G Knepley extern PetscErrorCode SNESMeshFormJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
35711f088b5SMatthew G Knepley 
358b67197daSBarry Smith /* --------- Solving systems of nonlinear equations --------------- */
3592d4b5aceSLisandro Dalcin typedef PetscErrorCode (*SNESFunction)(SNES,Vec,Vec,void*);
3602d4b5aceSLisandro Dalcin typedef PetscErrorCode (*SNESJacobian)(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
3612d4b5aceSLisandro Dalcin extern PetscErrorCode  SNESSetFunction(SNES,Vec,SNESFunction,void*);
3622d4b5aceSLisandro Dalcin extern PetscErrorCode  SNESGetFunction(SNES,Vec*,SNESFunction*,void**);
3637087cfbeSBarry Smith extern PetscErrorCode  SNESComputeFunction(SNES,Vec,Vec);
3642d4b5aceSLisandro Dalcin extern PetscErrorCode  SNESSetJacobian(SNES,Mat,Mat,SNESJacobian,void*);
3652d4b5aceSLisandro Dalcin extern PetscErrorCode  SNESGetJacobian(SNES,Mat*,Mat*,SNESJacobian*,void**);
3667087cfbeSBarry Smith extern PetscErrorCode  SNESDefaultComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
3677087cfbeSBarry Smith extern PetscErrorCode  SNESDefaultComputeJacobianColor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
368d25893d9SBarry Smith extern PetscErrorCode  SNESSetComputeInitialGuess(SNES,PetscErrorCode (*)(SNES,Vec,void*),void*);
36917bae607SBarry Smith 
37017bae607SBarry Smith /* --------- Routines specifically for line search methods --------------- */
371490ca623SBarry Smith /*E
37242f4f86dSBarry Smith     SNESLineSearchType - type of line search used in Newton's method as well as VI solvers and Richardson solvers
373490ca623SBarry Smith 
374490ca623SBarry Smith     Level: beginner
375490ca623SBarry Smith 
376490ca623SBarry Smith .seealso: SNESSetFromOptions(), SNESLineSearchSet()
377490ca623SBarry Smith E*/
378fe38d886SSatish Balay typedef enum {SNES_LS_BASIC, SNES_LS_BASIC_NONORMS, SNES_LS_QUADRATIC, SNES_LS_CUBIC, SNES_LS_EXACT, SNES_LS_TEST, SNES_LS_SECANT,SNES_LS_USER_DEFINED} SNESLineSearchType;
37921167be9SJed Brown extern const char *const SNESLineSearchTypes[];
38021167be9SJed Brown extern const char *SNESLineSearchTypeName(SNESLineSearchType); /* Does bounds checking, use this for viewing */
381490ca623SBarry Smith 
3821e633543SBarry Smith extern PetscErrorCode  SNESLineSearchSet(SNES,PetscErrorCode(*)(SNES,void*,Vec,Vec,Vec,PetscReal,PetscReal,Vec,Vec,PetscReal*,PetscReal*,PetscBool *),void*);
383ea630c6eSPeter Brune extern PetscErrorCode  SNESLineSearchSetType(SNES,SNESLineSearchType);
3841e633543SBarry Smith extern PetscErrorCode  SNESLineSearchNo(SNES,void*,Vec,Vec,Vec,PetscReal,PetscReal,Vec,Vec,PetscReal*,PetscReal*,PetscBool *);
3851e633543SBarry Smith extern PetscErrorCode  SNESLineSearchNoNorms(SNES,void*,Vec,Vec,Vec,PetscReal,PetscReal,Vec,Vec,PetscReal*,PetscReal*,PetscBool *);
3861e633543SBarry Smith extern PetscErrorCode  SNESLineSearchQuadratic(SNES,void*,Vec,Vec,Vec,PetscReal,PetscReal,Vec,Vec,PetscReal*,PetscReal*,PetscBool *);
38715f5eeeaSPeter Brune extern PetscErrorCode  SNESLineSearchCubic(SNES,void*,Vec,Vec,Vec,PetscReal,PetscReal,Vec,Vec,PetscReal*,PetscReal*,PetscBool *);
388cf9edfecSPeter Brune extern PetscErrorCode  SNESLineSearchSecant(SNES,void*,Vec,Vec,Vec,PetscReal,PetscReal,Vec,Vec,PetscReal*,PetscReal*,PetscBool *);
389af60355fSPeter Brune extern PetscErrorCode  SNESLineSearchQuadraticSecant(SNES,void*,Vec,Vec,Vec,PetscReal,PetscReal,Vec,Vec,PetscReal*,PetscReal*,PetscBool *);
390e56c5435SBarry Smith 
3917087cfbeSBarry Smith extern PetscErrorCode  SNESLineSearchSetPostCheck(SNES,PetscErrorCode(*)(SNES,Vec,Vec,Vec,void*,PetscBool *,PetscBool *),void*);
3927087cfbeSBarry Smith extern PetscErrorCode  SNESLineSearchSetPreCheck(SNES,PetscErrorCode(*)(SNES,Vec,Vec,void*,PetscBool *),void*);
39350f6de3fSJed Brown extern PetscErrorCode  SNESLineSearchPreCheckPicard(SNES,Vec,Vec,void*,PetscBool*);
3947087cfbeSBarry Smith extern PetscErrorCode  SNESLineSearchSetParams(SNES,PetscReal,PetscReal,PetscReal);
3957087cfbeSBarry Smith extern PetscErrorCode  SNESLineSearchGetParams(SNES,PetscReal*,PetscReal*,PetscReal*);
3967087cfbeSBarry Smith extern PetscErrorCode  SNESLineSearchSetMonitor(SNES,PetscBool );
39740191667SLois Curfman McInnes 
398c5ae4b9aSBarry Smith extern PetscErrorCode  SNESShellGetContext(SNES,void**);
399c5ae4b9aSBarry Smith extern PetscErrorCode  SNESShellSetContext(SNES,void*);
400c5ae4b9aSBarry Smith extern PetscErrorCode  SNESShellSetSolve(SNES,PetscErrorCode (*)(SNES,Vec));
401c5ae4b9aSBarry Smith 
402720c9a41SShri Abhyankar /* Routines for VI solver */
4037087cfbeSBarry Smith extern PetscErrorCode  SNESVISetVariableBounds(SNES,Vec,Vec);
40477cdaf69SJed Brown extern PetscErrorCode  SNESVISetComputeVariableBounds(SNES, PetscErrorCode (*)(SNES,Vec,Vec));
405ed70e96aSJungho Lee extern PetscErrorCode  SNESVIGetInactiveSet(SNES,IS*);
406*c2fc9fa9SBarry Smith extern PetscErrorCode  SNESVIGetActiveSetIS(SNES,Vec,Vec,IS*);
407*c2fc9fa9SBarry Smith extern PetscErrorCode  SNESVIComputeInactiveSetFnorm(SNES,Vec,Vec,PetscReal*);
408cb5fe31bSShri Abhyankar extern PetscErrorCode  SNESVISetRedundancyCheck(SNES,PetscErrorCode(*)(SNES,IS,IS*,void*),void*);
40901f0b76bSBarry Smith #define SNES_VI_INF   1.0e20
41001f0b76bSBarry Smith #define SNES_VI_NINF -1.0e20
411f5ea5bd2SShri Abhyankar 
4127087cfbeSBarry Smith extern PetscErrorCode  SNESTestLocalMin(SNES);
413da9b6338SBarry Smith 
414eef9c623SLois Curfman McInnes /* Should this routine be private? */
4157087cfbeSBarry Smith extern PetscErrorCode  SNESComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*);
416ddbbdb52SLois Curfman McInnes 
4177087cfbeSBarry Smith extern PetscErrorCode SNESSetDM(SNES,DM);
4187087cfbeSBarry Smith extern PetscErrorCode SNESGetDM(SNES,DM*);
41931823bd8SMatthew G Knepley extern PetscErrorCode SNESSetPC(SNES,SNES);
42031823bd8SMatthew G Knepley extern PetscErrorCode SNESGetPC(SNES,SNES*);
4216c699258SBarry Smith 
422b665c654SMatthew G Knepley /* Routines for Multiblock solver */
423b665c654SMatthew G Knepley PetscErrorCode SNESMultiblockSetFields(SNES, const char [], PetscInt, const PetscInt *);
424b665c654SMatthew G Knepley PetscErrorCode SNESMultiblockSetIS(SNES, const char [], IS);
425b665c654SMatthew G Knepley PetscErrorCode SNESMultiblockSetBlockSize(SNES, PetscInt);
426b665c654SMatthew G Knepley PetscErrorCode SNESMultiblockSetType(SNES, PCCompositeType);
427b665c654SMatthew G Knepley 
428e9fa29b7SSatish Balay PETSC_EXTERN_CXX_END
429ce3d82beSBarry Smith #endif
430