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 const char*
30: #define SNESLS "ls"
31: #define SNESTR "tr"
32: #define SNESTEST "test"
34: /* Logging support */
37: EXTERN PetscErrorCode SNESInitializePackage(const char[]);
39: EXTERN PetscErrorCode SNESCreate(MPI_Comm,SNES*);
40: EXTERN PetscErrorCode SNESDestroy(SNES);
41: EXTERN PetscErrorCode SNESSetType(SNES,SNESType);
42: EXTERN PetscErrorCode SNESMonitorSet(SNES,PetscErrorCode(*)(SNES,PetscInt,PetscReal,void*),void *,PetscErrorCode (*)(void*));
43: EXTERN PetscErrorCode SNESMonitorCancel(SNES);
44: EXTERN PetscErrorCode SNESSetConvergenceHistory(SNES,PetscReal[],PetscInt[],PetscInt,PetscTruth);
45: EXTERN PetscErrorCode SNESGetConvergenceHistory(SNES,PetscReal*[],PetscInt *[],PetscInt *);
46: EXTERN PetscErrorCode SNESSetUp(SNES);
47: EXTERN PetscErrorCode SNESSolve(SNES,Vec,Vec);
49: EXTERN PetscErrorCode SNESAddOptionsChecker(PetscErrorCode (*)(SNES));
51: EXTERN PetscErrorCode SNESSetUpdate(SNES, PetscErrorCode (*)(SNES, PetscInt));
52: EXTERN PetscErrorCode SNESDefaultUpdate(SNES, PetscInt);
55: EXTERN PetscErrorCode SNESRegisterDestroy(void);
56: EXTERN PetscErrorCode SNESRegisterAll(const char[]);
58: EXTERN PetscErrorCode SNESRegister(const char[],const char[],const char[],PetscErrorCode (*)(SNES));
60: /*MC
61: SNESRegisterDynamic - Adds a method to the nonlinear solver package.
63: Synopsis:
64: PetscErrorCode SNESRegisterDynamic(char *name_solver,char *path,char *name_create,PetscErrorCode (*routine_create)(SNES))
66: Not collective
68: Input Parameters:
69: + name_solver - name of a new user-defined solver
70: . path - path (either absolute or relative) the library containing this solver
71: . name_create - name of routine to create method context
72: - routine_create - routine to create method context
74: Notes:
75: SNESRegisterDynamic() may be called multiple times to add several user-defined solvers.
77: If dynamic libraries are used, then the fourth input argument (routine_create)
78: is ignored.
80: Environmental variables such as ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR},
81: and others of the form ${any_environmental_variable} occuring in pathname will be
82: replaced with appropriate values.
84: Sample usage:
85: .vb
86: SNESRegisterDynamic("my_solver",/home/username/my_lib/lib/libg/solaris/mylib.a,
87: "MySolverCreate",MySolverCreate);
88: .ve
90: Then, your solver can be chosen with the procedural interface via
91: $ SNESSetType(snes,"my_solver")
92: or at runtime via the option
93: $ -snes_type my_solver
95: Level: advanced
97: Note: If your function is not being put into a shared library then use SNESRegister() instead
99: .keywords: SNES, nonlinear, register
101: .seealso: SNESRegisterAll(), SNESRegisterDestroy()
102: M*/
103: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
104: #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,0)
105: #else
106: #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,d)
107: #endif
109: EXTERN PetscErrorCode SNESGetKSP(SNES,KSP*);
110: EXTERN PetscErrorCode SNESSetKSP(SNES,KSP);
111: EXTERN PetscErrorCode SNESGetSolution(SNES,Vec*);
112: EXTERN PetscErrorCode SNESGetSolutionUpdate(SNES,Vec*);
113: EXTERN PetscErrorCode SNESGetFunction(SNES,Vec*,PetscErrorCode(**)(SNES,Vec,Vec,void*),void**);
114: EXTERN PetscErrorCode SNESView(SNES,PetscViewer);
116: EXTERN PetscErrorCode SNESSetOptionsPrefix(SNES,const char[]);
117: EXTERN PetscErrorCode SNESAppendOptionsPrefix(SNES,const char[]);
118: EXTERN PetscErrorCode SNESGetOptionsPrefix(SNES,const char*[]);
119: EXTERN PetscErrorCode SNESSetFromOptions(SNES);
121: EXTERN PetscErrorCode MatCreateSNESMF(SNES,Mat*);
122: EXTERN PetscErrorCode MatMFFDComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
124: EXTERN PetscErrorCode MatDAADSetSNES(Mat,SNES);
126: EXTERN PetscErrorCode SNESGetType(SNES,SNESType*);
127: EXTERN PetscErrorCode SNESMonitorDefault(SNES,PetscInt,PetscReal,void *);
128: EXTERN PetscErrorCode SNESMonitorRatio(SNES,PetscInt,PetscReal,void *);
129: EXTERN PetscErrorCode SNESMonitorSetRatio(SNES,PetscViewerASCIIMonitor);
130: EXTERN PetscErrorCode SNESMonitorSolution(SNES,PetscInt,PetscReal,void *);
131: EXTERN PetscErrorCode SNESMonitorResidual(SNES,PetscInt,PetscReal,void *);
132: EXTERN PetscErrorCode SNESMonitorSolutionUpdate(SNES,PetscInt,PetscReal,void *);
133: EXTERN PetscErrorCode SNESMonitorDefaultShort(SNES,PetscInt,PetscReal,void *);
134: EXTERN PetscErrorCode SNESSetTolerances(SNES,PetscReal,PetscReal,PetscReal,PetscInt,PetscInt);
135: EXTERN PetscErrorCode SNESGetTolerances(SNES,PetscReal*,PetscReal*,PetscReal*,PetscInt*,PetscInt*);
136: EXTERN PetscErrorCode SNESSetTrustRegionTolerance(SNES,PetscReal);
137: EXTERN PetscErrorCode SNESGetFunctionNorm(SNES,PetscReal*);
138: EXTERN PetscErrorCode SNESGetIterationNumber(SNES,PetscInt*);
140: EXTERN PetscErrorCode SNESGetNonlinearStepFailures(SNES,PetscInt*);
141: EXTERN PetscErrorCode SNESSetMaxNonlinearStepFailures(SNES,PetscInt);
142: EXTERN PetscErrorCode SNESGetMaxNonlinearStepFailures(SNES,PetscInt*);
144: EXTERN PetscErrorCode SNESGetLinearSolveIterations(SNES,PetscInt*);
145: EXTERN PetscErrorCode SNESGetLinearSolveFailures(SNES,PetscInt*);
146: EXTERN PetscErrorCode SNESSetMaxLinearSolveFailures(SNES,PetscInt);
147: EXTERN PetscErrorCode SNESGetMaxLinearSolveFailures(SNES,PetscInt*);
149: EXTERN PetscErrorCode SNESKSPSetUseEW(SNES,PetscTruth);
150: EXTERN PetscErrorCode SNESKSPGetUseEW(SNES,PetscTruth*);
151: EXTERN PetscErrorCode SNESKSPSetParametersEW(SNES,PetscInt,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal);
152: EXTERN PetscErrorCode SNESKSPGetParametersEW(SNES,PetscInt*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*);
154: /*
155: Reuse the default KSP monitor routines for SNES
156: */
157: EXTERN PetscErrorCode SNESMonitorLGCreate(const char[],const char[],int,int,int,int,PetscDrawLG*);
158: EXTERN PetscErrorCode SNESMonitorLG(SNES,PetscInt,PetscReal,void*);
159: EXTERN PetscErrorCode SNESMonitorLGDestroy(PetscDrawLG);
161: EXTERN PetscErrorCode SNESSetApplicationContext(SNES,void *);
162: EXTERN PetscErrorCode SNESGetApplicationContext(SNES,void **);
164: /*E
165: SNESConvergedReason - reason a SNES method was said to
166: have converged or diverged
168: Level: beginner
170: Notes: this must match finclude/petscsnes.h
172: Developer note: The string versions of these are in
173: src/snes/interface/snes.c called convergedreasons.
174: If these enums are changed you much change those.
176: .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest()
177: E*/
178: typedef enum {/* converged */
179: SNES_CONVERGED_FNORM_ABS = 2, /* F < F_minabs */
180: SNES_CONVERGED_FNORM_RELATIVE = 3, /* F < F_mintol*F_initial */
181: SNES_CONVERGED_PNORM_RELATIVE = 4, /* step size small */
182: SNES_CONVERGED_ITS = 5, /* maximum iterations reached */
183: SNES_CONVERGED_TR_DELTA = 7,
184: /* diverged */
185: SNES_DIVERGED_FUNCTION_DOMAIN = -1,
186: SNES_DIVERGED_FUNCTION_COUNT = -2,
187: SNES_DIVERGED_LINEAR_SOLVE = -3,
188: SNES_DIVERGED_FNORM_NAN = -4,
189: SNES_DIVERGED_MAX_IT = -5,
190: SNES_DIVERGED_LS_FAILURE = -6,
191: SNES_DIVERGED_LOCAL_MIN = -8, /* || J^T b || is small, implies converged to local minimum of F() */
192: SNES_CONVERGED_ITERATING = 0} SNESConvergedReason;
195: /*MC
196: SNES_CONVERGED_FNORM_ABS - 2-norm(F) <= abstol
198: Level: beginner
200: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
202: M*/
204: /*MC
205: SNES_CONVERGED_FNORM_RELATIVE - 2-norm(F) <= rtol*2-norm(F(x_0)) where x_0 is the initial guess
207: Level: beginner
209: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
211: M*/
213: /*MC
214: SNES_CONVERGED_PNORM_RELATIVE - The 2-norm of the last step <= xtol * 2-norm(x) where x is the current
215: solution and xtol is the 4th argument to SNESSetTolerances()
217: Level: beginner
219: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
221: M*/
223: /*MC
224: SNES_DIVERGED_FUNCTION_COUNT - The user provided function has been called more times then the final
225: argument to SNESSetTolerances()
227: Level: beginner
229: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
231: M*/
233: /*MC
234: SNES_DIVERGED_FNORM_NAN - the 2-norm of the current function evaluation is not-a-number (NaN), this
235: is usually caused by a division of 0 by 0.
237: Level: beginner
239: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
241: M*/
243: /*MC
244: SNES_DIVERGED_MAX_IT - SNESSolve() has reached the maximum number of iterations requested
246: Level: beginner
248: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
250: M*/
252: /*MC
253: SNES_DIVERGED_LS_FAILURE - The line search has failed. This only occurs for a SNESType of SNESLS
255: Level: beginner
257: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
259: M*/
261: /*MC
262: SNES_DIVERGED_LOCAL_MIN - the algorithm seems to have stagnated at a local minimum that is not zero
264: Level: beginner
266: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
268: M*/
270: /*MC
271: SNES_CONERGED_ITERATING - this only occurs if SNESGetConvergedReason() is called during the SNESSolve()
273: Level: beginner
275: .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
277: M*/
279: EXTERN PetscErrorCode SNESSetConvergenceTest(SNES,PetscErrorCode (*)(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*),void*);
280: EXTERN PetscErrorCode SNESDefaultConverged(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
281: EXTERN PetscErrorCode SNESSkipConverged(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
282: EXTERN PetscErrorCode SNESConverged_LS(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
283: EXTERN PetscErrorCode SNESConverged_TR(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
284: EXTERN PetscErrorCode SNESGetConvergedReason(SNES,SNESConvergedReason*);
286: EXTERN PetscErrorCode SNESDAFormFunction(SNES,Vec,Vec,void*);
287: EXTERN PetscErrorCode SNESDAComputeJacobianWithAdic(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
288: EXTERN PetscErrorCode SNESDAComputeJacobianWithAdifor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
289: EXTERN PetscErrorCode SNESDAComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
291: /* --------- Solving systems of nonlinear equations --------------- */
292: EXTERN PetscErrorCode SNESSetFunction(SNES,Vec,PetscErrorCode(*)(SNES,Vec,Vec,void*),void *);
293: EXTERN PetscErrorCode SNESComputeFunction(SNES,Vec,Vec);
294: EXTERN PetscErrorCode SNESSetJacobian(SNES,Mat,Mat,PetscErrorCode(*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void *);
295: EXTERN PetscErrorCode SNESGetJacobian(SNES,Mat*,Mat*,PetscErrorCode(**)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void **);
296: EXTERN PetscErrorCode SNESDefaultComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
297: EXTERN PetscErrorCode SNESDefaultComputeJacobianColor(SNES,Vec,Mat*,Mat*,MatStructure*,void*);
298: EXTERN PetscErrorCode SNESSetRhs(SNES,Vec);
299: EXTERN PetscErrorCode SNESGetRhs(SNES,Vec*);
301: /* --------- Routines specifically for line search methods --------------- */
302: EXTERN PetscErrorCode SNESLineSearchSet(SNES,PetscErrorCode(*)(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*),void*);
303: EXTERN PetscErrorCode SNESLineSearchNo(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
304: EXTERN PetscErrorCode SNESLineSearchNoNorms(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
305: EXTERN PetscErrorCode SNESLineSearchCubic(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
306: EXTERN PetscErrorCode SNESLineSearchQuadratic(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*);
308: EXTERN PetscErrorCode SNESLineSearchSetPostCheck(SNES,PetscErrorCode(*)(SNES,Vec,Vec,Vec,void*,PetscTruth*,PetscTruth*),void*);
309: EXTERN PetscErrorCode SNESLineSearchSetPreCheck(SNES,PetscErrorCode(*)(SNES,Vec,Vec,void*,PetscTruth*),void*);
310: EXTERN PetscErrorCode SNESLineSearchSetParams(SNES,PetscReal,PetscReal,PetscReal);
311: EXTERN PetscErrorCode SNESLineSearchGetParams(SNES,PetscReal*,PetscReal*,PetscReal*);
313: EXTERN PetscErrorCode SNESTestLocalMin(SNES);
314: EXTERN PetscErrorCode SNESSetSolution(SNES,Vec);
316: /* Should this routine be private? */
317: EXTERN PetscErrorCode SNESComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*);
320: #endif