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 731 PETSC_EXTERN PetscFunctionList SNESList; 732 PETSC_EXTERN PetscClassId SNESLINESEARCH_CLASSID; 733 PETSC_EXTERN PetscFunctionList SNESLineSearchList; 734 735 #define SNES_LINESEARCH_ORDER_LINEAR 1 736 #define SNES_LINESEARCH_ORDER_QUADRATIC 2 737 #define SNES_LINESEARCH_ORDER_CUBIC 3 738 739 /*S 740 SNESLineSearchVIProjectFn - A prototype of a `SNES` function that projects a vector onto the VI bounds, passed to `SNESLineSearchSetVIFunctions()` 741 742 Calling Sequence: 743 + snes - `SNES` context 744 - u - the vector to project to the bounds 745 746 Level: advanced 747 748 Note: 749 The deprecated `SNESLineSearchVIProjectFunc` still works as a replacement for `SNESLineSearchVIProjectFn` *. 750 751 .seealso: [](ch_snes), `SNES`, `SNESLineSearch` 752 S*/ 753 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESLineSearchVIProjectFn)(SNES snes, Vec u); 754 PETSC_EXTERN_TYPEDEF typedef SNESLineSearchVIProjectFn *SNESLineSearchVIProjectFunc; // deprecated 755 756 /*S 757 SNESLineSearchVIProjectFn - A prototype of a `SNES` function that computes the norm of the active set variables in a vector in a VI solve, 758 passed to `SNESLineSearchSetVIFunctions()` 759 760 Calling Sequence: 761 + snes - `SNES` context 762 . f - the vector to compute the norm of 763 . u - the current solution, entries that are on the VI bounds are ignored 764 - fnorm - the resulting norm 765 766 Level: advanced 767 768 Note: 769 The deprecated `SNESLineSearchVINormFunc` still works as a replacement for `SNESLineSearchVINormFn` *. 770 771 .seealso: [](ch_snes), `SNES`, `SNESLineSearch` 772 S*/ 773 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESLineSearchVINormFn)(SNES snes, Vec f, Vec u, PetscReal *fnorm); 774 PETSC_EXTERN_TYPEDEF typedef SNESLineSearchVINormFn *SNESLineSearchVINormFunc; // deprecated 775 776 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESLineSearchApplyFn)(SNESLineSearch); 777 PETSC_EXTERN_TYPEDEF typedef SNESLineSearchApplyFn *SNESLineSearchApplyFunc; // deprecated 778 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESLineSearchShellApplyFn)(SNESLineSearch, void *); 779 PETSC_EXTERN_TYPEDEF typedef SNESLineSearchShellApplyFn *SNESLineSearchUserFunc; // deprecated 780 781 PETSC_EXTERN PetscErrorCode SNESLineSearchCreate(MPI_Comm, SNESLineSearch *); 782 PETSC_EXTERN PetscErrorCode SNESLineSearchReset(SNESLineSearch); 783 PETSC_EXTERN PetscErrorCode SNESLineSearchView(SNESLineSearch, PetscViewer); 784 PETSC_EXTERN PetscErrorCode SNESLineSearchDestroy(SNESLineSearch *); 785 PETSC_EXTERN PetscErrorCode SNESLineSearchGetType(SNESLineSearch, SNESLineSearchType *); 786 PETSC_EXTERN PetscErrorCode SNESLineSearchSetType(SNESLineSearch, SNESLineSearchType); 787 PETSC_EXTERN PetscErrorCode SNESLineSearchSetFromOptions(SNESLineSearch); 788 PETSC_EXTERN PetscErrorCode SNESLineSearchSetFunction(SNESLineSearch, PetscErrorCode (*)(SNES, Vec, Vec)); 789 PETSC_EXTERN PetscErrorCode SNESLineSearchSetUp(SNESLineSearch); 790 PETSC_EXTERN PetscErrorCode SNESLineSearchApply(SNESLineSearch, Vec, Vec, PetscReal *, Vec); 791 PETSC_EXTERN PetscErrorCode SNESLineSearchPreCheck(SNESLineSearch, Vec, Vec, PetscBool *); 792 PETSC_EXTERN PetscErrorCode SNESLineSearchPostCheck(SNESLineSearch, Vec, Vec, Vec, PetscBool *, PetscBool *); 793 PETSC_EXTERN PetscErrorCode SNESLineSearchSetWorkVecs(SNESLineSearch, PetscInt); 794 795 /* set the functions for precheck and postcheck */ 796 797 PETSC_EXTERN PetscErrorCode SNESLineSearchSetPreCheck(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch, Vec, Vec, PetscBool *, void *), void *ctx); 798 PETSC_EXTERN PetscErrorCode SNESLineSearchSetPostCheck(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void *ctx); 799 800 PETSC_EXTERN PetscErrorCode SNESLineSearchGetPreCheck(SNESLineSearch, PetscErrorCode (**)(SNESLineSearch, Vec, Vec, PetscBool *, void *), void **ctx); 801 PETSC_EXTERN PetscErrorCode SNESLineSearchGetPostCheck(SNESLineSearch, PetscErrorCode (**)(SNESLineSearch, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void **ctx); 802 803 /* set the functions for VI-specific line search operations */ 804 805 PETSC_EXTERN PetscErrorCode SNESLineSearchSetVIFunctions(SNESLineSearch, SNESLineSearchVIProjectFn *, SNESLineSearchVINormFn *); 806 PETSC_EXTERN PetscErrorCode SNESLineSearchGetVIFunctions(SNESLineSearch, SNESLineSearchVIProjectFn **, SNESLineSearchVINormFn **); 807 808 /* pointers to the associated SNES in order to be able to get the function evaluation out */ 809 PETSC_EXTERN PetscErrorCode SNESLineSearchSetSNES(SNESLineSearch, SNES); 810 PETSC_EXTERN PetscErrorCode SNESLineSearchGetSNES(SNESLineSearch, SNES *); 811 812 /* set and get the parameters and vectors */ 813 PETSC_EXTERN PetscErrorCode SNESLineSearchGetTolerances(SNESLineSearch, PetscReal *, PetscReal *, PetscReal *, PetscReal *, PetscReal *, PetscInt *); 814 PETSC_EXTERN PetscErrorCode SNESLineSearchSetTolerances(SNESLineSearch, PetscReal, PetscReal, PetscReal, PetscReal, PetscReal, PetscInt); 815 816 PETSC_EXTERN PetscErrorCode SNESLineSearchPreCheckPicard(SNESLineSearch, Vec, Vec, PetscBool *, void *); 817 818 PETSC_EXTERN PetscErrorCode SNESLineSearchGetLambda(SNESLineSearch, PetscReal *); 819 PETSC_EXTERN PetscErrorCode SNESLineSearchSetLambda(SNESLineSearch, PetscReal); 820 821 PETSC_EXTERN PetscErrorCode SNESLineSearchGetDamping(SNESLineSearch, PetscReal *); 822 PETSC_EXTERN PetscErrorCode SNESLineSearchSetDamping(SNESLineSearch, PetscReal); 823 824 PETSC_EXTERN PetscErrorCode SNESLineSearchGetOrder(SNESLineSearch, PetscInt *order); 825 PETSC_EXTERN PetscErrorCode SNESLineSearchSetOrder(SNESLineSearch, PetscInt order); 826 827 /*E 828 SNESLineSearchReason - indication if the line search has succeeded or failed and why 829 830 Values: 831 + `SNES_LINESEARCH_SUCCEEDED` - the line search succeeded 832 . `SNES_LINESEARCH_FAILED_NANORINF` - a not a number of infinity appeared in the computions 833 . `SNES_LINESEARCH_FAILED_DOMAIN` - the function was evaluated outside of its domain, see `SNESSetFunctionDomainError()` and `SNESSetJacobianDomainError()` 834 . `SNES_LINESEARCH_FAILED_REDUCT` - the linear search failed to get the requested decrease in its norm or objective 835 . `SNES_LINESEARCH_FAILED_USER` - used by `SNESLINESEARCHNLEQERR` to indicate the user changed the search direction inappropriately 836 - `SNES_LINESEARCH_FAILED_FUNCTION` - indicates the maximum number of function evaluations allowed has been surpassed, `SNESConvergedReason` is also 837 set to `SNES_DIVERGED_FUNCTION_COUNT` 838 839 Level: intermediate 840 841 Developer Note: 842 Some of these reasons overlap with values of `SNESConvergedReason` 843 844 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `KSPConvergedReason`, `SNESSetConvergenceTest()`, 845 `SNESSetFunctionDomainError()` and `SNESSetJacobianDomainError()` 846 E*/ 847 typedef enum { 848 SNES_LINESEARCH_SUCCEEDED, 849 SNES_LINESEARCH_FAILED_NANORINF, 850 SNES_LINESEARCH_FAILED_DOMAIN, 851 SNES_LINESEARCH_FAILED_REDUCT, /* INSUFFICIENT REDUCTION */ 852 SNES_LINESEARCH_FAILED_USER, 853 SNES_LINESEARCH_FAILED_FUNCTION 854 } SNESLineSearchReason; 855 856 PETSC_EXTERN PetscErrorCode SNESLineSearchGetReason(SNESLineSearch, SNESLineSearchReason *); 857 PETSC_EXTERN PetscErrorCode SNESLineSearchSetReason(SNESLineSearch, SNESLineSearchReason); 858 859 PETSC_EXTERN PetscErrorCode SNESLineSearchGetVecs(SNESLineSearch, Vec *, Vec *, Vec *, Vec *, Vec *); 860 PETSC_EXTERN PetscErrorCode SNESLineSearchSetVecs(SNESLineSearch, Vec, Vec, Vec, Vec, Vec); 861 862 PETSC_EXTERN PetscErrorCode SNESLineSearchGetNorms(SNESLineSearch, PetscReal *, PetscReal *, PetscReal *); 863 PETSC_EXTERN PetscErrorCode SNESLineSearchSetNorms(SNESLineSearch, PetscReal, PetscReal, PetscReal); 864 PETSC_EXTERN PetscErrorCode SNESLineSearchComputeNorms(SNESLineSearch); 865 PETSC_EXTERN PetscErrorCode SNESLineSearchSetComputeNorms(SNESLineSearch, PetscBool); 866 867 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitor(SNESLineSearch); 868 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSet(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch, void *), void *, PetscCtxDestroyFn *); 869 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSetFromOptions(SNESLineSearch, const char[], const char[], const char[], PetscErrorCode (*)(SNESLineSearch, PetscViewerAndFormat *), PetscErrorCode (*)(SNESLineSearch, PetscViewerAndFormat *)); 870 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorCancel(SNESLineSearch); 871 PETSC_EXTERN PetscErrorCode SNESLineSearchSetDefaultMonitor(SNESLineSearch, PetscViewer); 872 PETSC_EXTERN PetscErrorCode SNESLineSearchGetDefaultMonitor(SNESLineSearch, PetscViewer *); 873 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSolutionUpdate(SNESLineSearch, PetscViewerAndFormat *); 874 875 PETSC_EXTERN PetscErrorCode SNESLineSearchAppendOptionsPrefix(SNESLineSearch, const char prefix[]); 876 PETSC_EXTERN PetscErrorCode SNESLineSearchGetOptionsPrefix(SNESLineSearch, const char *prefix[]); 877 878 /* Shell interface functions */ 879 PETSC_EXTERN PetscErrorCode SNESLineSearchShellSetApply(SNESLineSearch, SNESLineSearchShellApplyFn, void *); 880 PETSC_EXTERN PetscErrorCode SNESLineSearchShellGetApply(SNESLineSearch, SNESLineSearchShellApplyFn **, void **); 881 882 PETSC_DEPRECATED_FUNCTION(3, 21, 0, "SNESLinesearchShellSetApply()", ) static inline PetscErrorCode SNESLineSearchShellSetUserFunc(SNESLineSearch ls, SNESLineSearchUserFunc f, void *ctx) 883 { 884 return SNESLineSearchShellSetApply(ls, f, ctx); 885 } 886 887 PETSC_DEPRECATED_FUNCTION(3, 21, 0, "SNESLinesearchShellGetApply()", ) static inline PetscErrorCode SNESLineSearchShellGetUserFunc(SNESLineSearch ls, SNESLineSearchUserFunc *f, void **ctx) 888 { 889 return SNESLineSearchShellGetApply(ls, f, ctx); 890 } 891 892 /* BT interface functions */ 893 PETSC_EXTERN PetscErrorCode SNESLineSearchBTSetAlpha(SNESLineSearch, PetscReal); 894 PETSC_EXTERN PetscErrorCode SNESLineSearchBTGetAlpha(SNESLineSearch, PetscReal *); 895 896 /*register line search types */ 897 PETSC_EXTERN PetscErrorCode SNESLineSearchRegister(const char[], PetscErrorCode (*)(SNESLineSearch)); 898 899 /* Routines for VI solver */ 900 PETSC_EXTERN PetscErrorCode SNESVISetVariableBounds(SNES, Vec, Vec); 901 PETSC_EXTERN PetscErrorCode SNESVIGetVariableBounds(SNES, Vec *, Vec *); 902 PETSC_EXTERN PetscErrorCode SNESVISetComputeVariableBounds(SNES, PetscErrorCode (*)(SNES, Vec, Vec)); 903 PETSC_EXTERN PetscErrorCode SNESVIGetInactiveSet(SNES, IS *); 904 PETSC_EXTERN PetscErrorCode SNESVIGetActiveSetIS(SNES, Vec, Vec, IS *); 905 PETSC_EXTERN PetscErrorCode SNESVIComputeInactiveSetFnorm(SNES, Vec, Vec, PetscReal *); 906 PETSC_EXTERN PetscErrorCode SNESVISetRedundancyCheck(SNES, PetscErrorCode (*)(SNES, IS, IS *, void *), void *); 907 PETSC_EXTERN PetscErrorCode SNESVIComputeMeritFunction(Vec, PetscReal *, PetscReal *); 908 PETSC_EXTERN PetscErrorCode SNESVIComputeFunction(SNES, Vec, Vec, void *); 909 PETSC_EXTERN PetscErrorCode DMSetVI(DM, IS); 910 PETSC_EXTERN PetscErrorCode DMDestroyVI(DM); 911 912 PETSC_EXTERN PetscErrorCode SNESTestLocalMin(SNES); 913 914 /* Should this routine be private? */ 915 PETSC_EXTERN PetscErrorCode SNESComputeJacobian(SNES, Vec, Mat, Mat); 916 PETSC_EXTERN PetscErrorCode SNESTestJacobian(SNES); 917 PETSC_EXTERN PetscErrorCode SNESTestFunction(SNES); 918 919 PETSC_EXTERN PetscErrorCode SNESSetDM(SNES, DM); 920 PETSC_EXTERN PetscErrorCode SNESGetDM(SNES, DM *); 921 PETSC_EXTERN PetscErrorCode SNESSetNPC(SNES, SNES); 922 PETSC_EXTERN PetscErrorCode SNESGetNPC(SNES, SNES *); 923 PETSC_EXTERN PetscErrorCode SNESHasNPC(SNES, PetscBool *); 924 PETSC_EXTERN PetscErrorCode SNESApplyNPC(SNES, Vec, Vec, Vec); 925 PETSC_EXTERN PetscErrorCode SNESGetNPCFunction(SNES, Vec, PetscReal *); 926 PETSC_EXTERN PetscErrorCode SNESComputeFunctionDefaultNPC(SNES, Vec, Vec); 927 PETSC_EXTERN PetscErrorCode SNESSetNPCSide(SNES, PCSide); 928 PETSC_EXTERN PetscErrorCode SNESGetNPCSide(SNES, PCSide *); 929 PETSC_EXTERN PetscErrorCode SNESSetLineSearch(SNES, SNESLineSearch); 930 PETSC_EXTERN PetscErrorCode SNESGetLineSearch(SNES, SNESLineSearch *); 931 932 PETSC_DEPRECATED_FUNCTION(3, 4, 0, "SNESGetLineSearch()", ) static inline PetscErrorCode SNESGetSNESLineSearch(SNES snes, SNESLineSearch *ls) 933 { 934 return SNESGetLineSearch(snes, ls); 935 } 936 PETSC_DEPRECATED_FUNCTION(3, 4, 0, "SNESSetLineSearch()", ) static inline PetscErrorCode SNESSetSNESLineSearch(SNES snes, SNESLineSearch ls) 937 { 938 return SNESSetLineSearch(snes, ls); 939 } 940 941 PETSC_EXTERN PetscErrorCode SNESSetUpMatrices(SNES); 942 PETSC_EXTERN PetscErrorCode DMSNESSetFunction(DM, SNESFunctionFn *, void *); 943 PETSC_EXTERN PetscErrorCode DMSNESGetFunction(DM, SNESFunctionFn **, void **); 944 PETSC_EXTERN PetscErrorCode DMSNESSetFunctionContextDestroy(DM, PetscCtxDestroyFn *); 945 PETSC_EXTERN PetscErrorCode DMSNESSetMFFunction(DM, SNESFunctionFn *, void *); 946 PETSC_EXTERN PetscErrorCode DMSNESSetNGS(DM, SNESNGSFn *, void *); 947 PETSC_EXTERN PetscErrorCode DMSNESGetNGS(DM, SNESNGSFn **, void **); 948 PETSC_EXTERN PetscErrorCode DMSNESSetJacobian(DM, SNESJacobianFn *, void *); 949 PETSC_EXTERN PetscErrorCode DMSNESGetJacobian(DM, SNESJacobianFn **, void **); 950 PETSC_EXTERN PetscErrorCode DMSNESSetJacobianContextDestroy(DM, PetscCtxDestroyFn *); 951 PETSC_EXTERN PetscErrorCode DMSNESSetPicard(DM, SNESFunctionFn *, SNESJacobianFn *, void *); 952 PETSC_EXTERN PetscErrorCode DMSNESGetPicard(DM, SNESFunctionFn **, SNESJacobianFn **, void **); 953 PETSC_EXTERN PetscErrorCode DMSNESSetObjective(DM, SNESObjectiveFn *, void *); 954 PETSC_EXTERN PetscErrorCode DMSNESGetObjective(DM, SNESObjectiveFn **, void **); 955 PETSC_EXTERN PetscErrorCode DMCopyDMSNES(DM, DM); 956 957 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESFunctionFn)(DMDALocalInfo *, void *, void *, void *); 958 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESJacobianFn)(DMDALocalInfo *, void *, Mat, Mat, void *); 959 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESObjectiveFn)(DMDALocalInfo *, void *, PetscReal *, void *); 960 961 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESFunctionVecFn)(DMDALocalInfo *, Vec, Vec, void *); 962 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESJacobianVecFn)(DMDALocalInfo *, Vec, Mat, Mat, void *); 963 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESObjectiveVecFn)(DMDALocalInfo *, Vec, PetscReal *, void *); 964 965 PETSC_EXTERN PetscErrorCode DMDASNESSetFunctionLocal(DM, InsertMode, DMDASNESFunctionFn *, void *); 966 PETSC_EXTERN PetscErrorCode DMDASNESSetJacobianLocal(DM, DMDASNESJacobianFn *, void *); 967 PETSC_EXTERN PetscErrorCode DMDASNESSetObjectiveLocal(DM, DMDASNESObjectiveFn *, void *); 968 PETSC_EXTERN PetscErrorCode DMDASNESSetPicardLocal(DM, InsertMode, DMDASNESFunctionFn *, DMDASNESJacobianFn, void *); 969 970 PETSC_EXTERN PetscErrorCode DMDASNESSetFunctionLocalVec(DM, InsertMode, DMDASNESFunctionVecFn *, void *); 971 PETSC_EXTERN PetscErrorCode DMDASNESSetJacobianLocalVec(DM, DMDASNESJacobianVecFn *, void *); 972 PETSC_EXTERN PetscErrorCode DMDASNESSetObjectiveLocalVec(DM, DMDASNESObjectiveVecFn *, void *); 973 974 PETSC_EXTERN PetscErrorCode DMSNESSetBoundaryLocal(DM, PetscErrorCode (*)(DM, Vec, void *), void *); 975 PETSC_EXTERN PetscErrorCode DMSNESSetObjectiveLocal(DM, PetscErrorCode (*)(DM, Vec, PetscReal *, void *), void *); 976 PETSC_EXTERN PetscErrorCode DMSNESSetFunctionLocal(DM, PetscErrorCode (*)(DM, Vec, Vec, void *), void *); 977 PETSC_EXTERN PetscErrorCode DMSNESSetJacobianLocal(DM, PetscErrorCode (*)(DM, Vec, Mat, Mat, void *), void *); 978 PETSC_EXTERN PetscErrorCode DMSNESGetBoundaryLocal(DM, PetscErrorCode (**)(DM, Vec, void *), void **); 979 PETSC_EXTERN PetscErrorCode DMSNESGetObjectiveLocal(DM, PetscErrorCode (**)(DM, Vec, PetscReal *, void *), void **); 980 PETSC_EXTERN PetscErrorCode DMSNESGetFunctionLocal(DM, PetscErrorCode (**)(DM, Vec, Vec, void *), void **); 981 PETSC_EXTERN PetscErrorCode DMSNESGetJacobianLocal(DM, PetscErrorCode (**)(DM, Vec, Mat, Mat, void *), void **); 982 983 /* Routines for Multiblock solver */ 984 PETSC_EXTERN PetscErrorCode SNESMultiblockSetFields(SNES, const char[], PetscInt, const PetscInt *); 985 PETSC_EXTERN PetscErrorCode SNESMultiblockSetIS(SNES, const char[], IS); 986 PETSC_EXTERN PetscErrorCode SNESMultiblockSetBlockSize(SNES, PetscInt); 987 PETSC_EXTERN PetscErrorCode SNESMultiblockSetType(SNES, PCCompositeType); 988 PETSC_EXTERN PetscErrorCode SNESMultiblockGetSubSNES(SNES, PetscInt *, SNES *[]); 989 990 /*J 991 SNESMSType - String with the name of a PETSc `SNESMS` method. 992 993 Level: intermediate 994 995 .seealso: [](ch_snes), `SNESMS`, `SNESMSGetType()`, `SNESMSSetType()`, `SNES` 996 J*/ 997 typedef const char *SNESMSType; 998 #define SNESMSM62 "m62" 999 #define SNESMSEULER "euler" 1000 #define SNESMSJAMESON83 "jameson83" 1001 #define SNESMSVLTP11 "vltp11" 1002 #define SNESMSVLTP21 "vltp21" 1003 #define SNESMSVLTP31 "vltp31" 1004 #define SNESMSVLTP41 "vltp41" 1005 #define SNESMSVLTP51 "vltp51" 1006 #define SNESMSVLTP61 "vltp61" 1007 1008 PETSC_EXTERN PetscErrorCode SNESMSRegister(SNESMSType, PetscInt, PetscInt, PetscReal, const PetscReal[], const PetscReal[], const PetscReal[]); 1009 PETSC_EXTERN PetscErrorCode SNESMSRegisterAll(void); 1010 PETSC_EXTERN PetscErrorCode SNESMSGetType(SNES, SNESMSType *); 1011 PETSC_EXTERN PetscErrorCode SNESMSSetType(SNES, SNESMSType); 1012 PETSC_EXTERN PetscErrorCode SNESMSGetDamping(SNES, PetscReal *); 1013 PETSC_EXTERN PetscErrorCode SNESMSSetDamping(SNES, PetscReal); 1014 PETSC_EXTERN PetscErrorCode SNESMSFinalizePackage(void); 1015 PETSC_EXTERN PetscErrorCode SNESMSInitializePackage(void); 1016 PETSC_EXTERN PetscErrorCode SNESMSRegisterDestroy(void); 1017 1018 /*MC 1019 SNESNGMRESRestartType - the restart approach used by `SNESNGMRES` 1020 1021 Values: 1022 + `SNES_NGMRES_RESTART_NONE` - never restart 1023 . `SNES_NGMRES_RESTART_DIFFERENCE` - restart based upon difference criteria 1024 - `SNES_NGMRES_RESTART_PERIODIC` - restart after a fixed number of iterations 1025 1026 Options Database Keys: 1027 + -snes_ngmres_restart_type <difference,periodic,none> - set the restart type 1028 - -snes_ngmres_restart <30> - sets the number of iterations before restart for periodic 1029 1030 Level: intermediate 1031 1032 .seealso: `SNES, `SNESNGMRES`, `SNESNGMRESSetSelectType()`, `SNESNGMRESGetSelectType()`, `SNESNGMRESSetRestartType()`, 1033 `SNESNGMRESGetRestartType()`, `SNESNGMRESSelectType` 1034 M*/ 1035 typedef enum { 1036 SNES_NGMRES_RESTART_NONE = 0, 1037 SNES_NGMRES_RESTART_PERIODIC = 1, 1038 SNES_NGMRES_RESTART_DIFFERENCE = 2 1039 } SNESNGMRESRestartType; 1040 PETSC_EXTERN const char *const SNESNGMRESRestartTypes[]; 1041 1042 /*MC 1043 SNESNGMRESSelectType - the approach used by `SNESNGMRES` to determine how the candidate solution and 1044 combined solution are used to create the next iterate. 1045 1046 Values: 1047 + `SNES_NGMRES_SELECT_NONE` - choose the combined solution all the time 1048 . `SNES_NGMRES_SELECT_DIFFERENCE` - choose based upon the selection criteria 1049 - `SNES_NGMRES_SELECT_LINESEARCH` - choose based upon line search combination 1050 1051 Options Database Key: 1052 . -snes_ngmres_select_type<difference,none,linesearch> - select type 1053 1054 Level: intermediate 1055 1056 .seealso: `SNES, `SNESNGMRES`, `SNESNGMRESSetSelectType()`, `SNESNGMRESGetSelectType()`, `SNESNGMRESSetRestartType()`, 1057 `SNESNGMRESGetRestartType()`, `SNESNGMRESRestartType` 1058 M*/ 1059 typedef enum { 1060 SNES_NGMRES_SELECT_NONE = 0, 1061 SNES_NGMRES_SELECT_DIFFERENCE = 1, 1062 SNES_NGMRES_SELECT_LINESEARCH = 2 1063 } SNESNGMRESSelectType; 1064 PETSC_EXTERN const char *const SNESNGMRESSelectTypes[]; 1065 1066 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartType(SNES, SNESNGMRESRestartType); 1067 PETSC_EXTERN PetscErrorCode SNESNGMRESSetSelectType(SNES, SNESNGMRESSelectType); 1068 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartFmRise(SNES, PetscBool); 1069 PETSC_EXTERN PetscErrorCode SNESNGMRESGetRestartFmRise(SNES, PetscBool *); 1070 1071 /*MC 1072 SNESNCGType - the conjugate update approach for `SNESNCG` 1073 1074 Values: 1075 + `SNES_NCG_FR` - Fletcher-Reeves update 1076 . `SNES_NCG_PRP` - Polak-Ribiere-Polyak update, the default and the only one that tolerates generalized search directions 1077 . `SNES_NCG_HS` - Hestenes-Steifel update 1078 . `SNES_NCG_DY` - Dai-Yuan update 1079 - `SNES_NCG_CD` - Conjugate Descent update 1080 1081 Options Database Key: 1082 . -snes_ncg_type<fr,prp,hs,dy,cd> - select type 1083 1084 Level: intermediate 1085 1086 .seealso: `SNES, `SNESNCG`, `SNESNCGSetType()` 1087 M*/ 1088 typedef enum { 1089 SNES_NCG_FR = 0, 1090 SNES_NCG_PRP = 1, 1091 SNES_NCG_HS = 2, 1092 SNES_NCG_DY = 3, 1093 SNES_NCG_CD = 4 1094 } SNESNCGType; 1095 PETSC_EXTERN const char *const SNESNCGTypes[]; 1096 1097 PETSC_EXTERN PetscErrorCode SNESNCGSetType(SNES, SNESNCGType); 1098 1099 /*MC 1100 SNESQNScaleType - the scaling type used by `SNESQN` 1101 1102 Values: 1103 + `SNES_QN_SCALE_NONE` - don't scale the problem 1104 . `SNES_QN_SCALE_SCALAR` - use Shanno scaling 1105 . `SNES_QN_SCALE_DIAGONAL` - scale with a diagonalized BFGS formula (see Gilbert and Lemarechal 1989), available 1106 - `SNES_QN_SCALE_JACOBIAN` - scale by solving a linear system coming from the Jacobian you provided with `SNESSetJacobian()` 1107 computed at the first iteration of `SNESQN` and at ever restart. 1108 1109 Options Database Key: 1110 . -snes_qn_scale_type <diagonal,none,scalar,jacobian> - Scaling type 1111 1112 Level: intermediate 1113 1114 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNType`, `SNESQNSetType()`, `SNESQNSetRestartType()`, `SNESQNRestartType` 1115 M*/ 1116 typedef enum { 1117 SNES_QN_SCALE_DEFAULT = 0, 1118 SNES_QN_SCALE_NONE = 1, 1119 SNES_QN_SCALE_SCALAR = 2, 1120 SNES_QN_SCALE_DIAGONAL = 3, 1121 SNES_QN_SCALE_JACOBIAN = 4 1122 } SNESQNScaleType; 1123 PETSC_EXTERN const char *const SNESQNScaleTypes[]; 1124 1125 /*MC 1126 SNESQNRestartType - the restart approached used by `SNESQN` 1127 1128 Values: 1129 + `SNES_QN_RESTART_NONE` - never restart 1130 . `SNES_QN_RESTART_POWELL` - restart based upon descent criteria 1131 - `SNES_QN_RESTART_PERIODIC` - restart after a fixed number of iterations 1132 1133 Options Database Keys: 1134 + -snes_qn_restart_type <powell,periodic,none> - set the restart type 1135 - -snes_qn_m <m> - sets the number of stored updates and the restart period for periodic 1136 1137 Level: intermediate 1138 1139 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNType`, `SNESQNSetType()`, `SNESQNSetRestartType()`, `SNESQNScaleType` 1140 M*/ 1141 typedef enum { 1142 SNES_QN_RESTART_DEFAULT = 0, 1143 SNES_QN_RESTART_NONE = 1, 1144 SNES_QN_RESTART_POWELL = 2, 1145 SNES_QN_RESTART_PERIODIC = 3 1146 } SNESQNRestartType; 1147 PETSC_EXTERN const char *const SNESQNRestartTypes[]; 1148 1149 /*MC 1150 SNESQNType - the type used by `SNESQN` 1151 1152 Values: 1153 + `SNES_QN_LBFGS` - LBFGS variant 1154 . `SNES_QN_BROYDEN` - Broyden variant 1155 - `SNES_QN_BADBROYDEN` - Bad Broyden variant 1156 1157 Options Database Key: 1158 . -snes_qn_type <lbfgs,broyden,badbroyden> - quasi-Newton type 1159 1160 Level: intermediate 1161 1162 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNSetType()`, `SNESQNScaleType`, `SNESQNRestartType`, `SNESQNSetRestartType()` 1163 M*/ 1164 typedef enum { 1165 SNES_QN_LBFGS = 0, 1166 SNES_QN_BROYDEN = 1, 1167 SNES_QN_BADBROYDEN = 2 1168 } SNESQNType; 1169 PETSC_EXTERN const char *const SNESQNTypes[]; 1170 1171 PETSC_EXTERN PetscErrorCode SNESQNSetType(SNES, SNESQNType); 1172 PETSC_EXTERN PetscErrorCode SNESQNSetScaleType(SNES, SNESQNScaleType); 1173 PETSC_EXTERN PetscErrorCode SNESQNSetRestartType(SNES, SNESQNRestartType); 1174 1175 PETSC_EXTERN PetscErrorCode SNESNASMGetType(SNES, PCASMType *); 1176 PETSC_EXTERN PetscErrorCode SNESNASMSetType(SNES, PCASMType); 1177 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomains(SNES, PetscInt *, SNES **, VecScatter **, VecScatter **, VecScatter **); 1178 PETSC_EXTERN PetscErrorCode SNESNASMSetSubdomains(SNES, PetscInt, SNES *, VecScatter *, VecScatter *, VecScatter *); 1179 PETSC_EXTERN PetscErrorCode SNESNASMSetDamping(SNES, PetscReal); 1180 PETSC_EXTERN PetscErrorCode SNESNASMGetDamping(SNES, PetscReal *); 1181 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomainVecs(SNES, PetscInt *, Vec **, Vec **, Vec **, Vec **); 1182 PETSC_EXTERN PetscErrorCode SNESNASMSetComputeFinalJacobian(SNES, PetscBool); 1183 PETSC_EXTERN PetscErrorCode SNESNASMGetSNES(SNES, PetscInt, SNES *); 1184 PETSC_EXTERN PetscErrorCode SNESNASMGetNumber(SNES, PetscInt *); 1185 PETSC_EXTERN PetscErrorCode SNESNASMSetWeight(SNES, Vec); 1186 1187 /*E 1188 SNESCompositeType - Determines how two or more preconditioners are composed with the `SNESType` of `SNESCOMPOSITE` 1189 1190 Values: 1191 + `SNES_COMPOSITE_ADDITIVE` - results from application of all preconditioners are added together 1192 . `SNES_COMPOSITE_MULTIPLICATIVE` - preconditioners are applied sequentially to the residual freshly 1193 computed after the previous preconditioner application 1194 - `SNES_COMPOSITE_ADDITIVEOPTIMAL` - uses a linear combination of the solutions obtained with each preconditioner that approximately minimize the function 1195 value at the new iteration. 1196 1197 Level: beginner 1198 1199 .seealso: [](sec_pc), `PCCOMPOSITE`, `PCFIELDSPLIT`, `PC`, `PCCompositeSetType()`, `PCCompositeType` 1200 E*/ 1201 typedef enum { 1202 SNES_COMPOSITE_ADDITIVE, 1203 SNES_COMPOSITE_MULTIPLICATIVE, 1204 SNES_COMPOSITE_ADDITIVEOPTIMAL 1205 } SNESCompositeType; 1206 PETSC_EXTERN const char *const SNESCompositeTypes[]; 1207 1208 PETSC_EXTERN PetscErrorCode SNESCompositeSetType(SNES, SNESCompositeType); 1209 PETSC_EXTERN PetscErrorCode SNESCompositeAddSNES(SNES, SNESType); 1210 PETSC_EXTERN PetscErrorCode SNESCompositeGetSNES(SNES, PetscInt, SNES *); 1211 PETSC_EXTERN PetscErrorCode SNESCompositeGetNumber(SNES, PetscInt *); 1212 PETSC_EXTERN PetscErrorCode SNESCompositeSetDamping(SNES, PetscInt, PetscReal); 1213 1214 PETSC_EXTERN PetscErrorCode SNESPatchSetDiscretisationInfo(SNES, PetscInt, DM *, PetscInt *, PetscInt *, const PetscInt **, const PetscInt *, PetscInt, const PetscInt *, PetscInt, const PetscInt *); 1215 PETSC_EXTERN PetscErrorCode SNESPatchSetComputeOperator(SNES, PetscErrorCode (*func)(PC, PetscInt, Vec, Mat, IS, PetscInt, const PetscInt *, const PetscInt *, void *), void *); 1216 PETSC_EXTERN PetscErrorCode SNESPatchSetComputeFunction(SNES, PetscErrorCode (*func)(PC, PetscInt, Vec, Vec, IS, PetscInt, const PetscInt *, const PetscInt *, void *), void *); 1217 PETSC_EXTERN PetscErrorCode SNESPatchSetConstructType(SNES, PCPatchConstructType, PetscErrorCode (*func)(PC, PetscInt *, IS **, IS *, void *), void *); 1218 PETSC_EXTERN PetscErrorCode SNESPatchSetCellNumbering(SNES, PetscSection); 1219 1220 /*E 1221 SNESFASType - Determines the type of nonlinear multigrid method that is run. 1222 1223 Values: 1224 + `SNES_FAS_MULTIPLICATIVE` (default) - traditional V or W cycle as determined by `SNESFASSetCycles()` 1225 . `SNES_FAS_ADDITIVE` - additive FAS cycle 1226 . `SNES_FAS_FULL` - full FAS cycle 1227 - `SNES_FAS_KASKADE` - Kaskade FAS cycle 1228 1229 Level: beginner 1230 1231 .seealso: [](ch_snes), `SNESFAS`, `PCMGSetType()`, `PCMGType` 1232 E*/ 1233 typedef enum { 1234 SNES_FAS_MULTIPLICATIVE, 1235 SNES_FAS_ADDITIVE, 1236 SNES_FAS_FULL, 1237 SNES_FAS_KASKADE 1238 } SNESFASType; 1239 PETSC_EXTERN const char *const SNESFASTypes[]; 1240 1241 /* called on the finest level FAS instance*/ 1242 PETSC_EXTERN PetscErrorCode SNESFASSetType(SNES, SNESFASType); 1243 PETSC_EXTERN PetscErrorCode SNESFASGetType(SNES, SNESFASType *); 1244 PETSC_EXTERN PetscErrorCode SNESFASSetLevels(SNES, PetscInt, MPI_Comm *); 1245 PETSC_EXTERN PetscErrorCode SNESFASGetLevels(SNES, PetscInt *); 1246 PETSC_EXTERN PetscErrorCode SNESFASGetCycleSNES(SNES, PetscInt, SNES *); 1247 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothUp(SNES, PetscInt); 1248 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothDown(SNES, PetscInt); 1249 PETSC_EXTERN PetscErrorCode SNESFASSetCycles(SNES, PetscInt); 1250 PETSC_EXTERN PetscErrorCode SNESFASSetMonitor(SNES, PetscViewerAndFormat *, PetscBool); 1251 PETSC_EXTERN PetscErrorCode SNESFASSetLog(SNES, PetscBool); 1252 1253 PETSC_EXTERN PetscErrorCode SNESFASSetGalerkin(SNES, PetscBool); 1254 PETSC_EXTERN PetscErrorCode SNESFASGetGalerkin(SNES, PetscBool *); 1255 PETSC_EXTERN PetscErrorCode SNESFASGalerkinFunctionDefault(SNES, Vec, Vec, void *); 1256 1257 /* called on any level -- "Cycle" FAS instance */ 1258 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmoother(SNES, SNES *); 1259 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherUp(SNES, SNES *); 1260 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherDown(SNES, SNES *); 1261 PETSC_EXTERN PetscErrorCode SNESFASCycleGetCorrection(SNES, SNES *); 1262 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInterpolation(SNES, Mat *); 1263 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRestriction(SNES, Mat *); 1264 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInjection(SNES, Mat *); 1265 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRScale(SNES, Vec *); 1266 PETSC_EXTERN PetscErrorCode SNESFASCycleSetCycles(SNES, PetscInt); 1267 PETSC_EXTERN PetscErrorCode SNESFASCycleIsFine(SNES, PetscBool *); 1268 1269 /* called on the (outer) finest level FAS to set/get parameters on any level instance */ 1270 PETSC_EXTERN PetscErrorCode SNESFASSetInterpolation(SNES, PetscInt, Mat); 1271 PETSC_EXTERN PetscErrorCode SNESFASGetInterpolation(SNES, PetscInt, Mat *); 1272 PETSC_EXTERN PetscErrorCode SNESFASSetRestriction(SNES, PetscInt, Mat); 1273 PETSC_EXTERN PetscErrorCode SNESFASGetRestriction(SNES, PetscInt, Mat *); 1274 PETSC_EXTERN PetscErrorCode SNESFASSetInjection(SNES, PetscInt, Mat); 1275 PETSC_EXTERN PetscErrorCode SNESFASGetInjection(SNES, PetscInt, Mat *); 1276 PETSC_EXTERN PetscErrorCode SNESFASSetRScale(SNES, PetscInt, Vec); 1277 PETSC_EXTERN PetscErrorCode SNESFASGetRScale(SNES, PetscInt, Vec *); 1278 PETSC_EXTERN PetscErrorCode SNESFASSetContinuation(SNES, PetscBool); 1279 1280 PETSC_EXTERN PetscErrorCode SNESFASGetSmoother(SNES, PetscInt, SNES *); 1281 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherUp(SNES, PetscInt, SNES *); 1282 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherDown(SNES, PetscInt, SNES *); 1283 PETSC_EXTERN PetscErrorCode SNESFASGetCoarseSolve(SNES, SNES *); 1284 1285 /* parameters for full FAS */ 1286 PETSC_EXTERN PetscErrorCode SNESFASFullSetDownSweep(SNES, PetscBool); 1287 PETSC_EXTERN PetscErrorCode SNESFASCreateCoarseVec(SNES, Vec *); 1288 PETSC_EXTERN PetscErrorCode SNESFASRestrict(SNES, Vec, Vec); 1289 PETSC_EXTERN PetscErrorCode SNESFASFullSetTotal(SNES, PetscBool); 1290 PETSC_EXTERN PetscErrorCode SNESFASFullGetTotal(SNES, PetscBool *); 1291 1292 PETSC_EXTERN PetscErrorCode DMSNESCheckDiscretization(SNES, DM, PetscReal, Vec, PetscReal, PetscReal[]); 1293 PETSC_EXTERN PetscErrorCode DMSNESCheckResidual(SNES, DM, Vec, PetscReal, PetscReal *); 1294 PETSC_EXTERN PetscErrorCode DMSNESCheckJacobian(SNES, DM, Vec, PetscReal, PetscBool *, PetscReal *); 1295 PETSC_EXTERN PetscErrorCode DMSNESCheckFromOptions(SNES, Vec); 1296 PETSC_EXTERN PetscErrorCode DMSNESComputeJacobianAction(DM, Vec, Vec, Vec, void *); 1297 PETSC_EXTERN PetscErrorCode DMSNESCreateJacobianMF(DM, Vec, void *, Mat *); 1298 1299 PETSC_EXTERN PetscErrorCode SNESNewtonALSetFunction(SNES, SNESFunctionFn *, void *ctx); 1300 PETSC_EXTERN PetscErrorCode SNESNewtonALGetFunction(SNES, SNESFunctionFn **, void **ctx); 1301 PETSC_EXTERN PetscErrorCode SNESNewtonALComputeFunction(SNES, Vec, Vec); 1302 PETSC_EXTERN PetscErrorCode SNESNewtonALGetLoadParameter(SNES, PetscReal *); 1303 1304 /*MC 1305 SNESNewtonALCorrectionType - the approach used by `SNESNEWTONAL` to determine 1306 the correction to the current increment. While the exact correction satisfies 1307 the constraint surface at every iteration, it also requires solving a quadratic 1308 equation which may not have real roots. Conversely, the normal correction is more 1309 efficient and always yields a real correction and is the default. 1310 1311 Values: 1312 + `SNES_NEWTONAL_CORRECTION_EXACT` - choose the correction which exactly satisfies the constraint 1313 - `SNES_NEWTONAL_CORRECTION_NORMAL` - choose the correction in the updated normal hyper-surface to the constraint surface 1314 1315 Options Database Key: 1316 . -snes_newtonal_correction_type <exact> - select type from <exact,normal> 1317 1318 Level: intermediate 1319 1320 .seealso: `SNES`, `SNESNEWTONAL`, `SNESNewtonALSetCorrectionType()` 1321 M*/ 1322 typedef enum { 1323 SNES_NEWTONAL_CORRECTION_EXACT = 0, 1324 SNES_NEWTONAL_CORRECTION_NORMAL = 1, 1325 } SNESNewtonALCorrectionType; 1326 PETSC_EXTERN const char *const SNESNewtonALCorrectionTypes[]; 1327 1328 PETSC_EXTERN PetscErrorCode SNESNewtonALSetCorrectionType(SNES, SNESNewtonALCorrectionType); 1329