xref: /petsc/include/petscsnes.h (revision b41ce5d507ea9a58bfa83cf403107a702e77a67d) 
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 SNESHasDM(SNES,PetscBool*);
654 PETSC_EXTERN PetscErrorCode SNESSetNPC(SNES,SNES);
655 PETSC_EXTERN PetscErrorCode SNESGetNPC(SNES,SNES*);
656 PETSC_EXTERN PetscErrorCode SNESHasNPC(SNES,PetscBool*);
657 PETSC_EXTERN PetscErrorCode SNESApplyNPC(SNES,Vec,Vec,Vec);
658 PETSC_EXTERN PetscErrorCode SNESGetNPCFunction(SNES,Vec,PetscReal*);
659 PETSC_EXTERN PetscErrorCode SNESComputeFunctionDefaultNPC(SNES,Vec,Vec);
660 PETSC_EXTERN PetscErrorCode SNESSetNPCSide(SNES,PCSide);
661 PETSC_EXTERN PetscErrorCode SNESGetNPCSide(SNES,PCSide*);
662 PETSC_EXTERN PetscErrorCode SNESSetLineSearch(SNES,SNESLineSearch);
663 PETSC_EXTERN PetscErrorCode SNESGetLineSearch(SNES,SNESLineSearch*);
664 PETSC_EXTERN PetscErrorCode SNESRestrictHookAdd(SNES,PetscErrorCode (*)(SNES,SNES,void*),void*);
665 PETSC_EXTERN PetscErrorCode SNESRestrictHooksRun(SNES,SNES);
666 
667 PETSC_DEPRECATED("Use SNESGetLineSearch()") PETSC_STATIC_INLINE PetscErrorCode SNESGetSNESLineSearch(SNES snes,SNESLineSearch *ls) {return SNESGetLineSearch(snes,ls);}
668 PETSC_DEPRECATED("Use SNESSetLineSearch()") PETSC_STATIC_INLINE PetscErrorCode SNESSetSNESLineSearch(SNES snes,SNESLineSearch ls) {return SNESSetLineSearch(snes,ls);}
669 
670 PETSC_EXTERN PetscErrorCode SNESSetUpMatrices(SNES);
671 PETSC_EXTERN PetscErrorCode DMSNESSetFunction(DM,PetscErrorCode(*)(SNES,Vec,Vec,void*),void*);
672 PETSC_EXTERN PetscErrorCode DMSNESGetFunction(DM,PetscErrorCode(**)(SNES,Vec,Vec,void*),void**);
673 PETSC_EXTERN PetscErrorCode DMSNESSetNGS(DM,PetscErrorCode(*)(SNES,Vec,Vec,void*),void*);
674 PETSC_EXTERN PetscErrorCode DMSNESGetNGS(DM,PetscErrorCode(**)(SNES,Vec,Vec,void*),void**);
675 PETSC_EXTERN PetscErrorCode DMSNESSetJacobian(DM,PetscErrorCode(*)(SNES,Vec,Mat,Mat,void*),void*);
676 PETSC_EXTERN PetscErrorCode DMSNESGetJacobian(DM,PetscErrorCode(**)(SNES,Vec,Mat,Mat,void*),void**);
677 PETSC_EXTERN PetscErrorCode DMSNESSetPicard(DM,PetscErrorCode(*)(SNES,Vec,Vec,void*),PetscErrorCode(*)(SNES,Vec,Mat,Mat,void*),void*);
678 PETSC_EXTERN PetscErrorCode DMSNESGetPicard(DM,PetscErrorCode(**)(SNES,Vec,Vec,void*),PetscErrorCode(**)(SNES,Vec,Mat,Mat,void*),void**);
679 PETSC_EXTERN PetscErrorCode DMSNESSetObjective(DM,PetscErrorCode (*)(SNES,Vec,PetscReal *,void*),void*);
680 PETSC_EXTERN PetscErrorCode DMSNESGetObjective(DM,PetscErrorCode (**)(SNES,Vec,PetscReal *,void*),void**);
681 PETSC_EXTERN PetscErrorCode DMCopyDMSNES(DM,DM);
682 
683 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESFunction)(DMDALocalInfo*,void*,void*,void*);
684 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESJacobian)(DMDALocalInfo*,void*,Mat,Mat,void*);
685 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESObjective)(DMDALocalInfo*,void*,PetscReal*,void*);
686 
687 PETSC_EXTERN PetscErrorCode DMDASNESSetFunctionLocal(DM,InsertMode,DMDASNESFunction,void*);
688 PETSC_EXTERN PetscErrorCode DMDASNESSetJacobianLocal(DM,DMDASNESJacobian,void*);
689 PETSC_EXTERN PetscErrorCode DMDASNESSetObjectiveLocal(DM,DMDASNESObjective,void*);
690 PETSC_EXTERN PetscErrorCode DMDASNESSetPicardLocal(DM,InsertMode,PetscErrorCode (*)(DMDALocalInfo*,void*,void*,void*),PetscErrorCode (*)(DMDALocalInfo*,void*,Mat,Mat,void*),void*);
691 
692 PETSC_EXTERN PetscErrorCode DMPlexSNESGetGeometryFEM(DM,Vec*);
693 PETSC_EXTERN PetscErrorCode DMPlexSNESGetGeometryFVM(DM,Vec*,Vec*,PetscReal*);
694 PETSC_EXTERN PetscErrorCode DMPlexSNESGetGradientDM(DM,PetscFV,DM*);
695 PETSC_EXTERN PetscErrorCode DMPlexGetCellFields(DM, PetscInt, PetscInt, Vec, Vec, Vec, PetscScalar **, PetscScalar **, PetscScalar **);
696 PETSC_EXTERN PetscErrorCode DMPlexRestoreCellFields(DM, PetscInt, PetscInt, Vec, Vec, Vec, PetscScalar **, PetscScalar **, PetscScalar **);
697 PETSC_EXTERN PetscErrorCode DMPlexGetFaceFields(DM, PetscInt, PetscInt, Vec, Vec, Vec, Vec, Vec, PetscInt *, PetscScalar **, PetscScalar **);
698 PETSC_EXTERN PetscErrorCode DMPlexRestoreFaceFields(DM, PetscInt, PetscInt, Vec, Vec, Vec, Vec, Vec, PetscInt *, PetscScalar **, PetscScalar **);
699 PETSC_EXTERN PetscErrorCode DMPlexGetFaceGeometry(DM, PetscInt, PetscInt, Vec, Vec, PetscInt *, PetscFVFaceGeom **, PetscReal **);
700 PETSC_EXTERN PetscErrorCode DMPlexRestoreFaceGeometry(DM, PetscInt, PetscInt, Vec, Vec, PetscInt *, PetscFVFaceGeom **, PetscReal **);
701 
702 PETSC_EXTERN PetscErrorCode DMSNESSetBoundaryLocal(DM,PetscErrorCode (*)(DM,Vec,void*),void*);
703 PETSC_EXTERN PetscErrorCode DMSNESSetFunctionLocal(DM,PetscErrorCode (*)(DM,Vec,Vec,void*),void*);
704 PETSC_EXTERN PetscErrorCode DMSNESSetJacobianLocal(DM,PetscErrorCode (*)(DM,Vec,Mat,Mat,void*),void*);
705 
706 /* Routines for Multiblock solver */
707 PETSC_EXTERN PetscErrorCode SNESMultiblockSetFields(SNES, const char [], PetscInt, const PetscInt *);
708 PETSC_EXTERN PetscErrorCode SNESMultiblockSetIS(SNES, const char [], IS);
709 PETSC_EXTERN PetscErrorCode SNESMultiblockSetBlockSize(SNES, PetscInt);
710 PETSC_EXTERN PetscErrorCode SNESMultiblockSetType(SNES, PCCompositeType);
711 
712 /*J
713     SNESMSType - String with the name of a PETSc SNESMS method.
714 
715    Level: intermediate
716 
717 .seealso: SNESMSSetType(), SNES
718 J*/
719 typedef const char* SNESMSType;
720 #define SNESMSM62       "m62"
721 #define SNESMSEULER     "euler"
722 #define SNESMSJAMESON83 "jameson83"
723 #define SNESMSVLTP21    "vltp21"
724 #define SNESMSVLTP31    "vltp31"
725 #define SNESMSVLTP41    "vltp41"
726 #define SNESMSVLTP51    "vltp51"
727 #define SNESMSVLTP61    "vltp61"
728 
729 PETSC_EXTERN PetscErrorCode SNESMSRegister(SNESMSType,PetscInt,PetscInt,PetscReal,const PetscReal[],const PetscReal[],const PetscReal[]);
730 PETSC_EXTERN PetscErrorCode SNESMSSetType(SNES,SNESMSType);
731 PETSC_EXTERN PetscErrorCode SNESMSFinalizePackage(void);
732 PETSC_EXTERN PetscErrorCode SNESMSInitializePackage(void);
733 PETSC_EXTERN PetscErrorCode SNESMSRegisterDestroy(void);
734 
735 /* routines for NGMRES solver */
736 
737 typedef enum {
738   SNES_NGMRES_RESTART_NONE       = 0,
739   SNES_NGMRES_RESTART_PERIODIC   = 1,
740   SNES_NGMRES_RESTART_DIFFERENCE = 2} SNESNGMRESRestartType;
741 PETSC_EXTERN const char *const SNESNGMRESRestartTypes[];
742 
743 typedef enum {
744   SNES_NGMRES_SELECT_NONE       = 0,
745   SNES_NGMRES_SELECT_DIFFERENCE = 1,
746   SNES_NGMRES_SELECT_LINESEARCH = 2} SNESNGMRESSelectType;
747 PETSC_EXTERN const char *const SNESNGMRESSelectTypes[];
748 
749 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartType(SNES, SNESNGMRESRestartType);
750 PETSC_EXTERN PetscErrorCode SNESNGMRESSetSelectType(SNES, SNESNGMRESSelectType);
751 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartFmRise(SNES, PetscBool);
752 PETSC_EXTERN PetscErrorCode SNESNGMRESGetRestartFmRise(SNES, PetscBool*);
753 
754 /* routines for NCG solver */
755 
756 typedef enum {
757   SNES_NCG_FR    = 0,
758   SNES_NCG_PRP   = 1,
759   SNES_NCG_HS    = 2,
760   SNES_NCG_DY    = 3,
761   SNES_NCG_CD    = 4} SNESNCGType;
762 PETSC_EXTERN const char *const SNESNCGTypes[];
763 
764 PETSC_EXTERN PetscErrorCode SNESNCGSetType(SNES, SNESNCGType);
765 
766 typedef enum {SNES_QN_SCALE_DEFAULT    = 0,
767               SNES_QN_SCALE_NONE       = 1,
768               SNES_QN_SCALE_SHANNO     = 2,
769               SNES_QN_SCALE_LINESEARCH = 3,
770               SNES_QN_SCALE_JACOBIAN   = 4} SNESQNScaleType;
771 PETSC_EXTERN const char *const SNESQNScaleTypes[];
772 typedef enum {SNES_QN_RESTART_DEFAULT  = 0,
773               SNES_QN_RESTART_NONE     = 1,
774               SNES_QN_RESTART_POWELL   = 2,
775               SNES_QN_RESTART_PERIODIC = 3} SNESQNRestartType;
776 PETSC_EXTERN const char *const SNESQNRestartTypes[];
777 typedef enum {SNES_QN_LBFGS      = 0,
778               SNES_QN_BROYDEN    = 1,
779               SNES_QN_BADBROYDEN = 2
780              } SNESQNType;
781 PETSC_EXTERN const char *const SNESQNTypes[];
782 
783 PETSC_EXTERN PetscErrorCode SNESQNSetType(SNES, SNESQNType);
784 PETSC_EXTERN PetscErrorCode SNESQNSetScaleType(SNES, SNESQNScaleType);
785 PETSC_EXTERN PetscErrorCode SNESQNSetRestartType(SNES, SNESQNRestartType);
786 
787 PETSC_EXTERN PetscErrorCode SNESNASMGetType(SNES,PCASMType*);
788 PETSC_EXTERN PetscErrorCode SNESNASMSetType(SNES,PCASMType);
789 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomains(SNES,PetscInt*,SNES**,VecScatter**,VecScatter**,VecScatter**);
790 PETSC_EXTERN PetscErrorCode SNESNASMSetSubdomains(SNES,PetscInt,SNES*,VecScatter*,VecScatter*,VecScatter*);
791 PETSC_EXTERN PetscErrorCode SNESNASMSetDamping(SNES,PetscReal);
792 PETSC_EXTERN PetscErrorCode SNESNASMGetDamping(SNES,PetscReal*);
793 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomainVecs(SNES,PetscInt*,Vec**,Vec**,Vec**,Vec**);
794 PETSC_EXTERN PetscErrorCode SNESNASMSetComputeFinalJacobian(SNES,PetscBool);
795 PETSC_EXTERN PetscErrorCode SNESNASMGetSNES(SNES,PetscInt,SNES *);
796 PETSC_EXTERN PetscErrorCode SNESNASMGetNumber(SNES,PetscInt*);
797 PETSC_EXTERN PetscErrorCode SNESNASMSetWeight(SNES,Vec);
798 
799 typedef enum {SNES_COMPOSITE_ADDITIVE,SNES_COMPOSITE_MULTIPLICATIVE,SNES_COMPOSITE_ADDITIVEOPTIMAL} SNESCompositeType;
800 PETSC_EXTERN const char *const SNESCompositeTypes[];
801 
802 PETSC_EXTERN PetscErrorCode SNESCompositeSetType(SNES,SNESCompositeType);
803 PETSC_EXTERN PetscErrorCode SNESCompositeAddSNES(SNES,SNESType);
804 PETSC_EXTERN PetscErrorCode SNESCompositeGetSNES(SNES,PetscInt,SNES *);
805 PETSC_EXTERN PetscErrorCode SNESCompositeGetNumber(SNES,PetscInt*);
806 PETSC_EXTERN PetscErrorCode SNESCompositeSetDamping(SNES,PetscInt,PetscReal);
807 
808 /*E
809     SNESFASType - Determines the type of nonlinear multigrid method that is run.
810 
811    Level: beginner
812 
813    Values:
814 +  SNES_FAS_MULTIPLICATIVE (default) - traditional V or W cycle as determined by SNESFASSetCycles()
815 .  SNES_FAS_ADDITIVE                 - additive FAS cycle
816 .  SNES_FAS_FULL                     - full FAS cycle
817 -  SNES_FAS_KASKADE                  - Kaskade FAS cycle
818 .seealso: PCMGSetType(), PCMGType
819 
820 E*/
821 typedef enum { SNES_FAS_MULTIPLICATIVE, SNES_FAS_ADDITIVE, SNES_FAS_FULL, SNES_FAS_KASKADE } SNESFASType;
822 PETSC_EXTERN const char *const  SNESFASTypes[];
823 
824 /* called on the finest level FAS instance*/
825 PETSC_EXTERN PetscErrorCode SNESFASSetType(SNES, SNESFASType);
826 PETSC_EXTERN PetscErrorCode SNESFASGetType(SNES, SNESFASType*);
827 PETSC_EXTERN PetscErrorCode SNESFASSetLevels(SNES, PetscInt, MPI_Comm *);
828 PETSC_EXTERN PetscErrorCode SNESFASGetLevels(SNES, PetscInt *);
829 PETSC_EXTERN PetscErrorCode SNESFASGetCycleSNES(SNES, PetscInt, SNES*);
830 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothUp(SNES, PetscInt);
831 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothDown(SNES, PetscInt);
832 PETSC_EXTERN PetscErrorCode SNESFASSetCycles(SNES, PetscInt);
833 PETSC_EXTERN PetscErrorCode SNESFASSetMonitor(SNES, PetscViewerAndFormat *, PetscBool);
834 PETSC_EXTERN PetscErrorCode SNESFASSetLog(SNES, PetscBool);
835 
836 PETSC_EXTERN PetscErrorCode SNESFASSetGalerkin(SNES, PetscBool);
837 PETSC_EXTERN PetscErrorCode SNESFASGetGalerkin(SNES, PetscBool*);
838 
839 /* called on any level -- "Cycle" FAS instance */
840 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmoother(SNES, SNES*);
841 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherUp(SNES, SNES*);
842 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherDown(SNES, SNES*);
843 PETSC_EXTERN PetscErrorCode SNESFASCycleGetCorrection(SNES, SNES*);
844 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInterpolation(SNES, Mat*);
845 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRestriction(SNES, Mat*);
846 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInjection(SNES, Mat*);
847 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRScale(SNES, Vec*);
848 PETSC_EXTERN PetscErrorCode SNESFASCycleSetCycles(SNES, PetscInt);
849 PETSC_EXTERN PetscErrorCode SNESFASCycleIsFine(SNES, PetscBool*);
850 
851 /* called on the (outer) finest level FAS to set/get parameters on any level instance */
852 PETSC_EXTERN PetscErrorCode SNESFASSetInterpolation(SNES, PetscInt, Mat);
853 PETSC_EXTERN PetscErrorCode SNESFASGetInterpolation(SNES, PetscInt, Mat*);
854 PETSC_EXTERN PetscErrorCode SNESFASSetRestriction(SNES, PetscInt, Mat);
855 PETSC_EXTERN PetscErrorCode SNESFASGetRestriction(SNES, PetscInt, Mat*);
856 PETSC_EXTERN PetscErrorCode SNESFASSetInjection(SNES, PetscInt, Mat);
857 PETSC_EXTERN PetscErrorCode SNESFASGetInjection(SNES, PetscInt, Mat*);
858 PETSC_EXTERN PetscErrorCode SNESFASSetRScale(SNES, PetscInt, Vec);
859 PETSC_EXTERN PetscErrorCode SNESFASGetRScale(SNES, PetscInt, Vec*);
860 PETSC_EXTERN PetscErrorCode SNESFASSetContinuation(SNES,PetscBool);
861 
862 PETSC_EXTERN PetscErrorCode SNESFASGetSmoother(SNES,     PetscInt, SNES*);
863 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherUp(SNES,   PetscInt, SNES*);
864 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherDown(SNES, PetscInt, SNES*);
865 PETSC_EXTERN PetscErrorCode SNESFASGetCoarseSolve(SNES, SNES*);
866 
867 /* parameters for full FAS */
868 PETSC_EXTERN PetscErrorCode SNESFASFullSetDownSweep(SNES,PetscBool);
869 PETSC_EXTERN PetscErrorCode SNESFASCreateCoarseVec(SNES,Vec*);
870 PETSC_EXTERN PetscErrorCode SNESFASRestrict(SNES,Vec,Vec);
871 
872 PETSC_EXTERN PetscErrorCode DMSNESCheckFromOptions(SNES,Vec,PetscErrorCode (**)(PetscInt,PetscReal,const PetscReal[],PetscInt,PetscScalar*,void*),void**);
873 
874 #endif
875