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