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 char*
34: /* Logging support */
39: EXTERN PetscErrorCode SNESInitializePackage(const char[]);
41: EXTERN PetscErrorCode SNESCreate(MPI_Comm,SNES*);
42: EXTERN PetscErrorCode SNESDestroy(SNES);
43: EXTERN PetscErrorCode SNESSetType(SNES,const SNESType);
44: EXTERN PetscErrorCode SNESSetMonitor(SNES,PetscErrorCode(*)(SNES,PetscInt,PetscReal,void*),void *,PetscErrorCode (*)(void*));
45: EXTERN PetscErrorCode SNESClearMonitor(SNES);
46: EXTERN PetscErrorCode SNESSetConvergenceHistory(SNES,PetscReal[],PetscInt[],PetscInt,PetscTruth);
47: EXTERN PetscErrorCode SNESGetConvergenceHistory(SNES,PetscReal*[],PetscInt *[],PetscInt *);
48: EXTERN PetscErrorCode SNESSetUp(SNES,Vec);
49: EXTERN PetscErrorCode SNESSolve(SNES,Vec);
51: EXTERN PetscErrorCode SNESAddOptionsChecker(PetscErrorCode (*)(SNES));
53: EXTERN PetscErrorCode SNESSetRhsBC(SNES, PetscErrorCode (*)(SNES, Vec, void *));
54: EXTERN PetscErrorCode SNESDefaultRhsBC(SNES, Vec, void *);
55: EXTERN PetscErrorCode SNESSetSolutionBC(SNES, PetscErrorCode (*)(SNES, Vec, void *));
56: EXTERN PetscErrorCode SNESDefaultSolutionBC(SNES, Vec, void *);
57: EXTERN PetscErrorCode SNESSetUpdate(SNES, PetscErrorCode (*)(SNES, PetscInt));
58: EXTERN PetscErrorCode SNESDefaultUpdate(SNES, PetscInt);
61: EXTERN PetscErrorCode SNESRegisterDestroy(void);
62: EXTERN PetscErrorCode SNESRegisterAll(const char[]);
64: EXTERN PetscErrorCode SNESRegister(const char[],const char[],const char[],PetscErrorCode (*)(SNES));
66: /*MC
67: SNESRegisterDynamic - Adds a method to the nonlinear solver package.
69: Synopsis:
70: PetscErrorCode SNESRegisterDynamic(char *name_solver,char *path,char *name_create,PetscErrorCode (*routine_create)(SNES))
72: Not collective
74: Input Parameters:
75: + name_solver - name of a new user-defined solver
76: . path - path (either absolute or relative) the library containing this solver
77: . name_create - name of routine to create method context
78: - routine_create - routine to create method context
80: Notes:
81: SNESRegisterDynamic() may be called multiple times to add several user-defined solvers.
83: If dynamic libraries are used, then the fourth input argument (routine_create)
84: is ignored.
86: Environmental variables such as ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR}, ${BOPT},
87: and others of the form ${any_environmental_variable} occuring in pathname will be
88: replaced with appropriate values.
90: Sample usage:
91: .vb
92: SNESRegisterDynamic("my_solver",/home/username/my_lib/lib/libg/solaris/mylib.a,
93: "MySolverCreate",MySolverCreate);
94: .ve
96: Then, your solver can be chosen with the procedural interface via
97: $ SNESSetType(snes,"my_solver")
98: or at runtime via the option
99: $ -snes_type my_solver
101: Level: advanced
103: Note: If your function is not being put into a shared library then use SNESRegister() instead
105: .keywords: SNES, nonlinear, register
107: .seealso: SNESRegisterAll(), SNESRegisterDestroy()
108: M*/
109: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
110: #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,0)
111: #else
112: #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,d)
113: #endif
115: EXTERN PetscErrorCode SNESGetKSP(SNES,KSP*);
116: EXTERN PetscErrorCode SNESGetSolution(SNES,Vec*);
117: EXTERN PetscErrorCode SNESGetSolutionUpdate(SNES,Vec*);
118: EXTERN PetscErrorCode SNESGetFunction(SNES,Vec*,void**,PetscErrorCode(**)(SNES,Vec,Vec,void*));
119: EXTERN PetscErrorCode SNESView(SNES,PetscViewer);
121: EXTERN PetscErrorCode SNESSetOptionsPrefix(SNES,const char[]);
122: EXTERN PetscErrorCode SNESAppendOptionsPrefix(SNES,const char[]);
123: EXTERN PetscErrorCode SNESGetOptionsPrefix(SNES,char*[]);
124: EXTERN PetscErrorCode SNESSetFromOptions(SNES);
126: EXTERN PetscErrorCode MatCreateSNESMF(SNES,Vec,Mat*);
127: EXTERN PetscErrorCode MatCreateMF(Vec,Mat*);
128: EXTERN PetscErrorCode MatSNESMFSetBase(Mat,Vec);
129: EXTERN PetscErrorCode MatSNESMFComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
130: EXTERN PetscErrorCode MatSNESMFSetFunction(Mat,Vec,PetscErrorCode(*)(SNES,Vec,Vec,void*),void*);
131: EXTERN PetscErrorCode MatSNESMFSetFunctioni(Mat,PetscErrorCode (*)(PetscInt,Vec,PetscScalar*,void*));
132: EXTERN PetscErrorCode MatSNESMFSetFunctioniBase(Mat,PetscErrorCode (*)(Vec,void*));
133: EXTERN PetscErrorCode MatSNESMFAddNullSpace(Mat,MatNullSpace);
134: EXTERN PetscErrorCode MatSNESMFSetHHistory(Mat,PetscScalar[],PetscInt);
135: EXTERN PetscErrorCode MatSNESMFResetHHistory(Mat);
136: EXTERN PetscErrorCode MatSNESMFSetFunctionError(Mat,PetscReal);
137: EXTERN PetscErrorCode MatSNESMFSetPeriod(Mat,PetscInt);
138: EXTERN PetscErrorCode MatSNESMFGetH(Mat,PetscScalar *);
139: EXTERN PetscErrorCode MatSNESMFKSPMonitor(KSP,PetscInt,PetscReal,void *);
140: EXTERN PetscErrorCode MatSNESMFSetFromOptions(Mat);
141: EXTERN PetscErrorCode MatSNESMFCheckPositivity(Vec,Vec,PetscScalar*,void*);
142: EXTERN PetscErrorCode MatSNESMFSetCheckh(Mat,PetscErrorCode (*)(Vec,Vec,PetscScalar*,void*),void*);
144: typedef struct _p_MatSNESMFCtx *MatSNESMFCtx;
146: #define MATSNESMF_DEFAULT "default"
147: #define MATSNESMF_WP "wp"
148: #define MatSNESMFType char*
149: EXTERN PetscErrorCode MatSNESMFSetType(Mat,const MatSNESMFType);
150: EXTERN PetscErrorCode MatSNESMFRegister(const char[],const char[],const char[],PetscErrorCode (*)(MatSNESMFCtx));
152: /*MC
153: MatSNESMFRegisterDynamic - Adds a method to the MatSNESMF registry.
155: Synopsis:
156: PetscErrorCode MatSNESMFRegisterDynamic(char *name_solver,char *path,char *name_create,PetscErrorCode (*routine_create)(MatSNESMF))
158: Not Collective
160: Input Parameters:
161: + name_solver - name of a new user-defined compute-h module
162: . path - path (either absolute or relative) the library containing this solver
163: . name_create - name of routine to create method context
164: - routine_create - routine to create method context
166: Level: developer
168: Notes:
169: MatSNESMFRegisterDynamic) may be called multiple times to add several user-defined solvers.
171: If dynamic libraries are used, then the fourth input argument (routine_create)
172: is ignored.
174: Sample usage:
175: .vb
176: MatSNESMFRegisterDynamic"my_h",/home/username/my_lib/lib/libO/solaris/mylib.a,
177: "MyHCreate",MyHCreate);
178: .ve
180: Then, your solver can be chosen with the procedural interface via
181: $ MatSNESMFSetType(mfctx,"my_h")
182: or at runtime via the option
183: $ -snes_mf_type my_h
185: .keywords: MatSNESMF, register
187: .seealso: MatSNESMFRegisterAll(), MatSNESMFRegisterDestroy()
188: M*/
189: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
190: #define MatSNESMFRegisterDynamic(a,b,c,d) MatSNESMFRegister(a,b,c,0)
191: #else
192: #define MatSNESMFRegisterDynamic(a,b,c,d) MatSNESMFRegister(a,b,c,d)
193: #endif
195: EXTERN PetscErrorCode MatSNESMFRegisterAll(const char[]);
196: EXTERN PetscErrorCode MatSNESMFRegisterDestroy(void);
197: EXTERN PetscErrorCode MatSNESMFDefaultSetUmin(Mat,PetscReal);
198: EXTERN PetscErrorCode MatSNESMFWPSetComputeNormA(Mat,PetscTruth);
199: EXTERN PetscErrorCode MatSNESMFWPSetComputeNormU(Mat,PetscTruth);
201: EXTERN PetscErrorCode MatDAADSetSNES(Mat,SNES);
203: EXTERN PetscErrorCode SNESGetType(SNES,SNESType*);
204: EXTERN PetscErrorCode SNESDefaultMonitor(SNES,PetscInt,PetscReal,void *);
205: EXTERN PetscErrorCode SNESRatioMonitor(SNES,PetscInt,PetscReal,void *);
206: EXTERN PetscErrorCode SNESSetRatioMonitor(SNES);
207: EXTERN PetscErrorCode SNESVecViewMonitor(SNES,PetscInt,PetscReal,void *);
208: EXTERN PetscErrorCode SNESVecViewResidualMonitor(SNES,PetscInt,PetscReal,void *);
209: EXTERN PetscErrorCode SNESVecViewUpdateMonitor(SNES,PetscInt,PetscReal,void *);
210: EXTERN PetscErrorCode SNESDefaultSMonitor(SNES,PetscInt,PetscReal,void *);
211: EXTERN PetscErrorCode SNESSetTolerances(SNES,PetscReal,PetscReal,PetscReal,PetscInt,PetscInt);
212: EXTERN PetscErrorCode SNESGetTolerances(SNES,PetscReal*,PetscReal*,PetscReal*,PetscInt*,PetscInt*);
213: EXTERN PetscErrorCode SNESSetTrustRegionTolerance(SNES,PetscReal);
214: EXTERN PetscErrorCode SNESGetIterationNumber(SNES,PetscInt*);
215: EXTERN PetscErrorCode SNESGetFunctionNorm(SNES,PetscScalar*);
216: EXTERN PetscErrorCode SNESGetNumberUnsuccessfulSteps(SNES,PetscInt*);
217: EXTERN PetscErrorCode SNESSetMaximumUnsuccessfulSteps(SNES,PetscInt);
218: EXTERN PetscErrorCode SNESGetMaximumUnsuccessfulSteps(SNES,PetscInt*);
219: EXTERN PetscErrorCode SNESGetNumberLinearIterations(SNES,PetscInt*);
220: EXTERN PetscErrorCode SNES_KSP_SetParametersEW(SNES,PetscInt,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal);
221: EXTERN PetscErrorCode SNES_KSP_SetConvergenceTestEW(SNES);
223: /*
224: Reuse the default KSP monitor routines for SNES
225: */
226: EXTERN PetscErrorCode SNESLGMonitorCreate(const char[],const char[],int,int,int,int,PetscDrawLG*);
227: EXTERN PetscErrorCode SNESLGMonitor(SNES,PetscInt,PetscReal,void*);
228: EXTERN PetscErrorCode SNESLGMonitorDestroy(PetscDrawLG);
230: EXTERN PetscErrorCode SNESSetApplicationContext(SNES,void *);
231: EXTERN PetscErrorCode SNESGetApplicationContext(SNES,void **);
233: /*E
234: SNESConvergedReason - reason a SNES method was said to
235: have converged or diverged
237: Level: beginner
239: Notes: this must match finclude/petscsnes.h
241: Developer note: The string versions of these are in
242: src/snes/interface/snes.c called convergedreasons.
243: If these enums are changed you much change those.
245: .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest()
246: E*/
247: typedef enum {/* converged */
248: SNES_CONVERGED_FNORM_ABS = 2, /* F < F_minabs */
249: SNES_CONVERGED_FNORM_RELATIVE = 3, /* F < F_mintol*F_initial */
250: SNES_CONVERGED_PNORM_RELATIVE = 4, /* step size small */
251: SNES_CONVERGED_TR_DELTA = 7,
252: /* diverged */
253: SNES_DIVERGED_FUNCTION_COUNT = -2,
254: SNES_DIVERGED_FNORM_NAN = -4,
255: SNES_DIVERGED_MAX_IT = -5,
256: SNES_DIVERGED_LS_FAILURE = -6,
257: SNES_DIVERGED_LOCAL_MIN = -8, /* || J^T b || is small, implies converged to local minimum of F() */
258: SNES_CONVERGED_ITERATING = 0} SNESConvergedReason;
260: /*MC
261: SNES_CONVERGED_FNORM_ABS - 2-norm(F) <= abstol
263: Level: beginner
265: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
267: M*/
269: /*MC
270: SNES_CONVERGED_FNORM_RELATIVE - 2-norm(F) <= rtol*2-norm(F(x_0)) where x_0 is the initial guess
272: Level: beginner
274: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
276: M*/
278: /*MC
279: SNES_CONVERGED_PNORM_RELATIVE - The 2-norm of the last step <= xtol * 2-norm(x) where x is the current
280: solution and xtol is the 4th argument to SNESSetTolerances()
282: Level: beginner
284: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
286: M*/
288: /*MC
289: SNES_DIVERGED_FUNCTION_COUNT - The user provided function has been called more times then the final
290: argument to SNESSetTolerances()
292: Level: beginner
294: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
296: M*/
298: /*MC
299: SNES_DIVERGED_FNORM_NAN - the 2-norm of the current function evaluation is not-a-number (NaN), this
300: is usually caused by a division of 0 by 0.
302: Level: beginner
304: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
306: M*/
308: /*MC
309: SNES_DIVERGED_MAX_IT - SNESSolve() has reached the maximum number of iterations requested
311: Level: beginner
313: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
315: M*/
317: /*MC
318: SNES_DIVERGED_LS_FAILURE - The line search has failed. This only occurs for a SNESType of SNESLS
320: Level: beginner
322: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
324: M*/
326: /*MC
327: SNES_DIVERGED_LOCAL_MIN - the algorithm seems to have stagnated at a local minimum that is not zero
329: Level: beginner
331: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
333: M*/
335: /*MC
336: SNES_CONERGED_ITERATING - this only occurs if SNESGetConvergedReason() is called during the SNESSolve()
338: Level: beginner
340: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
342: M*/
344: EXTERN PetscErrorCode SNESSetConvergenceTest(SNES,PetscErrorCode (*)(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*),void*);
345: EXTERN PetscErrorCode SNESConverged_LS(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
346: EXTERN PetscErrorCode SNESConverged_TR(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
347: EXTERN PetscErrorCode SNESGetConvergedReason(SNES,SNESConvergedReason*);
349: EXTERN PetscErrorCode SNESDAFormFunction(SNES,Vec,Vec,void*);
350: EXTERN PetscErrorCode SNESDAComputeJacobianWithAdic(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
351: EXTERN PetscErrorCode SNESDAComputeJacobianWithAdifor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
352: EXTERN PetscErrorCode SNESDAComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
354: /* --------- Solving systems of nonlinear equations --------------- */
355: EXTERN PetscErrorCode SNESSetFunction(SNES,Vec,PetscErrorCode(*)(SNES,Vec,Vec,void*),void *);
356: EXTERN PetscErrorCode SNESComputeFunction(SNES,Vec,Vec);
357: EXTERN PetscErrorCode SNESSetJacobian(SNES,Mat,Mat,PetscErrorCode(*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void *);
358: EXTERN PetscErrorCode SNESGetJacobian(SNES,Mat*,Mat*,void **,PetscErrorCode(**)(SNES,Vec,Mat*,Mat*,MatStructure*,void*));
359: EXTERN PetscErrorCode SNESDefaultComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
360: EXTERN PetscErrorCode SNESDefaultComputeJacobianColor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
361: EXTERN PetscErrorCode SNESSetRhs(SNES,Vec);
362: EXTERN PetscErrorCode SNESSetLineSearch(SNES,PetscErrorCode(*)(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*),void*);
363: EXTERN PetscErrorCode SNESNoLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
364: EXTERN PetscErrorCode SNESNoLineSearchNoNorms(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
365: EXTERN PetscErrorCode SNESCubicLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
366: EXTERN PetscErrorCode SNESQuadraticLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
368: EXTERN PetscErrorCode SNESSetLineSearchCheck(SNES,PetscErrorCode(*)(SNES,void*,Vec,PetscTruth*),void*);
369: EXTERN PetscErrorCode SNESSetLineSearchParams(SNES,PetscReal,PetscReal,PetscReal);
370: EXTERN PetscErrorCode SNESGetLineSearchParams(SNES,PetscReal*,PetscReal*,PetscReal*);
372: EXTERN PetscErrorCode SNESTestLocalMin(SNES snes);
374: /* Should this routine be private? */
375: EXTERN PetscErrorCode SNESComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*);
378: #endif