xref: /petsc/include/petscsnes.h (revision b351a90bee759614d0186c89aaaec1807ff73013) 
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 SNESNRICHARDSON      "nrichardson"
34 #define SNESKSPONLY          "ksponly"
35 #define SNESKSPTRANSPOSEONLY "ksptransposeonly"
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 PETSC_EXTERN PetscErrorCode SNESResetFromOptions(SNES);
102 
103 PETSC_EXTERN PetscErrorCode SNESSetUseMatrixFree(SNES,PetscBool,PetscBool);
104 PETSC_EXTERN PetscErrorCode SNESGetUseMatrixFree(SNES,PetscBool*,PetscBool*);
105 PETSC_EXTERN PetscErrorCode MatCreateSNESMF(SNES,Mat*);
106 PETSC_EXTERN PetscErrorCode MatSNESMFGetSNES(Mat,SNES*);
107 PETSC_EXTERN PetscErrorCode MatSNESMFSetReuseBase(Mat,PetscBool);
108 PETSC_EXTERN PetscErrorCode MatSNESMFGetReuseBase(Mat,PetscBool*);
109 PETSC_EXTERN PetscErrorCode MatMFFDComputeJacobian(SNES,Vec,Mat,Mat,void*);
110 
111 PETSC_EXTERN PetscErrorCode MatDAADSetSNES(Mat,SNES);
112 
113 PETSC_EXTERN PetscErrorCode SNESGetType(SNES,SNESType*);
114 PETSC_EXTERN PetscErrorCode SNESMonitorDefault(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
115 PETSC_EXTERN PetscErrorCode SNESMonitorScaling(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
116 PETSC_EXTERN PetscErrorCode SNESMonitorRange(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
117 PETSC_EXTERN PetscErrorCode SNESMonitorRatio(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
118 PETSC_EXTERN PetscErrorCode SNESMonitorRatioSetUp(SNES,PetscViewerAndFormat*);
119 PETSC_EXTERN PetscErrorCode SNESMonitorSolution(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
120 PETSC_EXTERN PetscErrorCode SNESMonitorResidual(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
121 PETSC_EXTERN PetscErrorCode SNESMonitorSolutionUpdate(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
122 PETSC_EXTERN PetscErrorCode SNESMonitorDefaultShort(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
123 PETSC_EXTERN PetscErrorCode SNESMonitorDefaultField(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
124 PETSC_EXTERN PetscErrorCode SNESMonitorJacUpdateSpectrum(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
125 PETSC_EXTERN PetscErrorCode SNESMonitorFields(SNES,PetscInt,PetscReal,PetscViewerAndFormat *);
126 PETSC_EXTERN PetscErrorCode KSPMonitorSNES(KSP,PetscInt,PetscReal,void*);
127 PETSC_EXTERN PetscErrorCode KSPMonitorSNESLGResidualNormCreate(MPI_Comm,const char[],const char[],int,int,int,int,PetscObject**);
128 PETSC_EXTERN PetscErrorCode KSPMonitorSNESLGResidualNorm(KSP,PetscInt,PetscReal,PetscObject*);
129 PETSC_EXTERN PetscErrorCode KSPMonitorSNESLGResidualNormDestroy(PetscObject**);
130 
131 PETSC_EXTERN PetscErrorCode SNESSetTolerances(SNES,PetscReal,PetscReal,PetscReal,PetscInt,PetscInt);
132 PETSC_EXTERN PetscErrorCode SNESSetDivergenceTolerance(SNES,PetscReal);
133 PETSC_EXTERN PetscErrorCode SNESGetTolerances(SNES,PetscReal*,PetscReal*,PetscReal*,PetscInt*,PetscInt*);
134 PETSC_EXTERN PetscErrorCode SNESGetDivergenceTolerance(SNES,PetscReal*);
135 PETSC_EXTERN PetscErrorCode SNESSetTrustRegionTolerance(SNES,PetscReal);
136 PETSC_EXTERN PetscErrorCode SNESGetForceIteration(SNES,PetscBool*);
137 PETSC_EXTERN PetscErrorCode SNESSetForceIteration(SNES,PetscBool);
138 PETSC_EXTERN PetscErrorCode SNESGetIterationNumber(SNES,PetscInt*);
139 PETSC_EXTERN PetscErrorCode SNESSetIterationNumber(SNES,PetscInt);
140 
141 PETSC_EXTERN PetscErrorCode SNESGetNonlinearStepFailures(SNES,PetscInt*);
142 PETSC_EXTERN PetscErrorCode SNESSetMaxNonlinearStepFailures(SNES,PetscInt);
143 PETSC_EXTERN PetscErrorCode SNESGetMaxNonlinearStepFailures(SNES,PetscInt*);
144 PETSC_EXTERN PetscErrorCode SNESGetNumberFunctionEvals(SNES,PetscInt*);
145 
146 PETSC_EXTERN PetscErrorCode SNESSetLagPreconditioner(SNES,PetscInt);
147 PETSC_EXTERN PetscErrorCode SNESGetLagPreconditioner(SNES,PetscInt*);
148 PETSC_EXTERN PetscErrorCode SNESSetLagJacobian(SNES,PetscInt);
149 PETSC_EXTERN PetscErrorCode SNESGetLagJacobian(SNES,PetscInt*);
150 PETSC_EXTERN PetscErrorCode SNESSetLagPreconditionerPersists(SNES,PetscBool);
151 PETSC_EXTERN PetscErrorCode SNESSetLagJacobianPersists(SNES,PetscBool);
152 PETSC_EXTERN PetscErrorCode SNESSetGridSequence(SNES,PetscInt);
153 PETSC_EXTERN PetscErrorCode SNESGetGridSequence(SNES,PetscInt*);
154 
155 PETSC_EXTERN PetscErrorCode SNESGetLinearSolveIterations(SNES,PetscInt*);
156 PETSC_EXTERN PetscErrorCode SNESGetLinearSolveFailures(SNES,PetscInt*);
157 PETSC_EXTERN PetscErrorCode SNESSetMaxLinearSolveFailures(SNES,PetscInt);
158 PETSC_EXTERN PetscErrorCode SNESGetMaxLinearSolveFailures(SNES,PetscInt*);
159 PETSC_EXTERN PetscErrorCode SNESSetCountersReset(SNES,PetscBool);
160 
161 PETSC_EXTERN PetscErrorCode SNESKSPSetUseEW(SNES,PetscBool );
162 PETSC_EXTERN PetscErrorCode SNESKSPGetUseEW(SNES,PetscBool *);
163 PETSC_EXTERN PetscErrorCode SNESKSPSetParametersEW(SNES,PetscInt,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal);
164 PETSC_EXTERN PetscErrorCode SNESKSPGetParametersEW(SNES,PetscInt*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*);
165 
166 #include <petscdrawtypes.h>
167 PETSC_EXTERN PetscErrorCode SNESMonitorLGCreate(MPI_Comm,const char[],const char[],int,int,int,int,PetscDrawLG*);
168 PETSC_EXTERN PetscErrorCode SNESMonitorLGResidualNorm(SNES,PetscInt,PetscReal,void*);
169 PETSC_EXTERN PetscErrorCode SNESMonitorLGRange(SNES,PetscInt,PetscReal,void*);
170 
171 PETSC_EXTERN PetscErrorCode SNESSetApplicationContext(SNES,void *);
172 PETSC_EXTERN PetscErrorCode SNESGetApplicationContext(SNES,void *);
173 PETSC_EXTERN PetscErrorCode SNESSetComputeApplicationContext(SNES,PetscErrorCode (*)(SNES,void**),PetscErrorCode (*)(void**));
174 
175 PETSC_EXTERN PetscErrorCode SNESPythonSetType(SNES,const char[]);
176 
177 PETSC_EXTERN PetscErrorCode SNESSetFunctionDomainError(SNES);
178 PETSC_EXTERN PetscErrorCode SNESGetFunctionDomainError(SNES, PetscBool *);
179 PETSC_EXTERN PetscErrorCode SNESGetJacobianDomainError(SNES,PetscBool*);
180 PETSC_EXTERN PetscErrorCode SNESSetJacobianDomainError(SNES);
181 PETSC_EXTERN PetscErrorCode SNESSetCheckJacobianDomainError(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("Use SNESConvergedSkip()") 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   Concepts: nonlinear solvers, line search
520 
521 .seealso:  SNESLineSearchCreate(), SNESLineSearchSetType(), SNES
522 S*/
523 typedef struct _p_LineSearch* SNESLineSearch;
524 
525 /*J
526     SNESLineSearchType - String with the name of a PETSc line search method
527 
528    Level: beginner
529 
530 .seealso: SNESLineSearchSetType(), SNES
531 J*/
532 typedef const char* SNESLineSearchType;
533 #define SNESLINESEARCHBT                 "bt"
534 #define SNESLINESEARCHNLEQERR            "nleqerr"
535 #define SNESLINESEARCHBASIC              "basic"
536 #define SNESLINESEARCHL2                 "l2"
537 #define SNESLINESEARCHCP                 "cp"
538 #define SNESLINESEARCHSHELL              "shell"
539 
540 PETSC_EXTERN PetscFunctionList SNESList;
541 PETSC_EXTERN PetscClassId      SNESLINESEARCH_CLASSID;
542 PETSC_EXTERN PetscFunctionList SNESLineSearchList;
543 
544 #define SNES_LINESEARCH_ORDER_LINEAR    1
545 #define SNES_LINESEARCH_ORDER_QUADRATIC 2
546 #define SNES_LINESEARCH_ORDER_CUBIC     3
547 
548 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*SNESLineSearchVIProjectFunc)(SNES,Vec);
549 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*SNESLineSearchVINormFunc)(SNES,Vec,Vec,PetscReal *);
550 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*SNESLineSearchApplyFunc)(SNESLineSearch);
551 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*SNESLineSearchUserFunc)(SNESLineSearch, void *);
552 
553 PETSC_EXTERN PetscErrorCode SNESLineSearchCreate(MPI_Comm, SNESLineSearch*);
554 PETSC_EXTERN PetscErrorCode SNESLineSearchReset(SNESLineSearch);
555 PETSC_EXTERN PetscErrorCode SNESLineSearchView(SNESLineSearch,PetscViewer);
556 PETSC_EXTERN PetscErrorCode SNESLineSearchDestroy(SNESLineSearch *);
557 PETSC_EXTERN PetscErrorCode SNESLineSearchSetType(SNESLineSearch, SNESLineSearchType);
558 PETSC_EXTERN PetscErrorCode SNESLineSearchSetFromOptions(SNESLineSearch);
559 PETSC_EXTERN PetscErrorCode SNESLineSearchSetFunction(SNESLineSearch,PetscErrorCode (*)(SNES,Vec,Vec));
560 PETSC_EXTERN PetscErrorCode SNESLineSearchSetUp(SNESLineSearch);
561 PETSC_EXTERN PetscErrorCode SNESLineSearchApply(SNESLineSearch, Vec, Vec, PetscReal *, Vec);
562 PETSC_EXTERN PetscErrorCode SNESLineSearchPreCheck(SNESLineSearch,Vec,Vec,PetscBool *);
563 PETSC_EXTERN PetscErrorCode SNESLineSearchPostCheck(SNESLineSearch,Vec,Vec,Vec,PetscBool *,PetscBool *);
564 PETSC_EXTERN PetscErrorCode SNESLineSearchSetWorkVecs(SNESLineSearch, PetscInt);
565 
566 /* set the functions for precheck and postcheck */
567 
568 PETSC_EXTERN PetscErrorCode SNESLineSearchSetPreCheck(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch,Vec,Vec,PetscBool*,void*), void *ctx);
569 PETSC_EXTERN PetscErrorCode SNESLineSearchSetPostCheck(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch,Vec,Vec,Vec,PetscBool *,PetscBool *,void*), void *ctx);
570 
571 PETSC_EXTERN PetscErrorCode SNESLineSearchGetPreCheck(SNESLineSearch, PetscErrorCode (**)(SNESLineSearch,Vec,Vec,PetscBool*,void*), void **ctx);
572 PETSC_EXTERN PetscErrorCode SNESLineSearchGetPostCheck(SNESLineSearch, PetscErrorCode (**)(SNESLineSearch,Vec,Vec,Vec,PetscBool *,PetscBool *,void*), void **ctx);
573 
574 /* set the functions for VI-specific line search operations */
575 
576 PETSC_EXTERN PetscErrorCode SNESLineSearchSetVIFunctions(SNESLineSearch, SNESLineSearchVIProjectFunc, SNESLineSearchVINormFunc);
577 PETSC_EXTERN PetscErrorCode SNESLineSearchGetVIFunctions(SNESLineSearch, SNESLineSearchVIProjectFunc*, SNESLineSearchVINormFunc*);
578 
579 /* pointers to the associated SNES in order to be able to get the function evaluation out */
580 PETSC_EXTERN PetscErrorCode SNESLineSearchSetSNES(SNESLineSearch,SNES);
581 PETSC_EXTERN PetscErrorCode SNESLineSearchGetSNES(SNESLineSearch,SNES*);
582 
583 /* set and get the parameters and vectors */
584 PETSC_EXTERN PetscErrorCode SNESLineSearchGetTolerances(SNESLineSearch,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscInt*);
585 PETSC_EXTERN PetscErrorCode SNESLineSearchSetTolerances(SNESLineSearch,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscInt);
586 
587 PETSC_EXTERN PetscErrorCode SNESLineSearchPreCheckPicard(SNESLineSearch,Vec,Vec,PetscBool*,void*);
588 
589 PETSC_EXTERN PetscErrorCode SNESLineSearchGetLambda(SNESLineSearch,PetscReal*);
590 PETSC_EXTERN PetscErrorCode SNESLineSearchSetLambda(SNESLineSearch,PetscReal);
591 
592 PETSC_EXTERN PetscErrorCode SNESLineSearchGetDamping(SNESLineSearch,PetscReal*);
593 PETSC_EXTERN PetscErrorCode SNESLineSearchSetDamping(SNESLineSearch,PetscReal);
594 
595 PETSC_EXTERN PetscErrorCode SNESLineSearchGetOrder(SNESLineSearch,PetscInt *order);
596 PETSC_EXTERN PetscErrorCode SNESLineSearchSetOrder(SNESLineSearch,PetscInt order);
597 
598 /*E
599     SNESLineSearchReason - if line search has succeeded or failed and why
600 
601    Level: intermediate
602 
603    Developer Notes:
604     this must match petsc/finclude/petscsnes.h
605 
606    Developer Note: The string versions of these are in SNESLineSearchReasons, if you change any value here you must
607      also adjust that array.
608 
609 .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest()
610 E*/
611 typedef enum {SNES_LINESEARCH_SUCCEEDED,
612               SNES_LINESEARCH_FAILED_NANORINF,
613               SNES_LINESEARCH_FAILED_DOMAIN,
614               SNES_LINESEARCH_FAILED_REDUCT,       /* INSUFFICENT REDUCTION */
615               SNES_LINESEARCH_FAILED_USER,
616               SNES_LINESEARCH_FAILED_FUNCTION} SNESLineSearchReason;
617 
618 PETSC_EXTERN PetscErrorCode SNESLineSearchGetReason(SNESLineSearch, SNESLineSearchReason*);
619 PETSC_EXTERN PetscErrorCode SNESLineSearchSetReason(SNESLineSearch, SNESLineSearchReason);
620 
621 PETSC_EXTERN PetscErrorCode SNESLineSearchGetVecs(SNESLineSearch,Vec*,Vec*,Vec*,Vec*,Vec*);
622 PETSC_EXTERN PetscErrorCode SNESLineSearchSetVecs(SNESLineSearch,Vec,Vec,Vec,Vec,Vec);
623 
624 PETSC_EXTERN PetscErrorCode SNESLineSearchGetNorms(SNESLineSearch, PetscReal *, PetscReal *, PetscReal *);
625 PETSC_EXTERN PetscErrorCode SNESLineSearchSetNorms(SNESLineSearch, PetscReal, PetscReal, PetscReal);
626 PETSC_EXTERN PetscErrorCode SNESLineSearchComputeNorms(SNESLineSearch);
627 PETSC_EXTERN PetscErrorCode SNESLineSearchSetComputeNorms(SNESLineSearch, PetscBool);
628 
629 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitor(SNESLineSearch);
630 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSet(SNESLineSearch,PetscErrorCode(*)(SNESLineSearch,void*),void *,PetscErrorCode (*)(void**));
631 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSetFromOptions(SNESLineSearch,const char[],const char[],const char[],PetscErrorCode (*)(SNESLineSearch,PetscViewerAndFormat*),PetscErrorCode (*)(SNESLineSearch,PetscViewerAndFormat*));
632 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorCancel(SNESLineSearch);
633 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorUpdate(SNESLineSearch,PetscViewerAndFormat*);
634 PETSC_EXTERN PetscErrorCode SNESLineSearchSetDefaultMonitor(SNESLineSearch,PetscViewer);
635 PETSC_EXTERN PetscErrorCode SNESLineSearchGetDefaultMonitor(SNESLineSearch,PetscViewer*);
636 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSolutionUpdate(SNESLineSearch,PetscViewerAndFormat*);
637 
638 PETSC_EXTERN PetscErrorCode SNESLineSearchAppendOptionsPrefix(SNESLineSearch, const char prefix[]);
639 PETSC_EXTERN PetscErrorCode SNESLineSearchGetOptionsPrefix(SNESLineSearch, const char *prefix[]);
640 
641 
642 /* Shell interface functions */
643 PETSC_EXTERN PetscErrorCode SNESLineSearchShellSetUserFunc(SNESLineSearch,SNESLineSearchUserFunc,void*);
644 PETSC_EXTERN PetscErrorCode SNESLineSearchShellGetUserFunc(SNESLineSearch,SNESLineSearchUserFunc*,void**);
645 
646 /* BT interface functions */
647 PETSC_EXTERN PetscErrorCode SNESLineSearchBTSetAlpha(SNESLineSearch, PetscReal);
648 PETSC_EXTERN PetscErrorCode SNESLineSearchBTGetAlpha(SNESLineSearch, PetscReal*);
649 
650 /*register line search types */
651 PETSC_EXTERN PetscErrorCode SNESLineSearchRegister(const char[],PetscErrorCode(*)(SNESLineSearch));
652 
653 /* Routines for VI solver */
654 PETSC_EXTERN PetscErrorCode SNESVISetVariableBounds(SNES,Vec,Vec);
655 PETSC_EXTERN PetscErrorCode SNESVISetComputeVariableBounds(SNES, PetscErrorCode (*)(SNES,Vec,Vec));
656 PETSC_EXTERN PetscErrorCode SNESVIGetInactiveSet(SNES,IS*);
657 PETSC_EXTERN PetscErrorCode SNESVIGetActiveSetIS(SNES,Vec,Vec,IS*);
658 PETSC_EXTERN PetscErrorCode SNESVIComputeInactiveSetFnorm(SNES,Vec,Vec,PetscReal*);
659 PETSC_EXTERN PetscErrorCode SNESVISetRedundancyCheck(SNES,PetscErrorCode(*)(SNES,IS,IS*,void*),void*);
660 
661 PETSC_EXTERN PetscErrorCode SNESTestLocalMin(SNES);
662 
663 /* Should this routine be private? */
664 PETSC_EXTERN PetscErrorCode SNESComputeJacobian(SNES,Vec,Mat,Mat);
665 PETSC_EXTERN PetscErrorCode SNESTestJacobian(SNES);
666 
667 PETSC_EXTERN PetscErrorCode SNESSetDM(SNES,DM);
668 PETSC_EXTERN PetscErrorCode SNESGetDM(SNES,DM*);
669 PETSC_EXTERN PetscErrorCode SNESSetNPC(SNES,SNES);
670 PETSC_EXTERN PetscErrorCode SNESGetNPC(SNES,SNES*);
671 PETSC_EXTERN PetscErrorCode SNESHasNPC(SNES,PetscBool*);
672 PETSC_EXTERN PetscErrorCode SNESApplyNPC(SNES,Vec,Vec,Vec);
673 PETSC_EXTERN PetscErrorCode SNESGetNPCFunction(SNES,Vec,PetscReal*);
674 PETSC_EXTERN PetscErrorCode SNESComputeFunctionDefaultNPC(SNES,Vec,Vec);
675 PETSC_EXTERN PetscErrorCode SNESSetNPCSide(SNES,PCSide);
676 PETSC_EXTERN PetscErrorCode SNESGetNPCSide(SNES,PCSide*);
677 PETSC_EXTERN PetscErrorCode SNESSetLineSearch(SNES,SNESLineSearch);
678 PETSC_EXTERN PetscErrorCode SNESGetLineSearch(SNES,SNESLineSearch*);
679 PETSC_EXTERN PetscErrorCode SNESRestrictHookAdd(SNES,PetscErrorCode (*)(SNES,SNES,void*),void*);
680 PETSC_EXTERN PetscErrorCode SNESRestrictHooksRun(SNES,SNES);
681 
682 PETSC_DEPRECATED("Use SNESGetLineSearch()") PETSC_STATIC_INLINE PetscErrorCode SNESGetSNESLineSearch(SNES snes,SNESLineSearch *ls) {return SNESGetLineSearch(snes,ls);}
683 PETSC_DEPRECATED("Use SNESSetLineSearch()") PETSC_STATIC_INLINE PetscErrorCode SNESSetSNESLineSearch(SNES snes,SNESLineSearch ls) {return SNESSetLineSearch(snes,ls);}
684 
685 PETSC_EXTERN PetscErrorCode SNESSetUpMatrices(SNES);
686 PETSC_EXTERN PetscErrorCode DMSNESSetFunction(DM,PetscErrorCode(*)(SNES,Vec,Vec,void*),void*);
687 PETSC_EXTERN PetscErrorCode DMSNESGetFunction(DM,PetscErrorCode(**)(SNES,Vec,Vec,void*),void**);
688 PETSC_EXTERN PetscErrorCode DMSNESSetNGS(DM,PetscErrorCode(*)(SNES,Vec,Vec,void*),void*);
689 PETSC_EXTERN PetscErrorCode DMSNESGetNGS(DM,PetscErrorCode(**)(SNES,Vec,Vec,void*),void**);
690 PETSC_EXTERN PetscErrorCode DMSNESSetJacobian(DM,PetscErrorCode(*)(SNES,Vec,Mat,Mat,void*),void*);
691 PETSC_EXTERN PetscErrorCode DMSNESGetJacobian(DM,PetscErrorCode(**)(SNES,Vec,Mat,Mat,void*),void**);
692 PETSC_EXTERN PetscErrorCode DMSNESSetPicard(DM,PetscErrorCode(*)(SNES,Vec,Vec,void*),PetscErrorCode(*)(SNES,Vec,Mat,Mat,void*),void*);
693 PETSC_EXTERN PetscErrorCode DMSNESGetPicard(DM,PetscErrorCode(**)(SNES,Vec,Vec,void*),PetscErrorCode(**)(SNES,Vec,Mat,Mat,void*),void**);
694 PETSC_EXTERN PetscErrorCode DMSNESSetObjective(DM,PetscErrorCode (*)(SNES,Vec,PetscReal *,void*),void*);
695 PETSC_EXTERN PetscErrorCode DMSNESGetObjective(DM,PetscErrorCode (**)(SNES,Vec,PetscReal *,void*),void**);
696 PETSC_EXTERN PetscErrorCode DMCopyDMSNES(DM,DM);
697 
698 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESFunction)(DMDALocalInfo*,void*,void*,void*);
699 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESJacobian)(DMDALocalInfo*,void*,Mat,Mat,void*);
700 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESObjective)(DMDALocalInfo*,void*,PetscReal*,void*);
701 
702 PETSC_EXTERN PetscErrorCode DMDASNESSetFunctionLocal(DM,InsertMode,DMDASNESFunction,void*);
703 PETSC_EXTERN PetscErrorCode DMDASNESSetJacobianLocal(DM,DMDASNESJacobian,void*);
704 PETSC_EXTERN PetscErrorCode DMDASNESSetObjectiveLocal(DM,DMDASNESObjective,void*);
705 PETSC_EXTERN PetscErrorCode DMDASNESSetPicardLocal(DM,InsertMode,PetscErrorCode (*)(DMDALocalInfo*,void*,void*,void*),PetscErrorCode (*)(DMDALocalInfo*,void*,Mat,Mat,void*),void*);
706 
707 PETSC_EXTERN PetscErrorCode DMPlexSNESGetGeometryFVM(DM,Vec*,Vec*,PetscReal*);
708 PETSC_EXTERN PetscErrorCode DMPlexSNESGetGradientDM(DM,PetscFV,DM*);
709 PETSC_EXTERN PetscErrorCode DMPlexGetCellFields(DM, IS, Vec, Vec, Vec, PetscScalar **, PetscScalar **, PetscScalar **);
710 PETSC_EXTERN PetscErrorCode DMPlexRestoreCellFields(DM, IS, Vec, Vec, Vec, PetscScalar **, PetscScalar **, PetscScalar **);
711 PETSC_EXTERN PetscErrorCode DMPlexGetFaceFields(DM, PetscInt, PetscInt, Vec, Vec, Vec, Vec, Vec, PetscInt *, PetscScalar **, PetscScalar **);
712 PETSC_EXTERN PetscErrorCode DMPlexRestoreFaceFields(DM, PetscInt, PetscInt, Vec, Vec, Vec, Vec, Vec, PetscInt *, PetscScalar **, PetscScalar **);
713 PETSC_EXTERN PetscErrorCode DMPlexGetFaceGeometry(DM, PetscInt, PetscInt, Vec, Vec, PetscInt *, PetscFVFaceGeom **, PetscReal **);
714 PETSC_EXTERN PetscErrorCode DMPlexRestoreFaceGeometry(DM, PetscInt, PetscInt, Vec, Vec, PetscInt *, PetscFVFaceGeom **, PetscReal **);
715 
716 PETSC_EXTERN PetscErrorCode DMSNESSetBoundaryLocal(DM,PetscErrorCode (*)(DM,Vec,void*),void*);
717 PETSC_EXTERN PetscErrorCode DMSNESSetFunctionLocal(DM,PetscErrorCode (*)(DM,Vec,Vec,void*),void*);
718 PETSC_EXTERN PetscErrorCode DMSNESSetJacobianLocal(DM,PetscErrorCode (*)(DM,Vec,Mat,Mat,void*),void*);
719 
720 /* Routines for Multiblock solver */
721 PETSC_EXTERN PetscErrorCode SNESMultiblockSetFields(SNES, const char [], PetscInt, const PetscInt *);
722 PETSC_EXTERN PetscErrorCode SNESMultiblockSetIS(SNES, const char [], IS);
723 PETSC_EXTERN PetscErrorCode SNESMultiblockSetBlockSize(SNES, PetscInt);
724 PETSC_EXTERN PetscErrorCode SNESMultiblockSetType(SNES, PCCompositeType);
725 
726 /*J
727     SNESMSType - String with the name of a PETSc SNESMS method.
728 
729    Level: intermediate
730 
731 .seealso: SNESMSSetType(), SNES
732 J*/
733 typedef const char* SNESMSType;
734 #define SNESMSM62       "m62"
735 #define SNESMSEULER     "euler"
736 #define SNESMSJAMESON83 "jameson83"
737 #define SNESMSVLTP21    "vltp21"
738 #define SNESMSVLTP31    "vltp31"
739 #define SNESMSVLTP41    "vltp41"
740 #define SNESMSVLTP51    "vltp51"
741 #define SNESMSVLTP61    "vltp61"
742 
743 PETSC_EXTERN PetscErrorCode SNESMSRegister(SNESMSType,PetscInt,PetscInt,PetscReal,const PetscReal[],const PetscReal[],const PetscReal[]);
744 PETSC_EXTERN PetscErrorCode SNESMSSetType(SNES,SNESMSType);
745 PETSC_EXTERN PetscErrorCode SNESMSFinalizePackage(void);
746 PETSC_EXTERN PetscErrorCode SNESMSInitializePackage(void);
747 PETSC_EXTERN PetscErrorCode SNESMSRegisterDestroy(void);
748 
749 /* routines for NGMRES solver */
750 
751 typedef enum {
752   SNES_NGMRES_RESTART_NONE       = 0,
753   SNES_NGMRES_RESTART_PERIODIC   = 1,
754   SNES_NGMRES_RESTART_DIFFERENCE = 2} SNESNGMRESRestartType;
755 PETSC_EXTERN const char *const SNESNGMRESRestartTypes[];
756 
757 typedef enum {
758   SNES_NGMRES_SELECT_NONE       = 0,
759   SNES_NGMRES_SELECT_DIFFERENCE = 1,
760   SNES_NGMRES_SELECT_LINESEARCH = 2} SNESNGMRESSelectType;
761 PETSC_EXTERN const char *const SNESNGMRESSelectTypes[];
762 
763 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartType(SNES, SNESNGMRESRestartType);
764 PETSC_EXTERN PetscErrorCode SNESNGMRESSetSelectType(SNES, SNESNGMRESSelectType);
765 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartFmRise(SNES, PetscBool);
766 PETSC_EXTERN PetscErrorCode SNESNGMRESGetRestartFmRise(SNES, PetscBool*);
767 
768 /* routines for NCG solver */
769 
770 typedef enum {
771   SNES_NCG_FR    = 0,
772   SNES_NCG_PRP   = 1,
773   SNES_NCG_HS    = 2,
774   SNES_NCG_DY    = 3,
775   SNES_NCG_CD    = 4} SNESNCGType;
776 PETSC_EXTERN const char *const SNESNCGTypes[];
777 
778 PETSC_EXTERN PetscErrorCode SNESNCGSetType(SNES, SNESNCGType);
779 
780 typedef enum {SNES_QN_SCALE_DEFAULT    = 0,
781               SNES_QN_SCALE_NONE       = 1,
782               SNES_QN_SCALE_SHANNO     = 2,
783               SNES_QN_SCALE_LINESEARCH = 3,
784               SNES_QN_SCALE_JACOBIAN   = 4} SNESQNScaleType;
785 PETSC_EXTERN const char *const SNESQNScaleTypes[];
786 typedef enum {SNES_QN_RESTART_DEFAULT  = 0,
787               SNES_QN_RESTART_NONE     = 1,
788               SNES_QN_RESTART_POWELL   = 2,
789               SNES_QN_RESTART_PERIODIC = 3} SNESQNRestartType;
790 PETSC_EXTERN const char *const SNESQNRestartTypes[];
791 typedef enum {SNES_QN_LBFGS      = 0,
792               SNES_QN_BROYDEN    = 1,
793               SNES_QN_BADBROYDEN = 2
794              } SNESQNType;
795 PETSC_EXTERN const char *const SNESQNTypes[];
796 
797 PETSC_EXTERN PetscErrorCode SNESQNSetType(SNES, SNESQNType);
798 PETSC_EXTERN PetscErrorCode SNESQNSetScaleType(SNES, SNESQNScaleType);
799 PETSC_EXTERN PetscErrorCode SNESQNSetRestartType(SNES, SNESQNRestartType);
800 
801 PETSC_EXTERN PetscErrorCode SNESNASMGetType(SNES,PCASMType*);
802 PETSC_EXTERN PetscErrorCode SNESNASMSetType(SNES,PCASMType);
803 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomains(SNES,PetscInt*,SNES**,VecScatter**,VecScatter**,VecScatter**);
804 PETSC_EXTERN PetscErrorCode SNESNASMSetSubdomains(SNES,PetscInt,SNES*,VecScatter*,VecScatter*,VecScatter*);
805 PETSC_EXTERN PetscErrorCode SNESNASMSetDamping(SNES,PetscReal);
806 PETSC_EXTERN PetscErrorCode SNESNASMGetDamping(SNES,PetscReal*);
807 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomainVecs(SNES,PetscInt*,Vec**,Vec**,Vec**,Vec**);
808 PETSC_EXTERN PetscErrorCode SNESNASMSetComputeFinalJacobian(SNES,PetscBool);
809 PETSC_EXTERN PetscErrorCode SNESNASMGetSNES(SNES,PetscInt,SNES *);
810 PETSC_EXTERN PetscErrorCode SNESNASMGetNumber(SNES,PetscInt*);
811 PETSC_EXTERN PetscErrorCode SNESNASMSetWeight(SNES,Vec);
812 
813 typedef enum {SNES_COMPOSITE_ADDITIVE,SNES_COMPOSITE_MULTIPLICATIVE,SNES_COMPOSITE_ADDITIVEOPTIMAL} SNESCompositeType;
814 PETSC_EXTERN const char *const SNESCompositeTypes[];
815 
816 PETSC_EXTERN PetscErrorCode SNESCompositeSetType(SNES,SNESCompositeType);
817 PETSC_EXTERN PetscErrorCode SNESCompositeAddSNES(SNES,SNESType);
818 PETSC_EXTERN PetscErrorCode SNESCompositeGetSNES(SNES,PetscInt,SNES *);
819 PETSC_EXTERN PetscErrorCode SNESCompositeGetNumber(SNES,PetscInt*);
820 PETSC_EXTERN PetscErrorCode SNESCompositeSetDamping(SNES,PetscInt,PetscReal);
821 
822 /*E
823     SNESFASType - Determines the type of nonlinear multigrid method that is run.
824 
825    Level: beginner
826 
827    Values:
828 +  SNES_FAS_MULTIPLICATIVE (default) - traditional V or W cycle as determined by SNESFASSetCycles()
829 .  SNES_FAS_ADDITIVE                 - additive FAS cycle
830 .  SNES_FAS_FULL                     - full FAS cycle
831 -  SNES_FAS_KASKADE                  - Kaskade FAS cycle
832 .seealso: PCMGSetType(), PCMGType
833 
834 E*/
835 typedef enum { SNES_FAS_MULTIPLICATIVE, SNES_FAS_ADDITIVE, SNES_FAS_FULL, SNES_FAS_KASKADE } SNESFASType;
836 PETSC_EXTERN const char *const  SNESFASTypes[];
837 
838 /* called on the finest level FAS instance*/
839 PETSC_EXTERN PetscErrorCode SNESFASSetType(SNES, SNESFASType);
840 PETSC_EXTERN PetscErrorCode SNESFASGetType(SNES, SNESFASType*);
841 PETSC_EXTERN PetscErrorCode SNESFASSetLevels(SNES, PetscInt, MPI_Comm *);
842 PETSC_EXTERN PetscErrorCode SNESFASGetLevels(SNES, PetscInt *);
843 PETSC_EXTERN PetscErrorCode SNESFASGetCycleSNES(SNES, PetscInt, SNES*);
844 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothUp(SNES, PetscInt);
845 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothDown(SNES, PetscInt);
846 PETSC_EXTERN PetscErrorCode SNESFASSetCycles(SNES, PetscInt);
847 PETSC_EXTERN PetscErrorCode SNESFASSetMonitor(SNES, PetscViewerAndFormat *, PetscBool);
848 PETSC_EXTERN PetscErrorCode SNESFASSetLog(SNES, PetscBool);
849 
850 PETSC_EXTERN PetscErrorCode SNESFASSetGalerkin(SNES, PetscBool);
851 PETSC_EXTERN PetscErrorCode SNESFASGetGalerkin(SNES, PetscBool*);
852 PETSC_EXTERN PetscErrorCode SNESFASGalerkinFunctionDefault(SNES,Vec,Vec,void*);
853 
854 /* called on any level -- "Cycle" FAS instance */
855 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmoother(SNES, SNES*);
856 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherUp(SNES, SNES*);
857 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherDown(SNES, SNES*);
858 PETSC_EXTERN PetscErrorCode SNESFASCycleGetCorrection(SNES, SNES*);
859 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInterpolation(SNES, Mat*);
860 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRestriction(SNES, Mat*);
861 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInjection(SNES, Mat*);
862 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRScale(SNES, Vec*);
863 PETSC_EXTERN PetscErrorCode SNESFASCycleSetCycles(SNES, PetscInt);
864 PETSC_EXTERN PetscErrorCode SNESFASCycleIsFine(SNES, PetscBool*);
865 
866 /* called on the (outer) finest level FAS to set/get parameters on any level instance */
867 PETSC_EXTERN PetscErrorCode SNESFASSetInterpolation(SNES, PetscInt, Mat);
868 PETSC_EXTERN PetscErrorCode SNESFASGetInterpolation(SNES, PetscInt, Mat*);
869 PETSC_EXTERN PetscErrorCode SNESFASSetRestriction(SNES, PetscInt, Mat);
870 PETSC_EXTERN PetscErrorCode SNESFASGetRestriction(SNES, PetscInt, Mat*);
871 PETSC_EXTERN PetscErrorCode SNESFASSetInjection(SNES, PetscInt, Mat);
872 PETSC_EXTERN PetscErrorCode SNESFASGetInjection(SNES, PetscInt, Mat*);
873 PETSC_EXTERN PetscErrorCode SNESFASSetRScale(SNES, PetscInt, Vec);
874 PETSC_EXTERN PetscErrorCode SNESFASGetRScale(SNES, PetscInt, Vec*);
875 PETSC_EXTERN PetscErrorCode SNESFASSetContinuation(SNES,PetscBool);
876 
877 PETSC_EXTERN PetscErrorCode SNESFASGetSmoother(SNES,     PetscInt, SNES*);
878 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherUp(SNES,   PetscInt, SNES*);
879 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherDown(SNES, PetscInt, SNES*);
880 PETSC_EXTERN PetscErrorCode SNESFASGetCoarseSolve(SNES, SNES*);
881 
882 /* parameters for full FAS */
883 PETSC_EXTERN PetscErrorCode SNESFASFullSetDownSweep(SNES,PetscBool);
884 PETSC_EXTERN PetscErrorCode SNESFASCreateCoarseVec(SNES,Vec*);
885 PETSC_EXTERN PetscErrorCode SNESFASRestrict(SNES,Vec,Vec);
886 
887 PETSC_EXTERN PetscErrorCode DMSNESCheckFromOptions(SNES,Vec,PetscErrorCode (**)(PetscInt,PetscReal,const PetscReal[],PetscInt,PetscScalar*,void*),void**);
888 
889 #endif
890