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 /* --------- Solving systems of nonlinear equations --------------- */ 434 PETSC_EXTERN PetscErrorCode SNESSetFunction(SNES, Vec, PetscErrorCode (*)(SNES, Vec, Vec, void *), void *); 435 PETSC_EXTERN PetscErrorCode SNESGetFunction(SNES, Vec *, PetscErrorCode (**)(SNES, Vec, Vec, void *), void **); 436 PETSC_EXTERN PetscErrorCode SNESComputeFunction(SNES, Vec, Vec); 437 PETSC_EXTERN PetscErrorCode SNESComputeMFFunction(SNES, Vec, Vec); 438 PETSC_EXTERN PetscErrorCode SNESSetInitialFunction(SNES, Vec); 439 440 PETSC_EXTERN PetscErrorCode SNESSetJacobian(SNES, Mat, Mat, PetscErrorCode (*)(SNES, Vec, Mat, Mat, void *), void *); 441 PETSC_EXTERN PetscErrorCode SNESGetJacobian(SNES, Mat *, Mat *, PetscErrorCode (**)(SNES, Vec, Mat, Mat, void *), void **); 442 PETSC_EXTERN PetscErrorCode SNESObjectiveComputeFunctionDefaultFD(SNES, Vec, Vec, void *); 443 PETSC_EXTERN PetscErrorCode SNESComputeJacobianDefault(SNES, Vec, Mat, Mat, void *); 444 PETSC_EXTERN PetscErrorCode SNESComputeJacobianDefaultColor(SNES, Vec, Mat, Mat, void *); 445 PETSC_EXTERN PetscErrorCode SNESPruneJacobianColor(SNES, Mat, Mat); 446 PETSC_EXTERN PetscErrorCode SNESSetComputeInitialGuess(SNES, PetscErrorCode (*)(SNES, Vec, void *), void *); 447 PETSC_EXTERN PetscErrorCode SNESSetPicard(SNES, Vec, PetscErrorCode (*)(SNES, Vec, Vec, void *), Mat, Mat, PetscErrorCode (*)(SNES, Vec, Mat, Mat, void *), void *); 448 PETSC_EXTERN PetscErrorCode SNESGetPicard(SNES, Vec *, PetscErrorCode (**)(SNES, Vec, Vec, void *), Mat *, Mat *, PetscErrorCode (**)(SNES, Vec, Mat, Mat, void *), void **); 449 PETSC_EXTERN PetscErrorCode SNESPicardComputeFunction(SNES, Vec, Vec, void *); 450 PETSC_EXTERN PetscErrorCode SNESPicardComputeMFFunction(SNES, Vec, Vec, void *); 451 PETSC_EXTERN PetscErrorCode SNESPicardComputeJacobian(SNES, Vec, Mat, Mat, void *); 452 453 PETSC_EXTERN PetscErrorCode SNESSetObjective(SNES, PetscErrorCode (*)(SNES, Vec, PetscReal *, void *), void *); 454 PETSC_EXTERN PetscErrorCode SNESGetObjective(SNES, PetscErrorCode (**)(SNES, Vec, PetscReal *, void *), void **); 455 PETSC_EXTERN PetscErrorCode SNESComputeObjective(SNES, Vec, PetscReal *); 456 457 /*E 458 SNESNormSchedule - Frequency with which the norm is computed during a nonliner solve 459 460 Values: 461 + `SNES_NORM_DEFAULT` - use the default behavior for the current `SNESType` 462 . `SNES_NORM_NONE` - avoid all norm computations 463 . `SNES_NORM_ALWAYS` - compute the norms whenever possible 464 . `SNES_NORM_INITIAL_ONLY` - compute the norm only when the algorithm starts 465 . `SNES_NORM_FINAL_ONLY` - compute the norm only when the algorithm finishes 466 - `SNES_NORM_INITIAL_FINAL_ONLY` - compute the norm at the start and end of the algorithm 467 468 Level: advanced 469 470 Notes: 471 Support for these is highly dependent on the solver. 472 473 Some options limit the convergence tests that can be used. 474 475 The `SNES_NORM_NONE` option is most commonly used when the nonlinear solver is being used as a smoother, for example for `SNESFAS` 476 477 This is primarily used to turn off extra norm and function computation 478 when the solvers are composed. 479 480 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `KSPSetNormType()`, 481 `KSPSetConvergenceTest()`, `KSPSetPCSide()` 482 E*/ 483 typedef enum { 484 SNES_NORM_DEFAULT = -1, 485 SNES_NORM_NONE = 0, 486 SNES_NORM_ALWAYS = 1, 487 SNES_NORM_INITIAL_ONLY = 2, 488 SNES_NORM_FINAL_ONLY = 3, 489 SNES_NORM_INITIAL_FINAL_ONLY = 4 490 } SNESNormSchedule; 491 PETSC_EXTERN const char *const *const SNESNormSchedules; 492 493 /*MC 494 SNES_NORM_NONE - Don't compute function and its L2 norm when possible 495 496 Level: advanced 497 498 Note: 499 This is most useful for stationary solvers with a fixed number of iterations used as smoothers. 500 501 .seealso: [](ch_snes), `SNESNormSchedule`, `SNES`, `SNESSetNormSchedule()`, `SNES_NORM_DEFAULT` 502 M*/ 503 504 /*MC 505 SNES_NORM_ALWAYS - Compute the function and its L2 norm at each iteration. 506 507 Level: advanced 508 509 Note: 510 Most solvers will use this no matter what norm type is passed to them. 511 512 .seealso: [](ch_snes), `SNESNormSchedule`, `SNES`, `SNESSetNormSchedule()`, `SNES_NORM_NONE` 513 M*/ 514 515 /*MC 516 SNES_NORM_INITIAL_ONLY - Compute the function and its L2 at iteration 0, but do not update it. 517 518 Level: advanced 519 520 Notes: 521 This method is useful in composed methods, when a true solution might actually be found before `SNESSolve()` is called. 522 This option enables the solve to abort on the zeroth iteration if this is the case. 523 524 For solvers that require the computation of the L2 norm of the function as part of the method, this merely cancels 525 the norm computation at the last iteration (if possible). 526 527 .seealso: [](ch_snes), `SNESNormSchedule`, `SNES`, `SNESSetNormSchedule()`, `SNES_NORM_FINAL_ONLY`, `SNES_NORM_INITIAL_FINAL_ONLY` 528 M*/ 529 530 /*MC 531 SNES_NORM_FINAL_ONLY - Compute the function and its L2 norm on only the final iteration. 532 533 Level: advanced 534 535 Note: 536 For solvers that require the computation of the L2 norm of the function as part of the method, behaves 537 exactly as `SNES_NORM_DEFAULT`. This method is useful when the function is gotten after `SNESSolve()` and 538 used in subsequent computation for methods that do not need the norm computed during the rest of the 539 solution procedure. 540 541 .seealso: [](ch_snes), `SNESNormSchedule`, `SNES`, `SNESSetNormSchedule()`, `SNES_NORM_INITIAL_ONLY`, `SNES_NORM_INITIAL_FINAL_ONLY` 542 M*/ 543 544 /*MC 545 SNES_NORM_INITIAL_FINAL_ONLY - Compute the function and its L2 norm on only the initial and final iterations. 546 547 Level: advanced 548 549 Note: 550 This method combines the benefits of `SNES_NORM_INITIAL_ONLY` and `SNES_NORM_FINAL_ONLY`. 551 552 .seealso: [](ch_snes), `SNESNormSchedule`, `SNES`, `SNESSetNormSchedule()`, `SNES_NORM_SNES_NORM_INITIAL_ONLY`, `SNES_NORM_FINAL_ONLY` 553 M*/ 554 555 PETSC_EXTERN PetscErrorCode SNESSetNormSchedule(SNES, SNESNormSchedule); 556 PETSC_EXTERN PetscErrorCode SNESGetNormSchedule(SNES, SNESNormSchedule *); 557 PETSC_EXTERN PetscErrorCode SNESSetFunctionNorm(SNES, PetscReal); 558 PETSC_EXTERN PetscErrorCode SNESGetFunctionNorm(SNES, PetscReal *); 559 PETSC_EXTERN PetscErrorCode SNESGetUpdateNorm(SNES, PetscReal *); 560 PETSC_EXTERN PetscErrorCode SNESGetSolutionNorm(SNES, PetscReal *); 561 562 /*E 563 SNESFunctionType - Type of function computed 564 565 Values: 566 + `SNES_FUNCTION_DEFAULT` - the default behavior for the current `SNESType` 567 . `SNES_FUNCTION_UNPRECONDITIONED` - the original function provided 568 - `SNES_FUNCTION_PRECONDITIONED` - the modification of the function by the preconditioner 569 570 Level: advanced 571 572 Note: 573 Support for these is dependent on the solver. 574 575 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `KSPSetNormType()`, 576 `KSPSetConvergenceTest()`, `KSPSetPCSide()` 577 E*/ 578 typedef enum { 579 SNES_FUNCTION_DEFAULT = -1, 580 SNES_FUNCTION_UNPRECONDITIONED = 0, 581 SNES_FUNCTION_PRECONDITIONED = 1 582 } SNESFunctionType; 583 PETSC_EXTERN const char *const *const SNESFunctionTypes; 584 585 PETSC_EXTERN PetscErrorCode SNESSetFunctionType(SNES, SNESFunctionType); 586 PETSC_EXTERN PetscErrorCode SNESGetFunctionType(SNES, SNESFunctionType *); 587 588 PETSC_EXTERN PetscErrorCode SNESSetNGS(SNES, PetscErrorCode (*)(SNES, Vec, Vec, void *), void *); 589 PETSC_EXTERN PetscErrorCode SNESGetNGS(SNES, PetscErrorCode (**)(SNES, Vec, Vec, void *), void **); 590 PETSC_EXTERN PetscErrorCode SNESComputeNGS(SNES, Vec, Vec); 591 592 PETSC_EXTERN PetscErrorCode SNESNGSSetSweeps(SNES, PetscInt); 593 PETSC_EXTERN PetscErrorCode SNESNGSGetSweeps(SNES, PetscInt *); 594 PETSC_EXTERN PetscErrorCode SNESNGSSetTolerances(SNES, PetscReal, PetscReal, PetscReal, PetscInt); 595 PETSC_EXTERN PetscErrorCode SNESNGSGetTolerances(SNES, PetscReal *, PetscReal *, PetscReal *, PetscInt *); 596 597 PETSC_EXTERN PetscErrorCode SNESSetAlwaysComputesFinalResidual(SNES, PetscBool); 598 PETSC_EXTERN PetscErrorCode SNESGetAlwaysComputesFinalResidual(SNES, PetscBool *); 599 600 PETSC_EXTERN PetscErrorCode SNESShellGetContext(SNES, void *); 601 PETSC_EXTERN PetscErrorCode SNESShellSetContext(SNES, void *); 602 PETSC_EXTERN PetscErrorCode SNESShellSetSolve(SNES, PetscErrorCode (*)(SNES, Vec)); 603 604 /* --------- Routines specifically for line search methods --------------- */ 605 606 /*S 607 SNESLineSearch - Abstract PETSc object that manages line-search operations for nonlinear solvers 608 609 Level: beginner 610 611 .seealso: [](ch_snes), `SNESLineSearchType`, `SNESLineSearchCreate()`, `SNESLineSearchSetType()`, `SNES` 612 S*/ 613 typedef struct _p_LineSearch *SNESLineSearch; 614 615 /*J 616 SNESLineSearchType - String with the name of a PETSc line search method `SNESLineSearch` 617 618 Values: 619 + `SNESLINESEARCHBASIC` - (or equivalently `SNESLINESEARCHNONE`) Simple damping line search, defaults to using the full Newton step 620 . `SNESLINESEARCHBT` - Backtracking line search over the L2 norm of the function 621 . `SNESLINESEARCHL2` - Secant line search over the L2 norm of the function 622 . `SNESLINESEARCHCP` - Critical point secant line search assuming F(x) = grad G(x) for some unknown G(x) 623 . `SNESLINESEARCHNLEQERR` - Affine-covariant error-oriented linesearch 624 - `SNESLINESEARCHSHELL` - User provided `SNESLineSearch` implementation 625 626 Level: beginner 627 628 .seealso: [](ch_snes), `SNESLineSearch`, `SNESLineSearchSetType()`, `SNES` 629 J*/ 630 typedef const char *SNESLineSearchType; 631 #define SNESLINESEARCHBT "bt" 632 #define SNESLINESEARCHNLEQERR "nleqerr" 633 #define SNESLINESEARCHBASIC "basic" 634 #define SNESLINESEARCHNONE "none" 635 #define SNESLINESEARCHL2 "l2" 636 #define SNESLINESEARCHCP "cp" 637 #define SNESLINESEARCHSHELL "shell" 638 #define SNESLINESEARCHNCGLINEAR "ncglinear" 639 640 PETSC_EXTERN PetscFunctionList SNESList; 641 PETSC_EXTERN PetscClassId SNESLINESEARCH_CLASSID; 642 PETSC_EXTERN PetscFunctionList SNESLineSearchList; 643 644 #define SNES_LINESEARCH_ORDER_LINEAR 1 645 #define SNES_LINESEARCH_ORDER_QUADRATIC 2 646 #define SNES_LINESEARCH_ORDER_CUBIC 3 647 648 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*SNESLineSearchVIProjectFunc)(SNES, Vec); 649 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*SNESLineSearchVINormFunc)(SNES, Vec, Vec, PetscReal *); 650 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*SNESLineSearchApplyFunc)(SNESLineSearch); 651 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*SNESLineSearchUserFunc)(SNESLineSearch, void *); 652 653 PETSC_EXTERN PetscErrorCode SNESLineSearchCreate(MPI_Comm, SNESLineSearch *); 654 PETSC_EXTERN PetscErrorCode SNESLineSearchReset(SNESLineSearch); 655 PETSC_EXTERN PetscErrorCode SNESLineSearchView(SNESLineSearch, PetscViewer); 656 PETSC_EXTERN PetscErrorCode SNESLineSearchDestroy(SNESLineSearch *); 657 PETSC_EXTERN PetscErrorCode SNESLineSearchGetType(SNESLineSearch, SNESLineSearchType *); 658 PETSC_EXTERN PetscErrorCode SNESLineSearchSetType(SNESLineSearch, SNESLineSearchType); 659 PETSC_EXTERN PetscErrorCode SNESLineSearchSetFromOptions(SNESLineSearch); 660 PETSC_EXTERN PetscErrorCode SNESLineSearchSetFunction(SNESLineSearch, PetscErrorCode (*)(SNES, Vec, Vec)); 661 PETSC_EXTERN PetscErrorCode SNESLineSearchSetUp(SNESLineSearch); 662 PETSC_EXTERN PetscErrorCode SNESLineSearchApply(SNESLineSearch, Vec, Vec, PetscReal *, Vec); 663 PETSC_EXTERN PetscErrorCode SNESLineSearchPreCheck(SNESLineSearch, Vec, Vec, PetscBool *); 664 PETSC_EXTERN PetscErrorCode SNESLineSearchPostCheck(SNESLineSearch, Vec, Vec, Vec, PetscBool *, PetscBool *); 665 PETSC_EXTERN PetscErrorCode SNESLineSearchSetWorkVecs(SNESLineSearch, PetscInt); 666 667 /* set the functions for precheck and postcheck */ 668 669 PETSC_EXTERN PetscErrorCode SNESLineSearchSetPreCheck(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch, Vec, Vec, PetscBool *, void *), void *ctx); 670 PETSC_EXTERN PetscErrorCode SNESLineSearchSetPostCheck(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void *ctx); 671 672 PETSC_EXTERN PetscErrorCode SNESLineSearchGetPreCheck(SNESLineSearch, PetscErrorCode (**)(SNESLineSearch, Vec, Vec, PetscBool *, void *), void **ctx); 673 PETSC_EXTERN PetscErrorCode SNESLineSearchGetPostCheck(SNESLineSearch, PetscErrorCode (**)(SNESLineSearch, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void **ctx); 674 675 /* set the functions for VI-specific line search operations */ 676 677 PETSC_EXTERN PetscErrorCode SNESLineSearchSetVIFunctions(SNESLineSearch, SNESLineSearchVIProjectFunc, SNESLineSearchVINormFunc); 678 PETSC_EXTERN PetscErrorCode SNESLineSearchGetVIFunctions(SNESLineSearch, SNESLineSearchVIProjectFunc *, SNESLineSearchVINormFunc *); 679 680 /* pointers to the associated SNES in order to be able to get the function evaluation out */ 681 PETSC_EXTERN PetscErrorCode SNESLineSearchSetSNES(SNESLineSearch, SNES); 682 PETSC_EXTERN PetscErrorCode SNESLineSearchGetSNES(SNESLineSearch, SNES *); 683 684 /* set and get the parameters and vectors */ 685 PETSC_EXTERN PetscErrorCode SNESLineSearchGetTolerances(SNESLineSearch, PetscReal *, PetscReal *, PetscReal *, PetscReal *, PetscReal *, PetscInt *); 686 PETSC_EXTERN PetscErrorCode SNESLineSearchSetTolerances(SNESLineSearch, PetscReal, PetscReal, PetscReal, PetscReal, PetscReal, PetscInt); 687 688 PETSC_EXTERN PetscErrorCode SNESLineSearchPreCheckPicard(SNESLineSearch, Vec, Vec, PetscBool *, void *); 689 690 PETSC_EXTERN PetscErrorCode SNESLineSearchGetLambda(SNESLineSearch, PetscReal *); 691 PETSC_EXTERN PetscErrorCode SNESLineSearchSetLambda(SNESLineSearch, PetscReal); 692 693 PETSC_EXTERN PetscErrorCode SNESLineSearchGetDamping(SNESLineSearch, PetscReal *); 694 PETSC_EXTERN PetscErrorCode SNESLineSearchSetDamping(SNESLineSearch, PetscReal); 695 696 PETSC_EXTERN PetscErrorCode SNESLineSearchGetOrder(SNESLineSearch, PetscInt *order); 697 PETSC_EXTERN PetscErrorCode SNESLineSearchSetOrder(SNESLineSearch, PetscInt order); 698 699 /*E 700 SNESLineSearchReason - indication if the line search has succeeded or failed and why 701 702 Values: 703 + `SNES_LINESEARCH_SUCCEEDED` - the line search succeeded 704 . `SNES_LINESEARCH_FAILED_NANORINF` - a not a number of infinity appeared in the computions 705 . `SNES_LINESEARCH_FAILED_DOMAIN` - the function was evaluated outside of its domain, see `SNESSetFunctionDomainError()` and `SNESSetJacobianDomainError()` 706 . `SNES_LINESEARCH_FAILED_REDUCT` - the linear search failed to get the requested decrease in its norm or objective 707 . `SNES_LINESEARCH_FAILED_USER` - used by `SNESLINESEARCHNLEQERR` to indicate the user changed the search direction inappropriately 708 - `SNES_LINESEARCH_FAILED_FUNCTION` - indicates the maximum number of function evaluations allowed has been surpassed, `SNESConvergedReason` is also 709 set to `SNES_DIVERGED_FUNCTION_COUNT` 710 711 Level: intermediate 712 713 Developer Note: 714 Some of these reasons overlap with values of `SNESConvergedReason` 715 716 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `KSPConvergedReason`, `SNESSetConvergenceTest()`, 717 `SNESSetFunctionDomainError()` and `SNESSetJacobianDomainError()` 718 E*/ 719 typedef enum { 720 SNES_LINESEARCH_SUCCEEDED, 721 SNES_LINESEARCH_FAILED_NANORINF, 722 SNES_LINESEARCH_FAILED_DOMAIN, 723 SNES_LINESEARCH_FAILED_REDUCT, /* INSUFFICIENT REDUCTION */ 724 SNES_LINESEARCH_FAILED_USER, 725 SNES_LINESEARCH_FAILED_FUNCTION 726 } SNESLineSearchReason; 727 728 PETSC_EXTERN PetscErrorCode SNESLineSearchGetReason(SNESLineSearch, SNESLineSearchReason *); 729 PETSC_EXTERN PetscErrorCode SNESLineSearchSetReason(SNESLineSearch, SNESLineSearchReason); 730 731 PETSC_EXTERN PetscErrorCode SNESLineSearchGetVecs(SNESLineSearch, Vec *, Vec *, Vec *, Vec *, Vec *); 732 PETSC_EXTERN PetscErrorCode SNESLineSearchSetVecs(SNESLineSearch, Vec, Vec, Vec, Vec, Vec); 733 734 PETSC_EXTERN PetscErrorCode SNESLineSearchGetNorms(SNESLineSearch, PetscReal *, PetscReal *, PetscReal *); 735 PETSC_EXTERN PetscErrorCode SNESLineSearchSetNorms(SNESLineSearch, PetscReal, PetscReal, PetscReal); 736 PETSC_EXTERN PetscErrorCode SNESLineSearchComputeNorms(SNESLineSearch); 737 PETSC_EXTERN PetscErrorCode SNESLineSearchSetComputeNorms(SNESLineSearch, PetscBool); 738 739 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitor(SNESLineSearch); 740 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSet(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch, void *), void *, PetscErrorCode (*)(void **)); 741 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSetFromOptions(SNESLineSearch, const char[], const char[], const char[], PetscErrorCode (*)(SNESLineSearch, PetscViewerAndFormat *), PetscErrorCode (*)(SNESLineSearch, PetscViewerAndFormat *)); 742 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorCancel(SNESLineSearch); 743 PETSC_EXTERN PetscErrorCode SNESLineSearchSetDefaultMonitor(SNESLineSearch, PetscViewer); 744 PETSC_EXTERN PetscErrorCode SNESLineSearchGetDefaultMonitor(SNESLineSearch, PetscViewer *); 745 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSolutionUpdate(SNESLineSearch, PetscViewerAndFormat *); 746 747 PETSC_EXTERN PetscErrorCode SNESLineSearchAppendOptionsPrefix(SNESLineSearch, const char prefix[]); 748 PETSC_EXTERN PetscErrorCode SNESLineSearchGetOptionsPrefix(SNESLineSearch, const char *prefix[]); 749 750 /* Shell interface functions */ 751 PETSC_EXTERN PetscErrorCode SNESLineSearchShellSetUserFunc(SNESLineSearch, SNESLineSearchUserFunc, void *); 752 PETSC_EXTERN PetscErrorCode SNESLineSearchShellGetUserFunc(SNESLineSearch, SNESLineSearchUserFunc *, void **); 753 754 /* BT interface functions */ 755 PETSC_EXTERN PetscErrorCode SNESLineSearchBTSetAlpha(SNESLineSearch, PetscReal); 756 PETSC_EXTERN PetscErrorCode SNESLineSearchBTGetAlpha(SNESLineSearch, PetscReal *); 757 758 /*register line search types */ 759 PETSC_EXTERN PetscErrorCode SNESLineSearchRegister(const char[], PetscErrorCode (*)(SNESLineSearch)); 760 761 /* Routines for VI solver */ 762 PETSC_EXTERN PetscErrorCode SNESVISetVariableBounds(SNES, Vec, Vec); 763 PETSC_EXTERN PetscErrorCode SNESVIGetVariableBounds(SNES, Vec *, Vec *); 764 PETSC_EXTERN PetscErrorCode SNESVISetComputeVariableBounds(SNES, PetscErrorCode (*)(SNES, Vec, Vec)); 765 PETSC_EXTERN PetscErrorCode SNESVIGetInactiveSet(SNES, IS *); 766 PETSC_EXTERN PetscErrorCode SNESVIGetActiveSetIS(SNES, Vec, Vec, IS *); 767 PETSC_EXTERN PetscErrorCode SNESVIComputeInactiveSetFnorm(SNES, Vec, Vec, PetscReal *); 768 PETSC_EXTERN PetscErrorCode SNESVISetRedundancyCheck(SNES, PetscErrorCode (*)(SNES, IS, IS *, void *), void *); 769 PETSC_EXTERN PetscErrorCode SNESVIComputeMeritFunction(Vec, PetscReal *, PetscReal *); 770 PETSC_EXTERN PetscErrorCode SNESVIComputeFunction(SNES, Vec, Vec, void *); 771 PETSC_EXTERN PetscErrorCode DMSetVI(DM, IS); 772 PETSC_EXTERN PetscErrorCode DMDestroyVI(DM); 773 774 PETSC_EXTERN PetscErrorCode SNESTestLocalMin(SNES); 775 776 /* Should this routine be private? */ 777 PETSC_EXTERN PetscErrorCode SNESComputeJacobian(SNES, Vec, Mat, Mat); 778 PETSC_EXTERN PetscErrorCode SNESTestJacobian(SNES); 779 PETSC_EXTERN PetscErrorCode SNESTestFunction(SNES); 780 781 PETSC_EXTERN PetscErrorCode SNESSetDM(SNES, DM); 782 PETSC_EXTERN PetscErrorCode SNESGetDM(SNES, DM *); 783 PETSC_EXTERN PetscErrorCode SNESSetNPC(SNES, SNES); 784 PETSC_EXTERN PetscErrorCode SNESGetNPC(SNES, SNES *); 785 PETSC_EXTERN PetscErrorCode SNESHasNPC(SNES, PetscBool *); 786 PETSC_EXTERN PetscErrorCode SNESApplyNPC(SNES, Vec, Vec, Vec); 787 PETSC_EXTERN PetscErrorCode SNESGetNPCFunction(SNES, Vec, PetscReal *); 788 PETSC_EXTERN PetscErrorCode SNESComputeFunctionDefaultNPC(SNES, Vec, Vec); 789 PETSC_EXTERN PetscErrorCode SNESSetNPCSide(SNES, PCSide); 790 PETSC_EXTERN PetscErrorCode SNESGetNPCSide(SNES, PCSide *); 791 PETSC_EXTERN PetscErrorCode SNESSetLineSearch(SNES, SNESLineSearch); 792 PETSC_EXTERN PetscErrorCode SNESGetLineSearch(SNES, SNESLineSearch *); 793 794 PETSC_DEPRECATED_FUNCTION(3, 4, 0, "SNESGetLineSearch()", ) static inline PetscErrorCode SNESGetSNESLineSearch(SNES snes, SNESLineSearch *ls) 795 { 796 return SNESGetLineSearch(snes, ls); 797 } 798 PETSC_DEPRECATED_FUNCTION(3, 4, 0, "SNESSetLineSearch()", ) static inline PetscErrorCode SNESSetSNESLineSearch(SNES snes, SNESLineSearch ls) 799 { 800 return SNESSetLineSearch(snes, ls); 801 } 802 803 PETSC_EXTERN PetscErrorCode SNESSetUpMatrices(SNES); 804 PETSC_EXTERN PetscErrorCode DMSNESSetFunction(DM, PetscErrorCode (*)(SNES, Vec, Vec, void *), void *); 805 PETSC_EXTERN PetscErrorCode DMSNESGetFunction(DM, PetscErrorCode (**)(SNES, Vec, Vec, void *), void **); 806 PETSC_EXTERN PetscErrorCode DMSNESSetFunctionContextDestroy(DM, PetscErrorCode (*)(void *)); 807 PETSC_EXTERN PetscErrorCode DMSNESSetMFFunction(DM, PetscErrorCode (*)(SNES, Vec, Vec, void *), void *); 808 PETSC_EXTERN PetscErrorCode DMSNESSetNGS(DM, PetscErrorCode (*)(SNES, Vec, Vec, void *), void *); 809 PETSC_EXTERN PetscErrorCode DMSNESGetNGS(DM, PetscErrorCode (**)(SNES, Vec, Vec, void *), void **); 810 PETSC_EXTERN PetscErrorCode DMSNESSetJacobian(DM, PetscErrorCode (*)(SNES, Vec, Mat, Mat, void *), void *); 811 PETSC_EXTERN PetscErrorCode DMSNESGetJacobian(DM, PetscErrorCode (**)(SNES, Vec, Mat, Mat, void *), void **); 812 PETSC_EXTERN PetscErrorCode DMSNESSetJacobianContextDestroy(DM, PetscErrorCode (*)(void *)); 813 PETSC_EXTERN PetscErrorCode DMSNESSetPicard(DM, PetscErrorCode (*)(SNES, Vec, Vec, void *), PetscErrorCode (*)(SNES, Vec, Mat, Mat, void *), void *); 814 PETSC_EXTERN PetscErrorCode DMSNESGetPicard(DM, PetscErrorCode (**)(SNES, Vec, Vec, void *), PetscErrorCode (**)(SNES, Vec, Mat, Mat, void *), void **); 815 PETSC_EXTERN PetscErrorCode DMSNESSetObjective(DM, PetscErrorCode (*)(SNES, Vec, PetscReal *, void *), void *); 816 PETSC_EXTERN PetscErrorCode DMSNESGetObjective(DM, PetscErrorCode (**)(SNES, Vec, PetscReal *, void *), void **); 817 PETSC_EXTERN PetscErrorCode DMCopyDMSNES(DM, DM); 818 819 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESFunction)(DMDALocalInfo *, void *, void *, void *); 820 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESJacobian)(DMDALocalInfo *, void *, Mat, Mat, void *); 821 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESObjective)(DMDALocalInfo *, void *, PetscReal *, void *); 822 823 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESFunctionVec)(DMDALocalInfo *, Vec, Vec, void *); 824 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESJacobianVec)(DMDALocalInfo *, Vec, Mat, Mat, void *); 825 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESObjectiveVec)(DMDALocalInfo *, Vec, PetscReal *, void *); 826 827 PETSC_EXTERN PetscErrorCode DMDASNESSetFunctionLocal(DM, InsertMode, DMDASNESFunction, void *); 828 PETSC_EXTERN PetscErrorCode DMDASNESSetJacobianLocal(DM, DMDASNESJacobian, void *); 829 PETSC_EXTERN PetscErrorCode DMDASNESSetObjectiveLocal(DM, DMDASNESObjective, void *); 830 PETSC_EXTERN PetscErrorCode DMDASNESSetPicardLocal(DM, InsertMode, PetscErrorCode (*)(DMDALocalInfo *, void *, void *, void *), PetscErrorCode (*)(DMDALocalInfo *, void *, Mat, Mat, void *), void *); 831 832 PETSC_EXTERN PetscErrorCode DMDASNESSetFunctionLocalVec(DM, InsertMode, DMDASNESFunctionVec, void *); 833 PETSC_EXTERN PetscErrorCode DMDASNESSetJacobianLocalVec(DM, DMDASNESJacobianVec, void *); 834 PETSC_EXTERN PetscErrorCode DMDASNESSetObjectiveLocalVec(DM, DMDASNESObjectiveVec, void *); 835 836 PETSC_EXTERN PetscErrorCode DMSNESSetBoundaryLocal(DM, PetscErrorCode (*)(DM, Vec, void *), void *); 837 PETSC_EXTERN PetscErrorCode DMSNESSetObjectiveLocal(DM, PetscErrorCode (*)(DM, Vec, PetscReal *, void *), void *); 838 PETSC_EXTERN PetscErrorCode DMSNESSetFunctionLocal(DM, PetscErrorCode (*)(DM, Vec, Vec, void *), void *); 839 PETSC_EXTERN PetscErrorCode DMSNESSetJacobianLocal(DM, PetscErrorCode (*)(DM, Vec, Mat, Mat, void *), void *); 840 PETSC_EXTERN PetscErrorCode DMSNESGetBoundaryLocal(DM, PetscErrorCode (**)(DM, Vec, void *), void **); 841 PETSC_EXTERN PetscErrorCode DMSNESGetObjectiveLocal(DM, PetscErrorCode (**)(DM, Vec, PetscReal *, void *), void **); 842 PETSC_EXTERN PetscErrorCode DMSNESGetFunctionLocal(DM, PetscErrorCode (**)(DM, Vec, Vec, void *), void **); 843 PETSC_EXTERN PetscErrorCode DMSNESGetJacobianLocal(DM, PetscErrorCode (**)(DM, Vec, Mat, Mat, void *), void **); 844 845 /* Routines for Multiblock solver */ 846 PETSC_EXTERN PetscErrorCode SNESMultiblockSetFields(SNES, const char[], PetscInt, const PetscInt *); 847 PETSC_EXTERN PetscErrorCode SNESMultiblockSetIS(SNES, const char[], IS); 848 PETSC_EXTERN PetscErrorCode SNESMultiblockSetBlockSize(SNES, PetscInt); 849 PETSC_EXTERN PetscErrorCode SNESMultiblockSetType(SNES, PCCompositeType); 850 PETSC_EXTERN PetscErrorCode SNESMultiblockGetSubSNES(SNES, PetscInt *, SNES *[]); 851 852 /*J 853 SNESMSType - String with the name of a PETSc `SNESMS` method. 854 855 Level: intermediate 856 857 .seealso: [](ch_snes), `SNESMS`, `SNESMSGetType()`, `SNESMSSetType()`, `SNES` 858 J*/ 859 typedef const char *SNESMSType; 860 #define SNESMSM62 "m62" 861 #define SNESMSEULER "euler" 862 #define SNESMSJAMESON83 "jameson83" 863 #define SNESMSVLTP11 "vltp11" 864 #define SNESMSVLTP21 "vltp21" 865 #define SNESMSVLTP31 "vltp31" 866 #define SNESMSVLTP41 "vltp41" 867 #define SNESMSVLTP51 "vltp51" 868 #define SNESMSVLTP61 "vltp61" 869 870 PETSC_EXTERN PetscErrorCode SNESMSRegister(SNESMSType, PetscInt, PetscInt, PetscReal, const PetscReal[], const PetscReal[], const PetscReal[]); 871 PETSC_EXTERN PetscErrorCode SNESMSRegisterAll(void); 872 PETSC_EXTERN PetscErrorCode SNESMSGetType(SNES, SNESMSType *); 873 PETSC_EXTERN PetscErrorCode SNESMSSetType(SNES, SNESMSType); 874 PETSC_EXTERN PetscErrorCode SNESMSGetDamping(SNES, PetscReal *); 875 PETSC_EXTERN PetscErrorCode SNESMSSetDamping(SNES, PetscReal); 876 PETSC_EXTERN PetscErrorCode SNESMSFinalizePackage(void); 877 PETSC_EXTERN PetscErrorCode SNESMSInitializePackage(void); 878 PETSC_EXTERN PetscErrorCode SNESMSRegisterDestroy(void); 879 880 /*MC 881 SNESNGMRESRestartType - the restart approach used by `SNESNGMRES` 882 883 Values: 884 + `SNES_NGMRES_RESTART_NONE` - never restart 885 . `SNES_NGMRES_RESTART_DIFFERENCE` - restart based upon difference criteria 886 - `SNES_NGMRES_RESTART_PERIODIC` - restart after a fixed number of iterations 887 888 Options Database Keys: 889 + -snes_ngmres_restart_type <difference,periodic,none> - set the restart type 890 - -snes_ngmres_restart <30> - sets the number of iterations before restart for periodic 891 892 Level: intermediate 893 894 .seealso: `SNES, `SNESNGMRES`, `SNESNGMRESSetSelectType()`, `SNESNGMRESGetSelectType()`, `SNESNGMRESSetRestartType()`, 895 `SNESNGMRESGetRestartType()`, `SNESNGMRESSelectType` 896 M*/ 897 typedef enum { 898 SNES_NGMRES_RESTART_NONE = 0, 899 SNES_NGMRES_RESTART_PERIODIC = 1, 900 SNES_NGMRES_RESTART_DIFFERENCE = 2 901 } SNESNGMRESRestartType; 902 PETSC_EXTERN const char *const SNESNGMRESRestartTypes[]; 903 904 /*MC 905 SNESNGMRESSelectType - the approach used by `SNESNGMRES` to determine how the candidate solution and 906 combined solution are used to create the next iterate. 907 908 Values: 909 + `SNES_NGMRES_SELECT_NONE` - choose the combined solution all the time 910 . `SNES_NGMRES_SELECT_DIFFERENCE` - choose based upon the selection criteria 911 - `SNES_NGMRES_SELECT_LINESEARCH` - choose based upon line search combination 912 913 Options Database Key: 914 . -snes_ngmres_select_type<difference,none,linesearch> - select type 915 916 Level: intermediate 917 918 .seealso: `SNES, `SNESNGMRES`, `SNESNGMRESSetSelectType()`, `SNESNGMRESGetSelectType()`, `SNESNGMRESSetRestartType()`, 919 `SNESNGMRESGetRestartType()`, `SNESNGMRESRestartType` 920 M*/ 921 typedef enum { 922 SNES_NGMRES_SELECT_NONE = 0, 923 SNES_NGMRES_SELECT_DIFFERENCE = 1, 924 SNES_NGMRES_SELECT_LINESEARCH = 2 925 } SNESNGMRESSelectType; 926 PETSC_EXTERN const char *const SNESNGMRESSelectTypes[]; 927 928 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartType(SNES, SNESNGMRESRestartType); 929 PETSC_EXTERN PetscErrorCode SNESNGMRESSetSelectType(SNES, SNESNGMRESSelectType); 930 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartFmRise(SNES, PetscBool); 931 PETSC_EXTERN PetscErrorCode SNESNGMRESGetRestartFmRise(SNES, PetscBool *); 932 933 /*MC 934 SNESNCGType - the conjugate update approach for `SNESNCG` 935 936 Values: 937 + `SNES_NCG_FR` - Fletcher-Reeves update 938 . `SNES_NCG_PRP` - Polak-Ribiere-Polyak update, the default and the only one that tolerates generalized search directions 939 . `SNES_NCG_HS` - Hestenes-Steifel update 940 . `SNES_NCG_DY` - Dai-Yuan update 941 - `SNES_NCG_CD` - Conjugate Descent update 942 943 Options Database Key: 944 . -snes_ncg_type<fr,prp,hs,dy,cd> - select type 945 946 Level: intermediate 947 948 .seealso: `SNES, `SNESNCG`, `SNESNCGSetType()` 949 M*/ 950 typedef enum { 951 SNES_NCG_FR = 0, 952 SNES_NCG_PRP = 1, 953 SNES_NCG_HS = 2, 954 SNES_NCG_DY = 3, 955 SNES_NCG_CD = 4 956 } SNESNCGType; 957 PETSC_EXTERN const char *const SNESNCGTypes[]; 958 959 PETSC_EXTERN PetscErrorCode SNESNCGSetType(SNES, SNESNCGType); 960 961 /*MC 962 SNESQNScaleType - the scaling type used by `SNESQN` 963 964 Values: 965 + `SNES_QN_SCALE_NONE` - don't scale the problem 966 . `SNES_QN_SCALE_SCALAR` - use Shanno scaling 967 . `SNES_QN_SCALE_DIAGONAL` - scale with a diagonalized BFGS formula (see Gilbert and Lemarechal 1989), available 968 - `SNES_QN_SCALE_JACOBIAN` - scale by solving a linear system coming from the Jacobian you provided with `SNESSetJacobian()` 969 computed at the first iteration of `SNESQN` and at ever restart. 970 971 Options Database Key: 972 . -snes_qn_scale_type <diagonal,none,scalar,jacobian> - Scaling type 973 974 Level: intermediate 975 976 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNType`, `SNESQNSetType()`, `SNESQNSetRestartType()`, `SNESQNRestartType` 977 M*/ 978 typedef enum { 979 SNES_QN_SCALE_DEFAULT = 0, 980 SNES_QN_SCALE_NONE = 1, 981 SNES_QN_SCALE_SCALAR = 2, 982 SNES_QN_SCALE_DIAGONAL = 3, 983 SNES_QN_SCALE_JACOBIAN = 4 984 } SNESQNScaleType; 985 PETSC_EXTERN const char *const SNESQNScaleTypes[]; 986 987 /*MC 988 SNESQNRestartType - the restart approached used by `SNESQN` 989 990 Values: 991 + `SNES_QN_RESTART_NONE` - never restart 992 . `SNES_QN_RESTART_POWELL` - restart based upon descent criteria 993 - `SNES_QN_RESTART_PERIODIC` - restart after a fixed number of iterations 994 995 Options Database Keys: 996 + -snes_qn_restart_type <powell,periodic,none> - set the restart type 997 - -snes_qn_m <m> - sets the number of stored updates and the restart period for periodic 998 999 Level: intermediate 1000 1001 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNType`, `SNESQNSetType()`, `SNESQNSetRestartType()`, `SNESQNScaleType` 1002 M*/ 1003 typedef enum { 1004 SNES_QN_RESTART_DEFAULT = 0, 1005 SNES_QN_RESTART_NONE = 1, 1006 SNES_QN_RESTART_POWELL = 2, 1007 SNES_QN_RESTART_PERIODIC = 3 1008 } SNESQNRestartType; 1009 PETSC_EXTERN const char *const SNESQNRestartTypes[]; 1010 1011 /*MC 1012 SNESQNType - the type used by `SNESQN` 1013 1014 Values: 1015 + `SNES_QN_LBFGS` - LBFGS variant 1016 . `SNES_QN_BROYDEN` - Broyden variant 1017 - `SNES_QN_BADBROYDEN` - Bad Broyden variant 1018 1019 Options Database Key: 1020 . -snes_qn_type <lbfgs,broyden,badbroyden> - quasi-Newton type 1021 1022 Level: intermediate 1023 1024 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNSetType()`, `SNESQNScaleType`, `SNESQNRestartType`, `SNESQNSetRestartType()` 1025 M*/ 1026 typedef enum { 1027 SNES_QN_LBFGS = 0, 1028 SNES_QN_BROYDEN = 1, 1029 SNES_QN_BADBROYDEN = 2 1030 } SNESQNType; 1031 PETSC_EXTERN const char *const SNESQNTypes[]; 1032 1033 PETSC_EXTERN PetscErrorCode SNESQNSetType(SNES, SNESQNType); 1034 PETSC_EXTERN PetscErrorCode SNESQNSetScaleType(SNES, SNESQNScaleType); 1035 PETSC_EXTERN PetscErrorCode SNESQNSetRestartType(SNES, SNESQNRestartType); 1036 1037 PETSC_EXTERN PetscErrorCode SNESNASMGetType(SNES, PCASMType *); 1038 PETSC_EXTERN PetscErrorCode SNESNASMSetType(SNES, PCASMType); 1039 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomains(SNES, PetscInt *, SNES **, VecScatter **, VecScatter **, VecScatter **); 1040 PETSC_EXTERN PetscErrorCode SNESNASMSetSubdomains(SNES, PetscInt, SNES *, VecScatter *, VecScatter *, VecScatter *); 1041 PETSC_EXTERN PetscErrorCode SNESNASMSetDamping(SNES, PetscReal); 1042 PETSC_EXTERN PetscErrorCode SNESNASMGetDamping(SNES, PetscReal *); 1043 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomainVecs(SNES, PetscInt *, Vec **, Vec **, Vec **, Vec **); 1044 PETSC_EXTERN PetscErrorCode SNESNASMSetComputeFinalJacobian(SNES, PetscBool); 1045 PETSC_EXTERN PetscErrorCode SNESNASMGetSNES(SNES, PetscInt, SNES *); 1046 PETSC_EXTERN PetscErrorCode SNESNASMGetNumber(SNES, PetscInt *); 1047 PETSC_EXTERN PetscErrorCode SNESNASMSetWeight(SNES, Vec); 1048 1049 typedef enum { 1050 SNES_COMPOSITE_ADDITIVE, 1051 SNES_COMPOSITE_MULTIPLICATIVE, 1052 SNES_COMPOSITE_ADDITIVEOPTIMAL 1053 } SNESCompositeType; 1054 PETSC_EXTERN const char *const SNESCompositeTypes[]; 1055 1056 PETSC_EXTERN PetscErrorCode SNESCompositeSetType(SNES, SNESCompositeType); 1057 PETSC_EXTERN PetscErrorCode SNESCompositeAddSNES(SNES, SNESType); 1058 PETSC_EXTERN PetscErrorCode SNESCompositeGetSNES(SNES, PetscInt, SNES *); 1059 PETSC_EXTERN PetscErrorCode SNESCompositeGetNumber(SNES, PetscInt *); 1060 PETSC_EXTERN PetscErrorCode SNESCompositeSetDamping(SNES, PetscInt, PetscReal); 1061 1062 PETSC_EXTERN PetscErrorCode SNESPatchSetDiscretisationInfo(SNES, PetscInt, DM *, PetscInt *, PetscInt *, const PetscInt **, const PetscInt *, PetscInt, const PetscInt *, PetscInt, const PetscInt *); 1063 PETSC_EXTERN PetscErrorCode SNESPatchSetComputeOperator(SNES, PetscErrorCode (*func)(PC, PetscInt, Vec, Mat, IS, PetscInt, const PetscInt *, const PetscInt *, void *), void *); 1064 PETSC_EXTERN PetscErrorCode SNESPatchSetComputeFunction(SNES, PetscErrorCode (*func)(PC, PetscInt, Vec, Vec, IS, PetscInt, const PetscInt *, const PetscInt *, void *), void *); 1065 PETSC_EXTERN PetscErrorCode SNESPatchSetConstructType(SNES, PCPatchConstructType, PetscErrorCode (*func)(PC, PetscInt *, IS **, IS *, void *), void *); 1066 PETSC_EXTERN PetscErrorCode SNESPatchSetCellNumbering(SNES, PetscSection); 1067 1068 /*E 1069 SNESFASType - Determines the type of nonlinear multigrid method that is run. 1070 1071 Values: 1072 + `SNES_FAS_MULTIPLICATIVE` (default) - traditional V or W cycle as determined by `SNESFASSetCycles()` 1073 . `SNES_FAS_ADDITIVE` - additive FAS cycle 1074 . `SNES_FAS_FULL` - full FAS cycle 1075 - `SNES_FAS_KASKADE` - Kaskade FAS cycle 1076 1077 Level: beginner 1078 1079 .seealso: [](ch_snes), `SNESFAS`, `PCMGSetType()`, `PCMGType` 1080 E*/ 1081 typedef enum { 1082 SNES_FAS_MULTIPLICATIVE, 1083 SNES_FAS_ADDITIVE, 1084 SNES_FAS_FULL, 1085 SNES_FAS_KASKADE 1086 } SNESFASType; 1087 PETSC_EXTERN const char *const SNESFASTypes[]; 1088 1089 /* called on the finest level FAS instance*/ 1090 PETSC_EXTERN PetscErrorCode SNESFASSetType(SNES, SNESFASType); 1091 PETSC_EXTERN PetscErrorCode SNESFASGetType(SNES, SNESFASType *); 1092 PETSC_EXTERN PetscErrorCode SNESFASSetLevels(SNES, PetscInt, MPI_Comm *); 1093 PETSC_EXTERN PetscErrorCode SNESFASGetLevels(SNES, PetscInt *); 1094 PETSC_EXTERN PetscErrorCode SNESFASGetCycleSNES(SNES, PetscInt, SNES *); 1095 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothUp(SNES, PetscInt); 1096 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothDown(SNES, PetscInt); 1097 PETSC_EXTERN PetscErrorCode SNESFASSetCycles(SNES, PetscInt); 1098 PETSC_EXTERN PetscErrorCode SNESFASSetMonitor(SNES, PetscViewerAndFormat *, PetscBool); 1099 PETSC_EXTERN PetscErrorCode SNESFASSetLog(SNES, PetscBool); 1100 1101 PETSC_EXTERN PetscErrorCode SNESFASSetGalerkin(SNES, PetscBool); 1102 PETSC_EXTERN PetscErrorCode SNESFASGetGalerkin(SNES, PetscBool *); 1103 PETSC_EXTERN PetscErrorCode SNESFASGalerkinFunctionDefault(SNES, Vec, Vec, void *); 1104 1105 /* called on any level -- "Cycle" FAS instance */ 1106 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmoother(SNES, SNES *); 1107 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherUp(SNES, SNES *); 1108 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherDown(SNES, SNES *); 1109 PETSC_EXTERN PetscErrorCode SNESFASCycleGetCorrection(SNES, SNES *); 1110 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInterpolation(SNES, Mat *); 1111 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRestriction(SNES, Mat *); 1112 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInjection(SNES, Mat *); 1113 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRScale(SNES, Vec *); 1114 PETSC_EXTERN PetscErrorCode SNESFASCycleSetCycles(SNES, PetscInt); 1115 PETSC_EXTERN PetscErrorCode SNESFASCycleIsFine(SNES, PetscBool *); 1116 1117 /* called on the (outer) finest level FAS to set/get parameters on any level instance */ 1118 PETSC_EXTERN PetscErrorCode SNESFASSetInterpolation(SNES, PetscInt, Mat); 1119 PETSC_EXTERN PetscErrorCode SNESFASGetInterpolation(SNES, PetscInt, Mat *); 1120 PETSC_EXTERN PetscErrorCode SNESFASSetRestriction(SNES, PetscInt, Mat); 1121 PETSC_EXTERN PetscErrorCode SNESFASGetRestriction(SNES, PetscInt, Mat *); 1122 PETSC_EXTERN PetscErrorCode SNESFASSetInjection(SNES, PetscInt, Mat); 1123 PETSC_EXTERN PetscErrorCode SNESFASGetInjection(SNES, PetscInt, Mat *); 1124 PETSC_EXTERN PetscErrorCode SNESFASSetRScale(SNES, PetscInt, Vec); 1125 PETSC_EXTERN PetscErrorCode SNESFASGetRScale(SNES, PetscInt, Vec *); 1126 PETSC_EXTERN PetscErrorCode SNESFASSetContinuation(SNES, PetscBool); 1127 1128 PETSC_EXTERN PetscErrorCode SNESFASGetSmoother(SNES, PetscInt, SNES *); 1129 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherUp(SNES, PetscInt, SNES *); 1130 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherDown(SNES, PetscInt, SNES *); 1131 PETSC_EXTERN PetscErrorCode SNESFASGetCoarseSolve(SNES, SNES *); 1132 1133 /* parameters for full FAS */ 1134 PETSC_EXTERN PetscErrorCode SNESFASFullSetDownSweep(SNES, PetscBool); 1135 PETSC_EXTERN PetscErrorCode SNESFASCreateCoarseVec(SNES, Vec *); 1136 PETSC_EXTERN PetscErrorCode SNESFASRestrict(SNES, Vec, Vec); 1137 PETSC_EXTERN PetscErrorCode SNESFASFullSetTotal(SNES, PetscBool); 1138 PETSC_EXTERN PetscErrorCode SNESFASFullGetTotal(SNES, PetscBool *); 1139 1140 PETSC_EXTERN PetscErrorCode DMSNESCheckDiscretization(SNES, DM, PetscReal, Vec, PetscReal, PetscReal[]); 1141 PETSC_EXTERN PetscErrorCode DMSNESCheckResidual(SNES, DM, Vec, PetscReal, PetscReal *); 1142 PETSC_EXTERN PetscErrorCode DMSNESCheckJacobian(SNES, DM, Vec, PetscReal, PetscBool *, PetscReal *); 1143 PETSC_EXTERN PetscErrorCode DMSNESCheckFromOptions(SNES, Vec); 1144 PETSC_EXTERN PetscErrorCode DMSNESComputeJacobianAction(DM, Vec, Vec, Vec, void *); 1145 PETSC_EXTERN PetscErrorCode DMSNESCreateJacobianMF(DM, Vec, void *, Mat *); 1146