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