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