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 Keys: 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 780 PETSC_EXTERN PetscErrorCode SNESSetDM(SNES, DM); 781 PETSC_EXTERN PetscErrorCode SNESGetDM(SNES, DM *); 782 PETSC_EXTERN PetscErrorCode SNESSetNPC(SNES, SNES); 783 PETSC_EXTERN PetscErrorCode SNESGetNPC(SNES, SNES *); 784 PETSC_EXTERN PetscErrorCode SNESHasNPC(SNES, PetscBool *); 785 PETSC_EXTERN PetscErrorCode SNESApplyNPC(SNES, Vec, Vec, Vec); 786 PETSC_EXTERN PetscErrorCode SNESGetNPCFunction(SNES, Vec, PetscReal *); 787 PETSC_EXTERN PetscErrorCode SNESComputeFunctionDefaultNPC(SNES, Vec, Vec); 788 PETSC_EXTERN PetscErrorCode SNESSetNPCSide(SNES, PCSide); 789 PETSC_EXTERN PetscErrorCode SNESGetNPCSide(SNES, PCSide *); 790 PETSC_EXTERN PetscErrorCode SNESSetLineSearch(SNES, SNESLineSearch); 791 PETSC_EXTERN PetscErrorCode SNESGetLineSearch(SNES, SNESLineSearch *); 792 793 PETSC_DEPRECATED_FUNCTION(3, 4, 0, "SNESGetLineSearch()", ) static inline PetscErrorCode SNESGetSNESLineSearch(SNES snes, SNESLineSearch *ls) 794 { 795 return SNESGetLineSearch(snes, ls); 796 } 797 PETSC_DEPRECATED_FUNCTION(3, 4, 0, "SNESSetLineSearch()", ) static inline PetscErrorCode SNESSetSNESLineSearch(SNES snes, SNESLineSearch ls) 798 { 799 return SNESSetLineSearch(snes, ls); 800 } 801 802 PETSC_EXTERN PetscErrorCode SNESSetUpMatrices(SNES); 803 PETSC_EXTERN PetscErrorCode DMSNESSetFunction(DM, PetscErrorCode (*)(SNES, Vec, Vec, void *), void *); 804 PETSC_EXTERN PetscErrorCode DMSNESGetFunction(DM, PetscErrorCode (**)(SNES, Vec, Vec, void *), void **); 805 PETSC_EXTERN PetscErrorCode DMSNESSetFunctionContextDestroy(DM, PetscErrorCode (*)(void *)); 806 PETSC_EXTERN PetscErrorCode DMSNESSetMFFunction(DM, PetscErrorCode (*)(SNES, Vec, Vec, void *), void *); 807 PETSC_EXTERN PetscErrorCode DMSNESSetNGS(DM, PetscErrorCode (*)(SNES, Vec, Vec, void *), void *); 808 PETSC_EXTERN PetscErrorCode DMSNESGetNGS(DM, PetscErrorCode (**)(SNES, Vec, Vec, void *), void **); 809 PETSC_EXTERN PetscErrorCode DMSNESSetJacobian(DM, PetscErrorCode (*)(SNES, Vec, Mat, Mat, void *), void *); 810 PETSC_EXTERN PetscErrorCode DMSNESGetJacobian(DM, PetscErrorCode (**)(SNES, Vec, Mat, Mat, void *), void **); 811 PETSC_EXTERN PetscErrorCode DMSNESSetJacobianContextDestroy(DM, PetscErrorCode (*)(void *)); 812 PETSC_EXTERN PetscErrorCode DMSNESSetPicard(DM, PetscErrorCode (*)(SNES, Vec, Vec, void *), PetscErrorCode (*)(SNES, Vec, Mat, Mat, void *), void *); 813 PETSC_EXTERN PetscErrorCode DMSNESGetPicard(DM, PetscErrorCode (**)(SNES, Vec, Vec, void *), PetscErrorCode (**)(SNES, Vec, Mat, Mat, void *), void **); 814 PETSC_EXTERN PetscErrorCode DMSNESSetObjective(DM, PetscErrorCode (*)(SNES, Vec, PetscReal *, void *), void *); 815 PETSC_EXTERN PetscErrorCode DMSNESGetObjective(DM, PetscErrorCode (**)(SNES, Vec, PetscReal *, void *), void **); 816 PETSC_EXTERN PetscErrorCode DMCopyDMSNES(DM, DM); 817 818 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESFunction)(DMDALocalInfo *, void *, void *, void *); 819 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESJacobian)(DMDALocalInfo *, void *, Mat, Mat, void *); 820 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESObjective)(DMDALocalInfo *, void *, PetscReal *, void *); 821 822 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESFunctionVec)(DMDALocalInfo *, Vec, Vec, void *); 823 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESJacobianVec)(DMDALocalInfo *, Vec, Mat, Mat, void *); 824 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*DMDASNESObjectiveVec)(DMDALocalInfo *, Vec, PetscReal *, void *); 825 826 PETSC_EXTERN PetscErrorCode DMDASNESSetFunctionLocal(DM, InsertMode, DMDASNESFunction, void *); 827 PETSC_EXTERN PetscErrorCode DMDASNESSetJacobianLocal(DM, DMDASNESJacobian, void *); 828 PETSC_EXTERN PetscErrorCode DMDASNESSetObjectiveLocal(DM, DMDASNESObjective, void *); 829 PETSC_EXTERN PetscErrorCode DMDASNESSetPicardLocal(DM, InsertMode, PetscErrorCode (*)(DMDALocalInfo *, void *, void *, void *), PetscErrorCode (*)(DMDALocalInfo *, void *, Mat, Mat, void *), void *); 830 831 PETSC_EXTERN PetscErrorCode DMDASNESSetFunctionLocalVec(DM, InsertMode, DMDASNESFunctionVec, void *); 832 PETSC_EXTERN PetscErrorCode DMDASNESSetJacobianLocalVec(DM, DMDASNESJacobianVec, void *); 833 PETSC_EXTERN PetscErrorCode DMDASNESSetObjectiveLocalVec(DM, DMDASNESObjectiveVec, void *); 834 835 PETSC_EXTERN PetscErrorCode DMSNESSetBoundaryLocal(DM, PetscErrorCode (*)(DM, Vec, void *), void *); 836 PETSC_EXTERN PetscErrorCode DMSNESSetFunctionLocal(DM, PetscErrorCode (*)(DM, Vec, Vec, void *), void *); 837 PETSC_EXTERN PetscErrorCode DMSNESSetJacobianLocal(DM, PetscErrorCode (*)(DM, Vec, Mat, Mat, void *), void *); 838 PETSC_EXTERN PetscErrorCode DMSNESGetBoundaryLocal(DM, PetscErrorCode (**)(DM, Vec, void *), void **); 839 PETSC_EXTERN PetscErrorCode DMSNESGetFunctionLocal(DM, PetscErrorCode (**)(DM, Vec, Vec, void *), void **); 840 PETSC_EXTERN PetscErrorCode DMSNESGetJacobianLocal(DM, PetscErrorCode (**)(DM, Vec, Mat, Mat, void *), void **); 841 842 /* Routines for Multiblock solver */ 843 PETSC_EXTERN PetscErrorCode SNESMultiblockSetFields(SNES, const char[], PetscInt, const PetscInt *); 844 PETSC_EXTERN PetscErrorCode SNESMultiblockSetIS(SNES, const char[], IS); 845 PETSC_EXTERN PetscErrorCode SNESMultiblockSetBlockSize(SNES, PetscInt); 846 PETSC_EXTERN PetscErrorCode SNESMultiblockSetType(SNES, PCCompositeType); 847 PETSC_EXTERN PetscErrorCode SNESMultiblockGetSubSNES(SNES, PetscInt *, SNES *[]); 848 849 /*J 850 SNESMSType - String with the name of a PETSc `SNESMS` method. 851 852 Level: intermediate 853 854 .seealso: [](ch_snes), `SNESMS`, `SNESMSGetType()`, `SNESMSSetType()`, `SNES` 855 J*/ 856 typedef const char *SNESMSType; 857 #define SNESMSM62 "m62" 858 #define SNESMSEULER "euler" 859 #define SNESMSJAMESON83 "jameson83" 860 #define SNESMSVLTP11 "vltp11" 861 #define SNESMSVLTP21 "vltp21" 862 #define SNESMSVLTP31 "vltp31" 863 #define SNESMSVLTP41 "vltp41" 864 #define SNESMSVLTP51 "vltp51" 865 #define SNESMSVLTP61 "vltp61" 866 867 PETSC_EXTERN PetscErrorCode SNESMSRegister(SNESMSType, PetscInt, PetscInt, PetscReal, const PetscReal[], const PetscReal[], const PetscReal[]); 868 PETSC_EXTERN PetscErrorCode SNESMSRegisterAll(void); 869 PETSC_EXTERN PetscErrorCode SNESMSGetType(SNES, SNESMSType *); 870 PETSC_EXTERN PetscErrorCode SNESMSSetType(SNES, SNESMSType); 871 PETSC_EXTERN PetscErrorCode SNESMSGetDamping(SNES, PetscReal *); 872 PETSC_EXTERN PetscErrorCode SNESMSSetDamping(SNES, PetscReal); 873 PETSC_EXTERN PetscErrorCode SNESMSFinalizePackage(void); 874 PETSC_EXTERN PetscErrorCode SNESMSInitializePackage(void); 875 PETSC_EXTERN PetscErrorCode SNESMSRegisterDestroy(void); 876 877 /*MC 878 SNESNGMRESRestartType - the restart approach used by `SNESNGMRES` 879 880 Values: 881 + `SNES_NGMRES_RESTART_NONE` - never restart 882 . `SNES_NGMRES_RESTART_DIFFERENCE` - restart based upon difference criteria 883 - `SNES_NGMRES_RESTART_PERIODIC` - restart after a fixed number of iterations 884 885 Options Database Keys: 886 + -snes_ngmres_restart_type<difference,periodic,none> - set the restart type 887 - -snes_ngmres_restart[30] - sets the number of iterations before restart for periodic 888 889 Level: intermediate 890 891 .seealso: `SNES, `SNESNGMRES`, `SNESNGMRESSetSelectType()`, `SNESNGMRESGetSelectType()`, `SNESNGMRESSetRestartType()`, 892 `SNESNGMRESGetRestartType()`, `SNESNGMRESSelectType` 893 M*/ 894 typedef enum { 895 SNES_NGMRES_RESTART_NONE = 0, 896 SNES_NGMRES_RESTART_PERIODIC = 1, 897 SNES_NGMRES_RESTART_DIFFERENCE = 2 898 } SNESNGMRESRestartType; 899 PETSC_EXTERN const char *const SNESNGMRESRestartTypes[]; 900 901 /*MC 902 SNESNGMRESSelectType - the approach used by `SNESNGMRES` to determine how the candidate solution and 903 combined solution are used to create the next iterate. 904 905 Values: 906 + `SNES_NGMRES_SELECT_NONE` - choose the combined solution all the time 907 . `SNES_NGMRES_SELECT_DIFFERENCE` - choose based upon the selection criteria 908 - `SNES_NGMRES_SELECT_LINESEARCH` - choose based upon line search combination 909 910 Options Database Key: 911 . -snes_ngmres_select_type<difference,none,linesearch> - select type 912 913 Level: intermediate 914 915 .seealso: `SNES, `SNESNGMRES`, `SNESNGMRESSetSelectType()`, `SNESNGMRESGetSelectType()`, `SNESNGMRESSetRestartType()`, 916 `SNESNGMRESGetRestartType()`, `SNESNGMRESRestartType` 917 M*/ 918 typedef enum { 919 SNES_NGMRES_SELECT_NONE = 0, 920 SNES_NGMRES_SELECT_DIFFERENCE = 1, 921 SNES_NGMRES_SELECT_LINESEARCH = 2 922 } SNESNGMRESSelectType; 923 PETSC_EXTERN const char *const SNESNGMRESSelectTypes[]; 924 925 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartType(SNES, SNESNGMRESRestartType); 926 PETSC_EXTERN PetscErrorCode SNESNGMRESSetSelectType(SNES, SNESNGMRESSelectType); 927 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartFmRise(SNES, PetscBool); 928 PETSC_EXTERN PetscErrorCode SNESNGMRESGetRestartFmRise(SNES, PetscBool *); 929 930 /*MC 931 SNESNCGType - the conjugate update approach for `SNESNCG` 932 933 Values: 934 + `SNES_NCG_FR` - Fletcher-Reeves update 935 . `SNES_NCG_PRP` - Polak-Ribiere-Polyak update, the default and the only one that tolerates generalized search directions 936 . `SNES_NCG_HS` - Hestenes-Steifel update 937 . `SNES_NCG_DY` - Dai-Yuan update 938 - `SNES_NCG_CD` - Conjugate Descent update 939 940 Options Database Key: 941 . -snes_ncg_type<fr,prp,hs,dy,cd> - select type 942 943 Level: intermediate 944 945 .seealso: `SNES, `SNESNCG`, `SNESNCGSetType()` 946 M*/ 947 typedef enum { 948 SNES_NCG_FR = 0, 949 SNES_NCG_PRP = 1, 950 SNES_NCG_HS = 2, 951 SNES_NCG_DY = 3, 952 SNES_NCG_CD = 4 953 } SNESNCGType; 954 PETSC_EXTERN const char *const SNESNCGTypes[]; 955 956 PETSC_EXTERN PetscErrorCode SNESNCGSetType(SNES, SNESNCGType); 957 958 /*MC 959 SNESQNScaleType - the scaling type used by `SNESQN` 960 961 Values: 962 + `SNES_QN_SCALE_NONE` - don't scale the problem 963 . `SNES_QN_SCALE_SCALAR` - use Shanno scaling 964 . `SNES_QN_SCALE_DIAGONAL` - scale with a diagonalized BFGS formula (see Gilbert and Lemarechal 1989), available 965 - `SNES_QN_SCALE_JACOBIAN` - scale by solving a linear system coming from the Jacobian you provided with `SNESSetJacobian()` 966 computed at the first iteration of `SNESQN` and at ever restart. 967 968 Options Database Key: 969 . -snes_qn_scale_type <diagonal,none,scalar,jacobian> - Scaling type 970 971 Level: intermediate 972 973 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNType`, `SNESQNSetType()`, `SNESQNSetRestartType()`, `SNESQNRestartType` 974 M*/ 975 typedef enum { 976 SNES_QN_SCALE_DEFAULT = 0, 977 SNES_QN_SCALE_NONE = 1, 978 SNES_QN_SCALE_SCALAR = 2, 979 SNES_QN_SCALE_DIAGONAL = 3, 980 SNES_QN_SCALE_JACOBIAN = 4 981 } SNESQNScaleType; 982 PETSC_EXTERN const char *const SNESQNScaleTypes[]; 983 984 /*MC 985 SNESQNRestartType - the restart approached used by `SNESQN` 986 987 Values: 988 + `SNES_QN_RESTART_NONE` - never restart 989 . `SNES_QN_RESTART_POWELL` - restart based upon descent criteria 990 - `SNES_QN_RESTART_PERIODIC` - restart after a fixed number of iterations 991 992 Options Database Keys: 993 + -snes_qn_restart_type <powell,periodic,none> - set the restart type 994 - -snes_qn_m <m> - sets the number of stored updates and the restart period for periodic 995 996 Level: intermediate 997 998 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNType`, `SNESQNSetType()`, `SNESQNSetRestartType()`, `SNESQNScaleType` 999 M*/ 1000 typedef enum { 1001 SNES_QN_RESTART_DEFAULT = 0, 1002 SNES_QN_RESTART_NONE = 1, 1003 SNES_QN_RESTART_POWELL = 2, 1004 SNES_QN_RESTART_PERIODIC = 3 1005 } SNESQNRestartType; 1006 PETSC_EXTERN const char *const SNESQNRestartTypes[]; 1007 1008 /*MC 1009 SNESQNType - the type used by `SNESQN` 1010 1011 Values: 1012 + `SNES_QN_LBFGS` - LBFGS variant 1013 . `SNES_QN_BROYDEN` - Broyden variant 1014 - `SNES_QN_BADBROYDEN` - Bad Broyden variant 1015 1016 Options Database Key: 1017 . -snes_qn_type <lbfgs,broyden,badbroyden> - quasi-Newton type 1018 1019 Level: intermediate 1020 1021 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNSetType()`, `SNESQNScaleType`, `SNESQNRestartType`, `SNESQNSetRestartType()` 1022 M*/ 1023 typedef enum { 1024 SNES_QN_LBFGS = 0, 1025 SNES_QN_BROYDEN = 1, 1026 SNES_QN_BADBROYDEN = 2 1027 } SNESQNType; 1028 PETSC_EXTERN const char *const SNESQNTypes[]; 1029 1030 PETSC_EXTERN PetscErrorCode SNESQNSetType(SNES, SNESQNType); 1031 PETSC_EXTERN PetscErrorCode SNESQNSetScaleType(SNES, SNESQNScaleType); 1032 PETSC_EXTERN PetscErrorCode SNESQNSetRestartType(SNES, SNESQNRestartType); 1033 1034 PETSC_EXTERN PetscErrorCode SNESNASMGetType(SNES, PCASMType *); 1035 PETSC_EXTERN PetscErrorCode SNESNASMSetType(SNES, PCASMType); 1036 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomains(SNES, PetscInt *, SNES **, VecScatter **, VecScatter **, VecScatter **); 1037 PETSC_EXTERN PetscErrorCode SNESNASMSetSubdomains(SNES, PetscInt, SNES *, VecScatter *, VecScatter *, VecScatter *); 1038 PETSC_EXTERN PetscErrorCode SNESNASMSetDamping(SNES, PetscReal); 1039 PETSC_EXTERN PetscErrorCode SNESNASMGetDamping(SNES, PetscReal *); 1040 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomainVecs(SNES, PetscInt *, Vec **, Vec **, Vec **, Vec **); 1041 PETSC_EXTERN PetscErrorCode SNESNASMSetComputeFinalJacobian(SNES, PetscBool); 1042 PETSC_EXTERN PetscErrorCode SNESNASMGetSNES(SNES, PetscInt, SNES *); 1043 PETSC_EXTERN PetscErrorCode SNESNASMGetNumber(SNES, PetscInt *); 1044 PETSC_EXTERN PetscErrorCode SNESNASMSetWeight(SNES, Vec); 1045 1046 typedef enum { 1047 SNES_COMPOSITE_ADDITIVE, 1048 SNES_COMPOSITE_MULTIPLICATIVE, 1049 SNES_COMPOSITE_ADDITIVEOPTIMAL 1050 } SNESCompositeType; 1051 PETSC_EXTERN const char *const SNESCompositeTypes[]; 1052 1053 PETSC_EXTERN PetscErrorCode SNESCompositeSetType(SNES, SNESCompositeType); 1054 PETSC_EXTERN PetscErrorCode SNESCompositeAddSNES(SNES, SNESType); 1055 PETSC_EXTERN PetscErrorCode SNESCompositeGetSNES(SNES, PetscInt, SNES *); 1056 PETSC_EXTERN PetscErrorCode SNESCompositeGetNumber(SNES, PetscInt *); 1057 PETSC_EXTERN PetscErrorCode SNESCompositeSetDamping(SNES, PetscInt, PetscReal); 1058 1059 PETSC_EXTERN PetscErrorCode SNESPatchSetDiscretisationInfo(SNES, PetscInt, DM *, PetscInt *, PetscInt *, const PetscInt **, const PetscInt *, PetscInt, const PetscInt *, PetscInt, const PetscInt *); 1060 PETSC_EXTERN PetscErrorCode SNESPatchSetComputeOperator(SNES, PetscErrorCode (*func)(PC, PetscInt, Vec, Mat, IS, PetscInt, const PetscInt *, const PetscInt *, void *), void *); 1061 PETSC_EXTERN PetscErrorCode SNESPatchSetComputeFunction(SNES, PetscErrorCode (*func)(PC, PetscInt, Vec, Vec, IS, PetscInt, const PetscInt *, const PetscInt *, void *), void *); 1062 PETSC_EXTERN PetscErrorCode SNESPatchSetConstructType(SNES, PCPatchConstructType, PetscErrorCode (*func)(PC, PetscInt *, IS **, IS *, void *), void *); 1063 PETSC_EXTERN PetscErrorCode SNESPatchSetCellNumbering(SNES, PetscSection); 1064 1065 /*E 1066 SNESFASType - Determines the type of nonlinear multigrid method that is run. 1067 1068 Values: 1069 + `SNES_FAS_MULTIPLICATIVE` (default) - traditional V or W cycle as determined by `SNESFASSetCycles()` 1070 . `SNES_FAS_ADDITIVE` - additive FAS cycle 1071 . `SNES_FAS_FULL` - full FAS cycle 1072 - `SNES_FAS_KASKADE` - Kaskade FAS cycle 1073 1074 Level: beginner 1075 1076 .seealso: [](ch_snes), `SNESFAS`, `PCMGSetType()`, `PCMGType` 1077 E*/ 1078 typedef enum { 1079 SNES_FAS_MULTIPLICATIVE, 1080 SNES_FAS_ADDITIVE, 1081 SNES_FAS_FULL, 1082 SNES_FAS_KASKADE 1083 } SNESFASType; 1084 PETSC_EXTERN const char *const SNESFASTypes[]; 1085 1086 /* called on the finest level FAS instance*/ 1087 PETSC_EXTERN PetscErrorCode SNESFASSetType(SNES, SNESFASType); 1088 PETSC_EXTERN PetscErrorCode SNESFASGetType(SNES, SNESFASType *); 1089 PETSC_EXTERN PetscErrorCode SNESFASSetLevels(SNES, PetscInt, MPI_Comm *); 1090 PETSC_EXTERN PetscErrorCode SNESFASGetLevels(SNES, PetscInt *); 1091 PETSC_EXTERN PetscErrorCode SNESFASGetCycleSNES(SNES, PetscInt, SNES *); 1092 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothUp(SNES, PetscInt); 1093 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothDown(SNES, PetscInt); 1094 PETSC_EXTERN PetscErrorCode SNESFASSetCycles(SNES, PetscInt); 1095 PETSC_EXTERN PetscErrorCode SNESFASSetMonitor(SNES, PetscViewerAndFormat *, PetscBool); 1096 PETSC_EXTERN PetscErrorCode SNESFASSetLog(SNES, PetscBool); 1097 1098 PETSC_EXTERN PetscErrorCode SNESFASSetGalerkin(SNES, PetscBool); 1099 PETSC_EXTERN PetscErrorCode SNESFASGetGalerkin(SNES, PetscBool *); 1100 PETSC_EXTERN PetscErrorCode SNESFASGalerkinFunctionDefault(SNES, Vec, Vec, void *); 1101 1102 /* called on any level -- "Cycle" FAS instance */ 1103 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmoother(SNES, SNES *); 1104 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherUp(SNES, SNES *); 1105 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherDown(SNES, SNES *); 1106 PETSC_EXTERN PetscErrorCode SNESFASCycleGetCorrection(SNES, SNES *); 1107 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInterpolation(SNES, Mat *); 1108 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRestriction(SNES, Mat *); 1109 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInjection(SNES, Mat *); 1110 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRScale(SNES, Vec *); 1111 PETSC_EXTERN PetscErrorCode SNESFASCycleSetCycles(SNES, PetscInt); 1112 PETSC_EXTERN PetscErrorCode SNESFASCycleIsFine(SNES, PetscBool *); 1113 1114 /* called on the (outer) finest level FAS to set/get parameters on any level instance */ 1115 PETSC_EXTERN PetscErrorCode SNESFASSetInterpolation(SNES, PetscInt, Mat); 1116 PETSC_EXTERN PetscErrorCode SNESFASGetInterpolation(SNES, PetscInt, Mat *); 1117 PETSC_EXTERN PetscErrorCode SNESFASSetRestriction(SNES, PetscInt, Mat); 1118 PETSC_EXTERN PetscErrorCode SNESFASGetRestriction(SNES, PetscInt, Mat *); 1119 PETSC_EXTERN PetscErrorCode SNESFASSetInjection(SNES, PetscInt, Mat); 1120 PETSC_EXTERN PetscErrorCode SNESFASGetInjection(SNES, PetscInt, Mat *); 1121 PETSC_EXTERN PetscErrorCode SNESFASSetRScale(SNES, PetscInt, Vec); 1122 PETSC_EXTERN PetscErrorCode SNESFASGetRScale(SNES, PetscInt, Vec *); 1123 PETSC_EXTERN PetscErrorCode SNESFASSetContinuation(SNES, PetscBool); 1124 1125 PETSC_EXTERN PetscErrorCode SNESFASGetSmoother(SNES, PetscInt, SNES *); 1126 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherUp(SNES, PetscInt, SNES *); 1127 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherDown(SNES, PetscInt, SNES *); 1128 PETSC_EXTERN PetscErrorCode SNESFASGetCoarseSolve(SNES, SNES *); 1129 1130 /* parameters for full FAS */ 1131 PETSC_EXTERN PetscErrorCode SNESFASFullSetDownSweep(SNES, PetscBool); 1132 PETSC_EXTERN PetscErrorCode SNESFASCreateCoarseVec(SNES, Vec *); 1133 PETSC_EXTERN PetscErrorCode SNESFASRestrict(SNES, Vec, Vec); 1134 PETSC_EXTERN PetscErrorCode SNESFASFullSetTotal(SNES, PetscBool); 1135 PETSC_EXTERN PetscErrorCode SNESFASFullGetTotal(SNES, PetscBool *); 1136 1137 PETSC_EXTERN PetscErrorCode DMSNESCheckDiscretization(SNES, DM, PetscReal, Vec, PetscReal, PetscReal[]); 1138 PETSC_EXTERN PetscErrorCode DMSNESCheckResidual(SNES, DM, Vec, PetscReal, PetscReal *); 1139 PETSC_EXTERN PetscErrorCode DMSNESCheckJacobian(SNES, DM, Vec, PetscReal, PetscBool *, PetscReal *); 1140 PETSC_EXTERN PetscErrorCode DMSNESCheckFromOptions(SNES, Vec); 1141 PETSC_EXTERN PetscErrorCode DMSNESComputeJacobianAction(DM, Vec, Vec, Vec, void *); 1142 PETSC_EXTERN PetscErrorCode DMSNESCreateJacobianMF(DM, Vec, void *, Mat *); 1143