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