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