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