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