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