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 SNESLS "ls"
30: #define SNESTR "tr"
31: #define SNESTEST "test"
32: #define SNESType const char*
34: /* 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,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,Vec,Mat*);
123: EXTERN PetscErrorCode MatCreateMF(Vec,Mat*);
124: EXTERN PetscErrorCode MatSNESMFSetBase(Mat,Vec);
125: EXTERN PetscErrorCode MatSNESMFComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
126: EXTERN PetscErrorCode MatSNESMFSetFunction(Mat,Vec,PetscErrorCode(*)(SNES,Vec,Vec,void*),void*);
127: EXTERN PetscErrorCode MatSNESMFSetFunctioni(Mat,PetscErrorCode (*)(PetscInt,Vec,PetscScalar*,void*));
128: EXTERN PetscErrorCode MatSNESMFSetFunctioniBase(Mat,PetscErrorCode (*)(Vec,void*));
129: EXTERN PetscErrorCode MatSNESMFAddNullSpace(Mat,MatNullSpace);
130: EXTERN PetscErrorCode MatSNESMFSetHHistory(Mat,PetscScalar[],PetscInt);
131: EXTERN PetscErrorCode MatSNESMFResetHHistory(Mat);
132: EXTERN PetscErrorCode MatSNESMFSetFunctionError(Mat,PetscReal);
133: EXTERN PetscErrorCode MatSNESMFSetPeriod(Mat,PetscInt);
134: EXTERN PetscErrorCode MatSNESMFGetH(Mat,PetscScalar *);
135: EXTERN PetscErrorCode MatSNESMFKSPMonitor(KSP,PetscInt,PetscReal,void *);
136: EXTERN PetscErrorCode MatSNESMFSetFromOptions(Mat);
137: EXTERN PetscErrorCode MatSNESMFCheckPositivity(Vec,Vec,PetscScalar*,void*);
138: EXTERN PetscErrorCode MatSNESMFSetCheckh(Mat,PetscErrorCode (*)(Vec,Vec,PetscScalar*,void*),void*);
139: EXTERN PetscErrorCode MatSNESMFDSSetUmin(Mat,PetscReal);
142: typedef struct _p_MatSNESMFCtx* MatSNESMFCtx;
144: #define MATSNESMF_DS "ds"
145: #define MATSNESMF_WP "wp"
146: #define MatSNESMFType char*
147: EXTERN PetscErrorCode MatSNESMFSetType(Mat,const MatSNESMFType);
148: EXTERN PetscErrorCode MatSNESMFRegister(const char[],const char[],const char[],PetscErrorCode (*)(MatSNESMFCtx));
150: /*MC
151: MatSNESMFRegisterDynamic - Adds a method to the MatSNESMF registry.
153: Synopsis:
154: PetscErrorCode MatSNESMFRegisterDynamic(char *name_solver,char *path,char *name_create,PetscErrorCode (*routine_create)(MatSNESMF))
156: Not Collective
158: Input Parameters:
159: + name_solver - name of a new user-defined compute-h module
160: . path - path (either absolute or relative) the library containing this solver
161: . name_create - name of routine to create method context
162: - routine_create - routine to create method context
164: Level: developer
166: Notes:
167: MatSNESMFRegisterDynamic) may be called multiple times to add several user-defined solvers.
169: If dynamic libraries are used, then the fourth input argument (routine_create)
170: is ignored.
172: Sample usage:
173: .vb
174: MatSNESMFRegisterDynamic"my_h",/home/username/my_lib/lib/libO/solaris/mylib.a,
175: "MyHCreate",MyHCreate);
176: .ve
178: Then, your solver can be chosen with the procedural interface via
179: $ MatSNESMFSetType(mfctx,"my_h")
180: or at runtime via the option
181: $ -snes_mf_type my_h
183: .keywords: MatSNESMF, register
185: .seealso: MatSNESMFRegisterAll(), MatSNESMFRegisterDestroy()
186: M*/
187: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
188: #define MatSNESMFRegisterDynamic(a,b,c,d) MatSNESMFRegister(a,b,c,0)
189: #else
190: #define MatSNESMFRegisterDynamic(a,b,c,d) MatSNESMFRegister(a,b,c,d)
191: #endif
193: EXTERN PetscErrorCode MatSNESMFRegisterAll(const char[]);
194: EXTERN PetscErrorCode MatSNESMFRegisterDestroy(void);
195: EXTERN PetscErrorCode MatSNESMFDefaultSetUmin(Mat,PetscReal);
196: EXTERN PetscErrorCode MatSNESMFWPSetComputeNormU(Mat,PetscTruth);
198: EXTERN PetscErrorCode MatDAADSetSNES(Mat,SNES);
200: EXTERN PetscErrorCode SNESGetType(SNES,SNESType*);
201: EXTERN PetscErrorCode SNESMonitorDefault(SNES,PetscInt,PetscReal,void *);
202: EXTERN PetscErrorCode SNESMonitorRatio(SNES,PetscInt,PetscReal,void *);
203: EXTERN PetscErrorCode SNESMonitorSetRatio(SNES,PetscViewerASCIIMonitor);
204: EXTERN PetscErrorCode SNESMonitorSolution(SNES,PetscInt,PetscReal,void *);
205: EXTERN PetscErrorCode SNESMonitorResidual(SNES,PetscInt,PetscReal,void *);
206: EXTERN PetscErrorCode SNESMonitorSolutionUpdate(SNES,PetscInt,PetscReal,void *);
207: EXTERN PetscErrorCode SNESMonitorDefaultShort(SNES,PetscInt,PetscReal,void *);
208: EXTERN PetscErrorCode SNESSetTolerances(SNES,PetscReal,PetscReal,PetscReal,PetscInt,PetscInt);
209: EXTERN PetscErrorCode SNESGetTolerances(SNES,PetscReal*,PetscReal*,PetscReal*,PetscInt*,PetscInt*);
210: EXTERN PetscErrorCode SNESSetTrustRegionTolerance(SNES,PetscReal);
211: EXTERN PetscErrorCode SNESGetIterationNumber(SNES,PetscInt*);
212: EXTERN PetscErrorCode SNESGetFunctionNorm(SNES,PetscScalar*);
213: EXTERN PetscErrorCode SNESGetNumberUnsuccessfulSteps(SNES,PetscInt*);
214: EXTERN PetscErrorCode SNESSetMaximumUnsuccessfulSteps(SNES,PetscInt);
215: EXTERN PetscErrorCode SNESGetMaximumUnsuccessfulSteps(SNES,PetscInt*);
217: EXTERN PetscErrorCode SNESGetLinearSolveFailures(SNES,PetscInt*);
218: EXTERN PetscErrorCode SNESSetMaxLinearSolveFailures(SNES,PetscInt);
219: EXTERN PetscErrorCode SNESGetMaxLinearSolveFailures(SNES,PetscInt*);
221: EXTERN PetscErrorCode SNESGetNumberLinearIterations(SNES,PetscInt*);
222: EXTERN PetscErrorCode SNES_KSP_SetParametersEW(SNES,PetscInt,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal);
223: EXTERN PetscErrorCode SNES_KSP_SetConvergenceTestEW(SNES);
225: /*
226: Reuse the default KSP monitor routines for SNES
227: */
228: EXTERN PetscErrorCode SNESMonitorLGCreate(const char[],const char[],int,int,int,int,PetscDrawLG*);
229: EXTERN PetscErrorCode SNESMonitorLG(SNES,PetscInt,PetscReal,void*);
230: EXTERN PetscErrorCode SNESMonitorLGDestroy(PetscDrawLG);
232: EXTERN PetscErrorCode SNESSetApplicationContext(SNES,void *);
233: EXTERN PetscErrorCode SNESGetApplicationContext(SNES,void **);
235: /*E
236: SNESConvergedReason - reason a SNES method was said to
237: have converged or diverged
239: Level: beginner
241: Notes: this must match finclude/petscsnes.h
243: Developer note: The string versions of these are in
244: src/snes/interface/snes.c called convergedreasons.
245: If these enums are changed you much change those.
247: .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest()
248: E*/
249: typedef enum {/* converged */
250: SNES_CONVERGED_FNORM_ABS = 2, /* F < F_minabs */
251: SNES_CONVERGED_FNORM_RELATIVE = 3, /* F < F_mintol*F_initial */
252: SNES_CONVERGED_PNORM_RELATIVE = 4, /* step size small */
253: SNES_CONVERGED_TR_DELTA = 7,
254: /* diverged */
255: SNES_DIVERGED_FUNCTION_DOMAIN = -1,
256: SNES_DIVERGED_FUNCTION_COUNT = -2,
257: SNES_DIVERGED_LINEAR_SOLVE = -3,
258: SNES_DIVERGED_FNORM_NAN = -4,
259: SNES_DIVERGED_MAX_IT = -5,
260: SNES_DIVERGED_LS_FAILURE = -6,
261: SNES_DIVERGED_LOCAL_MIN = -8, /* || J^T b || is small, implies converged to local minimum of F() */
262: SNES_CONVERGED_ITERATING = 0} SNESConvergedReason;
265: /*MC
266: SNES_CONVERGED_FNORM_ABS - 2-norm(F) <= abstol
268: Level: beginner
270: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
272: M*/
274: /*MC
275: SNES_CONVERGED_FNORM_RELATIVE - 2-norm(F) <= rtol*2-norm(F(x_0)) where x_0 is the initial guess
277: Level: beginner
279: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
281: M*/
283: /*MC
284: SNES_CONVERGED_PNORM_RELATIVE - The 2-norm of the last step <= xtol * 2-norm(x) where x is the current
285: solution and xtol is the 4th argument to SNESSetTolerances()
287: Level: beginner
289: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
291: M*/
293: /*MC
294: SNES_DIVERGED_FUNCTION_COUNT - The user provided function has been called more times then the final
295: argument to SNESSetTolerances()
297: Level: beginner
299: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
301: M*/
303: /*MC
304: SNES_DIVERGED_FNORM_NAN - the 2-norm of the current function evaluation is not-a-number (NaN), this
305: is usually caused by a division of 0 by 0.
307: Level: beginner
309: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
311: M*/
313: /*MC
314: SNES_DIVERGED_MAX_IT - SNESSolve() has reached the maximum number of iterations requested
316: Level: beginner
318: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
320: M*/
322: /*MC
323: SNES_DIVERGED_LS_FAILURE - The line search has failed. This only occurs for a SNESType of SNESLS
325: Level: beginner
327: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
329: M*/
331: /*MC
332: SNES_DIVERGED_LOCAL_MIN - the algorithm seems to have stagnated at a local minimum that is not zero
334: Level: beginner
336: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
338: M*/
340: /*MC
341: SNES_CONERGED_ITERATING - this only occurs if SNESGetConvergedReason() is called during the SNESSolve()
343: Level: beginner
345: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
347: M*/
349: EXTERN PetscErrorCode SNESSetConvergenceTest(SNES,PetscErrorCode (*)(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*),void*);
350: EXTERN PetscErrorCode SNESConverged_LS(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
351: EXTERN PetscErrorCode SNESConverged_TR(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
352: EXTERN PetscErrorCode SNESGetConvergedReason(SNES,SNESConvergedReason*);
354: EXTERN PetscErrorCode SNESDAFormFunction(SNES,Vec,Vec,void*);
355: EXTERN PetscErrorCode SNESDAComputeJacobianWithAdic(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
356: EXTERN PetscErrorCode SNESDAComputeJacobianWithAdifor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
357: EXTERN PetscErrorCode SNESDAComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
359: /* --------- Solving systems of nonlinear equations --------------- */
360: EXTERN PetscErrorCode SNESSetFunction(SNES,Vec,PetscErrorCode(*)(SNES,Vec,Vec,void*),void *);
361: EXTERN PetscErrorCode SNESComputeFunction(SNES,Vec,Vec);
362: EXTERN PetscErrorCode SNESSetJacobian(SNES,Mat,Mat,PetscErrorCode(*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void *);
363: EXTERN PetscErrorCode SNESGetJacobian(SNES,Mat*,Mat*,PetscErrorCode(**)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void **);
364: EXTERN PetscErrorCode SNESDefaultComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
365: EXTERN PetscErrorCode SNESDefaultComputeJacobianColor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
366: EXTERN PetscErrorCode SNESSetRhs(SNES,Vec);
367: EXTERN PetscErrorCode SNESGetRhs(SNES,Vec*);
369: /* --------- Routines specifically for line search methods --------------- */
370: EXTERN PetscErrorCode SNESLineSearchSet(SNES,PetscErrorCode(*)(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*),void*);
371: EXTERN PetscErrorCode SNESLineSearchNo(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
372: EXTERN PetscErrorCode SNESLineSearchNoNorms(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
373: EXTERN PetscErrorCode SNESLineSearchCubic(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
374: EXTERN PetscErrorCode SNESLineSearchQuadratic(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
376: EXTERN PetscErrorCode SNESLineSearchSetPostCheck(SNES,PetscErrorCode(*)(SNES,Vec,Vec,Vec,void*,PetscTruth*,PetscTruth*),void*);
377: EXTERN PetscErrorCode SNESLineSearchSetPreCheck(SNES,PetscErrorCode(*)(SNES,Vec,Vec,void*,PetscTruth*),void*);
378: EXTERN PetscErrorCode SNESLineSearchSetParams(SNES,PetscReal,PetscReal,PetscReal);
379: EXTERN PetscErrorCode SNESLineSearchGetParams(SNES,PetscReal*,PetscReal*,PetscReal*);
381: EXTERN PetscErrorCode SNESTestLocalMin(SNES);
382: EXTERN PetscErrorCode SNESSetSolution(SNES,Vec);
384: /* Should this routine be private? */
385: EXTERN PetscErrorCode SNESComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*);
388: #endif