1 /* 2 User interface for the nonlinear solvers package. 3 */ 4 #pragma once 5 6 #include <petscksp.h> 7 #include <petscdmtypes.h> 8 #include <petscfvtypes.h> 9 #include <petscdmdatypes.h> 10 #include <petscsnestypes.h> 11 12 /* SUBMANSEC = SNES */ 13 14 /*J 15 SNESType - String with the name of a PETSc `SNES` method. 16 17 Level: beginner 18 19 .seealso: [](doc_nonlinsolve), [](ch_snes), `SNESSetType()`, `SNES`, `SNESCreate()`, `SNESDestroy()`, `SNESSetFromOptions()` 20 J*/ 21 typedef const char *SNESType; 22 #define SNESNEWTONLS "newtonls" 23 #define SNESNEWTONTR "newtontr" 24 #define SNESNEWTONTRDC "newtontrdc" 25 #define SNESPYTHON "python" 26 #define SNESNRICHARDSON "nrichardson" 27 #define SNESKSPONLY "ksponly" 28 #define SNESKSPTRANSPOSEONLY "ksptransposeonly" 29 #define SNESVINEWTONRSLS "vinewtonrsls" 30 #define SNESVINEWTONSSLS "vinewtonssls" 31 #define SNESNGMRES "ngmres" 32 #define SNESQN "qn" 33 #define SNESSHELL "shell" 34 #define SNESNGS "ngs" 35 #define SNESNCG "ncg" 36 #define SNESFAS "fas" 37 #define SNESMS "ms" 38 #define SNESNASM "nasm" 39 #define SNESANDERSON "anderson" 40 #define SNESASPIN "aspin" 41 #define SNESCOMPOSITE "composite" 42 #define SNESPATCH "patch" 43 44 /* Logging support */ 45 PETSC_EXTERN PetscClassId SNES_CLASSID; 46 PETSC_EXTERN PetscClassId DMSNES_CLASSID; 47 48 PETSC_EXTERN PetscErrorCode SNESInitializePackage(void); 49 PETSC_EXTERN PetscErrorCode SNESFinalizePackage(void); 50 51 PETSC_EXTERN PetscErrorCode SNESCreate(MPI_Comm, SNES *); 52 PETSC_EXTERN PetscErrorCode SNESReset(SNES); 53 PETSC_EXTERN PetscErrorCode SNESDestroy(SNES *); 54 PETSC_EXTERN PetscErrorCode SNESSetType(SNES, SNESType); 55 PETSC_EXTERN PetscErrorCode SNESMonitor(SNES, PetscInt, PetscReal); 56 PETSC_EXTERN PetscErrorCode SNESMonitorSet(SNES, PetscErrorCode (*)(SNES, PetscInt, PetscReal, void *), void *, PetscErrorCode (*)(void **)); 57 PETSC_EXTERN PetscErrorCode SNESMonitorSetFromOptions(SNES, const char[], const char[], const char[], PetscErrorCode (*)(SNES, PetscInt, PetscReal, PetscViewerAndFormat *), PetscErrorCode (*)(SNES, PetscViewerAndFormat *)); 58 PETSC_EXTERN PetscErrorCode SNESMonitorCancel(SNES); 59 PETSC_EXTERN PetscErrorCode SNESMonitorSAWs(SNES, PetscInt, PetscReal, void *); 60 PETSC_EXTERN PetscErrorCode SNESMonitorSAWsCreate(SNES, void **); 61 PETSC_EXTERN PetscErrorCode SNESMonitorSAWsDestroy(void **); 62 PETSC_EXTERN PetscErrorCode SNESSetConvergenceHistory(SNES, PetscReal[], PetscInt[], PetscInt, PetscBool); 63 PETSC_EXTERN PetscErrorCode SNESGetConvergenceHistory(SNES, PetscReal *[], PetscInt *[], PetscInt *); 64 PETSC_EXTERN PetscErrorCode SNESSetUp(SNES); 65 PETSC_EXTERN PetscErrorCode SNESSolve(SNES, Vec, Vec); 66 PETSC_EXTERN PetscErrorCode SNESSetErrorIfNotConverged(SNES, PetscBool); 67 PETSC_EXTERN PetscErrorCode SNESGetErrorIfNotConverged(SNES, PetscBool *); 68 PETSC_EXTERN PetscErrorCode SNESConverged(SNES, PetscInt, PetscReal, PetscReal, PetscReal); 69 70 PETSC_EXTERN PetscErrorCode SNESSetWorkVecs(SNES, PetscInt); 71 72 PETSC_EXTERN PetscErrorCode SNESAddOptionsChecker(PetscErrorCode (*)(SNES)); 73 74 PETSC_EXTERN PetscErrorCode SNESRegister(const char[], PetscErrorCode (*)(SNES)); 75 76 PETSC_EXTERN PetscErrorCode SNESGetKSP(SNES, KSP *); 77 PETSC_EXTERN PetscErrorCode SNESSetKSP(SNES, KSP); 78 PETSC_EXTERN PetscErrorCode SNESSetSolution(SNES, Vec); 79 PETSC_EXTERN PetscErrorCode SNESGetSolution(SNES, Vec *); 80 PETSC_EXTERN PetscErrorCode SNESGetSolutionUpdate(SNES, Vec *); 81 PETSC_EXTERN PetscErrorCode SNESGetRhs(SNES, Vec *); 82 PETSC_EXTERN PetscErrorCode SNESView(SNES, PetscViewer); 83 PETSC_EXTERN PetscErrorCode SNESLoad(SNES, PetscViewer); 84 PETSC_EXTERN PetscErrorCode SNESConvergedReasonViewSet(SNES, PetscErrorCode (*)(SNES, void *), void *, PetscErrorCode (*)(void **)); 85 PETSC_EXTERN PetscErrorCode SNESViewFromOptions(SNES, PetscObject, const char[]); 86 PETSC_EXTERN PetscErrorCode SNESConvergedReasonView(SNES, PetscViewer); 87 PETSC_EXTERN PetscErrorCode SNESConvergedReasonViewFromOptions(SNES); 88 PETSC_EXTERN PetscErrorCode SNESConvergedReasonViewCancel(SNES); 89 90 PETSC_DEPRECATED_FUNCTION(3, 14, 0, "SNESConvergedReasonView()", ) static inline PetscErrorCode SNESReasonView(SNES snes, PetscViewer v) 91 { 92 return SNESConvergedReasonView(snes, v); 93 } 94 PETSC_DEPRECATED_FUNCTION(3, 14, 0, "SNESConvergedReasonViewFromOptions()", ) static inline PetscErrorCode SNESReasonViewFromOptions(SNES snes) 95 { 96 return SNESConvergedReasonViewFromOptions(snes); 97 } 98 99 #define SNES_FILE_CLASSID 1211224 100 101 PETSC_EXTERN PetscErrorCode SNESSetOptionsPrefix(SNES, const char[]); 102 PETSC_EXTERN PetscErrorCode SNESAppendOptionsPrefix(SNES, const char[]); 103 PETSC_EXTERN PetscErrorCode SNESGetOptionsPrefix(SNES, const char *[]); 104 PETSC_EXTERN PetscErrorCode SNESSetFromOptions(SNES); 105 PETSC_EXTERN PetscErrorCode SNESResetFromOptions(SNES); 106 107 PETSC_EXTERN PetscErrorCode SNESSetUseMatrixFree(SNES, PetscBool, PetscBool); 108 PETSC_EXTERN PetscErrorCode SNESGetUseMatrixFree(SNES, PetscBool *, PetscBool *); 109 PETSC_EXTERN PetscErrorCode MatCreateSNESMF(SNES, Mat *); 110 PETSC_EXTERN PetscErrorCode MatSNESMFGetSNES(Mat, SNES *); 111 PETSC_EXTERN PetscErrorCode MatSNESMFSetReuseBase(Mat, PetscBool); 112 PETSC_EXTERN PetscErrorCode MatSNESMFGetReuseBase(Mat, PetscBool *); 113 PETSC_EXTERN PetscErrorCode MatMFFDComputeJacobian(SNES, Vec, Mat, Mat, void *); 114 PETSC_EXTERN PetscErrorCode MatCreateSNESMFMore(SNES, Vec, Mat *); 115 PETSC_EXTERN PetscErrorCode MatSNESMFMoreSetParameters(Mat, PetscReal, PetscReal, PetscReal); 116 117 PETSC_EXTERN PetscErrorCode SNESGetType(SNES, SNESType *); 118 PETSC_EXTERN PetscErrorCode SNESMonitorDefaultSetUp(SNES, PetscViewerAndFormat *); 119 PETSC_EXTERN PetscErrorCode SNESMonitorDefault(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 120 PETSC_EXTERN PetscErrorCode SNESMonitorScaling(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 121 PETSC_EXTERN PetscErrorCode SNESMonitorRange(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 122 PETSC_EXTERN PetscErrorCode SNESMonitorRatio(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 123 PETSC_EXTERN PetscErrorCode SNESMonitorRatioSetUp(SNES, PetscViewerAndFormat *); 124 PETSC_EXTERN PetscErrorCode SNESMonitorSolution(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 125 PETSC_EXTERN PetscErrorCode SNESMonitorResidual(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 126 PETSC_EXTERN PetscErrorCode SNESMonitorSolutionUpdate(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 127 PETSC_EXTERN PetscErrorCode SNESMonitorDefaultShort(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 128 PETSC_EXTERN PetscErrorCode SNESMonitorDefaultField(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 129 PETSC_EXTERN PetscErrorCode SNESMonitorJacUpdateSpectrum(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 130 PETSC_EXTERN PetscErrorCode SNESMonitorFields(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 131 PETSC_EXTERN PetscErrorCode KSPMonitorSNESResidual(KSP, PetscInt, PetscReal, PetscViewerAndFormat *); 132 PETSC_EXTERN PetscErrorCode KSPMonitorSNESResidualDrawLG(KSP, PetscInt, PetscReal, PetscViewerAndFormat *); 133 PETSC_EXTERN PetscErrorCode KSPMonitorSNESResidualDrawLGCreate(PetscViewer, PetscViewerFormat, void *, PetscViewerAndFormat **); 134 135 PETSC_EXTERN PetscErrorCode SNESSetTolerances(SNES, PetscReal, PetscReal, PetscReal, PetscInt, PetscInt); 136 PETSC_EXTERN PetscErrorCode SNESSetDivergenceTolerance(SNES, PetscReal); 137 PETSC_EXTERN PetscErrorCode SNESGetTolerances(SNES, PetscReal *, PetscReal *, PetscReal *, PetscInt *, PetscInt *); 138 PETSC_EXTERN PetscErrorCode SNESGetDivergenceTolerance(SNES, PetscReal *); 139 PETSC_EXTERN PetscErrorCode SNESSetTrustRegionTolerance(SNES, PetscReal); 140 PETSC_EXTERN PetscErrorCode SNESGetForceIteration(SNES, PetscBool *); 141 PETSC_EXTERN PetscErrorCode SNESSetForceIteration(SNES, PetscBool); 142 PETSC_EXTERN PetscErrorCode SNESGetIterationNumber(SNES, PetscInt *); 143 PETSC_EXTERN PetscErrorCode SNESSetIterationNumber(SNES, PetscInt); 144 145 /*E 146 SNESNewtonTRFallbackType - type of fallback in case the solution of the trust-region subproblem is outside of the radius 147 148 Values: 149 + `SNES_TR_FALLBACK_NEWTON` - use scaled Newton step 150 . `SNES_TR_FALLBACK_CAUCHY` - use Cauchy direction 151 - `SNES_TR_FALLBACK_DOGLEG` - use dogleg method 152 153 Level: intermediate 154 155 .seealso: [](ch_snes), `SNES`, `SNESNEWTONTR`, `SNESNEWTONTRDC` 156 E*/ 157 typedef enum { 158 SNES_TR_FALLBACK_NEWTON, 159 SNES_TR_FALLBACK_CAUCHY, 160 SNES_TR_FALLBACK_DOGLEG, 161 } SNESNewtonTRFallbackType; 162 163 PETSC_EXTERN const char *const SNESNewtonTRFallbackTypes[]; 164 165 PETSC_EXTERN PetscErrorCode SNESNewtonTRSetPreCheck(SNES, PetscErrorCode (*)(SNES, Vec, Vec, PetscBool *, void *), void *ctx); 166 PETSC_EXTERN PetscErrorCode SNESNewtonTRGetPreCheck(SNES, PetscErrorCode (**)(SNES, Vec, Vec, PetscBool *, void *), void **ctx); 167 PETSC_EXTERN PetscErrorCode SNESNewtonTRSetPostCheck(SNES, PetscErrorCode (*)(SNES, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void *ctx); 168 PETSC_EXTERN PetscErrorCode SNESNewtonTRGetPostCheck(SNES, PetscErrorCode (**)(SNES, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void **ctx); 169 PETSC_EXTERN PetscErrorCode SNESNewtonTRSetFallbackType(SNES, SNESNewtonTRFallbackType); 170 PETSC_EXTERN PetscErrorCode SNESNewtonTRPreCheck(SNES, Vec, Vec, PetscBool *); 171 PETSC_EXTERN PetscErrorCode SNESNewtonTRPostCheck(SNES, Vec, Vec, Vec, PetscBool *, PetscBool *); 172 PETSC_EXTERN PetscErrorCode SNESNewtonTRSetNormType(SNES, NormType); 173 174 /*E 175 SNESNewtonTRQNType - type of quasi-Newton model to use 176 177 Values: 178 + `SNES_TR_QN_NONE` - do not use a quasi-Newton model 179 . `SNES_TR_QN_SAME` - use the same quasi-Newton model for matrix and preconditioner 180 - `SNES_TR_QN_DIFFERENT` - use different quasi-Newton models for matrix and preconditioner 181 182 Level: intermediate 183 184 .seealso: [](ch_snes), `SNES`, `SNESNEWTONTR` 185 E*/ 186 typedef enum { 187 SNES_TR_QN_NONE, 188 SNES_TR_QN_SAME, 189 SNES_TR_QN_DIFFERENT, 190 } SNESNewtonTRQNType; 191 192 PETSC_EXTERN const char *const SNESNewtonTRQNTypes[]; 193 194 PETSC_EXTERN PetscErrorCode SNESNewtonTRSetQNType(SNES, SNESNewtonTRQNType); 195 196 PETSC_EXTERN PetscErrorCode SNESNewtonTRDCGetRhoFlag(SNES, PetscBool *); 197 PETSC_EXTERN PetscErrorCode SNESNewtonTRDCSetPreCheck(SNES, PetscErrorCode (*)(SNES, Vec, Vec, PetscBool *, void *), void *ctx); 198 PETSC_EXTERN PetscErrorCode SNESNewtonTRDCGetPreCheck(SNES, PetscErrorCode (**)(SNES, Vec, Vec, PetscBool *, void *), void **ctx); 199 PETSC_EXTERN PetscErrorCode SNESNewtonTRDCSetPostCheck(SNES, PetscErrorCode (*)(SNES, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void *ctx); 200 PETSC_EXTERN PetscErrorCode SNESNewtonTRDCGetPostCheck(SNES, PetscErrorCode (**)(SNES, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void **ctx); 201 202 PETSC_EXTERN PetscErrorCode SNESGetNonlinearStepFailures(SNES, PetscInt *); 203 PETSC_EXTERN PetscErrorCode SNESSetMaxNonlinearStepFailures(SNES, PetscInt); 204 PETSC_EXTERN PetscErrorCode SNESGetMaxNonlinearStepFailures(SNES, PetscInt *); 205 PETSC_EXTERN PetscErrorCode SNESGetNumberFunctionEvals(SNES, PetscInt *); 206 207 PETSC_EXTERN PetscErrorCode SNESSetLagPreconditioner(SNES, PetscInt); 208 PETSC_EXTERN PetscErrorCode SNESGetLagPreconditioner(SNES, PetscInt *); 209 PETSC_EXTERN PetscErrorCode SNESSetLagJacobian(SNES, PetscInt); 210 PETSC_EXTERN PetscErrorCode SNESGetLagJacobian(SNES, PetscInt *); 211 PETSC_EXTERN PetscErrorCode SNESSetLagPreconditionerPersists(SNES, PetscBool); 212 PETSC_EXTERN PetscErrorCode SNESSetLagJacobianPersists(SNES, PetscBool); 213 PETSC_EXTERN PetscErrorCode SNESSetGridSequence(SNES, PetscInt); 214 PETSC_EXTERN PetscErrorCode SNESGetGridSequence(SNES, PetscInt *); 215 216 PETSC_EXTERN PetscErrorCode SNESGetLinearSolveIterations(SNES, PetscInt *); 217 PETSC_EXTERN PetscErrorCode SNESGetLinearSolveFailures(SNES, PetscInt *); 218 PETSC_EXTERN PetscErrorCode SNESSetMaxLinearSolveFailures(SNES, PetscInt); 219 PETSC_EXTERN PetscErrorCode SNESGetMaxLinearSolveFailures(SNES, PetscInt *); 220 PETSC_EXTERN PetscErrorCode SNESSetCountersReset(SNES, PetscBool); 221 222 PETSC_EXTERN PetscErrorCode SNESKSPSetUseEW(SNES, PetscBool); 223 PETSC_EXTERN PetscErrorCode SNESKSPGetUseEW(SNES, PetscBool *); 224 PETSC_EXTERN PetscErrorCode SNESKSPSetParametersEW(SNES, PetscInt, PetscReal, PetscReal, PetscReal, PetscReal, PetscReal, PetscReal); 225 PETSC_EXTERN PetscErrorCode SNESKSPGetParametersEW(SNES, PetscInt *, PetscReal *, PetscReal *, PetscReal *, PetscReal *, PetscReal *, PetscReal *); 226 227 #include <petscdrawtypes.h> 228 PETSC_EXTERN PetscErrorCode SNESMonitorLGRange(SNES, PetscInt, PetscReal, void *); 229 230 PETSC_EXTERN PetscErrorCode SNESSetApplicationContext(SNES, void *); 231 PETSC_EXTERN PetscErrorCode SNESGetApplicationContext(SNES, void *); 232 PETSC_EXTERN PetscErrorCode SNESSetComputeApplicationContext(SNES, PetscErrorCode (*)(SNES, void **), PetscErrorCode (*)(void **)); 233 234 PETSC_EXTERN PetscErrorCode SNESPythonSetType(SNES, const char[]); 235 PETSC_EXTERN PetscErrorCode SNESPythonGetType(SNES, const char *[]); 236 237 PETSC_EXTERN PetscErrorCode SNESSetFunctionDomainError(SNES); 238 PETSC_EXTERN PetscErrorCode SNESGetFunctionDomainError(SNES, PetscBool *); 239 PETSC_EXTERN PetscErrorCode SNESGetJacobianDomainError(SNES, PetscBool *); 240 PETSC_EXTERN PetscErrorCode SNESSetJacobianDomainError(SNES); 241 PETSC_EXTERN PetscErrorCode SNESSetCheckJacobianDomainError(SNES, PetscBool); 242 PETSC_EXTERN PetscErrorCode SNESGetCheckJacobianDomainError(SNES, PetscBool *); 243 244 #define SNES_CONVERGED_TR_DELTA_DEPRECATED SNES_CONVERGED_TR_DELTA PETSC_DEPRECATED_ENUM(3, 12, 0, "SNES_DIVERGED_TR_DELTA", ) 245 /*E 246 SNESConvergedReason - reason a `SNESSolve()` was determined to have converged or diverged 247 248 Values: 249 + `SNES_CONVERGED_FNORM_ABS` - 2-norm(F) <= abstol 250 . `SNES_CONVERGED_FNORM_RELATIVE` - 2-norm(F) <= rtol*2-norm(F(x_0)) where x_0 is the initial guess 251 . `SNES_CONVERGED_SNORM_RELATIVE` - The 2-norm of the last step <= stol * 2-norm(x) where x is the current 252 . `SNES_DIVERGED_FUNCTION_COUNT` - The user provided function has been called more times than the maximum set in `SNESSetTolerances()` 253 . `SNES_DIVERGED_DTOL` - The norm of the function has increased by a factor of divtol set with `SNESSetDivergenceTolerance()` 254 . `SNES_DIVERGED_FNORM_NAN` - the 2-norm of the current function evaluation is not-a-number (NaN), this 255 is usually caused by a division of 0 by 0. 256 . `SNES_DIVERGED_MAX_IT` - `SNESSolve()` has reached the maximum number of iterations requested 257 . `SNES_DIVERGED_LINE_SEARCH` - The line search has failed. This only occurs for `SNES` solvers that use a line search 258 . `SNES_DIVERGED_LOCAL_MIN` - the algorithm seems to have stagnated at a local minimum that is not zero. 259 - `SNES_CONERGED_ITERATING` - this only occurs if `SNESGetConvergedReason()` is called during the `SNESSolve()` 260 261 Level: beginner 262 263 Notes: 264 The two most common reasons for divergence are an incorrectly coded or computed Jacobian or failure or lack of convergence in the linear system (in this case we recommend 265 testing with `-pc_type lu` to eliminate the linear solver as the cause of the problem). 266 267 `SNES_DIVERGED_LOCAL_MIN` can only occur when using the line-search variant of `SNES`. 268 The line search wants to minimize Q(alpha) = 1/2 || F(x + alpha s) ||^2_2 this occurs 269 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 270 you get Q'(alpha) = -F(x)^T F'(x)^(-1)^T F'(x+alpha s)F(x+alpha s); when alpha = 0 271 Q'(0) = - ||F(x)||^2_2 which is always NEGATIVE if F'(x) is invertible. This means the Newton 272 direction is a descent direction and the line search should succeed if alpha is small enough. 273 274 If F'(x) is NOT invertible AND F'(x)^T F(x) = 0 then Q'(0) = 0 and the Newton direction 275 is NOT a descent direction so the line search will fail. All one can do at this point 276 is change the initial guess and try again. 277 278 An alternative explanation: Newton's method can be regarded as replacing the function with 279 its linear approximation and minimizing the 2-norm of that. That is F(x+s) approx F(x) + F'(x)s 280 so we minimize || F(x) + F'(x) s ||^2_2; do this using Least Squares. If F'(x) is invertible then 281 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 282 exists a nontrivial (that is F'(x)s != 0) solution to the equation and this direction is 283 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) 284 = - (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 285 and F'(x)^T F'(x) has no negative eigenvalues Q'(0) < 0 so s is a descent direction and the line 286 search should succeed for small enough alpha. 287 288 Note that this RARELY happens in practice. Far more likely the linear system is not being solved 289 (well enough?) or the Jacobian is wrong. 290 291 `SNES_DIVERGED_MAX_IT` means that the solver reached the maximum number of iterations without satisfying any 292 convergence criteria. `SNES_CONVERGED_ITS` means that `SNESConvergedSkip()` was chosen as the convergence test; 293 thus the usual convergence criteria have not been checked and may or may not be satisfied. 294 295 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `KSPConvergedReason`, `SNESSetConvergenceTest()`, `SNESSetTolerances()` 296 E*/ 297 typedef enum { /* converged */ 298 SNES_CONVERGED_FNORM_ABS = 2, /* ||F|| < atol */ 299 SNES_CONVERGED_FNORM_RELATIVE = 3, /* ||F|| < rtol*||F_initial|| */ 300 SNES_CONVERGED_SNORM_RELATIVE = 4, /* Newton computed step size small; || delta x || < stol || x ||*/ 301 SNES_CONVERGED_ITS = 5, /* maximum iterations reached */ 302 SNES_BREAKOUT_INNER_ITER = 6, /* Flag to break out of inner loop after checking custom convergence. */ 303 /* it is used in multi-phase flow when state changes */ 304 /* diverged */ 305 SNES_DIVERGED_FUNCTION_DOMAIN = -1, /* the new x location passed the function is not in the domain of F */ 306 SNES_DIVERGED_FUNCTION_COUNT = -2, 307 SNES_DIVERGED_LINEAR_SOLVE = -3, /* the linear solve failed */ 308 SNES_DIVERGED_FNORM_NAN = -4, 309 SNES_DIVERGED_MAX_IT = -5, 310 SNES_DIVERGED_LINE_SEARCH = -6, /* the line search failed */ 311 SNES_DIVERGED_INNER = -7, /* inner solve failed */ 312 SNES_DIVERGED_LOCAL_MIN = -8, /* || J^T b || is small, implies converged to local minimum of F() */ 313 SNES_DIVERGED_DTOL = -9, /* || F || > divtol*||F_initial|| */ 314 SNES_DIVERGED_JACOBIAN_DOMAIN = -10, /* Jacobian calculation does not make sense */ 315 SNES_DIVERGED_TR_DELTA = -11, 316 SNES_CONVERGED_TR_DELTA_DEPRECATED = -11, 317 318 SNES_CONVERGED_ITERATING = 0 319 } SNESConvergedReason; 320 PETSC_EXTERN const char *const *SNESConvergedReasons; 321 322 /*MC 323 SNES_CONVERGED_FNORM_ABS - 2-norm(F) <= abstol 324 325 Level: beginner 326 327 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `SNESConvergedReason`, `SNESSetTolerances()` 328 M*/ 329 330 /*MC 331 SNES_CONVERGED_FNORM_RELATIVE - 2-norm(F) <= rtol*2-norm(F(x_0)) where x_0 is the initial guess 332 333 Level: beginner 334 335 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `SNESConvergedReason`, `SNESSetTolerances()` 336 M*/ 337 338 /*MC 339 SNES_CONVERGED_SNORM_RELATIVE - The 2-norm of the last step <= stol * 2-norm(x) where x is the current 340 solution and stol is the 4th argument to `SNESSetTolerances()` 341 342 Options Database Key: 343 -snes_stol <stol> - the step tolerance 344 345 Level: beginner 346 347 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `SNESConvergedReason`, `SNESSetTolerances()` 348 M*/ 349 350 /*MC 351 SNES_DIVERGED_FUNCTION_COUNT - The user provided function has been called more times then the final 352 argument to `SNESSetTolerances()` 353 354 Level: beginner 355 356 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `SNESConvergedReason`, `SNESSetTolerances()` 357 M*/ 358 359 /*MC 360 SNES_DIVERGED_DTOL - The norm of the function has increased by a factor of divtol set with `SNESSetDivergenceTolerance()` 361 362 Level: beginner 363 364 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `SNESConvergedReason`, `SNESSetTolerances()`, `SNESSetDivergenceTolerance()` 365 M*/ 366 367 /*MC 368 SNES_DIVERGED_FNORM_NAN - the 2-norm of the current function evaluation is not-a-number (NaN), this 369 is usually caused by a division of 0 by 0. 370 371 Level: beginner 372 373 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `SNESConvergedReason`, `SNESSetTolerances()` 374 M*/ 375 376 /*MC 377 SNES_DIVERGED_MAX_IT - SNESSolve() has reached the maximum number of iterations requested 378 379 Level: beginner 380 381 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `SNESConvergedReason`, `SNESSetTolerances()` 382 M*/ 383 384 /*MC 385 SNES_DIVERGED_LINE_SEARCH - The line search has failed. This only occurs for a `SNES` solvers that use a line search 386 387 Level: beginner 388 389 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `SNESConvergedReason`, `SNESSetTolerances()`, `SNESLineSearch` 390 M*/ 391 392 /*MC 393 SNES_DIVERGED_LOCAL_MIN - the algorithm seems to have stagnated at a local minimum that is not zero. 394 See the manual page for `SNESConvergedReason` for more details 395 396 Level: beginner 397 398 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `SNESConvergedReason`, `SNESSetTolerances()` 399 M*/ 400 401 /*MC 402 SNES_CONERGED_ITERATING - this only occurs if `SNESGetConvergedReason()` is called during the `SNESSolve()` 403 404 Level: beginner 405 406 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `SNESConvergedReason`, `SNESSetTolerances()` 407 M*/ 408 409 PETSC_EXTERN PetscErrorCode SNESSetConvergenceTest(SNES, PetscErrorCode (*)(SNES, PetscInt, PetscReal, PetscReal, PetscReal, SNESConvergedReason *, void *), void *, PetscErrorCode (*)(void *)); 410 PETSC_EXTERN PetscErrorCode SNESConvergedDefault(SNES, PetscInt, PetscReal, PetscReal, PetscReal, SNESConvergedReason *, void *); 411 PETSC_EXTERN PetscErrorCode SNESConvergedSkip(SNES, PetscInt, PetscReal, PetscReal, PetscReal, SNESConvergedReason *, void *); 412 PETSC_EXTERN PetscErrorCode SNESConvergedCorrectPressure(SNES, PetscInt, PetscReal, PetscReal, PetscReal, SNESConvergedReason *, void *); 413 PETSC_EXTERN PetscErrorCode SNESGetConvergedReason(SNES, SNESConvergedReason *); 414 PETSC_EXTERN PetscErrorCode SNESGetConvergedReasonString(SNES, const char **); 415 PETSC_EXTERN PetscErrorCode SNESSetConvergedReason(SNES, SNESConvergedReason); 416 417 PETSC_DEPRECATED_FUNCTION(3, 5, 0, "SNESConvergedSkip()", ) static inline void SNESSkipConverged(void) 418 { /* never called */ 419 } 420 #define SNESSkipConverged (SNESSkipConverged, SNESConvergedSkip) 421 422 /*S 423 SNESInitialGuessFn - A prototype of a `SNES` compute initial guess function that would be passed to `SNESSetComputeInitialGuess()` 424 425 Calling Sequence: 426 + snes - `SNES` context 427 . u - output vector to contain initial guess 428 - ctx - [optional] user-defined function context 429 430 Level: beginner 431 432 .seealso: [](ch_snes), `SNES`, `SNESSetComputeInitialGuess()`, `SNESSetFunction()`, `SNESGetFunction()`, `SNESJacobianFn`, `SNESFunctionFn` 433 S*/ 434 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESInitialGuessFn)(SNES snes, Vec u, void *ctx); 435 436 /*S 437 SNESFunctionFn - A prototype of a `SNES` evaluation function that would be passed to `SNESSetFunction()` 438 439 Calling Sequence: 440 + snes - `SNES` context 441 . u - input vector 442 . F - function vector 443 - ctx - [optional] user-defined function context 444 445 Level: beginner 446 447 .seealso: [](ch_snes), `SNES`, `SNESSetFunction()`, `SNESGetFunction()`, `SNESJacobianFn`, `SNESNGSFn` 448 S*/ 449 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESFunctionFn)(SNES snes, Vec u, Vec F, void *ctx); 450 451 /*S 452 SNESObjectiveFn - A prototype of a `SNES` objective evaluation function that would be passed to `SNESSetObjective()` 453 454 Calling Sequence: 455 + snes - `SNES` context 456 . u - input vector 457 . o - output value 458 - ctx - [optional] user-defined function context 459 460 Level: beginner 461 462 .seealso: [](ch_snes), `SNES`, `SNESSetFunction()`, `SNESGetFunction()`, `SNESJacobianFn`, `SNESNGSFn` 463 S*/ 464 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESObjectiveFn)(SNES snes, Vec u, PetscReal *o, void *ctx); 465 466 /*S 467 SNESJacobianFn - A prototype of a `SNES` Jacobian evaluation function that would be passed to `SNESSetJacobian()` 468 469 Calling Sequence: 470 + snes - the `SNES` context obtained from `SNESCreate()` 471 . u - input vector 472 . Amat - (approximate) Jacobian matrix 473 . Pmat - matrix used to construct the preconditioner, often the same as `Amat` 474 - ctx - [optional] user-defined context for matrix evaluation routine 475 476 Level: beginner 477 478 .seealso: [](ch_snes), `SNES`, `SNESSetJacobian()`, `SNESGetJacobian()`, `SNESFunctionFn`, `SNESNGSFn` 479 S*/ 480 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESJacobianFn)(SNES snes, Vec u, Mat Amat, Mat Pmat, void *ctx); 481 482 /*S 483 SNESNGSFn - A prototype of a `SNES` nonlinear Gauss-Seidel function that would be passed to `SNESSetNGS()` 484 485 Calling Sequence: 486 + snes - the `SNES` context obtained from `SNESCreate()` 487 . u - the current solution, updated in place 488 . b - the right-hand side vector (which may be `NULL`) 489 - ctx - [optional] user-defined context for matrix evaluation routine 490 491 Level: beginner 492 493 .seealso: [](ch_snes), `SNES`, `SNESSetJacobian()`, `SNESGetJacobian()`, `SNESFunctionFn`, `SNESSetFunction()`, `SNESGetFunction()`, `SNESJacobianFn` 494 S*/ 495 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESNGSFn)(SNES snes, Vec u, Vec b, void *ctx); 496 497 /*S 498 SNESUpdateFn - A prototype of a `SNES` update function that would be passed to `SNESSetUpdate()` 499 500 Calling Sequence: 501 + snes - `SNES` context 502 - step - the current iteration index 503 504 Level: advanced 505 506 .seealso: [](ch_snes), `SNES`, `SNESSetUpdate()` 507 S*/ 508 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESUpdateFn)(SNES snes, PetscInt step); 509 510 /* --------- Solving systems of nonlinear equations --------------- */ 511 PETSC_EXTERN PetscErrorCode SNESSetFunction(SNES, Vec, SNESFunctionFn *, void *); 512 PETSC_EXTERN PetscErrorCode SNESGetFunction(SNES, Vec *, SNESFunctionFn **, void **); 513 PETSC_EXTERN PetscErrorCode SNESComputeFunction(SNES, Vec, Vec); 514 PETSC_EXTERN PetscErrorCode SNESComputeMFFunction(SNES, Vec, Vec); 515 PETSC_EXTERN PetscErrorCode SNESSetInitialFunction(SNES, Vec); 516 517 PETSC_EXTERN PetscErrorCode SNESSetJacobian(SNES, Mat, Mat, SNESJacobianFn *, void *); 518 PETSC_EXTERN PetscErrorCode SNESGetJacobian(SNES, Mat *, Mat *, SNESJacobianFn **, void **); 519 PETSC_EXTERN SNESFunctionFn SNESObjectiveComputeFunctionDefaultFD; 520 PETSC_EXTERN SNESJacobianFn SNESComputeJacobianDefault; 521 PETSC_EXTERN SNESJacobianFn SNESComputeJacobianDefaultColor; 522 PETSC_EXTERN PetscErrorCode SNESPruneJacobianColor(SNES, Mat, Mat); 523 PETSC_EXTERN PetscErrorCode SNESSetComputeInitialGuess(SNES, SNESInitialGuessFn *, void *); 524 PETSC_EXTERN PetscErrorCode SNESSetPicard(SNES, Vec, SNESFunctionFn *, Mat, Mat, SNESJacobianFn *, void *); 525 PETSC_EXTERN PetscErrorCode SNESGetPicard(SNES, Vec *, SNESFunctionFn **, Mat *, Mat *, SNESJacobianFn **, void **); 526 PETSC_EXTERN SNESFunctionFn SNESPicardComputeFunction; 527 PETSC_EXTERN SNESFunctionFn SNESPicardComputeMFFunction; 528 PETSC_EXTERN SNESJacobianFn SNESPicardComputeJacobian; 529 530 PETSC_EXTERN PetscErrorCode SNESSetObjective(SNES, SNESObjectiveFn *, void *); 531 PETSC_EXTERN PetscErrorCode SNESGetObjective(SNES, SNESObjectiveFn **, void **); 532 PETSC_EXTERN PetscErrorCode SNESComputeObjective(SNES, Vec, PetscReal *); 533 534 PETSC_EXTERN PetscErrorCode SNESSetUpdate(SNES, SNESUpdateFn *); 535 536 /*E 537 SNESNormSchedule - Frequency with which the norm is computed during a nonliner solve 538 539 Values: 540 + `SNES_NORM_DEFAULT` - use the default behavior for the current `SNESType` 541 . `SNES_NORM_NONE` - avoid all norm computations 542 . `SNES_NORM_ALWAYS` - compute the norms whenever possible 543 . `SNES_NORM_INITIAL_ONLY` - compute the norm only when the algorithm starts 544 . `SNES_NORM_FINAL_ONLY` - compute the norm only when the algorithm finishes 545 - `SNES_NORM_INITIAL_FINAL_ONLY` - compute the norm at the start and end of the algorithm 546 547 Level: advanced 548 549 Notes: 550 Support for these is highly dependent on the solver. 551 552 Some options limit the convergence tests that can be used. 553 554 The `SNES_NORM_NONE` option is most commonly used when the nonlinear solver is being used as a smoother, for example for `SNESFAS` 555 556 This is primarily used to turn off extra norm and function computation 557 when the solvers are composed. 558 559 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `KSPSetNormType()`, 560 `KSPSetConvergenceTest()`, `KSPSetPCSide()` 561 E*/ 562 typedef enum { 563 SNES_NORM_DEFAULT = -1, 564 SNES_NORM_NONE = 0, 565 SNES_NORM_ALWAYS = 1, 566 SNES_NORM_INITIAL_ONLY = 2, 567 SNES_NORM_FINAL_ONLY = 3, 568 SNES_NORM_INITIAL_FINAL_ONLY = 4 569 } SNESNormSchedule; 570 PETSC_EXTERN const char *const *const SNESNormSchedules; 571 572 /*MC 573 SNES_NORM_NONE - Don't compute function and its L2 norm when possible 574 575 Level: advanced 576 577 Note: 578 This is most useful for stationary solvers with a fixed number of iterations used as smoothers. 579 580 .seealso: [](ch_snes), `SNESNormSchedule`, `SNES`, `SNESSetNormSchedule()`, `SNES_NORM_DEFAULT` 581 M*/ 582 583 /*MC 584 SNES_NORM_ALWAYS - Compute the function and its L2 norm at each iteration. 585 586 Level: advanced 587 588 Note: 589 Most solvers will use this no matter what norm type is passed to them. 590 591 .seealso: [](ch_snes), `SNESNormSchedule`, `SNES`, `SNESSetNormSchedule()`, `SNES_NORM_NONE` 592 M*/ 593 594 /*MC 595 SNES_NORM_INITIAL_ONLY - Compute the function and its L2 at iteration 0, but do not update it. 596 597 Level: advanced 598 599 Notes: 600 This method is useful in composed methods, when a true solution might actually be found before `SNESSolve()` is called. 601 This option enables the solve to abort on the zeroth iteration if this is the case. 602 603 For solvers that require the computation of the L2 norm of the function as part of the method, this merely cancels 604 the norm computation at the last iteration (if possible). 605 606 .seealso: [](ch_snes), `SNESNormSchedule`, `SNES`, `SNESSetNormSchedule()`, `SNES_NORM_FINAL_ONLY`, `SNES_NORM_INITIAL_FINAL_ONLY` 607 M*/ 608 609 /*MC 610 SNES_NORM_FINAL_ONLY - Compute the function and its L2 norm on only the final iteration. 611 612 Level: advanced 613 614 Note: 615 For solvers that require the computation of the L2 norm of the function as part of the method, behaves 616 exactly as `SNES_NORM_DEFAULT`. This method is useful when the function is gotten after `SNESSolve()` and 617 used in subsequent computation for methods that do not need the norm computed during the rest of the 618 solution procedure. 619 620 .seealso: [](ch_snes), `SNESNormSchedule`, `SNES`, `SNESSetNormSchedule()`, `SNES_NORM_INITIAL_ONLY`, `SNES_NORM_INITIAL_FINAL_ONLY` 621 M*/ 622 623 /*MC 624 SNES_NORM_INITIAL_FINAL_ONLY - Compute the function and its L2 norm on only the initial and final iterations. 625 626 Level: advanced 627 628 Note: 629 This method combines the benefits of `SNES_NORM_INITIAL_ONLY` and `SNES_NORM_FINAL_ONLY`. 630 631 .seealso: [](ch_snes), `SNESNormSchedule`, `SNES`, `SNESSetNormSchedule()`, `SNES_NORM_SNES_NORM_INITIAL_ONLY`, `SNES_NORM_FINAL_ONLY` 632 M*/ 633 634 PETSC_EXTERN PetscErrorCode SNESSetNormSchedule(SNES, SNESNormSchedule); 635 PETSC_EXTERN PetscErrorCode SNESGetNormSchedule(SNES, SNESNormSchedule *); 636 PETSC_EXTERN PetscErrorCode SNESSetFunctionNorm(SNES, PetscReal); 637 PETSC_EXTERN PetscErrorCode SNESGetFunctionNorm(SNES, PetscReal *); 638 PETSC_EXTERN PetscErrorCode SNESGetUpdateNorm(SNES, PetscReal *); 639 PETSC_EXTERN PetscErrorCode SNESGetSolutionNorm(SNES, PetscReal *); 640 641 /*E 642 SNESFunctionType - Type of function computed 643 644 Values: 645 + `SNES_FUNCTION_DEFAULT` - the default behavior for the current `SNESType` 646 . `SNES_FUNCTION_UNPRECONDITIONED` - the original function provided 647 - `SNES_FUNCTION_PRECONDITIONED` - the modification of the function by the preconditioner 648 649 Level: advanced 650 651 Note: 652 Support for these is dependent on the solver. 653 654 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `KSPSetNormType()`, 655 `KSPSetConvergenceTest()`, `KSPSetPCSide()` 656 E*/ 657 typedef enum { 658 SNES_FUNCTION_DEFAULT = -1, 659 SNES_FUNCTION_UNPRECONDITIONED = 0, 660 SNES_FUNCTION_PRECONDITIONED = 1 661 } SNESFunctionType; 662 PETSC_EXTERN const char *const *const SNESFunctionTypes; 663 664 PETSC_EXTERN PetscErrorCode SNESSetFunctionType(SNES, SNESFunctionType); 665 PETSC_EXTERN PetscErrorCode SNESGetFunctionType(SNES, SNESFunctionType *); 666 667 PETSC_EXTERN PetscErrorCode SNESSetNGS(SNES, SNESNGSFn *, void *); 668 PETSC_EXTERN PetscErrorCode SNESGetNGS(SNES, SNESNGSFn **, void **); 669 PETSC_EXTERN PetscErrorCode SNESComputeNGS(SNES, Vec, Vec); 670 671 PETSC_EXTERN PetscErrorCode SNESNGSSetSweeps(SNES, PetscInt); 672 PETSC_EXTERN PetscErrorCode SNESNGSGetSweeps(SNES, PetscInt *); 673 PETSC_EXTERN PetscErrorCode SNESNGSSetTolerances(SNES, PetscReal, PetscReal, PetscReal, PetscInt); 674 PETSC_EXTERN PetscErrorCode SNESNGSGetTolerances(SNES, PetscReal *, PetscReal *, PetscReal *, PetscInt *); 675 676 PETSC_EXTERN PetscErrorCode SNESSetAlwaysComputesFinalResidual(SNES, PetscBool); 677 PETSC_EXTERN PetscErrorCode SNESGetAlwaysComputesFinalResidual(SNES, PetscBool *); 678 679 PETSC_EXTERN PetscErrorCode SNESShellGetContext(SNES, void *); 680 PETSC_EXTERN PetscErrorCode SNESShellSetContext(SNES, void *); 681 PETSC_EXTERN PetscErrorCode SNESShellSetSolve(SNES, PetscErrorCode (*)(SNES, Vec)); 682 683 /* --------- Routines specifically for line search methods --------------- */ 684 685 /*S 686 SNESLineSearch - Abstract PETSc object that manages line-search operations for nonlinear solvers 687 688 Level: beginner 689 690 .seealso: [](ch_snes), `SNESLineSearchType`, `SNESLineSearchCreate()`, `SNESLineSearchSetType()`, `SNES` 691 S*/ 692 typedef struct _p_LineSearch *SNESLineSearch; 693 694 /*J 695 SNESLineSearchType - String with the name of a PETSc line search method `SNESLineSearch` 696 697 Values: 698 + `SNESLINESEARCHBASIC` - (or equivalently `SNESLINESEARCHNONE`) Simple damping line search, defaults to using the full Newton step 699 . `SNESLINESEARCHBT` - Backtracking line search over the L2 norm of the function 700 . `SNESLINESEARCHL2` - Secant line search over the L2 norm of the function 701 . `SNESLINESEARCHCP` - Critical point secant line search assuming F(x) = grad G(x) for some unknown G(x) 702 . `SNESLINESEARCHNLEQERR` - Affine-covariant error-oriented linesearch 703 - `SNESLINESEARCHSHELL` - User provided `SNESLineSearch` implementation 704 705 Level: beginner 706 707 .seealso: [](ch_snes), `SNESLineSearch`, `SNESLineSearchSetType()`, `SNES` 708 J*/ 709 typedef const char *SNESLineSearchType; 710 #define SNESLINESEARCHBT "bt" 711 #define SNESLINESEARCHNLEQERR "nleqerr" 712 #define SNESLINESEARCHBASIC "basic" 713 #define SNESLINESEARCHNONE "none" 714 #define SNESLINESEARCHL2 "l2" 715 #define SNESLINESEARCHCP "cp" 716 #define SNESLINESEARCHSHELL "shell" 717 #define SNESLINESEARCHNCGLINEAR "ncglinear" 718 719 PETSC_EXTERN PetscFunctionList SNESList; 720 PETSC_EXTERN PetscClassId SNESLINESEARCH_CLASSID; 721 PETSC_EXTERN PetscFunctionList SNESLineSearchList; 722 723 #define SNES_LINESEARCH_ORDER_LINEAR 1 724 #define SNES_LINESEARCH_ORDER_QUADRATIC 2 725 #define SNES_LINESEARCH_ORDER_CUBIC 3 726 727 /*S 728 SNESLineSearchVIProjectFn - A prototype of a `SNES` function that projects a vector onto the VI bounds, passed to `SNESLineSearchSetVIFunctions()` 729 730 Calling Sequence: 731 + snes - `SNES` context 732 - u - the vector to project to the bounds 733 734 Level: advanced 735 736 Note: 737 The deprecated `SNESLineSearchVIProjectFunc` still works as a replacement for `SNESLineSearchVIProjectFn` *. 738 739 .seealso: [](ch_snes), `SNES`, `SNESLineSearch` 740 S*/ 741 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESLineSearchVIProjectFn)(SNES snes, Vec u); 742 PETSC_EXTERN_TYPEDEF typedef SNESLineSearchVIProjectFn *SNESLineSearchVIProjectFunc; // deprecated 743 744 /*S 745 SNESLineSearchVIProjectFn - A prototype of a `SNES` function that computes the norm of the active set variables in a vector in a VI solve, 746 passed to `SNESLineSearchSetVIFunctions()` 747 748 Calling Sequence: 749 + snes - `SNES` context 750 . f - the vector to compute the norm of 751 . u - the current solution, entries that are on the VI bounds are ignored 752 - fnorm - the resulting norm 753 754 Level: advanced 755 756 Note: 757 The deprecated `SNESLineSearchVINormFunc` still works as a replacement for `SNESLineSearchVINormFn` *. 758 759 .seealso: [](ch_snes), `SNES`, `SNESLineSearch` 760 S*/ 761 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESLineSearchVINormFn)(SNES snes, Vec f, Vec u, PetscReal *fnorm); 762 PETSC_EXTERN_TYPEDEF typedef SNESLineSearchVINormFn *SNESLineSearchVINormFunc; // deprecated 763 764 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESLineSearchApplyFn)(SNESLineSearch); 765 PETSC_EXTERN_TYPEDEF typedef SNESLineSearchApplyFn *SNESLineSearchApplyFunc; // deprecated 766 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESLineSearchShellApplyFn)(SNESLineSearch, void *); 767 PETSC_EXTERN_TYPEDEF typedef SNESLineSearchShellApplyFn *SNESLineSearchUserFunc; // deprecated 768 769 PETSC_EXTERN PetscErrorCode SNESLineSearchCreate(MPI_Comm, SNESLineSearch *); 770 PETSC_EXTERN PetscErrorCode SNESLineSearchReset(SNESLineSearch); 771 PETSC_EXTERN PetscErrorCode SNESLineSearchView(SNESLineSearch, PetscViewer); 772 PETSC_EXTERN PetscErrorCode SNESLineSearchDestroy(SNESLineSearch *); 773 PETSC_EXTERN PetscErrorCode SNESLineSearchGetType(SNESLineSearch, SNESLineSearchType *); 774 PETSC_EXTERN PetscErrorCode SNESLineSearchSetType(SNESLineSearch, SNESLineSearchType); 775 PETSC_EXTERN PetscErrorCode SNESLineSearchSetFromOptions(SNESLineSearch); 776 PETSC_EXTERN PetscErrorCode SNESLineSearchSetFunction(SNESLineSearch, PetscErrorCode (*)(SNES, Vec, Vec)); 777 PETSC_EXTERN PetscErrorCode SNESLineSearchSetUp(SNESLineSearch); 778 PETSC_EXTERN PetscErrorCode SNESLineSearchApply(SNESLineSearch, Vec, Vec, PetscReal *, Vec); 779 PETSC_EXTERN PetscErrorCode SNESLineSearchPreCheck(SNESLineSearch, Vec, Vec, PetscBool *); 780 PETSC_EXTERN PetscErrorCode SNESLineSearchPostCheck(SNESLineSearch, Vec, Vec, Vec, PetscBool *, PetscBool *); 781 PETSC_EXTERN PetscErrorCode SNESLineSearchSetWorkVecs(SNESLineSearch, PetscInt); 782 783 /* set the functions for precheck and postcheck */ 784 785 PETSC_EXTERN PetscErrorCode SNESLineSearchSetPreCheck(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch, Vec, Vec, PetscBool *, void *), void *ctx); 786 PETSC_EXTERN PetscErrorCode SNESLineSearchSetPostCheck(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void *ctx); 787 788 PETSC_EXTERN PetscErrorCode SNESLineSearchGetPreCheck(SNESLineSearch, PetscErrorCode (**)(SNESLineSearch, Vec, Vec, PetscBool *, void *), void **ctx); 789 PETSC_EXTERN PetscErrorCode SNESLineSearchGetPostCheck(SNESLineSearch, PetscErrorCode (**)(SNESLineSearch, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void **ctx); 790 791 /* set the functions for VI-specific line search operations */ 792 793 PETSC_EXTERN PetscErrorCode SNESLineSearchSetVIFunctions(SNESLineSearch, SNESLineSearchVIProjectFn *, SNESLineSearchVINormFn *); 794 PETSC_EXTERN PetscErrorCode SNESLineSearchGetVIFunctions(SNESLineSearch, SNESLineSearchVIProjectFn **, SNESLineSearchVINormFn **); 795 796 /* pointers to the associated SNES in order to be able to get the function evaluation out */ 797 PETSC_EXTERN PetscErrorCode SNESLineSearchSetSNES(SNESLineSearch, SNES); 798 PETSC_EXTERN PetscErrorCode SNESLineSearchGetSNES(SNESLineSearch, SNES *); 799 800 /* set and get the parameters and vectors */ 801 PETSC_EXTERN PetscErrorCode SNESLineSearchGetTolerances(SNESLineSearch, PetscReal *, PetscReal *, PetscReal *, PetscReal *, PetscReal *, PetscInt *); 802 PETSC_EXTERN PetscErrorCode SNESLineSearchSetTolerances(SNESLineSearch, PetscReal, PetscReal, PetscReal, PetscReal, PetscReal, PetscInt); 803 804 PETSC_EXTERN PetscErrorCode SNESLineSearchPreCheckPicard(SNESLineSearch, Vec, Vec, PetscBool *, void *); 805 806 PETSC_EXTERN PetscErrorCode SNESLineSearchGetLambda(SNESLineSearch, PetscReal *); 807 PETSC_EXTERN PetscErrorCode SNESLineSearchSetLambda(SNESLineSearch, PetscReal); 808 809 PETSC_EXTERN PetscErrorCode SNESLineSearchGetDamping(SNESLineSearch, PetscReal *); 810 PETSC_EXTERN PetscErrorCode SNESLineSearchSetDamping(SNESLineSearch, PetscReal); 811 812 PETSC_EXTERN PetscErrorCode SNESLineSearchGetOrder(SNESLineSearch, PetscInt *order); 813 PETSC_EXTERN PetscErrorCode SNESLineSearchSetOrder(SNESLineSearch, PetscInt order); 814 815 /*E 816 SNESLineSearchReason - indication if the line search has succeeded or failed and why 817 818 Values: 819 + `SNES_LINESEARCH_SUCCEEDED` - the line search succeeded 820 . `SNES_LINESEARCH_FAILED_NANORINF` - a not a number of infinity appeared in the computions 821 . `SNES_LINESEARCH_FAILED_DOMAIN` - the function was evaluated outside of its domain, see `SNESSetFunctionDomainError()` and `SNESSetJacobianDomainError()` 822 . `SNES_LINESEARCH_FAILED_REDUCT` - the linear search failed to get the requested decrease in its norm or objective 823 . `SNES_LINESEARCH_FAILED_USER` - used by `SNESLINESEARCHNLEQERR` to indicate the user changed the search direction inappropriately 824 - `SNES_LINESEARCH_FAILED_FUNCTION` - indicates the maximum number of function evaluations allowed has been surpassed, `SNESConvergedReason` is also 825 set to `SNES_DIVERGED_FUNCTION_COUNT` 826 827 Level: intermediate 828 829 Developer Note: 830 Some of these reasons overlap with values of `SNESConvergedReason` 831 832 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `KSPConvergedReason`, `SNESSetConvergenceTest()`, 833 `SNESSetFunctionDomainError()` and `SNESSetJacobianDomainError()` 834 E*/ 835 typedef enum { 836 SNES_LINESEARCH_SUCCEEDED, 837 SNES_LINESEARCH_FAILED_NANORINF, 838 SNES_LINESEARCH_FAILED_DOMAIN, 839 SNES_LINESEARCH_FAILED_REDUCT, /* INSUFFICIENT REDUCTION */ 840 SNES_LINESEARCH_FAILED_USER, 841 SNES_LINESEARCH_FAILED_FUNCTION 842 } SNESLineSearchReason; 843 844 PETSC_EXTERN PetscErrorCode SNESLineSearchGetReason(SNESLineSearch, SNESLineSearchReason *); 845 PETSC_EXTERN PetscErrorCode SNESLineSearchSetReason(SNESLineSearch, SNESLineSearchReason); 846 847 PETSC_EXTERN PetscErrorCode SNESLineSearchGetVecs(SNESLineSearch, Vec *, Vec *, Vec *, Vec *, Vec *); 848 PETSC_EXTERN PetscErrorCode SNESLineSearchSetVecs(SNESLineSearch, Vec, Vec, Vec, Vec, Vec); 849 850 PETSC_EXTERN PetscErrorCode SNESLineSearchGetNorms(SNESLineSearch, PetscReal *, PetscReal *, PetscReal *); 851 PETSC_EXTERN PetscErrorCode SNESLineSearchSetNorms(SNESLineSearch, PetscReal, PetscReal, PetscReal); 852 PETSC_EXTERN PetscErrorCode SNESLineSearchComputeNorms(SNESLineSearch); 853 PETSC_EXTERN PetscErrorCode SNESLineSearchSetComputeNorms(SNESLineSearch, PetscBool); 854 855 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitor(SNESLineSearch); 856 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSet(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch, void *), void *, PetscErrorCode (*)(void **)); 857 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSetFromOptions(SNESLineSearch, const char[], const char[], const char[], PetscErrorCode (*)(SNESLineSearch, PetscViewerAndFormat *), PetscErrorCode (*)(SNESLineSearch, PetscViewerAndFormat *)); 858 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorCancel(SNESLineSearch); 859 PETSC_EXTERN PetscErrorCode SNESLineSearchSetDefaultMonitor(SNESLineSearch, PetscViewer); 860 PETSC_EXTERN PetscErrorCode SNESLineSearchGetDefaultMonitor(SNESLineSearch, PetscViewer *); 861 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSolutionUpdate(SNESLineSearch, PetscViewerAndFormat *); 862 863 PETSC_EXTERN PetscErrorCode SNESLineSearchAppendOptionsPrefix(SNESLineSearch, const char prefix[]); 864 PETSC_EXTERN PetscErrorCode SNESLineSearchGetOptionsPrefix(SNESLineSearch, const char *prefix[]); 865 866 /* Shell interface functions */ 867 PETSC_EXTERN PetscErrorCode SNESLineSearchShellSetApply(SNESLineSearch, SNESLineSearchShellApplyFn, void *); 868 PETSC_EXTERN PetscErrorCode SNESLineSearchShellGetApply(SNESLineSearch, SNESLineSearchShellApplyFn **, void **); 869 870 PETSC_DEPRECATED_FUNCTION(3, 21, 0, "SNESLinesearchShellSetApply()", ) static inline PetscErrorCode SNESLineSearchShellSetUserFunc(SNESLineSearch ls, SNESLineSearchUserFunc f, void *ctx) 871 { 872 return SNESLineSearchShellSetApply(ls, f, ctx); 873 } 874 875 PETSC_DEPRECATED_FUNCTION(3, 21, 0, "SNESLinesearchShellGetApply()", ) static inline PetscErrorCode SNESLineSearchShellGetUserFunc(SNESLineSearch ls, SNESLineSearchUserFunc *f, void **ctx) 876 { 877 return SNESLineSearchShellGetApply(ls, f, ctx); 878 } 879 880 /* BT interface functions */ 881 PETSC_EXTERN PetscErrorCode SNESLineSearchBTSetAlpha(SNESLineSearch, PetscReal); 882 PETSC_EXTERN PetscErrorCode SNESLineSearchBTGetAlpha(SNESLineSearch, PetscReal *); 883 884 /*register line search types */ 885 PETSC_EXTERN PetscErrorCode SNESLineSearchRegister(const char[], PetscErrorCode (*)(SNESLineSearch)); 886 887 /* Routines for VI solver */ 888 PETSC_EXTERN PetscErrorCode SNESVISetVariableBounds(SNES, Vec, Vec); 889 PETSC_EXTERN PetscErrorCode SNESVIGetVariableBounds(SNES, Vec *, Vec *); 890 PETSC_EXTERN PetscErrorCode SNESVISetComputeVariableBounds(SNES, PetscErrorCode (*)(SNES, Vec, Vec)); 891 PETSC_EXTERN PetscErrorCode SNESVIGetInactiveSet(SNES, IS *); 892 PETSC_EXTERN PetscErrorCode SNESVIGetActiveSetIS(SNES, Vec, Vec, IS *); 893 PETSC_EXTERN PetscErrorCode SNESVIComputeInactiveSetFnorm(SNES, Vec, Vec, PetscReal *); 894 PETSC_EXTERN PetscErrorCode SNESVISetRedundancyCheck(SNES, PetscErrorCode (*)(SNES, IS, IS *, void *), void *); 895 PETSC_EXTERN PetscErrorCode SNESVIComputeMeritFunction(Vec, PetscReal *, PetscReal *); 896 PETSC_EXTERN PetscErrorCode SNESVIComputeFunction(SNES, Vec, Vec, void *); 897 PETSC_EXTERN PetscErrorCode DMSetVI(DM, IS); 898 PETSC_EXTERN PetscErrorCode DMDestroyVI(DM); 899 900 PETSC_EXTERN PetscErrorCode SNESTestLocalMin(SNES); 901 902 /* Should this routine be private? */ 903 PETSC_EXTERN PetscErrorCode SNESComputeJacobian(SNES, Vec, Mat, Mat); 904 PETSC_EXTERN PetscErrorCode SNESTestJacobian(SNES); 905 PETSC_EXTERN PetscErrorCode SNESTestFunction(SNES); 906 907 PETSC_EXTERN PetscErrorCode SNESSetDM(SNES, DM); 908 PETSC_EXTERN PetscErrorCode SNESGetDM(SNES, DM *); 909 PETSC_EXTERN PetscErrorCode SNESSetNPC(SNES, SNES); 910 PETSC_EXTERN PetscErrorCode SNESGetNPC(SNES, SNES *); 911 PETSC_EXTERN PetscErrorCode SNESHasNPC(SNES, PetscBool *); 912 PETSC_EXTERN PetscErrorCode SNESApplyNPC(SNES, Vec, Vec, Vec); 913 PETSC_EXTERN PetscErrorCode SNESGetNPCFunction(SNES, Vec, PetscReal *); 914 PETSC_EXTERN PetscErrorCode SNESComputeFunctionDefaultNPC(SNES, Vec, Vec); 915 PETSC_EXTERN PetscErrorCode SNESSetNPCSide(SNES, PCSide); 916 PETSC_EXTERN PetscErrorCode SNESGetNPCSide(SNES, PCSide *); 917 PETSC_EXTERN PetscErrorCode SNESSetLineSearch(SNES, SNESLineSearch); 918 PETSC_EXTERN PetscErrorCode SNESGetLineSearch(SNES, SNESLineSearch *); 919 920 PETSC_DEPRECATED_FUNCTION(3, 4, 0, "SNESGetLineSearch()", ) static inline PetscErrorCode SNESGetSNESLineSearch(SNES snes, SNESLineSearch *ls) 921 { 922 return SNESGetLineSearch(snes, ls); 923 } 924 PETSC_DEPRECATED_FUNCTION(3, 4, 0, "SNESSetLineSearch()", ) static inline PetscErrorCode SNESSetSNESLineSearch(SNES snes, SNESLineSearch ls) 925 { 926 return SNESSetLineSearch(snes, ls); 927 } 928 929 PETSC_EXTERN PetscErrorCode SNESSetUpMatrices(SNES); 930 PETSC_EXTERN PetscErrorCode DMSNESSetFunction(DM, SNESFunctionFn *, void *); 931 PETSC_EXTERN PetscErrorCode DMSNESGetFunction(DM, SNESFunctionFn **, void **); 932 PETSC_EXTERN PetscErrorCode DMSNESSetFunctionContextDestroy(DM, PetscErrorCode (*)(void *)); 933 PETSC_EXTERN PetscErrorCode DMSNESSetMFFunction(DM, SNESFunctionFn *, void *); 934 PETSC_EXTERN PetscErrorCode DMSNESSetNGS(DM, SNESNGSFn *, void *); 935 PETSC_EXTERN PetscErrorCode DMSNESGetNGS(DM, SNESNGSFn **, void **); 936 PETSC_EXTERN PetscErrorCode DMSNESSetJacobian(DM, SNESJacobianFn *, void *); 937 PETSC_EXTERN PetscErrorCode DMSNESGetJacobian(DM, SNESJacobianFn **, void **); 938 PETSC_EXTERN PetscErrorCode DMSNESSetJacobianContextDestroy(DM, PetscErrorCode (*)(void *)); 939 PETSC_EXTERN PetscErrorCode DMSNESSetPicard(DM, SNESFunctionFn *, SNESJacobianFn *, void *); 940 PETSC_EXTERN PetscErrorCode DMSNESGetPicard(DM, SNESFunctionFn **, SNESJacobianFn **, void **); 941 PETSC_EXTERN PetscErrorCode DMSNESSetObjective(DM, SNESObjectiveFn *, void *); 942 PETSC_EXTERN PetscErrorCode DMSNESGetObjective(DM, SNESObjectiveFn **, void **); 943 PETSC_EXTERN PetscErrorCode DMCopyDMSNES(DM, DM); 944 945 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESFunctionFn)(DMDALocalInfo *, void *, void *, void *); 946 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESJacobianFn)(DMDALocalInfo *, void *, Mat, Mat, void *); 947 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESObjectiveFn)(DMDALocalInfo *, void *, PetscReal *, void *); 948 949 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESFunctionVecFn)(DMDALocalInfo *, Vec, Vec, void *); 950 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESJacobianVecFn)(DMDALocalInfo *, Vec, Mat, Mat, void *); 951 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESObjectiveVecFn)(DMDALocalInfo *, Vec, PetscReal *, void *); 952 953 PETSC_EXTERN PetscErrorCode DMDASNESSetFunctionLocal(DM, InsertMode, DMDASNESFunctionFn *, void *); 954 PETSC_EXTERN PetscErrorCode DMDASNESSetJacobianLocal(DM, DMDASNESJacobianFn *, void *); 955 PETSC_EXTERN PetscErrorCode DMDASNESSetObjectiveLocal(DM, DMDASNESObjectiveFn *, void *); 956 PETSC_EXTERN PetscErrorCode DMDASNESSetPicardLocal(DM, InsertMode, DMDASNESFunctionFn *, DMDASNESJacobianFn, void *); 957 958 PETSC_EXTERN PetscErrorCode DMDASNESSetFunctionLocalVec(DM, InsertMode, DMDASNESFunctionVecFn *, void *); 959 PETSC_EXTERN PetscErrorCode DMDASNESSetJacobianLocalVec(DM, DMDASNESJacobianVecFn *, void *); 960 PETSC_EXTERN PetscErrorCode DMDASNESSetObjectiveLocalVec(DM, DMDASNESObjectiveVecFn *, void *); 961 962 PETSC_EXTERN PetscErrorCode DMSNESSetBoundaryLocal(DM, PetscErrorCode (*)(DM, Vec, void *), void *); 963 PETSC_EXTERN PetscErrorCode DMSNESSetObjectiveLocal(DM, PetscErrorCode (*)(DM, Vec, PetscReal *, void *), void *); 964 PETSC_EXTERN PetscErrorCode DMSNESSetFunctionLocal(DM, PetscErrorCode (*)(DM, Vec, Vec, void *), void *); 965 PETSC_EXTERN PetscErrorCode DMSNESSetJacobianLocal(DM, PetscErrorCode (*)(DM, Vec, Mat, Mat, void *), void *); 966 PETSC_EXTERN PetscErrorCode DMSNESGetBoundaryLocal(DM, PetscErrorCode (**)(DM, Vec, void *), void **); 967 PETSC_EXTERN PetscErrorCode DMSNESGetObjectiveLocal(DM, PetscErrorCode (**)(DM, Vec, PetscReal *, void *), void **); 968 PETSC_EXTERN PetscErrorCode DMSNESGetFunctionLocal(DM, PetscErrorCode (**)(DM, Vec, Vec, void *), void **); 969 PETSC_EXTERN PetscErrorCode DMSNESGetJacobianLocal(DM, PetscErrorCode (**)(DM, Vec, Mat, Mat, void *), void **); 970 971 /* Routines for Multiblock solver */ 972 PETSC_EXTERN PetscErrorCode SNESMultiblockSetFields(SNES, const char[], PetscInt, const PetscInt *); 973 PETSC_EXTERN PetscErrorCode SNESMultiblockSetIS(SNES, const char[], IS); 974 PETSC_EXTERN PetscErrorCode SNESMultiblockSetBlockSize(SNES, PetscInt); 975 PETSC_EXTERN PetscErrorCode SNESMultiblockSetType(SNES, PCCompositeType); 976 PETSC_EXTERN PetscErrorCode SNESMultiblockGetSubSNES(SNES, PetscInt *, SNES *[]); 977 978 /*J 979 SNESMSType - String with the name of a PETSc `SNESMS` method. 980 981 Level: intermediate 982 983 .seealso: [](ch_snes), `SNESMS`, `SNESMSGetType()`, `SNESMSSetType()`, `SNES` 984 J*/ 985 typedef const char *SNESMSType; 986 #define SNESMSM62 "m62" 987 #define SNESMSEULER "euler" 988 #define SNESMSJAMESON83 "jameson83" 989 #define SNESMSVLTP11 "vltp11" 990 #define SNESMSVLTP21 "vltp21" 991 #define SNESMSVLTP31 "vltp31" 992 #define SNESMSVLTP41 "vltp41" 993 #define SNESMSVLTP51 "vltp51" 994 #define SNESMSVLTP61 "vltp61" 995 996 PETSC_EXTERN PetscErrorCode SNESMSRegister(SNESMSType, PetscInt, PetscInt, PetscReal, const PetscReal[], const PetscReal[], const PetscReal[]); 997 PETSC_EXTERN PetscErrorCode SNESMSRegisterAll(void); 998 PETSC_EXTERN PetscErrorCode SNESMSGetType(SNES, SNESMSType *); 999 PETSC_EXTERN PetscErrorCode SNESMSSetType(SNES, SNESMSType); 1000 PETSC_EXTERN PetscErrorCode SNESMSGetDamping(SNES, PetscReal *); 1001 PETSC_EXTERN PetscErrorCode SNESMSSetDamping(SNES, PetscReal); 1002 PETSC_EXTERN PetscErrorCode SNESMSFinalizePackage(void); 1003 PETSC_EXTERN PetscErrorCode SNESMSInitializePackage(void); 1004 PETSC_EXTERN PetscErrorCode SNESMSRegisterDestroy(void); 1005 1006 /*MC 1007 SNESNGMRESRestartType - the restart approach used by `SNESNGMRES` 1008 1009 Values: 1010 + `SNES_NGMRES_RESTART_NONE` - never restart 1011 . `SNES_NGMRES_RESTART_DIFFERENCE` - restart based upon difference criteria 1012 - `SNES_NGMRES_RESTART_PERIODIC` - restart after a fixed number of iterations 1013 1014 Options Database Keys: 1015 + -snes_ngmres_restart_type <difference,periodic,none> - set the restart type 1016 - -snes_ngmres_restart <30> - sets the number of iterations before restart for periodic 1017 1018 Level: intermediate 1019 1020 .seealso: `SNES, `SNESNGMRES`, `SNESNGMRESSetSelectType()`, `SNESNGMRESGetSelectType()`, `SNESNGMRESSetRestartType()`, 1021 `SNESNGMRESGetRestartType()`, `SNESNGMRESSelectType` 1022 M*/ 1023 typedef enum { 1024 SNES_NGMRES_RESTART_NONE = 0, 1025 SNES_NGMRES_RESTART_PERIODIC = 1, 1026 SNES_NGMRES_RESTART_DIFFERENCE = 2 1027 } SNESNGMRESRestartType; 1028 PETSC_EXTERN const char *const SNESNGMRESRestartTypes[]; 1029 1030 /*MC 1031 SNESNGMRESSelectType - the approach used by `SNESNGMRES` to determine how the candidate solution and 1032 combined solution are used to create the next iterate. 1033 1034 Values: 1035 + `SNES_NGMRES_SELECT_NONE` - choose the combined solution all the time 1036 . `SNES_NGMRES_SELECT_DIFFERENCE` - choose based upon the selection criteria 1037 - `SNES_NGMRES_SELECT_LINESEARCH` - choose based upon line search combination 1038 1039 Options Database Key: 1040 . -snes_ngmres_select_type<difference,none,linesearch> - select type 1041 1042 Level: intermediate 1043 1044 .seealso: `SNES, `SNESNGMRES`, `SNESNGMRESSetSelectType()`, `SNESNGMRESGetSelectType()`, `SNESNGMRESSetRestartType()`, 1045 `SNESNGMRESGetRestartType()`, `SNESNGMRESRestartType` 1046 M*/ 1047 typedef enum { 1048 SNES_NGMRES_SELECT_NONE = 0, 1049 SNES_NGMRES_SELECT_DIFFERENCE = 1, 1050 SNES_NGMRES_SELECT_LINESEARCH = 2 1051 } SNESNGMRESSelectType; 1052 PETSC_EXTERN const char *const SNESNGMRESSelectTypes[]; 1053 1054 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartType(SNES, SNESNGMRESRestartType); 1055 PETSC_EXTERN PetscErrorCode SNESNGMRESSetSelectType(SNES, SNESNGMRESSelectType); 1056 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartFmRise(SNES, PetscBool); 1057 PETSC_EXTERN PetscErrorCode SNESNGMRESGetRestartFmRise(SNES, PetscBool *); 1058 1059 /*MC 1060 SNESNCGType - the conjugate update approach for `SNESNCG` 1061 1062 Values: 1063 + `SNES_NCG_FR` - Fletcher-Reeves update 1064 . `SNES_NCG_PRP` - Polak-Ribiere-Polyak update, the default and the only one that tolerates generalized search directions 1065 . `SNES_NCG_HS` - Hestenes-Steifel update 1066 . `SNES_NCG_DY` - Dai-Yuan update 1067 - `SNES_NCG_CD` - Conjugate Descent update 1068 1069 Options Database Key: 1070 . -snes_ncg_type<fr,prp,hs,dy,cd> - select type 1071 1072 Level: intermediate 1073 1074 .seealso: `SNES, `SNESNCG`, `SNESNCGSetType()` 1075 M*/ 1076 typedef enum { 1077 SNES_NCG_FR = 0, 1078 SNES_NCG_PRP = 1, 1079 SNES_NCG_HS = 2, 1080 SNES_NCG_DY = 3, 1081 SNES_NCG_CD = 4 1082 } SNESNCGType; 1083 PETSC_EXTERN const char *const SNESNCGTypes[]; 1084 1085 PETSC_EXTERN PetscErrorCode SNESNCGSetType(SNES, SNESNCGType); 1086 1087 /*MC 1088 SNESQNScaleType - the scaling type used by `SNESQN` 1089 1090 Values: 1091 + `SNES_QN_SCALE_NONE` - don't scale the problem 1092 . `SNES_QN_SCALE_SCALAR` - use Shanno scaling 1093 . `SNES_QN_SCALE_DIAGONAL` - scale with a diagonalized BFGS formula (see Gilbert and Lemarechal 1989), available 1094 - `SNES_QN_SCALE_JACOBIAN` - scale by solving a linear system coming from the Jacobian you provided with `SNESSetJacobian()` 1095 computed at the first iteration of `SNESQN` and at ever restart. 1096 1097 Options Database Key: 1098 . -snes_qn_scale_type <diagonal,none,scalar,jacobian> - Scaling type 1099 1100 Level: intermediate 1101 1102 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNType`, `SNESQNSetType()`, `SNESQNSetRestartType()`, `SNESQNRestartType` 1103 M*/ 1104 typedef enum { 1105 SNES_QN_SCALE_DEFAULT = 0, 1106 SNES_QN_SCALE_NONE = 1, 1107 SNES_QN_SCALE_SCALAR = 2, 1108 SNES_QN_SCALE_DIAGONAL = 3, 1109 SNES_QN_SCALE_JACOBIAN = 4 1110 } SNESQNScaleType; 1111 PETSC_EXTERN const char *const SNESQNScaleTypes[]; 1112 1113 /*MC 1114 SNESQNRestartType - the restart approached used by `SNESQN` 1115 1116 Values: 1117 + `SNES_QN_RESTART_NONE` - never restart 1118 . `SNES_QN_RESTART_POWELL` - restart based upon descent criteria 1119 - `SNES_QN_RESTART_PERIODIC` - restart after a fixed number of iterations 1120 1121 Options Database Keys: 1122 + -snes_qn_restart_type <powell,periodic,none> - set the restart type 1123 - -snes_qn_m <m> - sets the number of stored updates and the restart period for periodic 1124 1125 Level: intermediate 1126 1127 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNType`, `SNESQNSetType()`, `SNESQNSetRestartType()`, `SNESQNScaleType` 1128 M*/ 1129 typedef enum { 1130 SNES_QN_RESTART_DEFAULT = 0, 1131 SNES_QN_RESTART_NONE = 1, 1132 SNES_QN_RESTART_POWELL = 2, 1133 SNES_QN_RESTART_PERIODIC = 3 1134 } SNESQNRestartType; 1135 PETSC_EXTERN const char *const SNESQNRestartTypes[]; 1136 1137 /*MC 1138 SNESQNType - the type used by `SNESQN` 1139 1140 Values: 1141 + `SNES_QN_LBFGS` - LBFGS variant 1142 . `SNES_QN_BROYDEN` - Broyden variant 1143 - `SNES_QN_BADBROYDEN` - Bad Broyden variant 1144 1145 Options Database Key: 1146 . -snes_qn_type <lbfgs,broyden,badbroyden> - quasi-Newton type 1147 1148 Level: intermediate 1149 1150 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNSetType()`, `SNESQNScaleType`, `SNESQNRestartType`, `SNESQNSetRestartType()` 1151 M*/ 1152 typedef enum { 1153 SNES_QN_LBFGS = 0, 1154 SNES_QN_BROYDEN = 1, 1155 SNES_QN_BADBROYDEN = 2 1156 } SNESQNType; 1157 PETSC_EXTERN const char *const SNESQNTypes[]; 1158 1159 PETSC_EXTERN PetscErrorCode SNESQNSetType(SNES, SNESQNType); 1160 PETSC_EXTERN PetscErrorCode SNESQNSetScaleType(SNES, SNESQNScaleType); 1161 PETSC_EXTERN PetscErrorCode SNESQNSetRestartType(SNES, SNESQNRestartType); 1162 1163 PETSC_EXTERN PetscErrorCode SNESNASMGetType(SNES, PCASMType *); 1164 PETSC_EXTERN PetscErrorCode SNESNASMSetType(SNES, PCASMType); 1165 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomains(SNES, PetscInt *, SNES **, VecScatter **, VecScatter **, VecScatter **); 1166 PETSC_EXTERN PetscErrorCode SNESNASMSetSubdomains(SNES, PetscInt, SNES *, VecScatter *, VecScatter *, VecScatter *); 1167 PETSC_EXTERN PetscErrorCode SNESNASMSetDamping(SNES, PetscReal); 1168 PETSC_EXTERN PetscErrorCode SNESNASMGetDamping(SNES, PetscReal *); 1169 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomainVecs(SNES, PetscInt *, Vec **, Vec **, Vec **, Vec **); 1170 PETSC_EXTERN PetscErrorCode SNESNASMSetComputeFinalJacobian(SNES, PetscBool); 1171 PETSC_EXTERN PetscErrorCode SNESNASMGetSNES(SNES, PetscInt, SNES *); 1172 PETSC_EXTERN PetscErrorCode SNESNASMGetNumber(SNES, PetscInt *); 1173 PETSC_EXTERN PetscErrorCode SNESNASMSetWeight(SNES, Vec); 1174 1175 /*E 1176 SNESCompositeType - Determines how two or more preconditioners are composed with the `SNESType` of `SNESCOMPOSITE` 1177 1178 Values: 1179 + `SNES_COMPOSITE_ADDITIVE` - results from application of all preconditioners are added together 1180 . `SNES_COMPOSITE_MULTIPLICATIVE` - preconditioners are applied sequentially to the residual freshly 1181 computed after the previous preconditioner application 1182 - `SNES_COMPOSITE_ADDITIVEOPTIMAL` - uses a linear combination of the solutions obtained with each preconditioner that approximately minimize the function 1183 value at the new iteration. 1184 1185 Level: beginner 1186 1187 .seealso: [](sec_pc), `PCCOMPOSITE`, `PCFIELDSPLIT`, `PC`, `PCCompositeSetType()`, `PCCompositeType` 1188 E*/ 1189 typedef enum { 1190 SNES_COMPOSITE_ADDITIVE, 1191 SNES_COMPOSITE_MULTIPLICATIVE, 1192 SNES_COMPOSITE_ADDITIVEOPTIMAL 1193 } SNESCompositeType; 1194 PETSC_EXTERN const char *const SNESCompositeTypes[]; 1195 1196 PETSC_EXTERN PetscErrorCode SNESCompositeSetType(SNES, SNESCompositeType); 1197 PETSC_EXTERN PetscErrorCode SNESCompositeAddSNES(SNES, SNESType); 1198 PETSC_EXTERN PetscErrorCode SNESCompositeGetSNES(SNES, PetscInt, SNES *); 1199 PETSC_EXTERN PetscErrorCode SNESCompositeGetNumber(SNES, PetscInt *); 1200 PETSC_EXTERN PetscErrorCode SNESCompositeSetDamping(SNES, PetscInt, PetscReal); 1201 1202 PETSC_EXTERN PetscErrorCode SNESPatchSetDiscretisationInfo(SNES, PetscInt, DM *, PetscInt *, PetscInt *, const PetscInt **, const PetscInt *, PetscInt, const PetscInt *, PetscInt, const PetscInt *); 1203 PETSC_EXTERN PetscErrorCode SNESPatchSetComputeOperator(SNES, PetscErrorCode (*func)(PC, PetscInt, Vec, Mat, IS, PetscInt, const PetscInt *, const PetscInt *, void *), void *); 1204 PETSC_EXTERN PetscErrorCode SNESPatchSetComputeFunction(SNES, PetscErrorCode (*func)(PC, PetscInt, Vec, Vec, IS, PetscInt, const PetscInt *, const PetscInt *, void *), void *); 1205 PETSC_EXTERN PetscErrorCode SNESPatchSetConstructType(SNES, PCPatchConstructType, PetscErrorCode (*func)(PC, PetscInt *, IS **, IS *, void *), void *); 1206 PETSC_EXTERN PetscErrorCode SNESPatchSetCellNumbering(SNES, PetscSection); 1207 1208 /*E 1209 SNESFASType - Determines the type of nonlinear multigrid method that is run. 1210 1211 Values: 1212 + `SNES_FAS_MULTIPLICATIVE` (default) - traditional V or W cycle as determined by `SNESFASSetCycles()` 1213 . `SNES_FAS_ADDITIVE` - additive FAS cycle 1214 . `SNES_FAS_FULL` - full FAS cycle 1215 - `SNES_FAS_KASKADE` - Kaskade FAS cycle 1216 1217 Level: beginner 1218 1219 .seealso: [](ch_snes), `SNESFAS`, `PCMGSetType()`, `PCMGType` 1220 E*/ 1221 typedef enum { 1222 SNES_FAS_MULTIPLICATIVE, 1223 SNES_FAS_ADDITIVE, 1224 SNES_FAS_FULL, 1225 SNES_FAS_KASKADE 1226 } SNESFASType; 1227 PETSC_EXTERN const char *const SNESFASTypes[]; 1228 1229 /* called on the finest level FAS instance*/ 1230 PETSC_EXTERN PetscErrorCode SNESFASSetType(SNES, SNESFASType); 1231 PETSC_EXTERN PetscErrorCode SNESFASGetType(SNES, SNESFASType *); 1232 PETSC_EXTERN PetscErrorCode SNESFASSetLevels(SNES, PetscInt, MPI_Comm *); 1233 PETSC_EXTERN PetscErrorCode SNESFASGetLevels(SNES, PetscInt *); 1234 PETSC_EXTERN PetscErrorCode SNESFASGetCycleSNES(SNES, PetscInt, SNES *); 1235 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothUp(SNES, PetscInt); 1236 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothDown(SNES, PetscInt); 1237 PETSC_EXTERN PetscErrorCode SNESFASSetCycles(SNES, PetscInt); 1238 PETSC_EXTERN PetscErrorCode SNESFASSetMonitor(SNES, PetscViewerAndFormat *, PetscBool); 1239 PETSC_EXTERN PetscErrorCode SNESFASSetLog(SNES, PetscBool); 1240 1241 PETSC_EXTERN PetscErrorCode SNESFASSetGalerkin(SNES, PetscBool); 1242 PETSC_EXTERN PetscErrorCode SNESFASGetGalerkin(SNES, PetscBool *); 1243 PETSC_EXTERN PetscErrorCode SNESFASGalerkinFunctionDefault(SNES, Vec, Vec, void *); 1244 1245 /* called on any level -- "Cycle" FAS instance */ 1246 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmoother(SNES, SNES *); 1247 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherUp(SNES, SNES *); 1248 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherDown(SNES, SNES *); 1249 PETSC_EXTERN PetscErrorCode SNESFASCycleGetCorrection(SNES, SNES *); 1250 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInterpolation(SNES, Mat *); 1251 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRestriction(SNES, Mat *); 1252 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInjection(SNES, Mat *); 1253 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRScale(SNES, Vec *); 1254 PETSC_EXTERN PetscErrorCode SNESFASCycleSetCycles(SNES, PetscInt); 1255 PETSC_EXTERN PetscErrorCode SNESFASCycleIsFine(SNES, PetscBool *); 1256 1257 /* called on the (outer) finest level FAS to set/get parameters on any level instance */ 1258 PETSC_EXTERN PetscErrorCode SNESFASSetInterpolation(SNES, PetscInt, Mat); 1259 PETSC_EXTERN PetscErrorCode SNESFASGetInterpolation(SNES, PetscInt, Mat *); 1260 PETSC_EXTERN PetscErrorCode SNESFASSetRestriction(SNES, PetscInt, Mat); 1261 PETSC_EXTERN PetscErrorCode SNESFASGetRestriction(SNES, PetscInt, Mat *); 1262 PETSC_EXTERN PetscErrorCode SNESFASSetInjection(SNES, PetscInt, Mat); 1263 PETSC_EXTERN PetscErrorCode SNESFASGetInjection(SNES, PetscInt, Mat *); 1264 PETSC_EXTERN PetscErrorCode SNESFASSetRScale(SNES, PetscInt, Vec); 1265 PETSC_EXTERN PetscErrorCode SNESFASGetRScale(SNES, PetscInt, Vec *); 1266 PETSC_EXTERN PetscErrorCode SNESFASSetContinuation(SNES, PetscBool); 1267 1268 PETSC_EXTERN PetscErrorCode SNESFASGetSmoother(SNES, PetscInt, SNES *); 1269 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherUp(SNES, PetscInt, SNES *); 1270 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherDown(SNES, PetscInt, SNES *); 1271 PETSC_EXTERN PetscErrorCode SNESFASGetCoarseSolve(SNES, SNES *); 1272 1273 /* parameters for full FAS */ 1274 PETSC_EXTERN PetscErrorCode SNESFASFullSetDownSweep(SNES, PetscBool); 1275 PETSC_EXTERN PetscErrorCode SNESFASCreateCoarseVec(SNES, Vec *); 1276 PETSC_EXTERN PetscErrorCode SNESFASRestrict(SNES, Vec, Vec); 1277 PETSC_EXTERN PetscErrorCode SNESFASFullSetTotal(SNES, PetscBool); 1278 PETSC_EXTERN PetscErrorCode SNESFASFullGetTotal(SNES, PetscBool *); 1279 1280 PETSC_EXTERN PetscErrorCode DMSNESCheckDiscretization(SNES, DM, PetscReal, Vec, PetscReal, PetscReal[]); 1281 PETSC_EXTERN PetscErrorCode DMSNESCheckResidual(SNES, DM, Vec, PetscReal, PetscReal *); 1282 PETSC_EXTERN PetscErrorCode DMSNESCheckJacobian(SNES, DM, Vec, PetscReal, PetscBool *, PetscReal *); 1283 PETSC_EXTERN PetscErrorCode DMSNESCheckFromOptions(SNES, Vec); 1284 PETSC_EXTERN PetscErrorCode DMSNESComputeJacobianAction(DM, Vec, Vec, Vec, void *); 1285 PETSC_EXTERN PetscErrorCode DMSNESCreateJacobianMF(DM, Vec, void *, Mat *); 1286