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