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