xref: /petsc/include/petscsnes.h (revision 609bdbee21ea3be08735c64dbe00a9ab27759925) 
1 /*
2     User interface for the nonlinear solvers package.
3 */
4 #if !defined(__PETSCSNES_H)
5 #define __PETSCSNES_H
6 #include <petscksp.h>
7 #include <petscdmtypes.h>
8 #include <petscfvtypes.h>
9 #include <petscdmdatypes.h>
10 
11 /*S
12      SNES - Abstract PETSc object that manages all nonlinear solves
13 
14    Level: beginner
15 
16   Concepts: nonlinear solvers
17 
18 .seealso:  SNESCreate(), SNESSetType(), SNESType, TS, KSP, KSP, PC, SNESDestroy()
19 S*/
20 typedef struct _p_SNES* SNES;
21 
22 /*J
23     SNESType - String with the name of a PETSc SNES method.
24 
25    Level: beginner
26 
27 .seealso: SNESSetType(), SNES, SNESCreate(), SNESDestroy(), SNESSetFromOptions()
28 J*/
29 typedef const char* SNESType;
30 #define SNESNEWTONLS     "newtonls"
31 #define SNESNEWTONTR     "newtontr"
32 #define SNESPYTHON       "python"
33 #define SNESTEST         "test"
34 #define SNESNRICHARDSON  "nrichardson"
35 #define SNESKSPONLY      "ksponly"
36 #define SNESVINEWTONRSLS "vinewtonrsls"
37 #define SNESVINEWTONSSLS "vinewtonssls"
38 #define SNESNGMRES       "ngmres"
39 #define SNESQN           "qn"
40 #define SNESSHELL        "shell"
41 #define SNESNGS          "ngs"
42 #define SNESNCG          "ncg"
43 #define SNESFAS          "fas"
44 #define SNESMS           "ms"
45 #define SNESNASM         "nasm"
46 #define SNESANDERSON     "anderson"
47 #define SNESASPIN        "aspin"
48 #define SNESCOMPOSITE    "composite"
49 
50 /* Logging support */
51 PETSC_EXTERN PetscClassId SNES_CLASSID;
52 PETSC_EXTERN PetscClassId DMSNES_CLASSID;
53 
54 PETSC_EXTERN PetscErrorCode SNESInitializePackage(void);
55 
56 PETSC_EXTERN PetscErrorCode SNESCreate(MPI_Comm,SNES*);
57 PETSC_EXTERN PetscErrorCode SNESReset(SNES);
58 PETSC_EXTERN PetscErrorCode SNESDestroy(SNES*);
59 PETSC_EXTERN PetscErrorCode SNESSetType(SNES,SNESType);
60 PETSC_EXTERN PetscErrorCode SNESMonitor(SNES,PetscInt,PetscReal);
61 PETSC_EXTERN PetscErrorCode SNESMonitorSet(SNES,PetscErrorCode(*)(SNES,PetscInt,PetscReal,void*),void *,PetscErrorCode (*)(void**));
62 PETSC_EXTERN PetscErrorCode SNESMonitorSetFromOptions(SNES,const char[],const char[],const char [],PetscErrorCode (*)(SNES,PetscInt,PetscReal,PetscViewerAndFormat*),PetscErrorCode (*)(SNES,PetscViewerAndFormat*));
63 PETSC_EXTERN PetscErrorCode SNESMonitorCancel(SNES);
64 PETSC_EXTERN PetscErrorCode SNESMonitorSAWs(SNES,PetscInt,PetscReal,void*);
65 PETSC_EXTERN PetscErrorCode SNESMonitorSAWsCreate(SNES,void**);
66 PETSC_EXTERN PetscErrorCode SNESMonitorSAWsDestroy(void**);
67 PETSC_EXTERN PetscErrorCode SNESSetConvergenceHistory(SNES,PetscReal[],PetscInt[],PetscInt,PetscBool );
68 PETSC_EXTERN PetscErrorCode SNESGetConvergenceHistory(SNES,PetscReal*[],PetscInt *[],PetscInt *);
69 PETSC_EXTERN PetscErrorCode SNESSetUp(SNES);
70 PETSC_EXTERN PetscErrorCode SNESSolve(SNES,Vec,Vec);
71 PETSC_EXTERN PetscErrorCode SNESSetErrorIfNotConverged(SNES,PetscBool );
72 PETSC_EXTERN PetscErrorCode SNESGetErrorIfNotConverged(SNES,PetscBool  *);
73 
74 PETSC_EXTERN PetscErrorCode SNESSetWorkVecs(SNES,PetscInt);
75 
76 PETSC_EXTERN PetscErrorCode SNESAddOptionsChecker(PetscErrorCode (*)(SNES));
77 
78 PETSC_EXTERN PetscErrorCode SNESSetUpdate(SNES, PetscErrorCode (*)(SNES, PetscInt));
79 
80 
81 PETSC_EXTERN PetscErrorCode SNESRegister(const char[],PetscErrorCode (*)(SNES));
82 
83 PETSC_EXTERN PetscErrorCode SNESGetKSP(SNES,KSP*);
84 PETSC_EXTERN PetscErrorCode SNESSetKSP(SNES,KSP);
85 PETSC_EXTERN PetscErrorCode SNESSetSolution(SNES,Vec);
86 PETSC_EXTERN PetscErrorCode SNESGetSolution(SNES,Vec*);
87 PETSC_EXTERN PetscErrorCode SNESGetSolutionUpdate(SNES,Vec*);
88 PETSC_EXTERN PetscErrorCode SNESGetRhs(SNES,Vec*);
89 PETSC_EXTERN PetscErrorCode SNESView(SNES,PetscViewer);
90 PETSC_EXTERN PetscErrorCode SNESLoad(SNES,PetscViewer);
91 PETSC_STATIC_INLINE PetscErrorCode SNESViewFromOptions(SNES A,PetscObject obj,const char name[]) {return PetscObjectViewFromOptions((PetscObject)A,obj,name);}
92 PETSC_EXTERN PetscErrorCode SNESReasonView(SNES,PetscViewer);
93 PETSC_EXTERN PetscErrorCode SNESReasonViewFromOptions(SNES);
94 
95 #define SNES_FILE_CLASSID 1211224
96 
97 PETSC_EXTERN PetscErrorCode SNESSetOptionsPrefix(SNES,const char[]);
98 PETSC_EXTERN PetscErrorCode SNESAppendOptionsPrefix(SNES,const char[]);
99 PETSC_EXTERN PetscErrorCode SNESGetOptionsPrefix(SNES,const char*[]);
100 PETSC_EXTERN PetscErrorCode SNESSetFromOptions(SNES);
101 
102 PETSC_EXTERN PetscErrorCode MatCreateSNESMF(SNES,Mat*);
103 PETSC_EXTERN PetscErrorCode MatMFFDComputeJacobian(SNES,Vec,Mat,Mat,void*);
104 
105 PETSC_EXTERN PetscErrorCode MatDAADSetSNES(Mat,SNES);
106 
107 PETSC_EXTERN PetscErrorCode SNESGetType(SNES,SNESType*);
108 PETSC_EXTERN PetscErrorCode SNESMonitorDefault(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
109 PETSC_EXTERN PetscErrorCode SNESMonitorRange(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
110 PETSC_EXTERN PetscErrorCode SNESMonitorRatio(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
111 PETSC_EXTERN PetscErrorCode SNESMonitorRatioSetUp(SNES,PetscViewerAndFormat*);
112 PETSC_EXTERN PetscErrorCode SNESMonitorSolution(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
113 PETSC_EXTERN PetscErrorCode SNESMonitorResidual(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
114 PETSC_EXTERN PetscErrorCode SNESMonitorSolutionUpdate(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
115 PETSC_EXTERN PetscErrorCode SNESMonitorDefaultShort(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
116 PETSC_EXTERN PetscErrorCode SNESMonitorDefaultField(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
117 PETSC_EXTERN PetscErrorCode SNESMonitorJacUpdateSpectrum(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
118 PETSC_EXTERN PetscErrorCode SNESMonitorFields(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
119 PETSC_EXTERN PetscErrorCode KSPMonitorSNES(KSP,PetscInt,PetscReal,void*);
120 PETSC_EXTERN PetscErrorCode KSPMonitorSNESLGResidualNormCreate(MPI_Comm,const char[],const char[],int,int,int,int,PetscObject**);
121 PETSC_EXTERN PetscErrorCode KSPMonitorSNESLGResidualNorm(KSP,PetscInt,PetscReal,PetscObject*);
122 PETSC_EXTERN PetscErrorCode KSPMonitorSNESLGResidualNormDestroy(PetscObject**);
123 
124 PETSC_EXTERN PetscErrorCode SNESSetTolerances(SNES,PetscReal,PetscReal,PetscReal,PetscInt,PetscInt);
125 PETSC_EXTERN PetscErrorCode SNESSetDivergenceTolerance(SNES,PetscReal);
126 PETSC_EXTERN PetscErrorCode SNESGetTolerances(SNES,PetscReal*,PetscReal*,PetscReal*,PetscInt*,PetscInt*);
127 PETSC_EXTERN PetscErrorCode SNESGetDivergenceTolerance(SNES,PetscReal*);
128 PETSC_EXTERN PetscErrorCode SNESSetTrustRegionTolerance(SNES,PetscReal);
129 PETSC_EXTERN PetscErrorCode SNESGetIterationNumber(SNES,PetscInt*);
130 PETSC_EXTERN PetscErrorCode SNESSetIterationNumber(SNES,PetscInt);
131 
132 PETSC_EXTERN PetscErrorCode SNESGetNonlinearStepFailures(SNES,PetscInt*);
133 PETSC_EXTERN PetscErrorCode SNESSetMaxNonlinearStepFailures(SNES,PetscInt);
134 PETSC_EXTERN PetscErrorCode SNESGetMaxNonlinearStepFailures(SNES,PetscInt*);
135 PETSC_EXTERN PetscErrorCode SNESGetNumberFunctionEvals(SNES,PetscInt*);
136 
137 PETSC_EXTERN PetscErrorCode SNESSetLagPreconditioner(SNES,PetscInt);
138 PETSC_EXTERN PetscErrorCode SNESGetLagPreconditioner(SNES,PetscInt*);
139 PETSC_EXTERN PetscErrorCode SNESSetLagJacobian(SNES,PetscInt);
140 PETSC_EXTERN PetscErrorCode SNESGetLagJacobian(SNES,PetscInt*);
141 PETSC_EXTERN PetscErrorCode SNESSetLagPreconditionerPersists(SNES,PetscBool);
142 PETSC_EXTERN PetscErrorCode SNESSetLagJacobianPersists(SNES,PetscBool);
143 PETSC_EXTERN PetscErrorCode SNESSetGridSequence(SNES,PetscInt);
144 PETSC_EXTERN PetscErrorCode SNESGetGridSequence(SNES,PetscInt*);
145 
146 PETSC_EXTERN PetscErrorCode SNESGetLinearSolveIterations(SNES,PetscInt*);
147 PETSC_EXTERN PetscErrorCode SNESGetLinearSolveFailures(SNES,PetscInt*);
148 PETSC_EXTERN PetscErrorCode SNESSetMaxLinearSolveFailures(SNES,PetscInt);
149 PETSC_EXTERN PetscErrorCode SNESGetMaxLinearSolveFailures(SNES,PetscInt*);
150 PETSC_EXTERN PetscErrorCode SNESSetCountersReset(SNES,PetscBool);
151 
152 PETSC_EXTERN PetscErrorCode SNESKSPSetUseEW(SNES,PetscBool );
153 PETSC_EXTERN PetscErrorCode SNESKSPGetUseEW(SNES,PetscBool *);
154 PETSC_EXTERN PetscErrorCode SNESKSPSetParametersEW(SNES,PetscInt,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal);
155 PETSC_EXTERN PetscErrorCode SNESKSPGetParametersEW(SNES,PetscInt*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*);
156 
157 #include <petscdrawtypes.h>
158 PETSC_EXTERN PetscErrorCode SNESMonitorLGCreate(MPI_Comm,const char[],const char[],int,int,int,int,PetscDrawLG*);
159 PETSC_EXTERN PetscErrorCode SNESMonitorLGResidualNorm(SNES,PetscInt,PetscReal,void*);
160 PETSC_EXTERN PetscErrorCode SNESMonitorLGRange(SNES,PetscInt,PetscReal,void*);
161 
162 PETSC_EXTERN PetscErrorCode SNESSetApplicationContext(SNES,void *);
163 PETSC_EXTERN PetscErrorCode SNESGetApplicationContext(SNES,void *);
164 PETSC_EXTERN PetscErrorCode SNESSetComputeApplicationContext(SNES,PetscErrorCode (*)(SNES,void**),PetscErrorCode (*)(void**));
165 
166 PETSC_EXTERN PetscErrorCode SNESPythonSetType(SNES,const char[]);
167 
168 PETSC_EXTERN PetscErrorCode SNESSetFunctionDomainError(SNES);
169 PETSC_EXTERN PetscErrorCode SNESGetFunctionDomainError(SNES, PetscBool *);
170 
171 /*E
172     SNESConvergedReason - reason a SNES method was said to
173          have converged or diverged
174 
175    Level: beginner
176 
177    The two most common reasons for divergence are
178 $   1) an incorrectly coded or computed Jacobian or
179 $   2) failure or lack of convergence in the linear system (in this case we recommend
180 $      testing with -pc_type lu to eliminate the linear solver as the cause of the problem).
181 
182    Diverged Reasons:
183 .    SNES_DIVERGED_LOCAL_MIN - this can only occur when using the line-search variant of SNES.
184        The line search wants to minimize Q(alpha) = 1/2 || F(x + alpha s) ||^2_2  this occurs
185        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
186        you get Q'(alpha) = -F(x)^T F'(x)^(-1)^T F'(x+alpha s)F(x+alpha s); when alpha = 0
187        Q'(0) = - ||F(x)||^2_2 which is always NEGATIVE if F'(x) is invertible. This means the Newton
188        direction is a descent direction and the line search should succeed if alpha is small enough.
189 
190        If F'(x) is NOT invertible AND F'(x)^T F(x) = 0 then Q'(0) = 0 and the Newton direction
191        is NOT a descent direction so the line search will fail. All one can do at this point
192        is change the initial guess and try again.
193 
194        An alternative explanation: Newton's method can be regarded as replacing the function with
195        its linear approximation and minimizing the 2-norm of that. That is F(x+s) approx F(x) + F'(x)s
196        so we minimize || F(x) + F'(x) s ||^2_2; do this using Least Squares. If F'(x) is invertible then
197        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
198        exists a nontrival (that is F'(x)s != 0) solution to the equation and this direction is
199        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)
200        = - (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
201        and F'(x)^T F'(x) has no negative eigenvalues Q'(0) < 0 so s is a descent direction and the line
202        search should succeed for small enough alpha.
203 
204        Note that this RARELY happens in practice. Far more likely the linear system is not being solved
205        (well enough?) or the Jacobian is wrong.
206 
207    SNES_DIVERGED_MAX_IT means that the solver reached the maximum number of iterations without satisfying any
208    convergence criteria. SNES_CONVERGED_ITS means that SNESConvergedSkip() was chosen as the convergence test;
209    thus the usual convergence criteria have not been checked and may or may not be satisfied.
210 
211    Developer Notes: this must match petsc/finclude/petscsnes.h
212 
213        The string versions of these are in SNESConvergedReasons, if you change any value here you must
214      also adjust that array.
215 
216    Each reason has its own manual page.
217 
218 .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest()
219 E*/
220 typedef enum {/* converged */
221               SNES_CONVERGED_FNORM_ABS         =  2, /* ||F|| < atol */
222               SNES_CONVERGED_FNORM_RELATIVE    =  3, /* ||F|| < rtol*||F_initial|| */
223               SNES_CONVERGED_SNORM_RELATIVE    =  4, /* Newton computed step size small; || delta x || < stol || x ||*/
224               SNES_CONVERGED_ITS               =  5, /* maximum iterations reached */
225               SNES_CONVERGED_TR_DELTA          =  7,
226               /* diverged */
227               SNES_DIVERGED_FUNCTION_DOMAIN     = -1, /* the new x location passed the function is not in the domain of F */
228               SNES_DIVERGED_FUNCTION_COUNT      = -2,
229               SNES_DIVERGED_LINEAR_SOLVE        = -3, /* the linear solve failed */
230               SNES_DIVERGED_FNORM_NAN           = -4,
231               SNES_DIVERGED_MAX_IT              = -5,
232               SNES_DIVERGED_LINE_SEARCH         = -6, /* the line search failed */
233               SNES_DIVERGED_INNER               = -7, /* inner solve failed */
234               SNES_DIVERGED_LOCAL_MIN           = -8, /* || J^T b || is small, implies converged to local minimum of F() */
235               SNES_DIVERGED_DTOL                = -9, /* || F || > divtol*||F_initial|| */
236 
237               SNES_CONVERGED_ITERATING          =  0} SNESConvergedReason;
238 PETSC_EXTERN const char *const*SNESConvergedReasons;
239 
240 /*MC
241      SNES_CONVERGED_FNORM_ABS - 2-norm(F) <= abstol
242 
243    Level: beginner
244 
245 .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
246 
247 M*/
248 
249 /*MC
250      SNES_CONVERGED_FNORM_RELATIVE - 2-norm(F) <= rtol*2-norm(F(x_0)) where x_0 is the initial guess
251 
252    Level: beginner
253 
254 .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
255 
256 M*/
257 
258 /*MC
259      SNES_CONVERGED_SNORM_RELATIVE - The 2-norm of the last step <= stol * 2-norm(x) where x is the current
260           solution and stol is the 4th argument to SNESSetTolerances()
261 
262      Options Database Keys:
263       -snes_stol <stol> - the step tolerance
264 
265    Level: beginner
266 
267 .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
268 
269 M*/
270 
271 /*MC
272      SNES_DIVERGED_FUNCTION_COUNT - The user provided function has been called more times then the final
273          argument to SNESSetTolerances()
274 
275    Level: beginner
276 
277 .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
278 
279 M*/
280 
281 /*MC
282      SNES_DIVERGED_DTOL - The norm of the function has increased by a factor of divtol set with SNESSetDivergenceTolerance()
283 
284    Level: beginner
285 
286 .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances(), SNESSetDivergenceTolerance()
287 
288 M*/
289 
290 /*MC
291      SNES_DIVERGED_FNORM_NAN - the 2-norm of the current function evaluation is not-a-number (NaN), this
292       is usually caused by a division of 0 by 0.
293 
294    Level: beginner
295 
296 .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
297 
298 M*/
299 
300 /*MC
301      SNES_DIVERGED_MAX_IT - SNESSolve() has reached the maximum number of iterations requested
302 
303    Level: beginner
304 
305 .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
306 
307 M*/
308 
309 /*MC
310      SNES_DIVERGED_LINE_SEARCH - The line search has failed. This only occurs for a SNES solvers that use a line search
311 
312    Level: beginner
313 
314 .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances(), SNESLineSearch
315 
316 M*/
317 
318 /*MC
319      SNES_DIVERGED_LOCAL_MIN - the algorithm seems to have stagnated at a local minimum that is not zero.
320         See the manual page for SNESConvergedReason for more details
321 
322    Level: beginner
323 
324 .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
325 
326 M*/
327 
328 /*MC
329      SNES_CONERGED_ITERATING - this only occurs if SNESGetConvergedReason() is called during the SNESSolve()
330 
331    Level: beginner
332 
333 .seealso:  SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances()
334 
335 M*/
336 
337 PETSC_EXTERN PetscErrorCode SNESSetConvergenceTest(SNES,PetscErrorCode (*)(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*),void*,PetscErrorCode (*)(void*));
338 PETSC_EXTERN PetscErrorCode SNESConvergedDefault(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
339 PETSC_EXTERN PetscErrorCode SNESConvergedSkip(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*);
340 PETSC_EXTERN PetscErrorCode SNESGetConvergedReason(SNES,SNESConvergedReason*);
341 PETSC_EXTERN PetscErrorCode SNESSetConvergedReason(SNES,SNESConvergedReason);
342 
343 PETSC_DEPRECATED("Use SNESConvergedSkip()") PETSC_STATIC_INLINE void SNESSkipConverged(void) { /* never called */ }
344 #define SNESSkipConverged (SNESSkipConverged, SNESConvergedSkip)
345 
346 /* --------- Solving systems of nonlinear equations --------------- */
347 PETSC_EXTERN PetscErrorCode SNESSetFunction(SNES,Vec,PetscErrorCode (*)(SNES,Vec,Vec,void*),void*);
348 PETSC_EXTERN PetscErrorCode SNESGetFunction(SNES,Vec*,PetscErrorCode (**)(SNES,Vec,Vec,void*),void**);
349 PETSC_EXTERN PetscErrorCode SNESComputeFunction(SNES,Vec,Vec);
350 
351 PETSC_EXTERN PetscErrorCode SNESSetJacobian(SNES,Mat,Mat,PetscErrorCode (*)(SNES,Vec,Mat,Mat,void*),void*);
352 PETSC_EXTERN PetscErrorCode SNESGetJacobian(SNES,Mat*,Mat*,PetscErrorCode (**)(SNES,Vec,Mat,Mat,void*),void**);
353 PETSC_EXTERN PetscErrorCode SNESObjectiveComputeFunctionDefaultFD(SNES,Vec,Vec,void*);
354 PETSC_EXTERN PetscErrorCode SNESComputeJacobianDefault(SNES,Vec,Mat,Mat,void*);
355 PETSC_EXTERN PetscErrorCode SNESComputeJacobianDefaultColor(SNES,Vec,Mat,Mat,void*);
356 PETSC_EXTERN PetscErrorCode SNESSetComputeInitialGuess(SNES,PetscErrorCode (*)(SNES,Vec,void*),void*);
357 PETSC_EXTERN PetscErrorCode SNESSetPicard(SNES,Vec,PetscErrorCode (*)(SNES,Vec,Vec,void*),Mat,Mat,PetscErrorCode (*)(SNES,Vec,Mat,Mat,void*),void*);
358 PETSC_EXTERN PetscErrorCode SNESGetPicard(SNES,Vec*,PetscErrorCode (**)(SNES,Vec,Vec,void*),Mat*,Mat*,PetscErrorCode (**)(SNES,Vec,Mat,Mat,void*),void**);
359 PETSC_EXTERN PetscErrorCode SNESSetInitialFunction(SNES,Vec);
360 
361 PETSC_EXTERN PetscErrorCode SNESSetObjective(SNES,PetscErrorCode (*)(SNES,Vec,PetscReal *,void*),void*);
362 PETSC_EXTERN PetscErrorCode SNESGetObjective(SNES,PetscErrorCode (**)(SNES,Vec,PetscReal *,void*),void**);
363 PETSC_EXTERN PetscErrorCode SNESComputeObjective(SNES,Vec,PetscReal *);
364 
365 /*E
366     SNESNormSchedule - Frequency with which the norm is computed
367 
368    Level: advanced
369 
370    Support for these is highly dependent on the solver.
371 
372    Notes:
373    This is primarily used to turn off extra norm and function computation
374    when the solvers are composed.
375 
376 .seealso: SNESSolve(), SNESGetConvergedReason(), KSPSetNormType(),
377           KSPSetConvergenceTest(), KSPSetPCSide()
378 E*/
379 
380 typedef enum {SNES_NORM_DEFAULT            = -1,
381               SNES_NORM_NONE               =  0,
382               SNES_NORM_ALWAYS             =  1,
383               SNES_NORM_INITIAL_ONLY       =  2,
384               SNES_NORM_FINAL_ONLY         =  3,
385               SNES_NORM_INITIAL_FINAL_ONLY =  4} SNESNormSchedule;
386 PETSC_EXTERN const char *const*const SNESNormSchedules;
387 
388 /*MC
389     SNES_NORM_NONE - Don't compute function and its L2 norm.
390 
391    Level: advanced
392 
393     Notes:
394     This is most useful for stationary solvers with a fixed number of iterations used as smoothers.
395 
396 .seealso: SNESNormSchedule, SNESSetNormSchedule(), SNES_NORM_DEFAULT
397 M*/
398 
399 /*MC
400     SNES_NORM_ALWAYS - Compute the function and its L2 norm at each iteration.
401 
402    Level: advanced
403 
404     Notes:
405     Most solvers will use this no matter what norm type is passed to them.
406 
407 .seealso: SNESNormSchedule, SNESSetNormSchedule(), SNES_NORM_NONE
408 M*/
409 
410 /*MC
411     SNES_NORM_INITIAL_ONLY - Compute the function and its L2 at iteration 0, but do not update it.
412 
413    Level: advanced
414 
415    Notes:
416    This method is useful in composed methods, when a true solution might actually be found before SNESSolve() is called.
417    This option enables the solve to abort on the zeroth iteration if this is the case.
418 
419    For solvers that require the computation of the L2 norm of the function as part of the method, this merely cancels
420    the norm computation at the last iteration (if possible).
421 
422 .seealso: SNESNormSchedule, SNESSetNormSchedule(), SNES_NORM_FINAL_ONLY, SNES_NORM_INITIAL_FINAL_ONLY
423 M*/
424 
425 /*MC
426     SNES_NORM_FINAL_ONLY - Compute the function and its L2 norm on only the final iteration.
427 
428    Level: advanced
429 
430    Notes:
431    For solvers that require the computation of the L2 norm of the function as part of the method, behaves
432    exactly as SNES_NORM_DEFAULT.  This method is useful when the function is gotten after SNESSolve and
433    used in subsequent computation for methods that do not need the norm computed during the rest of the
434    solution procedure.
435 
436 .seealso: SNESNormSchedule, SNESSetNormSchedule(), SNES_NORM_INITIAL_ONLY, SNES_NORM_INITIAL_FINAL_ONLY
437 M*/
438 
439 /*MC
440     SNES_NORM_INITIAL_FINAL_ONLY - Compute the function and its L2 norm on only the initial and final iterations.
441 
442    Level: advanced
443 
444    Notes:
445    This method combines the benefits of SNES_NORM_INITIAL_ONLY and SNES_NORM_FINAL_ONLY.
446 
447 .seealso: SNESNormSchedule, SNESSetNormSchedule(), SNES_NORM_SNES_NORM_INITIAL_ONLY, SNES_NORM_FINAL_ONLY
448 M*/
449 
450 PETSC_EXTERN PetscErrorCode SNESSetNormSchedule(SNES,SNESNormSchedule);
451 PETSC_EXTERN PetscErrorCode SNESGetNormSchedule(SNES,SNESNormSchedule*);
452 PETSC_EXTERN PetscErrorCode SNESSetFunctionNorm(SNES,PetscReal);
453 PETSC_EXTERN PetscErrorCode SNESGetFunctionNorm(SNES,PetscReal*);
454 
455 /*E
456     SNESFunctionType - Type of function computed
457 
458    Level: advanced
459 
460    Support for these is highly dependent on the solver.
461 
462 .seealso: SNESSolve(), SNESGetConvergedReason(), KSPSetNormType(),
463           KSPSetConvergenceTest(), KSPSetPCSide()
464 E*/
465 typedef enum {SNES_FUNCTION_DEFAULT          = -1,
466               SNES_FUNCTION_UNPRECONDITIONED =  0,
467               SNES_FUNCTION_PRECONDITIONED   =  1} SNESFunctionType;
468 PETSC_EXTERN const char *const*const SNESFunctionTypes;
469 
470 PETSC_EXTERN PetscErrorCode SNESSetFunctionType(SNES,SNESFunctionType);
471 PETSC_EXTERN PetscErrorCode SNESGetFunctionType(SNES,SNESFunctionType*);
472 
473 PETSC_EXTERN PetscErrorCode SNESSetNGS(SNES,PetscErrorCode (*)(SNES,Vec,Vec,void*),void*);
474 PETSC_EXTERN PetscErrorCode SNESGetNGS(SNES,PetscErrorCode (**)(SNES,Vec,Vec,void*),void**);
475 PETSC_EXTERN PetscErrorCode SNESSetUseNGS(SNES,PetscBool);
476 PETSC_EXTERN PetscErrorCode SNESGetUseNGS(SNES,PetscBool *);
477 PETSC_EXTERN PetscErrorCode SNESComputeNGS(SNES,Vec,Vec);
478 
479 PETSC_EXTERN PetscErrorCode SNESNGSSetSweeps(SNES,PetscInt);
480 PETSC_EXTERN PetscErrorCode SNESNGSGetSweeps(SNES,PetscInt *);
481 PETSC_EXTERN PetscErrorCode SNESNGSSetTolerances(SNES,PetscReal,PetscReal,PetscReal,PetscInt);
482 PETSC_EXTERN PetscErrorCode SNESNGSGetTolerances(SNES,PetscReal*,PetscReal*,PetscReal*,PetscInt*);
483 
484 PETSC_EXTERN PetscErrorCode SNESUpdateCheckJacobian(SNES,PetscInt);
485 
486 PETSC_EXTERN PetscErrorCode SNESSetAlwaysComputesFinalResidual(SNES,PetscBool);
487 PETSC_EXTERN PetscErrorCode SNESGetAlwaysComputesFinalResidual(SNES,PetscBool*);
488 
489 PETSC_EXTERN PetscErrorCode SNESShellGetContext(SNES,void**);
490 PETSC_EXTERN PetscErrorCode SNESShellSetContext(SNES,void*);
491 PETSC_EXTERN PetscErrorCode SNESShellSetSolve(SNES,PetscErrorCode (*)(SNES,Vec));
492 
493 /* --------- Routines specifically for line search methods --------------- */
494 
495 
496 /*S
497      SNESLineSearch - Abstract PETSc object that manages line-search operations
498 
499    Level: beginner
500 
501   Concepts: nonlinear solvers, line search
502 
503 .seealso:  SNESLineSearchCreate(), SNESLineSearchSetType(), SNES
504 S*/
505 typedef struct _p_LineSearch* SNESLineSearch;
506 
507 /*J
508     SNESLineSearchType - String with the name of a PETSc line search method
509 
510    Level: beginner
511 
512 .seealso: SNESLineSearchSetType(), SNES
513 J*/
514 typedef const char* SNESLineSearchType;
515 #define SNESLINESEARCHBT                 "bt"
516 #define SNESLINESEARCHNLEQERR            "nleqerr"
517 #define SNESLINESEARCHBASIC              "basic"
518 #define SNESLINESEARCHL2                 "l2"
519 #define SNESLINESEARCHCP                 "cp"
520 #define SNESLINESEARCHSHELL              "shell"
521 
522 PETSC_EXTERN PetscFunctionList SNESList;
523 PETSC_EXTERN PetscClassId      SNESLINESEARCH_CLASSID;
524 PETSC_EXTERN PetscFunctionList SNESLineSearchList;
525 
526 #define SNES_LINESEARCH_ORDER_LINEAR    1
527 #define SNES_LINESEARCH_ORDER_QUADRATIC 2
528 #define SNES_LINESEARCH_ORDER_CUBIC     3
529 
530 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*SNESLineSearchVIProjectFunc)(SNES,Vec);
531 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*SNESLineSearchVINormFunc)(SNES,Vec,Vec,PetscReal *);
532 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*SNESLineSearchApplyFunc)(SNESLineSearch);
533 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*SNESLineSearchUserFunc)(SNESLineSearch, void *);
534 
535 PETSC_EXTERN PetscErrorCode SNESLineSearchCreate(MPI_Comm, SNESLineSearch*);
536 PETSC_EXTERN PetscErrorCode SNESLineSearchReset(SNESLineSearch);
537 PETSC_EXTERN PetscErrorCode SNESLineSearchView(SNESLineSearch,PetscViewer);
538 PETSC_EXTERN PetscErrorCode SNESLineSearchDestroy(SNESLineSearch *);
539 PETSC_EXTERN PetscErrorCode SNESLineSearchSetType(SNESLineSearch, SNESLineSearchType);
540 PETSC_EXTERN PetscErrorCode SNESLineSearchSetFromOptions(SNESLineSearch);
541 PETSC_EXTERN PetscErrorCode SNESLineSearchSetFunction(SNESLineSearch,PetscErrorCode (*)(SNES,Vec,Vec));
542 PETSC_EXTERN PetscErrorCode SNESLineSearchSetUp(SNESLineSearch);
543 PETSC_EXTERN PetscErrorCode SNESLineSearchApply(SNESLineSearch, Vec, Vec, PetscReal *, Vec);
544 PETSC_EXTERN PetscErrorCode SNESLineSearchPreCheck(SNESLineSearch,Vec,Vec,PetscBool *);
545 PETSC_EXTERN PetscErrorCode SNESLineSearchPostCheck(SNESLineSearch,Vec,Vec,Vec,PetscBool *,PetscBool *);
546 PETSC_EXTERN PetscErrorCode SNESLineSearchSetWorkVecs(SNESLineSearch, PetscInt);
547 
548 /* set the functions for precheck and postcheck */
549 
550 PETSC_EXTERN PetscErrorCode SNESLineSearchSetPreCheck(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch,Vec,Vec,PetscBool*,void*), void *ctx);
551 PETSC_EXTERN PetscErrorCode SNESLineSearchSetPostCheck(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch,Vec,Vec,Vec,PetscBool *,PetscBool *,void*), void *ctx);
552 
553 PETSC_EXTERN PetscErrorCode SNESLineSearchGetPreCheck(SNESLineSearch, PetscErrorCode (**)(SNESLineSearch,Vec,Vec,PetscBool*,void*), void **ctx);
554 PETSC_EXTERN PetscErrorCode SNESLineSearchGetPostCheck(SNESLineSearch, PetscErrorCode (**)(SNESLineSearch,Vec,Vec,Vec,PetscBool *,PetscBool *,void*), void **ctx);
555 
556 /* set the functions for VI-specific line search operations */
557 
558 PETSC_EXTERN PetscErrorCode SNESLineSearchSetVIFunctions(SNESLineSearch, SNESLineSearchVIProjectFunc, SNESLineSearchVINormFunc);
559 PETSC_EXTERN PetscErrorCode SNESLineSearchGetVIFunctions(SNESLineSearch, SNESLineSearchVIProjectFunc*, SNESLineSearchVINormFunc*);
560 
561 /* pointers to the associated SNES in order to be able to get the function evaluation out */
562 PETSC_EXTERN PetscErrorCode SNESLineSearchSetSNES(SNESLineSearch,SNES);
563 PETSC_EXTERN PetscErrorCode SNESLineSearchGetSNES(SNESLineSearch,SNES*);
564 
565 /* set and get the parameters and vectors */
566 PETSC_EXTERN PetscErrorCode SNESLineSearchGetTolerances(SNESLineSearch,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscInt*);
567 PETSC_EXTERN PetscErrorCode SNESLineSearchSetTolerances(SNESLineSearch,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscInt);
568 
569 PETSC_EXTERN PetscErrorCode SNESLineSearchPreCheckPicard(SNESLineSearch,Vec,Vec,PetscBool*,void*);
570 
571 PETSC_EXTERN PetscErrorCode SNESLineSearchGetLambda(SNESLineSearch,PetscReal*);
572 PETSC_EXTERN PetscErrorCode SNESLineSearchSetLambda(SNESLineSearch,PetscReal);
573 
574 PETSC_EXTERN PetscErrorCode SNESLineSearchGetDamping(SNESLineSearch,PetscReal*);
575 PETSC_EXTERN PetscErrorCode SNESLineSearchSetDamping(SNESLineSearch,PetscReal);
576 
577 PETSC_EXTERN PetscErrorCode SNESLineSearchGetOrder(SNESLineSearch,PetscInt *order);
578 PETSC_EXTERN PetscErrorCode SNESLineSearchSetOrder(SNESLineSearch,PetscInt order);
579 
580 /*E
581     SNESLineSearchReason - if line search has succeeded or failed and why
582 
583    Level: intermediate
584 
585    Developer Notes: this must match petsc/finclude/petscsnes.h
586 
587    Developer Note: The string versions of these are in SNESLineSearchReasons, if you change any value here you must
588      also adjust that array.
589 
590 .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest()
591 E*/
592 typedef enum {SNES_LINESEARCH_SUCCEEDED,
593               SNES_LINESEARCH_FAILED_NANORINF,
594               SNES_LINESEARCH_FAILED_DOMAIN,
595               SNES_LINESEARCH_FAILED_REDUCT,       /* INSUFFICENT REDUCTION */
596               SNES_LINESEARCH_FAILED_USER,
597               SNES_LINESEARCH_FAILED_FUNCTION} SNESLineSearchReason;
598 
599 PETSC_EXTERN PetscErrorCode SNESLineSearchGetReason(SNESLineSearch, SNESLineSearchReason*);
600 PETSC_EXTERN PetscErrorCode SNESLineSearchSetReason(SNESLineSearch, SNESLineSearchReason);
601 
602 PETSC_EXTERN PetscErrorCode SNESLineSearchGetVecs(SNESLineSearch,Vec*,Vec*,Vec*,Vec*,Vec*);
603 PETSC_EXTERN PetscErrorCode SNESLineSearchSetVecs(SNESLineSearch,Vec,Vec,Vec,Vec,Vec);
604 
605 PETSC_EXTERN PetscErrorCode SNESLineSearchGetNorms(SNESLineSearch, PetscReal *, PetscReal *, PetscReal *);
606 PETSC_EXTERN PetscErrorCode SNESLineSearchSetNorms(SNESLineSearch, PetscReal, PetscReal, PetscReal);
607 PETSC_EXTERN PetscErrorCode SNESLineSearchComputeNorms(SNESLineSearch);
608 PETSC_EXTERN PetscErrorCode SNESLineSearchSetComputeNorms(SNESLineSearch, PetscBool);
609 
610 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitor(SNESLineSearch);
611 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSet(SNESLineSearch,PetscErrorCode(*)(SNESLineSearch,void*),void *,PetscErrorCode (*)(void**));
612 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSetFromOptions(SNESLineSearch,const char[],const char[],const char[],PetscErrorCode (*)(SNESLineSearch,PetscViewerAndFormat*),PetscErrorCode (*)(SNESLineSearch,PetscViewerAndFormat*));
613 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorCancel(SNESLineSearch);
614 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorUpdate(SNESLineSearch,PetscViewerAndFormat*);
615 PETSC_EXTERN PetscErrorCode SNESLineSearchSetDefaultMonitor(SNESLineSearch,PetscViewer);
616 PETSC_EXTERN PetscErrorCode SNESLineSearchGetDefaultMonitor(SNESLineSearch,PetscViewer*);
617 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSolutionUpdate(SNESLineSearch,PetscViewerAndFormat*);
618 
619 PETSC_EXTERN PetscErrorCode SNESLineSearchAppendOptionsPrefix(SNESLineSearch, const char prefix[]);
620 PETSC_EXTERN PetscErrorCode SNESLineSearchGetOptionsPrefix(SNESLineSearch, const char *prefix[]);
621 
622 
623 /* Shell interface functions */
624 PETSC_EXTERN PetscErrorCode SNESLineSearchShellSetUserFunc(SNESLineSearch,SNESLineSearchUserFunc,void*);
625 PETSC_EXTERN PetscErrorCode SNESLineSearchShellGetUserFunc(SNESLineSearch,SNESLineSearchUserFunc*,void**);
626 
627 /* BT interface functions */
628 PETSC_EXTERN PetscErrorCode SNESLineSearchBTSetAlpha(SNESLineSearch, PetscReal);
629 PETSC_EXTERN PetscErrorCode SNESLineSearchBTGetAlpha(SNESLineSearch, PetscReal*);
630 
631 /*register line search types */
632 PETSC_EXTERN PetscErrorCode SNESLineSearchRegister(const char[],PetscErrorCode(*)(SNESLineSearch));
633 
634 /* Routines for VI solver */
635 PETSC_EXTERN PetscErrorCode SNESVISetVariableBounds(SNES,Vec,Vec);
636 PETSC_EXTERN PetscErrorCode SNESVISetComputeVariableBounds(SNES, PetscErrorCode (*)(SNES,Vec,Vec));
637 PETSC_EXTERN PetscErrorCode SNESVIGetInactiveSet(SNES,IS*);
638 PETSC_EXTERN PetscErrorCode SNESVIGetActiveSetIS(SNES,Vec,Vec,IS*);
639 PETSC_EXTERN PetscErrorCode SNESVIComputeInactiveSetFnorm(SNES,Vec,Vec,PetscReal*);
640 PETSC_EXTERN PetscErrorCode SNESVISetRedundancyCheck(SNES,PetscErrorCode(*)(SNES,IS,IS*,void*),void*);
641 
642 PETSC_EXTERN PetscErrorCode SNESTestLocalMin(SNES);
643 
644 /* Should this routine be private? */
645 PETSC_EXTERN PetscErrorCode SNESComputeJacobian(SNES,Vec,Mat,Mat);
646 
647 PETSC_EXTERN PetscErrorCode SNESSetDM(SNES,DM);
648 PETSC_EXTERN PetscErrorCode SNESGetDM(SNES,DM*);
649 PETSC_EXTERN PetscErrorCode SNESSetNPC(SNES,SNES);
650 PETSC_EXTERN PetscErrorCode SNESGetNPC(SNES,SNES*);
651 PETSC_EXTERN PetscErrorCode SNESHasNPC(SNES,PetscBool*);
652 PETSC_EXTERN PetscErrorCode SNESApplyNPC(SNES,Vec,Vec,Vec);
653 PETSC_EXTERN PetscErrorCode SNESGetNPCFunction(SNES,Vec,PetscReal*);
654 PETSC_EXTERN PetscErrorCode SNESComputeFunctionDefaultNPC(SNES,Vec,Vec);
655 PETSC_EXTERN PetscErrorCode SNESSetNPCSide(SNES,PCSide);
656 PETSC_EXTERN PetscErrorCode SNESGetNPCSide(SNES,PCSide*);
657 PETSC_EXTERN PetscErrorCode SNESSetLineSearch(SNES,SNESLineSearch);
658 PETSC_EXTERN PetscErrorCode SNESGetLineSearch(SNES,SNESLineSearch*);
659 PETSC_EXTERN PetscErrorCode SNESRestrictHookAdd(SNES,PetscErrorCode (*)(SNES,SNES,void*),void*);
660 PETSC_EXTERN PetscErrorCode SNESRestrictHooksRun(SNES,SNES);
661 
662 PETSC_DEPRECATED("Use SNESGetLineSearch()") PETSC_STATIC_INLINE PetscErrorCode SNESGetSNESLineSearch(SNES snes,SNESLineSearch *ls) {return SNESGetLineSearch(snes,ls);}
663 PETSC_DEPRECATED("Use SNESSetLineSearch()") PETSC_STATIC_INLINE PetscErrorCode SNESSetSNESLineSearch(SNES snes,SNESLineSearch ls) {return SNESSetLineSearch(snes,ls);}
664 
665 PETSC_EXTERN PetscErrorCode SNESSetUpMatrices(SNES);
666 PETSC_EXTERN PetscErrorCode DMSNESSetFunction(DM,PetscErrorCode(*)(SNES,Vec,Vec,void*),void*);
667 PETSC_EXTERN PetscErrorCode DMSNESGetFunction(DM,PetscErrorCode(**)(SNES,Vec,Vec,void*),void**);
668 PETSC_EXTERN PetscErrorCode DMSNESSetNGS(DM,PetscErrorCode(*)(SNES,Vec,Vec,void*),void*);
669 PETSC_EXTERN PetscErrorCode DMSNESGetNGS(DM,PetscErrorCode(**)(SNES,Vec,Vec,void*),void**);
670 PETSC_EXTERN PetscErrorCode DMSNESSetJacobian(DM,PetscErrorCode(*)(SNES,Vec,Mat,Mat,void*),void*);
671 PETSC_EXTERN PetscErrorCode DMSNESGetJacobian(DM,PetscErrorCode(**)(SNES,Vec,Mat,Mat,void*),void**);
672 PETSC_EXTERN PetscErrorCode DMSNESSetPicard(DM,PetscErrorCode(*)(SNES,Vec,Vec,void*),PetscErrorCode(*)(SNES,Vec,Mat,Mat,void*),void*);
673 PETSC_EXTERN PetscErrorCode DMSNESGetPicard(DM,PetscErrorCode(**)(SNES,Vec,Vec,void*),PetscErrorCode(**)(SNES,Vec,Mat,Mat,void*),void**);
674 PETSC_EXTERN PetscErrorCode DMSNESSetObjective(DM,PetscErrorCode (*)(SNES,Vec,PetscReal *,void*),void*);
675 PETSC_EXTERN PetscErrorCode DMSNESGetObjective(DM,PetscErrorCode (**)(SNES,Vec,PetscReal *,void*),void**);
676 
677 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESFunction)(DMDALocalInfo*,void*,void*,void*);
678 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESJacobian)(DMDALocalInfo*,void*,Mat,Mat,void*);
679 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESObjective)(DMDALocalInfo*,void*,PetscReal*,void*);
680 
681 PETSC_EXTERN PetscErrorCode DMDASNESSetFunctionLocal(DM,InsertMode,DMDASNESFunction,void*);
682 PETSC_EXTERN PetscErrorCode DMDASNESSetJacobianLocal(DM,DMDASNESJacobian,void*);
683 PETSC_EXTERN PetscErrorCode DMDASNESSetObjectiveLocal(DM,DMDASNESObjective,void*);
684 PETSC_EXTERN PetscErrorCode DMDASNESSetPicardLocal(DM,InsertMode,PetscErrorCode (*)(DMDALocalInfo*,void*,void*,void*),PetscErrorCode (*)(DMDALocalInfo*,void*,Mat,Mat,void*),void*);
685 
686 PETSC_EXTERN PetscErrorCode DMPlexSNESGetGeometryFEM(DM,Vec*);
687 PETSC_EXTERN PetscErrorCode DMPlexSNESGetGeometryFVM(DM,Vec*,Vec*,PetscReal*);
688 PETSC_EXTERN PetscErrorCode DMPlexSNESGetGradientDM(DM,PetscFV,DM*);
689 PETSC_EXTERN PetscErrorCode DMPlexGetCellFields(DM, PetscInt, PetscInt, Vec, Vec, Vec, PetscScalar **, PetscScalar **, PetscScalar **);
690 PETSC_EXTERN PetscErrorCode DMPlexRestoreCellFields(DM, PetscInt, PetscInt, Vec, Vec, Vec, PetscScalar **, PetscScalar **, PetscScalar **);
691 PETSC_EXTERN PetscErrorCode DMPlexGetFaceFields(DM, PetscInt, PetscInt, Vec, Vec, Vec, Vec, Vec, PetscInt *, PetscScalar **, PetscScalar **);
692 PETSC_EXTERN PetscErrorCode DMPlexRestoreFaceFields(DM, PetscInt, PetscInt, Vec, Vec, Vec, Vec, Vec, PetscInt *, PetscScalar **, PetscScalar **);
693 PETSC_EXTERN PetscErrorCode DMPlexGetFaceGeometry(DM, PetscInt, PetscInt, Vec, Vec, PetscInt *, PetscFVFaceGeom **, PetscReal **);
694 PETSC_EXTERN PetscErrorCode DMPlexRestoreFaceGeometry(DM, PetscInt, PetscInt, Vec, Vec, PetscInt *, PetscFVFaceGeom **, PetscReal **);
695 
696 PETSC_EXTERN PetscErrorCode DMSNESSetBoundaryLocal(DM,PetscErrorCode (*)(DM,Vec,void*),void*);
697 PETSC_EXTERN PetscErrorCode DMSNESSetFunctionLocal(DM,PetscErrorCode (*)(DM,Vec,Vec,void*),void*);
698 PETSC_EXTERN PetscErrorCode DMSNESSetJacobianLocal(DM,PetscErrorCode (*)(DM,Vec,Mat,Mat,void*),void*);
699 
700 /* Routines for Multiblock solver */
701 PETSC_EXTERN PetscErrorCode SNESMultiblockSetFields(SNES, const char [], PetscInt, const PetscInt *);
702 PETSC_EXTERN PetscErrorCode SNESMultiblockSetIS(SNES, const char [], IS);
703 PETSC_EXTERN PetscErrorCode SNESMultiblockSetBlockSize(SNES, PetscInt);
704 PETSC_EXTERN PetscErrorCode SNESMultiblockSetType(SNES, PCCompositeType);
705 
706 /*J
707     SNESMSType - String with the name of a PETSc SNESMS method.
708 
709    Level: intermediate
710 
711 .seealso: SNESMSSetType(), SNES
712 J*/
713 typedef const char* SNESMSType;
714 #define SNESMSM62       "m62"
715 #define SNESMSEULER     "euler"
716 #define SNESMSJAMESON83 "jameson83"
717 #define SNESMSVLTP21    "vltp21"
718 #define SNESMSVLTP31    "vltp31"
719 #define SNESMSVLTP41    "vltp41"
720 #define SNESMSVLTP51    "vltp51"
721 #define SNESMSVLTP61    "vltp61"
722 
723 PETSC_EXTERN PetscErrorCode SNESMSRegister(SNESMSType,PetscInt,PetscInt,PetscReal,const PetscReal[],const PetscReal[],const PetscReal[]);
724 PETSC_EXTERN PetscErrorCode SNESMSSetType(SNES,SNESMSType);
725 PETSC_EXTERN PetscErrorCode SNESMSFinalizePackage(void);
726 PETSC_EXTERN PetscErrorCode SNESMSInitializePackage(void);
727 PETSC_EXTERN PetscErrorCode SNESMSRegisterDestroy(void);
728 
729 /* routines for NGMRES solver */
730 
731 typedef enum {
732   SNES_NGMRES_RESTART_NONE       = 0,
733   SNES_NGMRES_RESTART_PERIODIC   = 1,
734   SNES_NGMRES_RESTART_DIFFERENCE = 2} SNESNGMRESRestartType;
735 PETSC_EXTERN const char *const SNESNGMRESRestartTypes[];
736 
737 typedef enum {
738   SNES_NGMRES_SELECT_NONE       = 0,
739   SNES_NGMRES_SELECT_DIFFERENCE = 1,
740   SNES_NGMRES_SELECT_LINESEARCH = 2} SNESNGMRESSelectType;
741 PETSC_EXTERN const char *const SNESNGMRESSelectTypes[];
742 
743 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartType(SNES, SNESNGMRESRestartType);
744 PETSC_EXTERN PetscErrorCode SNESNGMRESSetSelectType(SNES, SNESNGMRESSelectType);
745 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartFmRise(SNES, PetscBool);
746 PETSC_EXTERN PetscErrorCode SNESNGMRESGetRestartFmRise(SNES, PetscBool*);
747 
748 /* routines for NCG solver */
749 
750 typedef enum {
751   SNES_NCG_FR    = 0,
752   SNES_NCG_PRP   = 1,
753   SNES_NCG_HS    = 2,
754   SNES_NCG_DY    = 3,
755   SNES_NCG_CD    = 4} SNESNCGType;
756 PETSC_EXTERN const char *const SNESNCGTypes[];
757 
758 PETSC_EXTERN PetscErrorCode SNESNCGSetType(SNES, SNESNCGType);
759 
760 typedef enum {SNES_QN_SCALE_DEFAULT    = 0,
761               SNES_QN_SCALE_NONE       = 1,
762               SNES_QN_SCALE_SHANNO     = 2,
763               SNES_QN_SCALE_LINESEARCH = 3,
764               SNES_QN_SCALE_JACOBIAN   = 4} SNESQNScaleType;
765 PETSC_EXTERN const char *const SNESQNScaleTypes[];
766 typedef enum {SNES_QN_RESTART_DEFAULT  = 0,
767               SNES_QN_RESTART_NONE     = 1,
768               SNES_QN_RESTART_POWELL   = 2,
769               SNES_QN_RESTART_PERIODIC = 3} SNESQNRestartType;
770 PETSC_EXTERN const char *const SNESQNRestartTypes[];
771 typedef enum {SNES_QN_LBFGS      = 0,
772               SNES_QN_BROYDEN    = 1,
773               SNES_QN_BADBROYDEN = 2
774              } SNESQNType;
775 PETSC_EXTERN const char *const SNESQNTypes[];
776 
777 PETSC_EXTERN PetscErrorCode SNESQNSetType(SNES, SNESQNType);
778 PETSC_EXTERN PetscErrorCode SNESQNSetScaleType(SNES, SNESQNScaleType);
779 PETSC_EXTERN PetscErrorCode SNESQNSetRestartType(SNES, SNESQNRestartType);
780 
781 PETSC_EXTERN PetscErrorCode SNESNASMGetType(SNES,PCASMType*);
782 PETSC_EXTERN PetscErrorCode SNESNASMSetType(SNES,PCASMType);
783 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomains(SNES,PetscInt*,SNES**,VecScatter**,VecScatter**,VecScatter**);
784 PETSC_EXTERN PetscErrorCode SNESNASMSetSubdomains(SNES,PetscInt,SNES*,VecScatter*,VecScatter*,VecScatter*);
785 PETSC_EXTERN PetscErrorCode SNESNASMSetDamping(SNES,PetscReal);
786 PETSC_EXTERN PetscErrorCode SNESNASMGetDamping(SNES,PetscReal*);
787 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomainVecs(SNES,PetscInt*,Vec**,Vec**,Vec**,Vec**);
788 PETSC_EXTERN PetscErrorCode SNESNASMSetComputeFinalJacobian(SNES,PetscBool);
789 
790 typedef enum {SNES_COMPOSITE_ADDITIVE,SNES_COMPOSITE_MULTIPLICATIVE,SNES_COMPOSITE_ADDITIVEOPTIMAL} SNESCompositeType;
791 PETSC_EXTERN const char *const SNESCompositeTypes[];
792 
793 PETSC_EXTERN PetscErrorCode SNESCompositeSetType(SNES,SNESCompositeType);
794 PETSC_EXTERN PetscErrorCode SNESCompositeAddSNES(SNES,SNESType);
795 PETSC_EXTERN PetscErrorCode SNESCompositeGetSNES(SNES,PetscInt,SNES *);
796 PETSC_EXTERN PetscErrorCode SNESCompositeGetNumber(SNES,PetscInt*);
797 PETSC_EXTERN PetscErrorCode SNESCompositeSetDamping(SNES,PetscInt,PetscReal);
798 
799 /*E
800     SNESFASType - Determines the type of nonlinear multigrid method that is run.
801 
802    Level: beginner
803 
804    Values:
805 +  SNES_FAS_MULTIPLICATIVE (default) - traditional V or W cycle as determined by SNESFASSetCycles()
806 .  SNES_FAS_ADDITIVE                 - additive FAS cycle
807 .  SNES_FAS_FULL                     - full FAS cycle
808 -  SNES_FAS_KASKADE                  - Kaskade FAS cycle
809 .seealso: PCMGSetType(), PCMGType
810 
811 E*/
812 typedef enum { SNES_FAS_MULTIPLICATIVE, SNES_FAS_ADDITIVE, SNES_FAS_FULL, SNES_FAS_KASKADE } SNESFASType;
813 PETSC_EXTERN const char *const  SNESFASTypes[];
814 
815 /* called on the finest level FAS instance*/
816 PETSC_EXTERN PetscErrorCode SNESFASSetType(SNES, SNESFASType);
817 PETSC_EXTERN PetscErrorCode SNESFASGetType(SNES, SNESFASType*);
818 PETSC_EXTERN PetscErrorCode SNESFASSetLevels(SNES, PetscInt, MPI_Comm *);
819 PETSC_EXTERN PetscErrorCode SNESFASGetLevels(SNES, PetscInt *);
820 PETSC_EXTERN PetscErrorCode SNESFASGetCycleSNES(SNES, PetscInt, SNES*);
821 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothUp(SNES, PetscInt);
822 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothDown(SNES, PetscInt);
823 PETSC_EXTERN PetscErrorCode SNESFASSetCycles(SNES, PetscInt);
824 PETSC_EXTERN PetscErrorCode SNESFASSetMonitor(SNES, PetscViewerAndFormat *, PetscBool);
825 PETSC_EXTERN PetscErrorCode SNESFASSetLog(SNES, PetscBool);
826 
827 PETSC_EXTERN PetscErrorCode SNESFASSetGalerkin(SNES, PetscBool);
828 PETSC_EXTERN PetscErrorCode SNESFASGetGalerkin(SNES, PetscBool*);
829 
830 /* called on any level -- "Cycle" FAS instance */
831 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmoother(SNES, SNES*);
832 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherUp(SNES, SNES*);
833 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherDown(SNES, SNES*);
834 PETSC_EXTERN PetscErrorCode SNESFASCycleGetCorrection(SNES, SNES*);
835 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInterpolation(SNES, Mat*);
836 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRestriction(SNES, Mat*);
837 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInjection(SNES, Mat*);
838 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRScale(SNES, Vec*);
839 PETSC_EXTERN PetscErrorCode SNESFASCycleSetCycles(SNES, PetscInt);
840 PETSC_EXTERN PetscErrorCode SNESFASCycleIsFine(SNES, PetscBool*);
841 
842 /* called on the (outer) finest level FAS to set/get parameters on any level instance */
843 PETSC_EXTERN PetscErrorCode SNESFASSetInterpolation(SNES, PetscInt, Mat);
844 PETSC_EXTERN PetscErrorCode SNESFASGetInterpolation(SNES, PetscInt, Mat*);
845 PETSC_EXTERN PetscErrorCode SNESFASSetRestriction(SNES, PetscInt, Mat);
846 PETSC_EXTERN PetscErrorCode SNESFASGetRestriction(SNES, PetscInt, Mat*);
847 PETSC_EXTERN PetscErrorCode SNESFASSetInjection(SNES, PetscInt, Mat);
848 PETSC_EXTERN PetscErrorCode SNESFASGetInjection(SNES, PetscInt, Mat*);
849 PETSC_EXTERN PetscErrorCode SNESFASSetRScale(SNES, PetscInt, Vec);
850 PETSC_EXTERN PetscErrorCode SNESFASGetRScale(SNES, PetscInt, Vec*);
851 PETSC_EXTERN PetscErrorCode SNESFASSetContinuation(SNES,PetscBool);
852 
853 PETSC_EXTERN PetscErrorCode SNESFASGetSmoother(SNES,     PetscInt, SNES*);
854 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherUp(SNES,   PetscInt, SNES*);
855 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherDown(SNES, PetscInt, SNES*);
856 PETSC_EXTERN PetscErrorCode SNESFASGetCoarseSolve(SNES, SNES*);
857 
858 /* parameters for full FAS */
859 PETSC_EXTERN PetscErrorCode SNESFASFullSetDownSweep(SNES,PetscBool);
860 PETSC_EXTERN PetscErrorCode SNESFASCreateCoarseVec(SNES,Vec*);
861 PETSC_EXTERN PetscErrorCode SNESFASRestrict(SNES,Vec,Vec);
862 
863 PETSC_EXTERN PetscErrorCode DMSNESCheckFromOptions(SNES,Vec,PetscErrorCode (**)(PetscInt,PetscReal,const PetscReal[],PetscInt,PetscScalar*,void*),void**);
864 
865 #endif
866