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 SNESPruneJacobianColor(SNES, Mat, Mat); 403 PETSC_EXTERN PetscErrorCode SNESSetComputeInitialGuess(SNES, PetscErrorCode (*)(SNES, Vec, void *), void *); 404 PETSC_EXTERN PetscErrorCode SNESSetPicard(SNES, Vec, PetscErrorCode (*)(SNES, Vec, Vec, void *), Mat, Mat, PetscErrorCode (*)(SNES, Vec, Mat, Mat, void *), void *); 405 PETSC_EXTERN PetscErrorCode SNESGetPicard(SNES, Vec *, PetscErrorCode (**)(SNES, Vec, Vec, void *), Mat *, Mat *, PetscErrorCode (**)(SNES, Vec, Mat, Mat, void *), void **); 406 PETSC_EXTERN PetscErrorCode SNESPicardComputeFunction(SNES, Vec, Vec, void *); 407 PETSC_EXTERN PetscErrorCode SNESPicardComputeMFFunction(SNES, Vec, Vec, void *); 408 PETSC_EXTERN PetscErrorCode SNESPicardComputeJacobian(SNES, Vec, Mat, Mat, void *); 409 410 PETSC_EXTERN PetscErrorCode SNESSetObjective(SNES, PetscErrorCode (*)(SNES, Vec, PetscReal *, void *), void *); 411 PETSC_EXTERN PetscErrorCode SNESGetObjective(SNES, PetscErrorCode (**)(SNES, Vec, PetscReal *, void *), void **); 412 PETSC_EXTERN PetscErrorCode SNESComputeObjective(SNES, Vec, PetscReal *); 413 414 /*E 415 SNESNormSchedule - Frequency with which the norm is computed 416 417 Level: advanced 418 419 Support for these is highly dependent on the solver. 420 421 Notes: 422 This is primarily used to turn off extra norm and function computation 423 when the solvers are composed. 424 425 .seealso: `SNESSolve()`, `SNESGetConvergedReason()`, `KSPSetNormType()`, 426 `KSPSetConvergenceTest()`, `KSPSetPCSide()` 427 E*/ 428 429 typedef enum { 430 SNES_NORM_DEFAULT = -1, 431 SNES_NORM_NONE = 0, 432 SNES_NORM_ALWAYS = 1, 433 SNES_NORM_INITIAL_ONLY = 2, 434 SNES_NORM_FINAL_ONLY = 3, 435 SNES_NORM_INITIAL_FINAL_ONLY = 4 436 } SNESNormSchedule; 437 PETSC_EXTERN const char *const *const SNESNormSchedules; 438 439 /*MC 440 SNES_NORM_NONE - Don't compute function and its L2 norm. 441 442 Level: advanced 443 444 Notes: 445 This is most useful for stationary solvers with a fixed number of iterations used as smoothers. 446 447 .seealso: `SNESNormSchedule`, `SNESSetNormSchedule()`, `SNES_NORM_DEFAULT` 448 M*/ 449 450 /*MC 451 SNES_NORM_ALWAYS - Compute the function and its L2 norm at each iteration. 452 453 Level: advanced 454 455 Notes: 456 Most solvers will use this no matter what norm type is passed to them. 457 458 .seealso: `SNESNormSchedule`, `SNESSetNormSchedule()`, `SNES_NORM_NONE` 459 M*/ 460 461 /*MC 462 SNES_NORM_INITIAL_ONLY - Compute the function and its L2 at iteration 0, but do not update it. 463 464 Level: advanced 465 466 Notes: 467 This method is useful in composed methods, when a true solution might actually be found before SNESSolve() is called. 468 This option enables the solve to abort on the zeroth iteration if this is the case. 469 470 For solvers that require the computation of the L2 norm of the function as part of the method, this merely cancels 471 the norm computation at the last iteration (if possible). 472 473 .seealso: `SNESNormSchedule`, `SNESSetNormSchedule()`, `SNES_NORM_FINAL_ONLY`, `SNES_NORM_INITIAL_FINAL_ONLY` 474 M*/ 475 476 /*MC 477 SNES_NORM_FINAL_ONLY - Compute the function and its L2 norm on only the final iteration. 478 479 Level: advanced 480 481 Notes: 482 For solvers that require the computation of the L2 norm of the function as part of the method, behaves 483 exactly as `SNES_NORM_DEFAULT`. This method is useful when the function is gotten after `SNESSolve()` and 484 used in subsequent computation for methods that do not need the norm computed during the rest of the 485 solution procedure. 486 487 .seealso: `SNESNormSchedule`, `SNESSetNormSchedule()`, `SNES_NORM_INITIAL_ONLY`, `SNES_NORM_INITIAL_FINAL_ONLY` 488 M*/ 489 490 /*MC 491 SNES_NORM_INITIAL_FINAL_ONLY - Compute the function and its L2 norm on only the initial and final iterations. 492 493 Level: advanced 494 495 Notes: 496 This method combines the benefits of `SNES_NORM_INITIAL_ONLY` and `SNES_NORM_FINAL_ONLY`. 497 498 .seealso: `SNESNormSchedule`, `SNESSetNormSchedule()`, `SNES_NORM_SNES_NORM_INITIAL_ONLY`, `SNES_NORM_FINAL_ONLY` 499 M*/ 500 501 PETSC_EXTERN PetscErrorCode SNESSetNormSchedule(SNES, SNESNormSchedule); 502 PETSC_EXTERN PetscErrorCode SNESGetNormSchedule(SNES, SNESNormSchedule *); 503 PETSC_EXTERN PetscErrorCode SNESSetFunctionNorm(SNES, PetscReal); 504 PETSC_EXTERN PetscErrorCode SNESGetFunctionNorm(SNES, PetscReal *); 505 PETSC_EXTERN PetscErrorCode SNESGetUpdateNorm(SNES, PetscReal *); 506 PETSC_EXTERN PetscErrorCode SNESGetSolutionNorm(SNES, PetscReal *); 507 508 /*E 509 SNESFunctionType - Type of function computed 510 511 Level: advanced 512 513 Support for these is highly dependent on the solver. 514 515 .seealso: `SNESSolve()`, `SNESGetConvergedReason()`, `KSPSetNormType()`, 516 `KSPSetConvergenceTest()`, `KSPSetPCSide()` 517 E*/ 518 typedef enum { 519 SNES_FUNCTION_DEFAULT = -1, 520 SNES_FUNCTION_UNPRECONDITIONED = 0, 521 SNES_FUNCTION_PRECONDITIONED = 1 522 } SNESFunctionType; 523 PETSC_EXTERN const char *const *const SNESFunctionTypes; 524 525 PETSC_EXTERN PetscErrorCode SNESSetFunctionType(SNES, SNESFunctionType); 526 PETSC_EXTERN PetscErrorCode SNESGetFunctionType(SNES, SNESFunctionType *); 527 528 PETSC_EXTERN PetscErrorCode SNESSetNGS(SNES, PetscErrorCode (*)(SNES, Vec, Vec, void *), void *); 529 PETSC_EXTERN PetscErrorCode SNESGetNGS(SNES, PetscErrorCode (**)(SNES, Vec, Vec, void *), void **); 530 PETSC_EXTERN PetscErrorCode SNESComputeNGS(SNES, Vec, Vec); 531 532 PETSC_EXTERN PetscErrorCode SNESNGSSetSweeps(SNES, PetscInt); 533 PETSC_EXTERN PetscErrorCode SNESNGSGetSweeps(SNES, PetscInt *); 534 PETSC_EXTERN PetscErrorCode SNESNGSSetTolerances(SNES, PetscReal, PetscReal, PetscReal, PetscInt); 535 PETSC_EXTERN PetscErrorCode SNESNGSGetTolerances(SNES, PetscReal *, PetscReal *, PetscReal *, PetscInt *); 536 537 PETSC_EXTERN PetscErrorCode SNESSetAlwaysComputesFinalResidual(SNES, PetscBool); 538 PETSC_EXTERN PetscErrorCode SNESGetAlwaysComputesFinalResidual(SNES, PetscBool *); 539 540 PETSC_EXTERN PetscErrorCode SNESShellGetContext(SNES, void *); 541 PETSC_EXTERN PetscErrorCode SNESShellSetContext(SNES, void *); 542 PETSC_EXTERN PetscErrorCode SNESShellSetSolve(SNES, PetscErrorCode (*)(SNES, Vec)); 543 544 /* --------- Routines specifically for line search methods --------------- */ 545 546 /*S 547 SNESLineSearch - Abstract PETSc object that manages line-search operations for nonlinear solvers 548 549 Level: beginner 550 551 .seealso: `SNESLineSearchCreate()`, `SNESLineSearchSetType()`, `SNES` 552 S*/ 553 typedef struct _p_LineSearch *SNESLineSearch; 554 555 /*J 556 SNESLineSearchType - String with the name of a PETSc line search method 557 558 Level: beginner 559 560 .seealso: `SNESLineSearchSetType()`, `SNES` 561 J*/ 562 typedef const char *SNESLineSearchType; 563 #define SNESLINESEARCHBT "bt" 564 #define SNESLINESEARCHNLEQERR "nleqerr" 565 #define SNESLINESEARCHBASIC "basic" 566 #define SNESLINESEARCHNONE "none" 567 #define SNESLINESEARCHL2 "l2" 568 #define SNESLINESEARCHCP "cp" 569 #define SNESLINESEARCHSHELL "shell" 570 #define SNESLINESEARCHNCGLINEAR "ncglinear" 571 572 PETSC_EXTERN PetscFunctionList SNESList; 573 PETSC_EXTERN PetscClassId SNESLINESEARCH_CLASSID; 574 PETSC_EXTERN PetscFunctionList SNESLineSearchList; 575 576 #define SNES_LINESEARCH_ORDER_LINEAR 1 577 #define SNES_LINESEARCH_ORDER_QUADRATIC 2 578 #define SNES_LINESEARCH_ORDER_CUBIC 3 579 580 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*SNESLineSearchVIProjectFunc)(SNES, Vec); 581 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*SNESLineSearchVINormFunc)(SNES, Vec, Vec, PetscReal *); 582 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*SNESLineSearchApplyFunc)(SNESLineSearch); 583 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*SNESLineSearchUserFunc)(SNESLineSearch, void *); 584 585 PETSC_EXTERN PetscErrorCode SNESLineSearchCreate(MPI_Comm, SNESLineSearch *); 586 PETSC_EXTERN PetscErrorCode SNESLineSearchReset(SNESLineSearch); 587 PETSC_EXTERN PetscErrorCode SNESLineSearchView(SNESLineSearch, PetscViewer); 588 PETSC_EXTERN PetscErrorCode SNESLineSearchDestroy(SNESLineSearch *); 589 PETSC_EXTERN PetscErrorCode SNESLineSearchGetType(SNESLineSearch, SNESLineSearchType *); 590 PETSC_EXTERN PetscErrorCode SNESLineSearchSetType(SNESLineSearch, SNESLineSearchType); 591 PETSC_EXTERN PetscErrorCode SNESLineSearchSetFromOptions(SNESLineSearch); 592 PETSC_EXTERN PetscErrorCode SNESLineSearchSetFunction(SNESLineSearch, PetscErrorCode (*)(SNES, Vec, Vec)); 593 PETSC_EXTERN PetscErrorCode SNESLineSearchSetUp(SNESLineSearch); 594 PETSC_EXTERN PetscErrorCode SNESLineSearchApply(SNESLineSearch, Vec, Vec, PetscReal *, Vec); 595 PETSC_EXTERN PetscErrorCode SNESLineSearchPreCheck(SNESLineSearch, Vec, Vec, PetscBool *); 596 PETSC_EXTERN PetscErrorCode SNESLineSearchPostCheck(SNESLineSearch, Vec, Vec, Vec, PetscBool *, PetscBool *); 597 PETSC_EXTERN PetscErrorCode SNESLineSearchSetWorkVecs(SNESLineSearch, PetscInt); 598 599 /* set the functions for precheck and postcheck */ 600 601 PETSC_EXTERN PetscErrorCode SNESLineSearchSetPreCheck(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch, Vec, Vec, PetscBool *, void *), void *ctx); 602 PETSC_EXTERN PetscErrorCode SNESLineSearchSetPostCheck(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void *ctx); 603 604 PETSC_EXTERN PetscErrorCode SNESLineSearchGetPreCheck(SNESLineSearch, PetscErrorCode (**)(SNESLineSearch, Vec, Vec, PetscBool *, void *), void **ctx); 605 PETSC_EXTERN PetscErrorCode SNESLineSearchGetPostCheck(SNESLineSearch, PetscErrorCode (**)(SNESLineSearch, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void **ctx); 606 607 /* set the functions for VI-specific line search operations */ 608 609 PETSC_EXTERN PetscErrorCode SNESLineSearchSetVIFunctions(SNESLineSearch, SNESLineSearchVIProjectFunc, SNESLineSearchVINormFunc); 610 PETSC_EXTERN PetscErrorCode SNESLineSearchGetVIFunctions(SNESLineSearch, SNESLineSearchVIProjectFunc *, SNESLineSearchVINormFunc *); 611 612 /* pointers to the associated SNES in order to be able to get the function evaluation out */ 613 PETSC_EXTERN PetscErrorCode SNESLineSearchSetSNES(SNESLineSearch, SNES); 614 PETSC_EXTERN PetscErrorCode SNESLineSearchGetSNES(SNESLineSearch, SNES *); 615 616 /* set and get the parameters and vectors */ 617 PETSC_EXTERN PetscErrorCode SNESLineSearchGetTolerances(SNESLineSearch, PetscReal *, PetscReal *, PetscReal *, PetscReal *, PetscReal *, PetscInt *); 618 PETSC_EXTERN PetscErrorCode SNESLineSearchSetTolerances(SNESLineSearch, PetscReal, PetscReal, PetscReal, PetscReal, PetscReal, PetscInt); 619 620 PETSC_EXTERN PetscErrorCode SNESLineSearchPreCheckPicard(SNESLineSearch, Vec, Vec, PetscBool *, void *); 621 622 PETSC_EXTERN PetscErrorCode SNESLineSearchGetLambda(SNESLineSearch, PetscReal *); 623 PETSC_EXTERN PetscErrorCode SNESLineSearchSetLambda(SNESLineSearch, PetscReal); 624 625 PETSC_EXTERN PetscErrorCode SNESLineSearchGetDamping(SNESLineSearch, PetscReal *); 626 PETSC_EXTERN PetscErrorCode SNESLineSearchSetDamping(SNESLineSearch, PetscReal); 627 628 PETSC_EXTERN PetscErrorCode SNESLineSearchGetOrder(SNESLineSearch, PetscInt *order); 629 PETSC_EXTERN PetscErrorCode SNESLineSearchSetOrder(SNESLineSearch, PetscInt order); 630 631 /*E 632 SNESLineSearchReason - if line search has succeeded or failed and why 633 634 Level: intermediate 635 636 Developer Notes: 637 This must match petsc/finclude/petscsnes.h 638 639 The string versions of these are in `SNESLineSearchReasons`, if you change any value here you must 640 also adjust that array. 641 642 .seealso: `SNESSolve()`, `SNESGetConvergedReason()`, `KSPConvergedReason`, `SNESSetConvergenceTest()` 643 E*/ 644 typedef enum { 645 SNES_LINESEARCH_SUCCEEDED, 646 SNES_LINESEARCH_FAILED_NANORINF, 647 SNES_LINESEARCH_FAILED_DOMAIN, 648 SNES_LINESEARCH_FAILED_REDUCT, /* INSUFFICIENT REDUCTION */ 649 SNES_LINESEARCH_FAILED_USER, 650 SNES_LINESEARCH_FAILED_FUNCTION 651 } SNESLineSearchReason; 652 653 PETSC_EXTERN PetscErrorCode SNESLineSearchGetReason(SNESLineSearch, SNESLineSearchReason *); 654 PETSC_EXTERN PetscErrorCode SNESLineSearchSetReason(SNESLineSearch, SNESLineSearchReason); 655 656 PETSC_EXTERN PetscErrorCode SNESLineSearchGetVecs(SNESLineSearch, Vec *, Vec *, Vec *, Vec *, Vec *); 657 PETSC_EXTERN PetscErrorCode SNESLineSearchSetVecs(SNESLineSearch, Vec, Vec, Vec, Vec, Vec); 658 659 PETSC_EXTERN PetscErrorCode SNESLineSearchGetNorms(SNESLineSearch, PetscReal *, PetscReal *, PetscReal *); 660 PETSC_EXTERN PetscErrorCode SNESLineSearchSetNorms(SNESLineSearch, PetscReal, PetscReal, PetscReal); 661 PETSC_EXTERN PetscErrorCode SNESLineSearchComputeNorms(SNESLineSearch); 662 PETSC_EXTERN PetscErrorCode SNESLineSearchSetComputeNorms(SNESLineSearch, PetscBool); 663 664 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitor(SNESLineSearch); 665 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSet(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch, void *), void *, PetscErrorCode (*)(void **)); 666 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSetFromOptions(SNESLineSearch, const char[], const char[], const char[], PetscErrorCode (*)(SNESLineSearch, PetscViewerAndFormat *), PetscErrorCode (*)(SNESLineSearch, PetscViewerAndFormat *)); 667 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorCancel(SNESLineSearch); 668 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorUpdate(SNESLineSearch, PetscViewerAndFormat *); 669 PETSC_EXTERN PetscErrorCode SNESLineSearchSetDefaultMonitor(SNESLineSearch, PetscViewer); 670 PETSC_EXTERN PetscErrorCode SNESLineSearchGetDefaultMonitor(SNESLineSearch, PetscViewer *); 671 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSolutionUpdate(SNESLineSearch, PetscViewerAndFormat *); 672 673 PETSC_EXTERN PetscErrorCode SNESLineSearchAppendOptionsPrefix(SNESLineSearch, const char prefix[]); 674 PETSC_EXTERN PetscErrorCode SNESLineSearchGetOptionsPrefix(SNESLineSearch, const char *prefix[]); 675 676 /* Shell interface functions */ 677 PETSC_EXTERN PetscErrorCode SNESLineSearchShellSetUserFunc(SNESLineSearch, SNESLineSearchUserFunc, void *); 678 PETSC_EXTERN PetscErrorCode SNESLineSearchShellGetUserFunc(SNESLineSearch, SNESLineSearchUserFunc *, void **); 679 680 /* BT interface functions */ 681 PETSC_EXTERN PetscErrorCode SNESLineSearchBTSetAlpha(SNESLineSearch, PetscReal); 682 PETSC_EXTERN PetscErrorCode SNESLineSearchBTGetAlpha(SNESLineSearch, PetscReal *); 683 684 /*register line search types */ 685 PETSC_EXTERN PetscErrorCode SNESLineSearchRegister(const char[], PetscErrorCode (*)(SNESLineSearch)); 686 687 /* Routines for VI solver */ 688 PETSC_EXTERN PetscErrorCode SNESVISetVariableBounds(SNES, Vec, Vec); 689 PETSC_EXTERN PetscErrorCode SNESVISetComputeVariableBounds(SNES, PetscErrorCode (*)(SNES, Vec, Vec)); 690 PETSC_EXTERN PetscErrorCode SNESVIGetInactiveSet(SNES, IS *); 691 PETSC_EXTERN PetscErrorCode SNESVIGetActiveSetIS(SNES, Vec, Vec, IS *); 692 PETSC_EXTERN PetscErrorCode SNESVIComputeInactiveSetFnorm(SNES, Vec, Vec, PetscReal *); 693 PETSC_EXTERN PetscErrorCode SNESVISetRedundancyCheck(SNES, PetscErrorCode (*)(SNES, IS, IS *, void *), void *); 694 PETSC_EXTERN PetscErrorCode SNESVIComputeMeritFunction(Vec, PetscReal *, PetscReal *); 695 PETSC_EXTERN PetscErrorCode SNESVIComputeFunction(SNES, Vec, Vec, void *); 696 PETSC_EXTERN PetscErrorCode DMSetVI(DM, IS); 697 PETSC_EXTERN PetscErrorCode DMDestroyVI(DM); 698 699 PETSC_EXTERN PetscErrorCode SNESTestLocalMin(SNES); 700 701 /* Should this routine be private? */ 702 PETSC_EXTERN PetscErrorCode SNESComputeJacobian(SNES, Vec, Mat, Mat); 703 PETSC_EXTERN PetscErrorCode SNESTestJacobian(SNES); 704 705 PETSC_EXTERN PetscErrorCode SNESSetDM(SNES, DM); 706 PETSC_EXTERN PetscErrorCode SNESGetDM(SNES, DM *); 707 PETSC_EXTERN PetscErrorCode SNESSetNPC(SNES, SNES); 708 PETSC_EXTERN PetscErrorCode SNESGetNPC(SNES, SNES *); 709 PETSC_EXTERN PetscErrorCode SNESHasNPC(SNES, PetscBool *); 710 PETSC_EXTERN PetscErrorCode SNESApplyNPC(SNES, Vec, Vec, Vec); 711 PETSC_EXTERN PetscErrorCode SNESGetNPCFunction(SNES, Vec, PetscReal *); 712 PETSC_EXTERN PetscErrorCode SNESComputeFunctionDefaultNPC(SNES, Vec, Vec); 713 PETSC_EXTERN PetscErrorCode SNESSetNPCSide(SNES, PCSide); 714 PETSC_EXTERN PetscErrorCode SNESGetNPCSide(SNES, PCSide *); 715 PETSC_EXTERN PetscErrorCode SNESSetLineSearch(SNES, SNESLineSearch); 716 PETSC_EXTERN PetscErrorCode SNESGetLineSearch(SNES, SNESLineSearch *); 717 PETSC_EXTERN PetscErrorCode SNESRestrictHookAdd(SNES, PetscErrorCode (*)(SNES, SNES, void *), void *); 718 719 PETSC_DEPRECATED_FUNCTION("Use SNESGetLineSearch() (since version 3.4)") static inline PetscErrorCode SNESGetSNESLineSearch(SNES snes, SNESLineSearch *ls) 720 { 721 return SNESGetLineSearch(snes, ls); 722 } 723 PETSC_DEPRECATED_FUNCTION("Use SNESSetLineSearch() (since version 3.4)") static inline PetscErrorCode SNESSetSNESLineSearch(SNES snes, SNESLineSearch ls) 724 { 725 return SNESSetLineSearch(snes, ls); 726 } 727 728 PETSC_EXTERN PetscErrorCode SNESSetUpMatrices(SNES); 729 PETSC_EXTERN PetscErrorCode DMSNESSetFunction(DM, PetscErrorCode (*)(SNES, Vec, Vec, void *), void *); 730 PETSC_EXTERN PetscErrorCode DMSNESGetFunction(DM, PetscErrorCode (**)(SNES, Vec, Vec, void *), void **); 731 PETSC_EXTERN PetscErrorCode DMSNESSetFunctionContextDestroy(DM, PetscErrorCode (*)(void *)); 732 PETSC_EXTERN PetscErrorCode DMSNESSetMFFunction(DM, PetscErrorCode (*)(SNES, Vec, Vec, void *), void *); 733 PETSC_EXTERN PetscErrorCode DMSNESSetNGS(DM, PetscErrorCode (*)(SNES, Vec, Vec, void *), void *); 734 PETSC_EXTERN PetscErrorCode DMSNESGetNGS(DM, PetscErrorCode (**)(SNES, Vec, Vec, void *), void **); 735 PETSC_EXTERN PetscErrorCode DMSNESSetJacobian(DM, PetscErrorCode (*)(SNES, Vec, Mat, Mat, void *), void *); 736 PETSC_EXTERN PetscErrorCode DMSNESGetJacobian(DM, PetscErrorCode (**)(SNES, Vec, Mat, Mat, void *), void **); 737 PETSC_EXTERN PetscErrorCode DMSNESSetJacobianContextDestroy(DM, PetscErrorCode (*)(void *)); 738 PETSC_EXTERN PetscErrorCode DMSNESSetPicard(DM, PetscErrorCode (*)(SNES, Vec, Vec, void *), PetscErrorCode (*)(SNES, Vec, Mat, Mat, void *), void *); 739 PETSC_EXTERN PetscErrorCode DMSNESGetPicard(DM, PetscErrorCode (**)(SNES, Vec, Vec, void *), PetscErrorCode (**)(SNES, Vec, Mat, Mat, void *), void **); 740 PETSC_EXTERN PetscErrorCode DMSNESSetObjective(DM, PetscErrorCode (*)(SNES, Vec, PetscReal *, void *), void *); 741 PETSC_EXTERN PetscErrorCode DMSNESGetObjective(DM, PetscErrorCode (**)(SNES, Vec, PetscReal *, void *), void **); 742 PETSC_EXTERN PetscErrorCode DMCopyDMSNES(DM, DM); 743 744 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESFunction)(DMDALocalInfo *, void *, void *, void *); 745 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESJacobian)(DMDALocalInfo *, void *, Mat, Mat, void *); 746 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESObjective)(DMDALocalInfo *, void *, PetscReal *, void *); 747 748 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESFunctionVec)(DMDALocalInfo *, Vec, Vec, void *); 749 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESJacobianVec)(DMDALocalInfo *, Vec, Mat, Mat, void *); 750 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESObjectiveVec)(DMDALocalInfo *, Vec, PetscReal *, void *); 751 752 PETSC_EXTERN PetscErrorCode DMDASNESSetFunctionLocal(DM, InsertMode, DMDASNESFunction, void *); 753 PETSC_EXTERN PetscErrorCode DMDASNESSetJacobianLocal(DM, DMDASNESJacobian, void *); 754 PETSC_EXTERN PetscErrorCode DMDASNESSetObjectiveLocal(DM, DMDASNESObjective, void *); 755 PETSC_EXTERN PetscErrorCode DMDASNESSetPicardLocal(DM, InsertMode, PetscErrorCode (*)(DMDALocalInfo *, void *, void *, void *), PetscErrorCode (*)(DMDALocalInfo *, void *, Mat, Mat, void *), void *); 756 757 PETSC_EXTERN PetscErrorCode DMDASNESSetFunctionLocalVec(DM, InsertMode, DMDASNESFunctionVec, void *); 758 PETSC_EXTERN PetscErrorCode DMDASNESSetJacobianLocalVec(DM, DMDASNESJacobianVec, void *); 759 PETSC_EXTERN PetscErrorCode DMDASNESSetObjectiveLocalVec(DM, DMDASNESObjectiveVec, void *); 760 761 PETSC_EXTERN PetscErrorCode DMSNESSetBoundaryLocal(DM, PetscErrorCode (*)(DM, Vec, void *), void *); 762 PETSC_EXTERN PetscErrorCode DMSNESSetFunctionLocal(DM, PetscErrorCode (*)(DM, Vec, Vec, void *), void *); 763 PETSC_EXTERN PetscErrorCode DMSNESSetJacobianLocal(DM, PetscErrorCode (*)(DM, Vec, Mat, Mat, void *), void *); 764 PETSC_EXTERN PetscErrorCode DMSNESGetBoundaryLocal(DM, PetscErrorCode (**)(DM, Vec, void *), void **); 765 PETSC_EXTERN PetscErrorCode DMSNESGetFunctionLocal(DM, PetscErrorCode (**)(DM, Vec, Vec, void *), void **); 766 PETSC_EXTERN PetscErrorCode DMSNESGetJacobianLocal(DM, PetscErrorCode (**)(DM, Vec, Mat, Mat, void *), void **); 767 768 /* Routines for Multiblock solver */ 769 PETSC_EXTERN PetscErrorCode SNESMultiblockSetFields(SNES, const char[], PetscInt, const PetscInt *); 770 PETSC_EXTERN PetscErrorCode SNESMultiblockSetIS(SNES, const char[], IS); 771 PETSC_EXTERN PetscErrorCode SNESMultiblockSetBlockSize(SNES, PetscInt); 772 PETSC_EXTERN PetscErrorCode SNESMultiblockSetType(SNES, PCCompositeType); 773 774 /*J 775 SNESMSType - String with the name of a PETSc `SNESMS` method. 776 777 Level: intermediate 778 779 .seealso: `SNESMSGetType()`, `SNESMSSetType()`, `SNES` 780 J*/ 781 typedef const char *SNESMSType; 782 #define SNESMSM62 "m62" 783 #define SNESMSEULER "euler" 784 #define SNESMSJAMESON83 "jameson83" 785 #define SNESMSVLTP11 "vltp11" 786 #define SNESMSVLTP21 "vltp21" 787 #define SNESMSVLTP31 "vltp31" 788 #define SNESMSVLTP41 "vltp41" 789 #define SNESMSVLTP51 "vltp51" 790 #define SNESMSVLTP61 "vltp61" 791 792 PETSC_EXTERN PetscErrorCode SNESMSRegister(SNESMSType, PetscInt, PetscInt, PetscReal, const PetscReal[], const PetscReal[], const PetscReal[]); 793 PETSC_EXTERN PetscErrorCode SNESMSGetType(SNES, SNESMSType *); 794 PETSC_EXTERN PetscErrorCode SNESMSSetType(SNES, SNESMSType); 795 PETSC_EXTERN PetscErrorCode SNESMSGetDamping(SNES, PetscReal *); 796 PETSC_EXTERN PetscErrorCode SNESMSSetDamping(SNES, PetscReal); 797 PETSC_EXTERN PetscErrorCode SNESMSFinalizePackage(void); 798 PETSC_EXTERN PetscErrorCode SNESMSInitializePackage(void); 799 PETSC_EXTERN PetscErrorCode SNESMSRegisterDestroy(void); 800 801 /* routines for NGMRES solver */ 802 803 typedef enum { 804 SNES_NGMRES_RESTART_NONE = 0, 805 SNES_NGMRES_RESTART_PERIODIC = 1, 806 SNES_NGMRES_RESTART_DIFFERENCE = 2 807 } SNESNGMRESRestartType; 808 PETSC_EXTERN const char *const SNESNGMRESRestartTypes[]; 809 810 typedef enum { 811 SNES_NGMRES_SELECT_NONE = 0, 812 SNES_NGMRES_SELECT_DIFFERENCE = 1, 813 SNES_NGMRES_SELECT_LINESEARCH = 2 814 } SNESNGMRESSelectType; 815 PETSC_EXTERN const char *const SNESNGMRESSelectTypes[]; 816 817 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartType(SNES, SNESNGMRESRestartType); 818 PETSC_EXTERN PetscErrorCode SNESNGMRESSetSelectType(SNES, SNESNGMRESSelectType); 819 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartFmRise(SNES, PetscBool); 820 PETSC_EXTERN PetscErrorCode SNESNGMRESGetRestartFmRise(SNES, PetscBool *); 821 822 /* routines for NCG solver */ 823 824 typedef enum { 825 SNES_NCG_FR = 0, 826 SNES_NCG_PRP = 1, 827 SNES_NCG_HS = 2, 828 SNES_NCG_DY = 3, 829 SNES_NCG_CD = 4 830 } SNESNCGType; 831 PETSC_EXTERN const char *const SNESNCGTypes[]; 832 833 PETSC_EXTERN PetscErrorCode SNESNCGSetType(SNES, SNESNCGType); 834 835 typedef enum { 836 SNES_QN_SCALE_DEFAULT = 0, 837 SNES_QN_SCALE_NONE = 1, 838 SNES_QN_SCALE_SCALAR = 2, 839 SNES_QN_SCALE_DIAGONAL = 3, 840 SNES_QN_SCALE_JACOBIAN = 4 841 } SNESQNScaleType; 842 PETSC_EXTERN const char *const SNESQNScaleTypes[]; 843 typedef enum { 844 SNES_QN_RESTART_DEFAULT = 0, 845 SNES_QN_RESTART_NONE = 1, 846 SNES_QN_RESTART_POWELL = 2, 847 SNES_QN_RESTART_PERIODIC = 3 848 } SNESQNRestartType; 849 PETSC_EXTERN const char *const SNESQNRestartTypes[]; 850 typedef enum { 851 SNES_QN_LBFGS = 0, 852 SNES_QN_BROYDEN = 1, 853 SNES_QN_BADBROYDEN = 2 854 } SNESQNType; 855 PETSC_EXTERN const char *const SNESQNTypes[]; 856 857 PETSC_EXTERN PetscErrorCode SNESQNSetType(SNES, SNESQNType); 858 PETSC_EXTERN PetscErrorCode SNESQNSetScaleType(SNES, SNESQNScaleType); 859 PETSC_EXTERN PetscErrorCode SNESQNSetRestartType(SNES, SNESQNRestartType); 860 861 PETSC_EXTERN PetscErrorCode SNESNASMGetType(SNES, PCASMType *); 862 PETSC_EXTERN PetscErrorCode SNESNASMSetType(SNES, PCASMType); 863 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomains(SNES, PetscInt *, SNES **, VecScatter **, VecScatter **, VecScatter **); 864 PETSC_EXTERN PetscErrorCode SNESNASMSetSubdomains(SNES, PetscInt, SNES *, VecScatter *, VecScatter *, VecScatter *); 865 PETSC_EXTERN PetscErrorCode SNESNASMSetDamping(SNES, PetscReal); 866 PETSC_EXTERN PetscErrorCode SNESNASMGetDamping(SNES, PetscReal *); 867 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomainVecs(SNES, PetscInt *, Vec **, Vec **, Vec **, Vec **); 868 PETSC_EXTERN PetscErrorCode SNESNASMSetComputeFinalJacobian(SNES, PetscBool); 869 PETSC_EXTERN PetscErrorCode SNESNASMGetSNES(SNES, PetscInt, SNES *); 870 PETSC_EXTERN PetscErrorCode SNESNASMGetNumber(SNES, PetscInt *); 871 PETSC_EXTERN PetscErrorCode SNESNASMSetWeight(SNES, Vec); 872 873 typedef enum { 874 SNES_COMPOSITE_ADDITIVE, 875 SNES_COMPOSITE_MULTIPLICATIVE, 876 SNES_COMPOSITE_ADDITIVEOPTIMAL 877 } SNESCompositeType; 878 PETSC_EXTERN const char *const SNESCompositeTypes[]; 879 880 PETSC_EXTERN PetscErrorCode SNESCompositeSetType(SNES, SNESCompositeType); 881 PETSC_EXTERN PetscErrorCode SNESCompositeAddSNES(SNES, SNESType); 882 PETSC_EXTERN PetscErrorCode SNESCompositeGetSNES(SNES, PetscInt, SNES *); 883 PETSC_EXTERN PetscErrorCode SNESCompositeGetNumber(SNES, PetscInt *); 884 PETSC_EXTERN PetscErrorCode SNESCompositeSetDamping(SNES, PetscInt, PetscReal); 885 886 PETSC_EXTERN PetscErrorCode SNESPatchSetDiscretisationInfo(SNES, PetscInt, DM *, PetscInt *, PetscInt *, const PetscInt **, const PetscInt *, PetscInt, const PetscInt *, PetscInt, const PetscInt *); 887 PETSC_EXTERN PetscErrorCode SNESPatchSetComputeOperator(SNES, PetscErrorCode (*func)(PC, PetscInt, Vec, Mat, IS, PetscInt, const PetscInt *, const PetscInt *, void *), void *); 888 PETSC_EXTERN PetscErrorCode SNESPatchSetComputeFunction(SNES, PetscErrorCode (*func)(PC, PetscInt, Vec, Vec, IS, PetscInt, const PetscInt *, const PetscInt *, void *), void *); 889 PETSC_EXTERN PetscErrorCode SNESPatchSetConstructType(SNES, PCPatchConstructType, PetscErrorCode (*func)(PC, PetscInt *, IS **, IS *, void *), void *); 890 PETSC_EXTERN PetscErrorCode SNESPatchSetCellNumbering(SNES, PetscSection); 891 892 /*E 893 SNESFASType - Determines the type of nonlinear multigrid method that is run. 894 895 Level: beginner 896 897 Values: 898 + `SNES_FAS_MULTIPLICATIVE` (default) - traditional V or W cycle as determined by `SNESFASSetCycles()` 899 . `SNES_FAS_ADDITIVE` - additive FAS cycle 900 . `SNES_FAS_FULL` - full FAS cycle 901 - `SNES_FAS_KASKADE` - Kaskade FAS cycle 902 .seealso: `PCMGSetType()`, `PCMGType` 903 904 E*/ 905 typedef enum { 906 SNES_FAS_MULTIPLICATIVE, 907 SNES_FAS_ADDITIVE, 908 SNES_FAS_FULL, 909 SNES_FAS_KASKADE 910 } SNESFASType; 911 PETSC_EXTERN const char *const SNESFASTypes[]; 912 913 /* called on the finest level FAS instance*/ 914 PETSC_EXTERN PetscErrorCode SNESFASSetType(SNES, SNESFASType); 915 PETSC_EXTERN PetscErrorCode SNESFASGetType(SNES, SNESFASType *); 916 PETSC_EXTERN PetscErrorCode SNESFASSetLevels(SNES, PetscInt, MPI_Comm *); 917 PETSC_EXTERN PetscErrorCode SNESFASGetLevels(SNES, PetscInt *); 918 PETSC_EXTERN PetscErrorCode SNESFASGetCycleSNES(SNES, PetscInt, SNES *); 919 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothUp(SNES, PetscInt); 920 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothDown(SNES, PetscInt); 921 PETSC_EXTERN PetscErrorCode SNESFASSetCycles(SNES, PetscInt); 922 PETSC_EXTERN PetscErrorCode SNESFASSetMonitor(SNES, PetscViewerAndFormat *, PetscBool); 923 PETSC_EXTERN PetscErrorCode SNESFASSetLog(SNES, PetscBool); 924 925 PETSC_EXTERN PetscErrorCode SNESFASSetGalerkin(SNES, PetscBool); 926 PETSC_EXTERN PetscErrorCode SNESFASGetGalerkin(SNES, PetscBool *); 927 PETSC_EXTERN PetscErrorCode SNESFASGalerkinFunctionDefault(SNES, Vec, Vec, void *); 928 929 /* called on any level -- "Cycle" FAS instance */ 930 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmoother(SNES, SNES *); 931 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherUp(SNES, SNES *); 932 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherDown(SNES, SNES *); 933 PETSC_EXTERN PetscErrorCode SNESFASCycleGetCorrection(SNES, SNES *); 934 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInterpolation(SNES, Mat *); 935 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRestriction(SNES, Mat *); 936 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInjection(SNES, Mat *); 937 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRScale(SNES, Vec *); 938 PETSC_EXTERN PetscErrorCode SNESFASCycleSetCycles(SNES, PetscInt); 939 PETSC_EXTERN PetscErrorCode SNESFASCycleIsFine(SNES, PetscBool *); 940 941 /* called on the (outer) finest level FAS to set/get parameters on any level instance */ 942 PETSC_EXTERN PetscErrorCode SNESFASSetInterpolation(SNES, PetscInt, Mat); 943 PETSC_EXTERN PetscErrorCode SNESFASGetInterpolation(SNES, PetscInt, Mat *); 944 PETSC_EXTERN PetscErrorCode SNESFASSetRestriction(SNES, PetscInt, Mat); 945 PETSC_EXTERN PetscErrorCode SNESFASGetRestriction(SNES, PetscInt, Mat *); 946 PETSC_EXTERN PetscErrorCode SNESFASSetInjection(SNES, PetscInt, Mat); 947 PETSC_EXTERN PetscErrorCode SNESFASGetInjection(SNES, PetscInt, Mat *); 948 PETSC_EXTERN PetscErrorCode SNESFASSetRScale(SNES, PetscInt, Vec); 949 PETSC_EXTERN PetscErrorCode SNESFASGetRScale(SNES, PetscInt, Vec *); 950 PETSC_EXTERN PetscErrorCode SNESFASSetContinuation(SNES, PetscBool); 951 952 PETSC_EXTERN PetscErrorCode SNESFASGetSmoother(SNES, PetscInt, SNES *); 953 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherUp(SNES, PetscInt, SNES *); 954 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherDown(SNES, PetscInt, SNES *); 955 PETSC_EXTERN PetscErrorCode SNESFASGetCoarseSolve(SNES, SNES *); 956 957 /* parameters for full FAS */ 958 PETSC_EXTERN PetscErrorCode SNESFASFullSetDownSweep(SNES, PetscBool); 959 PETSC_EXTERN PetscErrorCode SNESFASCreateCoarseVec(SNES, Vec *); 960 PETSC_EXTERN PetscErrorCode SNESFASRestrict(SNES, Vec, Vec); 961 PETSC_EXTERN PetscErrorCode SNESFASFullSetTotal(SNES, PetscBool); 962 PETSC_EXTERN PetscErrorCode SNESFASFullGetTotal(SNES, PetscBool *); 963 964 PETSC_EXTERN PetscErrorCode DMSNESCheckDiscretization(SNES, DM, PetscReal, Vec, PetscReal, PetscReal[]); 965 PETSC_EXTERN PetscErrorCode DMSNESCheckResidual(SNES, DM, Vec, PetscReal, PetscReal *); 966 PETSC_EXTERN PetscErrorCode DMSNESCheckJacobian(SNES, DM, Vec, PetscReal, PetscBool *, PetscReal *); 967 PETSC_EXTERN PetscErrorCode DMSNESCheckFromOptions(SNES, Vec); 968 PETSC_EXTERN PetscErrorCode DMSNESComputeJacobianAction(DM, Vec, Vec, Vec, void *); 969 PETSC_EXTERN PetscErrorCode DMSNESCreateJacobianMF(DM, Vec, void *, Mat *); 970 971 #endif 972