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