Actual source code: petscsnes.h
1: /*
2: User interface for the nonlinear solvers package.
3: */
6: #include petscksp.h
9: /*S
10: SNES - Abstract PETSc object that manages all nonlinear solves
12: Level: beginner
14: Concepts: nonlinear solvers
16: .seealso: SNESCreate(), SNESSetType(), SNESType, TS, KSP, KSP, PC
17: S*/
18: typedef struct _p_SNES* SNES;
20: /*E
21: SNESType - String with the name of a PETSc SNES method or the creation function
22: with an optional dynamic library name, for example
23: http://www.mcs.anl.gov/petsc/lib.a:mysnescreate()
25: Level: beginner
27: .seealso: SNESSetType(), SNES
28: E*/
29: #define SNESType char*
30: #define SNESLS "ls"
31: #define SNESTR "tr"
32: #define SNESPYTHON "python"
33: #define SNESTEST "test"
35: /* Logging support */
38: EXTERN PetscErrorCode SNESInitializePackage(const char[]);
40: EXTERN PetscErrorCode SNESCreate(MPI_Comm,SNES*);
41: EXTERN PetscErrorCode SNESDestroy(SNES);
42: EXTERN PetscErrorCode SNESSetType(SNES,const SNESType);
43: EXTERN PetscErrorCode SNESMonitorSet(SNES,PetscErrorCode(*)(SNES,PetscInt,PetscReal,void*),void *,PetscErrorCode (*)(void*));
44: EXTERN PetscErrorCode SNESMonitorCancel(SNES);
45: EXTERN PetscErrorCode SNESSetConvergenceHistory(SNES,PetscReal[],PetscInt[],PetscInt,PetscTruth);
46: EXTERN PetscErrorCode SNESGetConvergenceHistory(SNES,PetscReal*[],PetscInt *[],PetscInt *);
47: EXTERN PetscErrorCode SNESSetUp(SNES);
48: EXTERN PetscErrorCode SNESSolve(SNES,Vec,Vec);
50: EXTERN PetscErrorCode SNESAddOptionsChecker(PetscErrorCode (*)(SNES));
52: EXTERN PetscErrorCode SNESSetUpdate(SNES, PetscErrorCode (*)(SNES, PetscInt));
53: EXTERN PetscErrorCode SNESDefaultUpdate(SNES, PetscInt);
56: EXTERN PetscErrorCode SNESRegisterDestroy(void);
57: EXTERN PetscErrorCode SNESRegisterAll(const char[]);
59: EXTERN PetscErrorCode SNESRegister(const char[],const char[],const char[],PetscErrorCode (*)(SNES));
61: /*MC
62: SNESRegisterDynamic - Adds a method to the nonlinear solver package.
64: Synopsis:
65: PetscErrorCode SNESRegisterDynamic(char *name_solver,char *path,char *name_create,PetscErrorCode (*routine_create)(SNES))
67: Not collective
69: Input Parameters:
70: + name_solver - name of a new user-defined solver
71: . path - path (either absolute or relative) the library containing this solver
72: . name_create - name of routine to create method context
73: - routine_create - routine to create method context
75: Notes:
76: SNESRegisterDynamic() may be called multiple times to add several user-defined solvers.
78: If dynamic libraries are used, then the fourth input argument (routine_create)
79: is ignored.
81: Environmental variables such as ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR},
82: and others of the form ${any_environmental_variable} occuring in pathname will be
83: replaced with appropriate values.
85: Sample usage:
86: .vb
87: SNESRegisterDynamic("my_solver",/home/username/my_lib/lib/libg/solaris/mylib.a,
88: "MySolverCreate",MySolverCreate);
89: .ve
91: Then, your solver can be chosen with the procedural interface via
92: $ SNESSetType(snes,"my_solver")
93: or at runtime via the option
94: $ -snes_type my_solver
96: Level: advanced
98: Note: If your function is not being put into a shared library then use SNESRegister() instead
100: .keywords: SNES, nonlinear, register
102: .seealso: SNESRegisterAll(), SNESRegisterDestroy()
103: M*/
104: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
105: #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,0)
106: #else
107: #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,d)
108: #endif
110: EXTERN PetscErrorCode SNESGetKSP(SNES,KSP*);
111: EXTERN PetscErrorCode SNESSetKSP(SNES,KSP);
112: EXTERN PetscErrorCode SNESGetSolution(SNES,Vec*);
113: EXTERN PetscErrorCode SNESGetSolutionUpdate(SNES,Vec*);
114: EXTERN PetscErrorCode SNESGetFunction(SNES,Vec*,PetscErrorCode(**)(SNES,Vec,Vec,void*),void**);
115: EXTERN PetscErrorCode SNESView(SNES,PetscViewer);
117: EXTERN PetscErrorCode SNESSetOptionsPrefix(SNES,const char[]);
118: EXTERN PetscErrorCode SNESAppendOptionsPrefix(SNES,const char[]);
119: EXTERN PetscErrorCode SNESGetOptionsPrefix(SNES,const char*[]);
120: EXTERN PetscErrorCode SNESSetFromOptions(SNES);
122: EXTERN PetscErrorCode MatCreateSNESMF(SNES,Mat*);
123: EXTERN PetscErrorCode MatMFFDComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
125: EXTERN PetscErrorCode MatDAADSetSNES(Mat,SNES);
127: EXTERN PetscErrorCode SNESGetType(SNES,const SNESType*);
128: EXTERN PetscErrorCode SNESMonitorDefault(SNES,PetscInt,PetscReal,void *);
129: EXTERN PetscErrorCode SNESMonitorRange(SNES,PetscInt,PetscReal,void *);
130: EXTERN PetscErrorCode SNESMonitorRatio(SNES,PetscInt,PetscReal,void *);
131: EXTERN PetscErrorCode SNESMonitorSetRatio(SNES,PetscViewerASCIIMonitor);
132: EXTERN PetscErrorCode SNESMonitorSolution(SNES,PetscInt,PetscReal,void *);
133: EXTERN PetscErrorCode SNESMonitorResidual(SNES,PetscInt,PetscReal,void *);
134: EXTERN PetscErrorCode SNESMonitorSolutionUpdate(SNES,PetscInt,PetscReal,void *);
135: EXTERN PetscErrorCode SNESMonitorDefaultShort(SNES,PetscInt,PetscReal,void *);
136: EXTERN PetscErrorCode SNESSetTolerances(SNES,PetscReal,PetscReal,PetscReal,PetscInt,PetscInt);
137: EXTERN PetscErrorCode SNESGetTolerances(SNES,PetscReal*,PetscReal*,PetscReal*,PetscInt*,PetscInt*);
138: EXTERN PetscErrorCode SNESSetTrustRegionTolerance(SNES,PetscReal);
139: EXTERN PetscErrorCode SNESGetFunctionNorm(SNES,PetscReal*);
140: EXTERN PetscErrorCode SNESGetIterationNumber(SNES,PetscInt*);
142: EXTERN PetscErrorCode SNESGetNonlinearStepFailures(SNES,PetscInt*);
143: EXTERN PetscErrorCode SNESSetMaxNonlinearStepFailures(SNES,PetscInt);
144: EXTERN PetscErrorCode SNESGetMaxNonlinearStepFailures(SNES,PetscInt*);
145: EXTERN PetscErrorCode SNESGetNumberFunctionEvals(SNES,PetscInt*);
147: EXTERN PetscErrorCode SNESSetLagPreconditioner(SNES,PetscInt);
148: EXTERN PetscErrorCode SNESGetLagPreconditioner(SNES,PetscInt*);
149: EXTERN PetscErrorCode SNESSetLagJacobian(SNES,PetscInt);
150: EXTERN PetscErrorCode SNESGetLagJacobian(SNES,PetscInt*);
152: EXTERN PetscErrorCode SNESGetLinearSolveIterations(SNES,PetscInt*);
153: EXTERN PetscErrorCode SNESGetLinearSolveFailures(SNES,PetscInt*);
154: EXTERN PetscErrorCode SNESSetMaxLinearSolveFailures(SNES,PetscInt);
155: EXTERN PetscErrorCode SNESGetMaxLinearSolveFailures(SNES,PetscInt*);
157: EXTERN PetscErrorCode SNESKSPSetUseEW(SNES,PetscTruth);
158: EXTERN PetscErrorCode SNESKSPGetUseEW(SNES,PetscTruth*);
159: EXTERN PetscErrorCode SNESKSPSetParametersEW(SNES,PetscInt,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal);
160: EXTERN PetscErrorCode SNESKSPGetParametersEW(SNES,PetscInt*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*);
162: EXTERN PetscErrorCode SNESMonitorLGCreate(const char[],const char[],int,int,int,int,PetscDrawLG*);
163: EXTERN PetscErrorCode SNESMonitorLG(SNES,PetscInt,PetscReal,void*);
164: EXTERN PetscErrorCode SNESMonitorLGDestroy(PetscDrawLG);
165: EXTERN PetscErrorCode SNESMonitorLGRangeCreate(const char[],const char[],int,int,int,int,PetscDrawLG*);
166: EXTERN PetscErrorCode SNESMonitorLGRange(SNES,PetscInt,PetscReal,void*);
167: EXTERN PetscErrorCode SNESMonitorLGRangeDestroy(PetscDrawLG);
169: EXTERN PetscErrorCode SNESSetApplicationContext(SNES,void *);
170: EXTERN PetscErrorCode SNESGetApplicationContext(SNES,void **);
172: EXTERN PetscErrorCode SNESPythonSetType(SNES,const char[]);
174: EXTERN PetscErrorCode SNESSetFunctionDomainError(SNES);
175: /*E
176: SNESConvergedReason - reason a SNES method was said to
177: have converged or diverged
179: Level: beginner
181: The two most common reasons for divergence are
182: $ 1) an incorrectly coded or computed Jacobian or
183: $ 2) failure or lack of convergence in the linear system (in this case we recommend
184: $ testing with -pc_type lu to eliminate the linear solver as the cause of the problem).
186: Diverged Reasons:
187: . SNES_DIVERGED_LOCAL_MIN - this can only occur when using the line-search variant of SNES.
188: The line search wants to minimize Q(alpha) = 1/2 || F(x + alpha s) ||^2_2 this occurs
189: 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
190: you get Q'(alpha) = -F(x)^T F'(x)^(-1)^T F'(x+alpha s)F(x+alpha s); when alpha = 0
191: Q'(0) = - ||F(x)||^2_2 which is always NEGATIVE if F'(x) is invertible. This means the Newton
192: direction is a descent direction and the line search should succeed if alpha is small enough.
194: If F'(x) is NOT invertible AND F'(x)^T F(x) = 0 then Q'(0) = 0 and the Newton direction
195: is NOT a descent direction so the line search will fail. All one can do at this point
196: is change the initial guess and try again.
198: An alternative explanation: Newton's method can be regarded as replacing the function with
199: its linear approximation and minimizing the 2-norm of that. That is F(x+s) approx F(x) + F'(x)s
200: so we minimize || F(x) + F'(x) s ||^2_2; do this using Least Squares. If F'(x) is invertible then
201: 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
202: exists a nontrival (that is F'(x)s != 0) solution to the equation and this direction is
203: 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)
204: = - (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
205: and F'(x)^T F'(x) has no negative eigenvalues Q'(0) < 0 so s is a descent direction and the line
206: search should succeed for small enough alpha.
208: Note that this RARELY happens in practice. Far more likely the linear system is not being solved
209: (well enough?) or the Jacobian is wrong.
210:
211: SNES_DIVERGED_MAX_IT means that the solver reached the maximum number of iterations without satisfying any
212: convergence criteria. SNES_CONVERGED_ITS means that SNESSkipConverged() was chosen as the convergence test;
213: thus the usual convergence criteria have not been checked and may or may not be satisfied.
215: Developer Notes: this must match finclude/petscsnes.h
217: The string versions of these are in SNESConvergedReason, if you change any value here you must
218: also adjust that array.
220: .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest()
221: E*/
222: typedef enum {/* converged */
223: SNES_CONVERGED_FNORM_ABS = 2, /* ||F|| < atol */
224: SNES_CONVERGED_FNORM_RELATIVE = 3, /* ||F|| < rtol*||F_initial|| */
225: SNES_CONVERGED_PNORM_RELATIVE = 4, /* Newton computed step size small; || delta x || < tol */
226: SNES_CONVERGED_ITS = 5, /* maximum iterations reached */
227: SNES_CONVERGED_TR_DELTA = 7,
228: /* diverged */
229: SNES_DIVERGED_FUNCTION_DOMAIN = -1,
230: SNES_DIVERGED_FUNCTION_COUNT = -2,
231: SNES_DIVERGED_LINEAR_SOLVE = -3,
232: SNES_DIVERGED_FNORM_NAN = -4,
233: SNES_DIVERGED_MAX_IT = -5,
234: SNES_DIVERGED_LS_FAILURE = -6,
235: SNES_DIVERGED_LOCAL_MIN = -8, /* || J^T b || is small, implies converged to local minimum of F() */
236: SNES_CONVERGED_ITERATING = 0} SNESConvergedReason;
239: /*MC
240: SNES_CONVERGED_FNORM_ABS - 2-norm(F) <= abstol
242: Level: beginner
244: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
246: M*/
248: /*MC
249: SNES_CONVERGED_FNORM_RELATIVE - 2-norm(F) <= rtol*2-norm(F(x_0)) where x_0 is the initial guess
251: Level: beginner
253: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
255: M*/
257: /*MC
258: SNES_CONVERGED_PNORM_RELATIVE - The 2-norm of the last step <= xtol * 2-norm(x) where x is the current
259: solution and xtol is the 4th argument to SNESSetTolerances()
261: Level: beginner
263: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
265: M*/
267: /*MC
268: SNES_DIVERGED_FUNCTION_COUNT - The user provided function has been called more times then the final
269: argument to SNESSetTolerances()
271: Level: beginner
273: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
275: M*/
277: /*MC
278: SNES_DIVERGED_FNORM_NAN - the 2-norm of the current function evaluation is not-a-number (NaN), this
279: is usually caused by a division of 0 by 0.
281: Level: beginner
283: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
285: M*/
287: /*MC
288: SNES_DIVERGED_MAX_IT - SNESSolve() has reached the maximum number of iterations requested
290: Level: beginner
292: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
294: M*/
296: /*MC
297: SNES_DIVERGED_LS_FAILURE - The line search has failed. This only occurs for a SNESType of SNESLS
299: Level: beginner
301: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
303: M*/
305: /*MC
306: SNES_DIVERGED_LOCAL_MIN - the algorithm seems to have stagnated at a local minimum that is not zero
308: Level: beginner
310: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
312: M*/
314: /*MC
315: SNES_CONERGED_ITERATING - this only occurs if SNESGetConvergedReason() is called during the SNESSolve()
317: Level: beginner
319: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
321: M*/
323: EXTERN PetscErrorCode SNESSetConvergenceTest(SNES,PetscErrorCode (*)(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*),void*,PetscErrorCode (*)(void*));
324: EXTERN PetscErrorCode SNESDefaultConverged(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
325: EXTERN PetscErrorCode SNESSkipConverged(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
326: EXTERN PetscErrorCode SNESGetConvergedReason(SNES,SNESConvergedReason*);
328: EXTERN PetscErrorCode SNESDAFormFunction(SNES,Vec,Vec,void*);
329: EXTERN PetscErrorCode SNESDAComputeJacobianWithAdic(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
330: EXTERN PetscErrorCode SNESDAComputeJacobianWithAdifor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
331: EXTERN PetscErrorCode SNESDAComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
333: /* --------- Solving systems of nonlinear equations --------------- */
334: EXTERN PetscErrorCode SNESSetFunction(SNES,Vec,PetscErrorCode(*)(SNES,Vec,Vec,void*),void *);
335: EXTERN PetscErrorCode SNESComputeFunction(SNES,Vec,Vec);
336: EXTERN PetscErrorCode SNESSetJacobian(SNES,Mat,Mat,PetscErrorCode(*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void *);
337: EXTERN PetscErrorCode SNESGetJacobian(SNES,Mat*,Mat*,PetscErrorCode(**)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void **);
338: EXTERN PetscErrorCode SNESDefaultComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
339: EXTERN PetscErrorCode SNESDefaultComputeJacobianColor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
340: EXTERN PetscErrorCode SNESGetRhs(SNES,Vec*);
342: /* --------- Routines specifically for line search methods --------------- */
343: EXTERN PetscErrorCode SNESLineSearchSet(SNES,PetscErrorCode(*)(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal*,PetscReal*,PetscTruth*),void*);
344: EXTERN PetscErrorCode SNESLineSearchNo(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
345: EXTERN PetscErrorCode SNESLineSearchNoNorms(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
346: EXTERN PetscErrorCode SNESLineSearchCubic(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
347: EXTERN PetscErrorCode SNESLineSearchQuadratic(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
349: EXTERN PetscErrorCode SNESLineSearchSetPostCheck(SNES,PetscErrorCode(*)(SNES,Vec,Vec,Vec,void*,PetscTruth*,PetscTruth*),void*);
350: EXTERN PetscErrorCode SNESLineSearchSetPreCheck(SNES,PetscErrorCode(*)(SNES,Vec,Vec,void*,PetscTruth*),void*);
351: EXTERN PetscErrorCode SNESLineSearchSetParams(SNES,PetscReal,PetscReal);
352: EXTERN PetscErrorCode SNESLineSearchGetParams(SNES,PetscReal*,PetscReal*);
354: EXTERN PetscErrorCode SNESTestLocalMin(SNES);
356: /* Should this routine be private? */
357: EXTERN PetscErrorCode SNESComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*);
360: #endif