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. These are all the nonlinear solvers that PETSc provides. 16 17 Level: beginner 18 19 Note: 20 Use `SNESSetType()` or the options database key `-snes_type` to set the specific nonlinear solver algorithm to use with a given `SNES` object 21 22 .seealso: [](doc_nonlinsolve), [](ch_snes), `SNESSetType()`, `SNES`, `SNESCreate()`, `SNESDestroy()`, `SNESSetFromOptions()` 23 J*/ 24 typedef const char *SNESType; 25 #define SNESNEWTONLS "newtonls" 26 #define SNESNEWTONTR "newtontr" 27 #define SNESNEWTONTRDC "newtontrdc" 28 #define SNESPYTHON "python" 29 #define SNESNRICHARDSON "nrichardson" 30 #define SNESKSPONLY "ksponly" 31 #define SNESKSPTRANSPOSEONLY "ksptransposeonly" 32 #define SNESVINEWTONRSLS "vinewtonrsls" 33 #define SNESVINEWTONSSLS "vinewtonssls" 34 #define SNESNGMRES "ngmres" 35 #define SNESQN "qn" 36 #define SNESSHELL "shell" 37 #define SNESNGS "ngs" 38 #define SNESNCG "ncg" 39 #define SNESFAS "fas" 40 #define SNESMS "ms" 41 #define SNESNASM "nasm" 42 #define SNESANDERSON "anderson" 43 #define SNESASPIN "aspin" 44 #define SNESCOMPOSITE "composite" 45 #define SNESPATCH "patch" 46 #define SNESNEWTONAL "newtonal" 47 48 /* Logging support */ 49 PETSC_EXTERN PetscClassId SNES_CLASSID; 50 PETSC_EXTERN PetscClassId DMSNES_CLASSID; 51 52 PETSC_EXTERN PetscErrorCode SNESInitializePackage(void); 53 PETSC_EXTERN PetscErrorCode SNESFinalizePackage(void); 54 55 PETSC_EXTERN PetscErrorCode SNESCreate(MPI_Comm, SNES *); 56 PETSC_EXTERN PetscErrorCode SNESParametersInitialize(SNES); 57 PETSC_EXTERN PetscErrorCode SNESReset(SNES); 58 PETSC_EXTERN PetscErrorCode SNESDestroy(SNES *); 59 PETSC_EXTERN PetscErrorCode SNESSetType(SNES, SNESType); 60 PETSC_EXTERN PetscErrorCode SNESMonitor(SNES, PetscInt, PetscReal); 61 PETSC_EXTERN PetscErrorCode SNESMonitorSet(SNES, PetscErrorCode (*)(SNES, PetscInt, PetscReal, void *), void *, PetscErrorCode (*)(void **)); 62 PETSC_EXTERN PetscErrorCode SNESMonitorSetFromOptions(SNES, const char[], const char[], const char[], PetscErrorCode (*)(SNES, PetscInt, PetscReal, PetscViewerAndFormat *), PetscErrorCode (*)(SNES, PetscViewerAndFormat *)); 63 PETSC_EXTERN PetscErrorCode SNESMonitorCancel(SNES); 64 PETSC_EXTERN PetscErrorCode SNESMonitorSAWs(SNES, PetscInt, PetscReal, void *); 65 PETSC_EXTERN PetscErrorCode SNESMonitorSAWsCreate(SNES, void **); 66 PETSC_EXTERN PetscErrorCode SNESMonitorSAWsDestroy(void **); 67 PETSC_EXTERN PetscErrorCode SNESSetConvergenceHistory(SNES, PetscReal[], PetscInt[], PetscInt, PetscBool); 68 PETSC_EXTERN PetscErrorCode SNESGetConvergenceHistory(SNES, PetscReal *[], PetscInt *[], PetscInt *); 69 PETSC_EXTERN PetscErrorCode SNESSetUp(SNES); 70 PETSC_EXTERN PetscErrorCode SNESSolve(SNES, Vec, Vec); 71 PETSC_EXTERN PetscErrorCode SNESSetErrorIfNotConverged(SNES, PetscBool); 72 PETSC_EXTERN PetscErrorCode SNESGetErrorIfNotConverged(SNES, PetscBool *); 73 PETSC_EXTERN PetscErrorCode SNESConverged(SNES, PetscInt, PetscReal, PetscReal, PetscReal); 74 75 PETSC_EXTERN PetscErrorCode SNESSetWorkVecs(SNES, PetscInt); 76 77 PETSC_EXTERN PetscErrorCode SNESAddOptionsChecker(PetscErrorCode (*)(SNES)); 78 79 PETSC_EXTERN PetscErrorCode SNESRegister(const char[], PetscErrorCode (*)(SNES)); 80 81 PETSC_EXTERN PetscErrorCode SNESGetKSP(SNES, KSP *); 82 PETSC_EXTERN PetscErrorCode SNESSetKSP(SNES, KSP); 83 PETSC_EXTERN PetscErrorCode SNESSetSolution(SNES, Vec); 84 PETSC_EXTERN PetscErrorCode SNESGetSolution(SNES, Vec *); 85 PETSC_EXTERN PetscErrorCode SNESGetSolutionUpdate(SNES, Vec *); 86 PETSC_EXTERN PetscErrorCode SNESGetRhs(SNES, Vec *); 87 PETSC_EXTERN PetscErrorCode SNESView(SNES, PetscViewer); 88 PETSC_EXTERN PetscErrorCode SNESLoad(SNES, PetscViewer); 89 PETSC_EXTERN PetscErrorCode SNESConvergedReasonViewSet(SNES, PetscErrorCode (*)(SNES, void *), void *, PetscErrorCode (*)(void **)); 90 PETSC_EXTERN PetscErrorCode SNESViewFromOptions(SNES, PetscObject, const char[]); 91 PETSC_EXTERN PetscErrorCode SNESConvergedReasonView(SNES, PetscViewer); 92 PETSC_EXTERN PetscErrorCode SNESConvergedReasonViewFromOptions(SNES); 93 PETSC_EXTERN PetscErrorCode SNESConvergedReasonViewCancel(SNES); 94 95 PETSC_DEPRECATED_FUNCTION(3, 14, 0, "SNESConvergedReasonView()", ) static inline PetscErrorCode SNESReasonView(SNES snes, PetscViewer v) 96 { 97 return SNESConvergedReasonView(snes, v); 98 } 99 PETSC_DEPRECATED_FUNCTION(3, 14, 0, "SNESConvergedReasonViewFromOptions()", ) static inline PetscErrorCode SNESReasonViewFromOptions(SNES snes) 100 { 101 return SNESConvergedReasonViewFromOptions(snes); 102 } 103 104 #define SNES_FILE_CLASSID 1211224 105 106 PETSC_EXTERN PetscErrorCode SNESSetOptionsPrefix(SNES, const char[]); 107 PETSC_EXTERN PetscErrorCode SNESAppendOptionsPrefix(SNES, const char[]); 108 PETSC_EXTERN PetscErrorCode SNESGetOptionsPrefix(SNES, const char *[]); 109 PETSC_EXTERN PetscErrorCode SNESSetFromOptions(SNES); 110 PETSC_EXTERN PetscErrorCode SNESResetFromOptions(SNES); 111 112 PETSC_EXTERN PetscErrorCode SNESSetUseMatrixFree(SNES, PetscBool, PetscBool); 113 PETSC_EXTERN PetscErrorCode SNESGetUseMatrixFree(SNES, PetscBool *, PetscBool *); 114 PETSC_EXTERN PetscErrorCode MatCreateSNESMF(SNES, Mat *); 115 PETSC_EXTERN PetscErrorCode MatSNESMFGetSNES(Mat, SNES *); 116 PETSC_EXTERN PetscErrorCode MatSNESMFSetReuseBase(Mat, PetscBool); 117 PETSC_EXTERN PetscErrorCode MatSNESMFGetReuseBase(Mat, PetscBool *); 118 PETSC_EXTERN PetscErrorCode MatMFFDComputeJacobian(SNES, Vec, Mat, Mat, void *); 119 PETSC_EXTERN PetscErrorCode MatCreateSNESMFMore(SNES, Vec, Mat *); 120 PETSC_EXTERN PetscErrorCode MatSNESMFMoreSetParameters(Mat, PetscReal, PetscReal, PetscReal); 121 122 PETSC_EXTERN PetscErrorCode SNESGetType(SNES, SNESType *); 123 PETSC_EXTERN PetscErrorCode SNESMonitorDefaultSetUp(SNES, PetscViewerAndFormat *); 124 PETSC_EXTERN PetscErrorCode SNESMonitorDefault(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 125 PETSC_EXTERN PetscErrorCode SNESMonitorScaling(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 126 PETSC_EXTERN PetscErrorCode SNESMonitorRange(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 127 PETSC_EXTERN PetscErrorCode SNESMonitorRatio(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 128 PETSC_EXTERN PetscErrorCode SNESMonitorRatioSetUp(SNES, PetscViewerAndFormat *); 129 PETSC_EXTERN PetscErrorCode SNESMonitorSolution(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 130 PETSC_EXTERN PetscErrorCode SNESMonitorResidual(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 131 PETSC_EXTERN PetscErrorCode SNESMonitorSolutionUpdate(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 132 PETSC_EXTERN PetscErrorCode SNESMonitorDefaultShort(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 133 PETSC_EXTERN PetscErrorCode SNESMonitorDefaultField(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 134 PETSC_EXTERN PetscErrorCode SNESMonitorJacUpdateSpectrum(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 135 PETSC_EXTERN PetscErrorCode SNESMonitorFields(SNES, PetscInt, PetscReal, PetscViewerAndFormat *); 136 PETSC_EXTERN PetscErrorCode KSPMonitorSNESResidual(KSP, PetscInt, PetscReal, PetscViewerAndFormat *); 137 PETSC_EXTERN PetscErrorCode KSPMonitorSNESResidualDrawLG(KSP, PetscInt, PetscReal, PetscViewerAndFormat *); 138 PETSC_EXTERN PetscErrorCode KSPMonitorSNESResidualDrawLGCreate(PetscViewer, PetscViewerFormat, void *, PetscViewerAndFormat **); 139 140 PETSC_EXTERN PetscErrorCode SNESSetTolerances(SNES, PetscReal, PetscReal, PetscReal, PetscInt, PetscInt); 141 PETSC_EXTERN PetscErrorCode SNESSetDivergenceTolerance(SNES, PetscReal); 142 PETSC_EXTERN PetscErrorCode SNESGetTolerances(SNES, PetscReal *, PetscReal *, PetscReal *, PetscInt *, PetscInt *); 143 PETSC_EXTERN PetscErrorCode SNESGetDivergenceTolerance(SNES, PetscReal *); 144 PETSC_EXTERN PetscErrorCode SNESGetForceIteration(SNES, PetscBool *); 145 PETSC_EXTERN PetscErrorCode SNESSetForceIteration(SNES, PetscBool); 146 PETSC_EXTERN PetscErrorCode SNESGetIterationNumber(SNES, PetscInt *); 147 PETSC_EXTERN PetscErrorCode SNESSetIterationNumber(SNES, PetscInt); 148 149 /*E 150 SNESNewtonTRFallbackType - type of fallback in case the solution of the trust-region subproblem is outside of the radius 151 152 Values: 153 + `SNES_TR_FALLBACK_NEWTON` - use scaled Newton step 154 . `SNES_TR_FALLBACK_CAUCHY` - use Cauchy direction 155 - `SNES_TR_FALLBACK_DOGLEG` - use dogleg method 156 157 Level: intermediate 158 159 .seealso: [](ch_snes), `SNES`, `SNESNEWTONTR`, `SNESNEWTONTRDC` 160 E*/ 161 typedef enum { 162 SNES_TR_FALLBACK_NEWTON, 163 SNES_TR_FALLBACK_CAUCHY, 164 SNES_TR_FALLBACK_DOGLEG, 165 } SNESNewtonTRFallbackType; 166 167 PETSC_EXTERN const char *const SNESNewtonTRFallbackTypes[]; 168 169 PETSC_EXTERN PetscErrorCode SNESNewtonTRSetPreCheck(SNES, PetscErrorCode (*)(SNES, Vec, Vec, PetscBool *, void *), void *ctx); 170 PETSC_EXTERN PetscErrorCode SNESNewtonTRGetPreCheck(SNES, PetscErrorCode (**)(SNES, Vec, Vec, PetscBool *, void *), void **ctx); 171 PETSC_EXTERN PetscErrorCode SNESNewtonTRSetPostCheck(SNES, PetscErrorCode (*)(SNES, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void *ctx); 172 PETSC_EXTERN PetscErrorCode SNESNewtonTRGetPostCheck(SNES, PetscErrorCode (**)(SNES, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void **ctx); 173 PETSC_EXTERN PetscErrorCode SNESNewtonTRSetFallbackType(SNES, SNESNewtonTRFallbackType); 174 PETSC_EXTERN PetscErrorCode SNESNewtonTRPreCheck(SNES, Vec, Vec, PetscBool *); 175 PETSC_EXTERN PetscErrorCode SNESNewtonTRPostCheck(SNES, Vec, Vec, Vec, PetscBool *, PetscBool *); 176 PETSC_EXTERN PetscErrorCode SNESNewtonTRSetNormType(SNES, NormType); 177 178 /*E 179 SNESNewtonTRQNType - type of quasi-Newton model to use 180 181 Values: 182 + `SNES_TR_QN_NONE` - do not use a quasi-Newton model 183 . `SNES_TR_QN_SAME` - use the same quasi-Newton model for matrix and preconditioner 184 - `SNES_TR_QN_DIFFERENT` - use different quasi-Newton models for matrix and preconditioner 185 186 Level: intermediate 187 188 .seealso: [](ch_snes), `SNES`, `SNESNEWTONTR` 189 E*/ 190 typedef enum { 191 SNES_TR_QN_NONE, 192 SNES_TR_QN_SAME, 193 SNES_TR_QN_DIFFERENT, 194 } SNESNewtonTRQNType; 195 196 PETSC_EXTERN const char *const SNESNewtonTRQNTypes[]; 197 198 PETSC_EXTERN PetscErrorCode SNESNewtonTRSetQNType(SNES, SNESNewtonTRQNType); 199 200 PETSC_EXTERN PETSC_DEPRECATED_FUNCTION(3, 22, 0, "SNESNewtonTRSetTolerances()", ) PetscErrorCode SNESSetTrustRegionTolerance(SNES, PetscReal); 201 PETSC_EXTERN PetscErrorCode SNESNewtonTRSetTolerances(SNES, PetscReal, PetscReal, PetscReal); 202 PETSC_EXTERN PetscErrorCode SNESNewtonTRGetTolerances(SNES, PetscReal *, PetscReal *, PetscReal *); 203 PETSC_EXTERN PetscErrorCode SNESNewtonTRSetUpdateParameters(SNES, PetscReal, PetscReal, PetscReal, PetscReal, PetscReal); 204 PETSC_EXTERN PetscErrorCode SNESNewtonTRGetUpdateParameters(SNES, PetscReal *, PetscReal *, PetscReal *, PetscReal *, PetscReal *); 205 206 PETSC_EXTERN PetscErrorCode SNESNewtonTRDCGetRhoFlag(SNES, PetscBool *); 207 PETSC_EXTERN PetscErrorCode SNESNewtonTRDCSetPreCheck(SNES, PetscErrorCode (*)(SNES, Vec, Vec, PetscBool *, void *), void *ctx); 208 PETSC_EXTERN PetscErrorCode SNESNewtonTRDCGetPreCheck(SNES, PetscErrorCode (**)(SNES, Vec, Vec, PetscBool *, void *), void **ctx); 209 PETSC_EXTERN PetscErrorCode SNESNewtonTRDCSetPostCheck(SNES, PetscErrorCode (*)(SNES, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void *ctx); 210 PETSC_EXTERN PetscErrorCode SNESNewtonTRDCGetPostCheck(SNES, PetscErrorCode (**)(SNES, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void **ctx); 211 212 PETSC_EXTERN PetscErrorCode SNESGetNonlinearStepFailures(SNES, PetscInt *); 213 PETSC_EXTERN PetscErrorCode SNESSetMaxNonlinearStepFailures(SNES, PetscInt); 214 PETSC_EXTERN PetscErrorCode SNESGetMaxNonlinearStepFailures(SNES, PetscInt *); 215 PETSC_EXTERN PetscErrorCode SNESGetNumberFunctionEvals(SNES, PetscInt *); 216 217 PETSC_EXTERN PetscErrorCode SNESSetLagPreconditioner(SNES, PetscInt); 218 PETSC_EXTERN PetscErrorCode SNESGetLagPreconditioner(SNES, PetscInt *); 219 PETSC_EXTERN PetscErrorCode SNESSetLagJacobian(SNES, PetscInt); 220 PETSC_EXTERN PetscErrorCode SNESGetLagJacobian(SNES, PetscInt *); 221 PETSC_EXTERN PetscErrorCode SNESSetLagPreconditionerPersists(SNES, PetscBool); 222 PETSC_EXTERN PetscErrorCode SNESSetLagJacobianPersists(SNES, PetscBool); 223 PETSC_EXTERN PetscErrorCode SNESSetGridSequence(SNES, PetscInt); 224 PETSC_EXTERN PetscErrorCode SNESGetGridSequence(SNES, PetscInt *); 225 226 PETSC_EXTERN PetscErrorCode SNESGetLinearSolveIterations(SNES, PetscInt *); 227 PETSC_EXTERN PetscErrorCode SNESGetLinearSolveFailures(SNES, PetscInt *); 228 PETSC_EXTERN PetscErrorCode SNESSetMaxLinearSolveFailures(SNES, PetscInt); 229 PETSC_EXTERN PetscErrorCode SNESGetMaxLinearSolveFailures(SNES, PetscInt *); 230 PETSC_EXTERN PetscErrorCode SNESSetCountersReset(SNES, PetscBool); 231 PETSC_EXTERN PetscErrorCode SNESResetCounters(SNES); 232 233 PETSC_EXTERN PetscErrorCode SNESKSPSetUseEW(SNES, PetscBool); 234 PETSC_EXTERN PetscErrorCode SNESKSPGetUseEW(SNES, PetscBool *); 235 PETSC_EXTERN PetscErrorCode SNESKSPSetParametersEW(SNES, PetscInt, PetscReal, PetscReal, PetscReal, PetscReal, PetscReal, PetscReal); 236 PETSC_EXTERN PetscErrorCode SNESKSPGetParametersEW(SNES, PetscInt *, PetscReal *, PetscReal *, PetscReal *, PetscReal *, PetscReal *, PetscReal *); 237 238 #include <petscdrawtypes.h> 239 PETSC_EXTERN PetscErrorCode SNESMonitorLGRange(SNES, PetscInt, PetscReal, void *); 240 241 PETSC_EXTERN PetscErrorCode SNESSetApplicationContext(SNES, void *); 242 PETSC_EXTERN PetscErrorCode SNESGetApplicationContext(SNES, void *); 243 PETSC_EXTERN PetscErrorCode SNESSetComputeApplicationContext(SNES, PetscErrorCode (*)(SNES, void **), PetscErrorCode (*)(void **)); 244 245 PETSC_EXTERN PetscErrorCode SNESPythonSetType(SNES, const char[]); 246 PETSC_EXTERN PetscErrorCode SNESPythonGetType(SNES, const char *[]); 247 248 PETSC_EXTERN PetscErrorCode SNESSetFunctionDomainError(SNES); 249 PETSC_EXTERN PetscErrorCode SNESGetFunctionDomainError(SNES, PetscBool *); 250 PETSC_EXTERN PetscErrorCode SNESGetJacobianDomainError(SNES, PetscBool *); 251 PETSC_EXTERN PetscErrorCode SNESSetJacobianDomainError(SNES); 252 PETSC_EXTERN PetscErrorCode SNESSetCheckJacobianDomainError(SNES, PetscBool); 253 PETSC_EXTERN PetscErrorCode SNESGetCheckJacobianDomainError(SNES, PetscBool *); 254 255 #define SNES_CONVERGED_TR_DELTA_DEPRECATED SNES_CONVERGED_TR_DELTA PETSC_DEPRECATED_ENUM(3, 12, 0, "SNES_DIVERGED_TR_DELTA", ) 256 /*E 257 SNESConvergedReason - reason a `SNESSolve()` was determined to have converged or diverged 258 259 Values: 260 + `SNES_CONVERGED_FNORM_ABS` - 2-norm(F) <= abstol 261 . `SNES_CONVERGED_FNORM_RELATIVE` - 2-norm(F) <= rtol*2-norm(F(x_0)) where x_0 is the initial guess 262 . `SNES_CONVERGED_SNORM_RELATIVE` - The 2-norm of the last step <= stol * 2-norm(x) where x is the current 263 . `SNES_DIVERGED_FUNCTION_COUNT` - The user provided function has been called more times than the maximum set in `SNESSetTolerances()` 264 . `SNES_DIVERGED_DTOL` - The norm of the function has increased by a factor of divtol set with `SNESSetDivergenceTolerance()` 265 . `SNES_DIVERGED_FNORM_NAN` - the 2-norm of the current function evaluation is not-a-number (NaN), this 266 is usually caused by a division of 0 by 0. 267 . `SNES_DIVERGED_MAX_IT` - `SNESSolve()` has reached the maximum number of iterations requested 268 . `SNES_DIVERGED_LINE_SEARCH` - The line search has failed. This only occurs for `SNES` solvers that use a line search 269 . `SNES_DIVERGED_LOCAL_MIN` - the algorithm seems to have stagnated at a local minimum that is not zero. 270 - `SNES_CONERGED_ITERATING` - this only occurs if `SNESGetConvergedReason()` is called during the `SNESSolve()` 271 272 Level: beginner 273 274 Notes: 275 The two most common reasons for divergence are an incorrectly coded or computed Jacobian or failure or lack of convergence in the linear system 276 (in this case we recommend 277 testing with `-pc_type lu` to eliminate the linear solver as the cause of the problem). 278 279 `SNES_DIVERGED_LOCAL_MIN` can only occur when using a `SNES` solver that uses a line search (`SNESLineSearch`). 280 The line search wants to minimize Q(alpha) = 1/2 || F(x + alpha s) ||^2_2 this occurs 281 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 282 you get Q'(alpha) = -F(x)^T F'(x)^(-1)^T F'(x+alpha s)F(x+alpha s); when alpha = 0 283 Q'(0) = - ||F(x)||^2_2 which is always NEGATIVE if F'(x) is invertible. This means the Newton 284 direction is a descent direction and the line search should succeed if alpha is small enough. 285 286 If F'(x) is NOT invertible AND F'(x)^T F(x) = 0 then Q'(0) = 0 and the Newton direction 287 is NOT a descent direction so the line search will fail. All one can do at this point 288 is change the initial guess and try again. 289 290 An alternative explanation: Newton's method can be regarded as replacing the function with 291 its linear approximation and minimizing the 2-norm of that. That is F(x+s) approx F(x) + F'(x)s 292 so we minimize || F(x) + F'(x) s ||^2_2; do this using Least Squares. If F'(x) is invertible then 293 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 294 exists a nontrivial (that is F'(x)s != 0) solution to the equation and this direction is 295 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) 296 = - (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 297 and F'(x)^T F'(x) has no negative eigenvalues Q'(0) < 0 so s is a descent direction and the line 298 search should succeed for small enough alpha. 299 300 Note that this RARELY happens in practice. Far more likely the linear system is not being solved 301 (well enough?) or the Jacobian is wrong. 302 303 `SNES_DIVERGED_MAX_IT` means that the solver reached the maximum number of iterations without satisfying any 304 convergence criteria. `SNES_CONVERGED_ITS` means that `SNESConvergedSkip()` was chosen as the convergence test; 305 thus the usual convergence criteria have not been checked and may or may not be satisfied. 306 307 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `KSPConvergedReason`, `SNESSetConvergenceTest()`, `SNESSetTolerances()` 308 E*/ 309 typedef enum { /* converged */ 310 SNES_CONVERGED_FNORM_ABS = 2, /* ||F|| < atol */ 311 SNES_CONVERGED_FNORM_RELATIVE = 3, /* ||F|| < rtol*||F_initial|| */ 312 SNES_CONVERGED_SNORM_RELATIVE = 4, /* Newton computed step size small; || delta x || < stol || x ||*/ 313 SNES_CONVERGED_ITS = 5, /* maximum iterations reached */ 314 SNES_BREAKOUT_INNER_ITER = 6, /* Flag to break out of inner loop after checking custom convergence. */ 315 /* it is used in multi-phase flow when state changes */ 316 /* diverged */ 317 SNES_DIVERGED_FUNCTION_DOMAIN = -1, /* the new x location passed the function is not in the domain of F */ 318 SNES_DIVERGED_FUNCTION_COUNT = -2, 319 SNES_DIVERGED_LINEAR_SOLVE = -3, /* the linear solve failed */ 320 SNES_DIVERGED_FNORM_NAN = -4, 321 SNES_DIVERGED_MAX_IT = -5, 322 SNES_DIVERGED_LINE_SEARCH = -6, /* the line search failed */ 323 SNES_DIVERGED_INNER = -7, /* inner solve failed */ 324 SNES_DIVERGED_LOCAL_MIN = -8, /* || J^T b || is small, implies converged to local minimum of F() */ 325 SNES_DIVERGED_DTOL = -9, /* || F || > divtol*||F_initial|| */ 326 SNES_DIVERGED_JACOBIAN_DOMAIN = -10, /* Jacobian calculation does not make sense */ 327 SNES_DIVERGED_TR_DELTA = -11, 328 SNES_CONVERGED_TR_DELTA_DEPRECATED = -11, 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`. Provides all the linesearches for the nonlinear solvers, `SNES`, 708 in PETSc. 709 710 Values: 711 + `SNESLINESEARCHBASIC` - (or equivalently `SNESLINESEARCHNONE`) Simple damping line search, defaults to using the full Newton step 712 . `SNESLINESEARCHBT` - Backtracking line search over the L2 norm of the function 713 . `SNESLINESEARCHL2` - Secant line search over the L2 norm of the function 714 . `SNESLINESEARCHCP` - Critical point secant line search assuming $F(x) = \nabla G(x)$ for some unknown $G(x)$ 715 . `SNESLINESEARCHNLEQERR` - Affine-covariant error-oriented linesearch 716 - `SNESLINESEARCHSHELL` - User provided `SNESLineSearch` implementation 717 718 Level: beginner 719 720 Note: 721 Use `SNESLineSearchSetType()` or the options database key `-snes_linesearch_type` to set 722 the specific line search algorithm to use with a given `SNES` object. Not all `SNESType` can utilize a line search. 723 724 .seealso: [](ch_snes), `SNESLineSearch`, `SNESLineSearchSetType()`, `SNES` 725 J*/ 726 typedef const char *SNESLineSearchType; 727 #define SNESLINESEARCHBT "bt" 728 #define SNESLINESEARCHNLEQERR "nleqerr" 729 #define SNESLINESEARCHBASIC "basic" 730 #define SNESLINESEARCHNONE "none" 731 #define SNESLINESEARCHL2 "l2" 732 #define SNESLINESEARCHCP "cp" 733 #define SNESLINESEARCHSHELL "shell" 734 #define SNESLINESEARCHNCGLINEAR "ncglinear" 735 736 PETSC_EXTERN PetscFunctionList SNESList; 737 PETSC_EXTERN PetscClassId SNESLINESEARCH_CLASSID; 738 PETSC_EXTERN PetscFunctionList SNESLineSearchList; 739 740 #define SNES_LINESEARCH_ORDER_LINEAR 1 741 #define SNES_LINESEARCH_ORDER_QUADRATIC 2 742 #define SNES_LINESEARCH_ORDER_CUBIC 3 743 744 /*S 745 SNESLineSearchVIProjectFn - A prototype of a `SNES` function that projects a vector onto the VI bounds, passed to `SNESLineSearchSetVIFunctions()` 746 747 Calling Sequence: 748 + snes - `SNES` context 749 - u - the vector to project to the bounds 750 751 Level: advanced 752 753 Note: 754 The deprecated `SNESLineSearchVIProjectFunc` still works as a replacement for `SNESLineSearchVIProjectFn` *. 755 756 .seealso: [](ch_snes), `SNES`, `SNESLineSearch` 757 S*/ 758 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESLineSearchVIProjectFn)(SNES snes, Vec u); 759 PETSC_EXTERN_TYPEDEF typedef SNESLineSearchVIProjectFn *SNESLineSearchVIProjectFunc; // deprecated 760 761 /*S 762 SNESLineSearchVIProjectFn - A prototype of a `SNES` function that computes the norm of the active set variables in a vector in a VI solve, 763 passed to `SNESLineSearchSetVIFunctions()` 764 765 Calling Sequence: 766 + snes - `SNES` context 767 . f - the vector to compute the norm of 768 . u - the current solution, entries that are on the VI bounds are ignored 769 - fnorm - the resulting norm 770 771 Level: advanced 772 773 Note: 774 The deprecated `SNESLineSearchVINormFunc` still works as a replacement for `SNESLineSearchVINormFn` *. 775 776 .seealso: [](ch_snes), `SNES`, `SNESLineSearch` 777 S*/ 778 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESLineSearchVINormFn)(SNES snes, Vec f, Vec u, PetscReal *fnorm); 779 PETSC_EXTERN_TYPEDEF typedef SNESLineSearchVINormFn *SNESLineSearchVINormFunc; // deprecated 780 781 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESLineSearchApplyFn)(SNESLineSearch); 782 PETSC_EXTERN_TYPEDEF typedef SNESLineSearchApplyFn *SNESLineSearchApplyFunc; // deprecated 783 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(SNESLineSearchShellApplyFn)(SNESLineSearch, void *); 784 PETSC_EXTERN_TYPEDEF typedef SNESLineSearchShellApplyFn *SNESLineSearchUserFunc; // deprecated 785 786 PETSC_EXTERN PetscErrorCode SNESLineSearchCreate(MPI_Comm, SNESLineSearch *); 787 PETSC_EXTERN PetscErrorCode SNESLineSearchReset(SNESLineSearch); 788 PETSC_EXTERN PetscErrorCode SNESLineSearchView(SNESLineSearch, PetscViewer); 789 PETSC_EXTERN PetscErrorCode SNESLineSearchDestroy(SNESLineSearch *); 790 PETSC_EXTERN PetscErrorCode SNESLineSearchGetType(SNESLineSearch, SNESLineSearchType *); 791 PETSC_EXTERN PetscErrorCode SNESLineSearchSetType(SNESLineSearch, SNESLineSearchType); 792 PETSC_EXTERN PetscErrorCode SNESLineSearchSetFromOptions(SNESLineSearch); 793 PETSC_EXTERN PetscErrorCode SNESLineSearchSetFunction(SNESLineSearch, PetscErrorCode (*)(SNES, Vec, Vec)); 794 PETSC_EXTERN PetscErrorCode SNESLineSearchSetUp(SNESLineSearch); 795 PETSC_EXTERN PetscErrorCode SNESLineSearchApply(SNESLineSearch, Vec, Vec, PetscReal *, Vec); 796 PETSC_EXTERN PetscErrorCode SNESLineSearchPreCheck(SNESLineSearch, Vec, Vec, PetscBool *); 797 PETSC_EXTERN PetscErrorCode SNESLineSearchPostCheck(SNESLineSearch, Vec, Vec, Vec, PetscBool *, PetscBool *); 798 PETSC_EXTERN PetscErrorCode SNESLineSearchSetWorkVecs(SNESLineSearch, PetscInt); 799 800 /* set the functions for precheck and postcheck */ 801 802 PETSC_EXTERN PetscErrorCode SNESLineSearchSetPreCheck(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch, Vec, Vec, PetscBool *, void *), void *ctx); 803 PETSC_EXTERN PetscErrorCode SNESLineSearchSetPostCheck(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void *ctx); 804 805 PETSC_EXTERN PetscErrorCode SNESLineSearchGetPreCheck(SNESLineSearch, PetscErrorCode (**)(SNESLineSearch, Vec, Vec, PetscBool *, void *), void **ctx); 806 PETSC_EXTERN PetscErrorCode SNESLineSearchGetPostCheck(SNESLineSearch, PetscErrorCode (**)(SNESLineSearch, Vec, Vec, Vec, PetscBool *, PetscBool *, void *), void **ctx); 807 808 /* set the functions for VI-specific line search operations */ 809 810 PETSC_EXTERN PetscErrorCode SNESLineSearchSetVIFunctions(SNESLineSearch, SNESLineSearchVIProjectFn *, SNESLineSearchVINormFn *); 811 PETSC_EXTERN PetscErrorCode SNESLineSearchGetVIFunctions(SNESLineSearch, SNESLineSearchVIProjectFn **, SNESLineSearchVINormFn **); 812 813 /* pointers to the associated SNES in order to be able to get the function evaluation out */ 814 PETSC_EXTERN PetscErrorCode SNESLineSearchSetSNES(SNESLineSearch, SNES); 815 PETSC_EXTERN PetscErrorCode SNESLineSearchGetSNES(SNESLineSearch, SNES *); 816 817 /* set and get the parameters and vectors */ 818 PETSC_EXTERN PetscErrorCode SNESLineSearchGetTolerances(SNESLineSearch, PetscReal *, PetscReal *, PetscReal *, PetscReal *, PetscReal *, PetscInt *); 819 PETSC_EXTERN PetscErrorCode SNESLineSearchSetTolerances(SNESLineSearch, PetscReal, PetscReal, PetscReal, PetscReal, PetscReal, PetscInt); 820 821 PETSC_EXTERN PetscErrorCode SNESLineSearchPreCheckPicard(SNESLineSearch, Vec, Vec, PetscBool *, void *); 822 823 PETSC_EXTERN PetscErrorCode SNESLineSearchGetLambda(SNESLineSearch, PetscReal *); 824 PETSC_EXTERN PetscErrorCode SNESLineSearchSetLambda(SNESLineSearch, PetscReal); 825 826 PETSC_EXTERN PetscErrorCode SNESLineSearchGetDamping(SNESLineSearch, PetscReal *); 827 PETSC_EXTERN PetscErrorCode SNESLineSearchSetDamping(SNESLineSearch, PetscReal); 828 829 PETSC_EXTERN PetscErrorCode SNESLineSearchGetOrder(SNESLineSearch, PetscInt *order); 830 PETSC_EXTERN PetscErrorCode SNESLineSearchSetOrder(SNESLineSearch, PetscInt order); 831 832 /*E 833 SNESLineSearchReason - indication if the line search has succeeded or failed and why 834 835 Values: 836 + `SNES_LINESEARCH_SUCCEEDED` - the line search succeeded 837 . `SNES_LINESEARCH_FAILED_NANORINF` - a not a number of infinity appeared in the computions 838 . `SNES_LINESEARCH_FAILED_DOMAIN` - the function was evaluated outside of its domain, see `SNESSetFunctionDomainError()` and `SNESSetJacobianDomainError()` 839 . `SNES_LINESEARCH_FAILED_REDUCT` - the linear search failed to get the requested decrease in its norm or objective 840 . `SNES_LINESEARCH_FAILED_USER` - used by `SNESLINESEARCHNLEQERR` to indicate the user changed the search direction inappropriately 841 - `SNES_LINESEARCH_FAILED_FUNCTION` - indicates the maximum number of function evaluations allowed has been surpassed, `SNESConvergedReason` is also 842 set to `SNES_DIVERGED_FUNCTION_COUNT` 843 844 Level: intermediate 845 846 Developer Note: 847 Some of these reasons overlap with values of `SNESConvergedReason` 848 849 .seealso: [](ch_snes), `SNES`, `SNESSolve()`, `SNESGetConvergedReason()`, `KSPConvergedReason`, `SNESSetConvergenceTest()`, 850 `SNESSetFunctionDomainError()` and `SNESSetJacobianDomainError()` 851 E*/ 852 typedef enum { 853 SNES_LINESEARCH_SUCCEEDED, 854 SNES_LINESEARCH_FAILED_NANORINF, 855 SNES_LINESEARCH_FAILED_DOMAIN, 856 SNES_LINESEARCH_FAILED_REDUCT, /* INSUFFICIENT REDUCTION */ 857 SNES_LINESEARCH_FAILED_USER, 858 SNES_LINESEARCH_FAILED_FUNCTION 859 } SNESLineSearchReason; 860 861 PETSC_EXTERN PetscErrorCode SNESLineSearchGetReason(SNESLineSearch, SNESLineSearchReason *); 862 PETSC_EXTERN PetscErrorCode SNESLineSearchSetReason(SNESLineSearch, SNESLineSearchReason); 863 864 PETSC_EXTERN PetscErrorCode SNESLineSearchGetVecs(SNESLineSearch, Vec *, Vec *, Vec *, Vec *, Vec *); 865 PETSC_EXTERN PetscErrorCode SNESLineSearchSetVecs(SNESLineSearch, Vec, Vec, Vec, Vec, Vec); 866 867 PETSC_EXTERN PetscErrorCode SNESLineSearchGetNorms(SNESLineSearch, PetscReal *, PetscReal *, PetscReal *); 868 PETSC_EXTERN PetscErrorCode SNESLineSearchSetNorms(SNESLineSearch, PetscReal, PetscReal, PetscReal); 869 PETSC_EXTERN PetscErrorCode SNESLineSearchComputeNorms(SNESLineSearch); 870 PETSC_EXTERN PetscErrorCode SNESLineSearchSetComputeNorms(SNESLineSearch, PetscBool); 871 872 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitor(SNESLineSearch); 873 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSet(SNESLineSearch, PetscErrorCode (*)(SNESLineSearch, void *), void *, PetscErrorCode (*)(void **)); 874 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSetFromOptions(SNESLineSearch, const char[], const char[], const char[], PetscErrorCode (*)(SNESLineSearch, PetscViewerAndFormat *), PetscErrorCode (*)(SNESLineSearch, PetscViewerAndFormat *)); 875 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorCancel(SNESLineSearch); 876 PETSC_EXTERN PetscErrorCode SNESLineSearchSetDefaultMonitor(SNESLineSearch, PetscViewer); 877 PETSC_EXTERN PetscErrorCode SNESLineSearchGetDefaultMonitor(SNESLineSearch, PetscViewer *); 878 PETSC_EXTERN PetscErrorCode SNESLineSearchMonitorSolutionUpdate(SNESLineSearch, PetscViewerAndFormat *); 879 880 PETSC_EXTERN PetscErrorCode SNESLineSearchAppendOptionsPrefix(SNESLineSearch, const char prefix[]); 881 PETSC_EXTERN PetscErrorCode SNESLineSearchGetOptionsPrefix(SNESLineSearch, const char *prefix[]); 882 883 /* Shell interface functions */ 884 PETSC_EXTERN PetscErrorCode SNESLineSearchShellSetApply(SNESLineSearch, SNESLineSearchShellApplyFn, void *); 885 PETSC_EXTERN PetscErrorCode SNESLineSearchShellGetApply(SNESLineSearch, SNESLineSearchShellApplyFn **, void **); 886 887 PETSC_DEPRECATED_FUNCTION(3, 21, 0, "SNESLinesearchShellSetApply()", ) static inline PetscErrorCode SNESLineSearchShellSetUserFunc(SNESLineSearch ls, SNESLineSearchUserFunc f, void *ctx) 888 { 889 return SNESLineSearchShellSetApply(ls, f, ctx); 890 } 891 892 PETSC_DEPRECATED_FUNCTION(3, 21, 0, "SNESLinesearchShellGetApply()", ) static inline PetscErrorCode SNESLineSearchShellGetUserFunc(SNESLineSearch ls, SNESLineSearchUserFunc *f, void **ctx) 893 { 894 return SNESLineSearchShellGetApply(ls, f, ctx); 895 } 896 897 /* BT interface functions */ 898 PETSC_EXTERN PetscErrorCode SNESLineSearchBTSetAlpha(SNESLineSearch, PetscReal); 899 PETSC_EXTERN PetscErrorCode SNESLineSearchBTGetAlpha(SNESLineSearch, PetscReal *); 900 901 /*register line search types */ 902 PETSC_EXTERN PetscErrorCode SNESLineSearchRegister(const char[], PetscErrorCode (*)(SNESLineSearch)); 903 904 /* Routines for VI solver */ 905 PETSC_EXTERN PetscErrorCode SNESVISetVariableBounds(SNES, Vec, Vec); 906 PETSC_EXTERN PetscErrorCode SNESVIGetVariableBounds(SNES, Vec *, Vec *); 907 PETSC_EXTERN PetscErrorCode SNESVISetComputeVariableBounds(SNES, PetscErrorCode (*)(SNES, Vec, Vec)); 908 PETSC_EXTERN PetscErrorCode SNESVIGetInactiveSet(SNES, IS *); 909 PETSC_EXTERN PetscErrorCode SNESVIGetActiveSetIS(SNES, Vec, Vec, IS *); 910 PETSC_EXTERN PetscErrorCode SNESVIComputeInactiveSetFnorm(SNES, Vec, Vec, PetscReal *); 911 PETSC_EXTERN PetscErrorCode SNESVISetRedundancyCheck(SNES, PetscErrorCode (*)(SNES, IS, IS *, void *), void *); 912 PETSC_EXTERN PetscErrorCode SNESVIComputeMeritFunction(Vec, PetscReal *, PetscReal *); 913 PETSC_EXTERN PetscErrorCode SNESVIComputeFunction(SNES, Vec, Vec, void *); 914 PETSC_EXTERN PetscErrorCode DMSetVI(DM, IS); 915 PETSC_EXTERN PetscErrorCode DMDestroyVI(DM); 916 917 PETSC_EXTERN PetscErrorCode SNESTestLocalMin(SNES); 918 919 /* Should this routine be private? */ 920 PETSC_EXTERN PetscErrorCode SNESComputeJacobian(SNES, Vec, Mat, Mat); 921 PETSC_EXTERN PetscErrorCode SNESTestJacobian(SNES); 922 PETSC_EXTERN PetscErrorCode SNESTestFunction(SNES); 923 924 PETSC_EXTERN PetscErrorCode SNESSetDM(SNES, DM); 925 PETSC_EXTERN PetscErrorCode SNESGetDM(SNES, DM *); 926 PETSC_EXTERN PetscErrorCode SNESSetNPC(SNES, SNES); 927 PETSC_EXTERN PetscErrorCode SNESGetNPC(SNES, SNES *); 928 PETSC_EXTERN PetscErrorCode SNESHasNPC(SNES, PetscBool *); 929 PETSC_EXTERN PetscErrorCode SNESApplyNPC(SNES, Vec, Vec, Vec); 930 PETSC_EXTERN PetscErrorCode SNESGetNPCFunction(SNES, Vec, PetscReal *); 931 PETSC_EXTERN PetscErrorCode SNESComputeFunctionDefaultNPC(SNES, Vec, Vec); 932 PETSC_EXTERN PetscErrorCode SNESSetNPCSide(SNES, PCSide); 933 PETSC_EXTERN PetscErrorCode SNESGetNPCSide(SNES, PCSide *); 934 PETSC_EXTERN PetscErrorCode SNESSetLineSearch(SNES, SNESLineSearch); 935 PETSC_EXTERN PetscErrorCode SNESGetLineSearch(SNES, SNESLineSearch *); 936 937 PETSC_DEPRECATED_FUNCTION(3, 4, 0, "SNESGetLineSearch()", ) static inline PetscErrorCode SNESGetSNESLineSearch(SNES snes, SNESLineSearch *ls) 938 { 939 return SNESGetLineSearch(snes, ls); 940 } 941 PETSC_DEPRECATED_FUNCTION(3, 4, 0, "SNESSetLineSearch()", ) static inline PetscErrorCode SNESSetSNESLineSearch(SNES snes, SNESLineSearch ls) 942 { 943 return SNESSetLineSearch(snes, ls); 944 } 945 946 PETSC_EXTERN PetscErrorCode SNESSetUpMatrices(SNES); 947 PETSC_EXTERN PetscErrorCode DMSNESSetFunction(DM, SNESFunctionFn *, void *); 948 PETSC_EXTERN PetscErrorCode DMSNESGetFunction(DM, SNESFunctionFn **, void **); 949 PETSC_EXTERN PetscErrorCode DMSNESSetFunctionContextDestroy(DM, PetscErrorCode (*)(void *)); 950 PETSC_EXTERN PetscErrorCode DMSNESSetMFFunction(DM, SNESFunctionFn *, void *); 951 PETSC_EXTERN PetscErrorCode DMSNESSetNGS(DM, SNESNGSFn *, void *); 952 PETSC_EXTERN PetscErrorCode DMSNESGetNGS(DM, SNESNGSFn **, void **); 953 PETSC_EXTERN PetscErrorCode DMSNESSetJacobian(DM, SNESJacobianFn *, void *); 954 PETSC_EXTERN PetscErrorCode DMSNESGetJacobian(DM, SNESJacobianFn **, void **); 955 PETSC_EXTERN PetscErrorCode DMSNESSetJacobianContextDestroy(DM, PetscErrorCode (*)(void *)); 956 PETSC_EXTERN PetscErrorCode DMSNESSetPicard(DM, SNESFunctionFn *, SNESJacobianFn *, void *); 957 PETSC_EXTERN PetscErrorCode DMSNESGetPicard(DM, SNESFunctionFn **, SNESJacobianFn **, void **); 958 PETSC_EXTERN PetscErrorCode DMSNESSetObjective(DM, SNESObjectiveFn *, void *); 959 PETSC_EXTERN PetscErrorCode DMSNESGetObjective(DM, SNESObjectiveFn **, void **); 960 PETSC_EXTERN PetscErrorCode DMCopyDMSNES(DM, DM); 961 962 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESFunctionFn)(DMDALocalInfo *, void *, void *, void *); 963 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESJacobianFn)(DMDALocalInfo *, void *, Mat, Mat, void *); 964 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESObjectiveFn)(DMDALocalInfo *, void *, PetscReal *, void *); 965 966 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESFunctionVecFn)(DMDALocalInfo *, Vec, Vec, void *); 967 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESJacobianVecFn)(DMDALocalInfo *, Vec, Mat, Mat, void *); 968 PETSC_EXTERN_TYPEDEF typedef PetscErrorCode(DMDASNESObjectiveVecFn)(DMDALocalInfo *, Vec, PetscReal *, void *); 969 970 PETSC_EXTERN PetscErrorCode DMDASNESSetFunctionLocal(DM, InsertMode, DMDASNESFunctionFn *, void *); 971 PETSC_EXTERN PetscErrorCode DMDASNESSetJacobianLocal(DM, DMDASNESJacobianFn *, void *); 972 PETSC_EXTERN PetscErrorCode DMDASNESSetObjectiveLocal(DM, DMDASNESObjectiveFn *, void *); 973 PETSC_EXTERN PetscErrorCode DMDASNESSetPicardLocal(DM, InsertMode, DMDASNESFunctionFn *, DMDASNESJacobianFn, void *); 974 975 PETSC_EXTERN PetscErrorCode DMDASNESSetFunctionLocalVec(DM, InsertMode, DMDASNESFunctionVecFn *, void *); 976 PETSC_EXTERN PetscErrorCode DMDASNESSetJacobianLocalVec(DM, DMDASNESJacobianVecFn *, void *); 977 PETSC_EXTERN PetscErrorCode DMDASNESSetObjectiveLocalVec(DM, DMDASNESObjectiveVecFn *, void *); 978 979 PETSC_EXTERN PetscErrorCode DMSNESSetBoundaryLocal(DM, PetscErrorCode (*)(DM, Vec, void *), void *); 980 PETSC_EXTERN PetscErrorCode DMSNESSetObjectiveLocal(DM, PetscErrorCode (*)(DM, Vec, PetscReal *, void *), void *); 981 PETSC_EXTERN PetscErrorCode DMSNESSetFunctionLocal(DM, PetscErrorCode (*)(DM, Vec, Vec, void *), void *); 982 PETSC_EXTERN PetscErrorCode DMSNESSetJacobianLocal(DM, PetscErrorCode (*)(DM, Vec, Mat, Mat, void *), void *); 983 PETSC_EXTERN PetscErrorCode DMSNESGetBoundaryLocal(DM, PetscErrorCode (**)(DM, Vec, void *), void **); 984 PETSC_EXTERN PetscErrorCode DMSNESGetObjectiveLocal(DM, PetscErrorCode (**)(DM, Vec, PetscReal *, void *), void **); 985 PETSC_EXTERN PetscErrorCode DMSNESGetFunctionLocal(DM, PetscErrorCode (**)(DM, Vec, Vec, void *), void **); 986 PETSC_EXTERN PetscErrorCode DMSNESGetJacobianLocal(DM, PetscErrorCode (**)(DM, Vec, Mat, Mat, void *), void **); 987 988 /* Routines for Multiblock solver */ 989 PETSC_EXTERN PetscErrorCode SNESMultiblockSetFields(SNES, const char[], PetscInt, const PetscInt *); 990 PETSC_EXTERN PetscErrorCode SNESMultiblockSetIS(SNES, const char[], IS); 991 PETSC_EXTERN PetscErrorCode SNESMultiblockSetBlockSize(SNES, PetscInt); 992 PETSC_EXTERN PetscErrorCode SNESMultiblockSetType(SNES, PCCompositeType); 993 PETSC_EXTERN PetscErrorCode SNESMultiblockGetSubSNES(SNES, PetscInt *, SNES *[]); 994 995 /*J 996 SNESMSType - String with the name of a PETSc `SNESMS` method. 997 998 Level: intermediate 999 1000 .seealso: [](ch_snes), `SNESMS`, `SNESMSGetType()`, `SNESMSSetType()`, `SNES` 1001 J*/ 1002 typedef const char *SNESMSType; 1003 #define SNESMSM62 "m62" 1004 #define SNESMSEULER "euler" 1005 #define SNESMSJAMESON83 "jameson83" 1006 #define SNESMSVLTP11 "vltp11" 1007 #define SNESMSVLTP21 "vltp21" 1008 #define SNESMSVLTP31 "vltp31" 1009 #define SNESMSVLTP41 "vltp41" 1010 #define SNESMSVLTP51 "vltp51" 1011 #define SNESMSVLTP61 "vltp61" 1012 1013 PETSC_EXTERN PetscErrorCode SNESMSRegister(SNESMSType, PetscInt, PetscInt, PetscReal, const PetscReal[], const PetscReal[], const PetscReal[]); 1014 PETSC_EXTERN PetscErrorCode SNESMSRegisterAll(void); 1015 PETSC_EXTERN PetscErrorCode SNESMSGetType(SNES, SNESMSType *); 1016 PETSC_EXTERN PetscErrorCode SNESMSSetType(SNES, SNESMSType); 1017 PETSC_EXTERN PetscErrorCode SNESMSGetDamping(SNES, PetscReal *); 1018 PETSC_EXTERN PetscErrorCode SNESMSSetDamping(SNES, PetscReal); 1019 PETSC_EXTERN PetscErrorCode SNESMSFinalizePackage(void); 1020 PETSC_EXTERN PetscErrorCode SNESMSInitializePackage(void); 1021 PETSC_EXTERN PetscErrorCode SNESMSRegisterDestroy(void); 1022 1023 /*MC 1024 SNESNGMRESRestartType - the restart approach used by `SNESNGMRES` 1025 1026 Values: 1027 + `SNES_NGMRES_RESTART_NONE` - never restart 1028 . `SNES_NGMRES_RESTART_DIFFERENCE` - restart based upon difference criteria 1029 - `SNES_NGMRES_RESTART_PERIODIC` - restart after a fixed number of iterations 1030 1031 Options Database Keys: 1032 + -snes_ngmres_restart_type <difference,periodic,none> - set the restart type 1033 - -snes_ngmres_restart <30> - sets the number of iterations before restart for periodic 1034 1035 Level: intermediate 1036 1037 .seealso: `SNES, `SNESNGMRES`, `SNESNGMRESSetSelectType()`, `SNESNGMRESGetSelectType()`, `SNESNGMRESSetRestartType()`, 1038 `SNESNGMRESGetRestartType()`, `SNESNGMRESSelectType` 1039 M*/ 1040 typedef enum { 1041 SNES_NGMRES_RESTART_NONE = 0, 1042 SNES_NGMRES_RESTART_PERIODIC = 1, 1043 SNES_NGMRES_RESTART_DIFFERENCE = 2 1044 } SNESNGMRESRestartType; 1045 PETSC_EXTERN const char *const SNESNGMRESRestartTypes[]; 1046 1047 /*MC 1048 SNESNGMRESSelectType - the approach used by `SNESNGMRES` to determine how the candidate solution and 1049 combined solution are used to create the next iterate. 1050 1051 Values: 1052 + `SNES_NGMRES_SELECT_NONE` - choose the combined solution all the time 1053 . `SNES_NGMRES_SELECT_DIFFERENCE` - choose based upon the selection criteria 1054 - `SNES_NGMRES_SELECT_LINESEARCH` - choose based upon line search combination 1055 1056 Options Database Key: 1057 . -snes_ngmres_select_type<difference,none,linesearch> - select type 1058 1059 Level: intermediate 1060 1061 .seealso: `SNES, `SNESNGMRES`, `SNESNGMRESSetSelectType()`, `SNESNGMRESGetSelectType()`, `SNESNGMRESSetRestartType()`, 1062 `SNESNGMRESGetRestartType()`, `SNESNGMRESRestartType` 1063 M*/ 1064 typedef enum { 1065 SNES_NGMRES_SELECT_NONE = 0, 1066 SNES_NGMRES_SELECT_DIFFERENCE = 1, 1067 SNES_NGMRES_SELECT_LINESEARCH = 2 1068 } SNESNGMRESSelectType; 1069 PETSC_EXTERN const char *const SNESNGMRESSelectTypes[]; 1070 1071 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartType(SNES, SNESNGMRESRestartType); 1072 PETSC_EXTERN PetscErrorCode SNESNGMRESSetSelectType(SNES, SNESNGMRESSelectType); 1073 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartFmRise(SNES, PetscBool); 1074 PETSC_EXTERN PetscErrorCode SNESNGMRESGetRestartFmRise(SNES, PetscBool *); 1075 1076 /*MC 1077 SNESNCGType - the conjugate update approach for `SNESNCG` 1078 1079 Values: 1080 + `SNES_NCG_FR` - Fletcher-Reeves update 1081 . `SNES_NCG_PRP` - Polak-Ribiere-Polyak update, the default and the only one that tolerates generalized search directions 1082 . `SNES_NCG_HS` - Hestenes-Steifel update 1083 . `SNES_NCG_DY` - Dai-Yuan update 1084 - `SNES_NCG_CD` - Conjugate Descent update 1085 1086 Options Database Key: 1087 . -snes_ncg_type<fr,prp,hs,dy,cd> - select type 1088 1089 Level: intermediate 1090 1091 .seealso: `SNES, `SNESNCG`, `SNESNCGSetType()` 1092 M*/ 1093 typedef enum { 1094 SNES_NCG_FR = 0, 1095 SNES_NCG_PRP = 1, 1096 SNES_NCG_HS = 2, 1097 SNES_NCG_DY = 3, 1098 SNES_NCG_CD = 4 1099 } SNESNCGType; 1100 PETSC_EXTERN const char *const SNESNCGTypes[]; 1101 1102 PETSC_EXTERN PetscErrorCode SNESNCGSetType(SNES, SNESNCGType); 1103 1104 /*MC 1105 SNESQNScaleType - the scaling type used by `SNESQN` 1106 1107 Values: 1108 + `SNES_QN_SCALE_NONE` - don't scale the problem 1109 . `SNES_QN_SCALE_SCALAR` - use Shanno scaling 1110 . `SNES_QN_SCALE_DIAGONAL` - scale with a diagonalized BFGS formula (see Gilbert and Lemarechal 1989), available 1111 - `SNES_QN_SCALE_JACOBIAN` - scale by solving a linear system coming from the Jacobian you provided with `SNESSetJacobian()` 1112 computed at the first iteration of `SNESQN` and at ever restart. 1113 1114 Options Database Key: 1115 . -snes_qn_scale_type <diagonal,none,scalar,jacobian> - Scaling type 1116 1117 Level: intermediate 1118 1119 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNType`, `SNESQNSetType()`, `SNESQNSetRestartType()`, `SNESQNRestartType` 1120 M*/ 1121 typedef enum { 1122 SNES_QN_SCALE_DEFAULT = 0, 1123 SNES_QN_SCALE_NONE = 1, 1124 SNES_QN_SCALE_SCALAR = 2, 1125 SNES_QN_SCALE_DIAGONAL = 3, 1126 SNES_QN_SCALE_JACOBIAN = 4 1127 } SNESQNScaleType; 1128 PETSC_EXTERN const char *const SNESQNScaleTypes[]; 1129 1130 /*MC 1131 SNESQNRestartType - the restart approached used by `SNESQN` 1132 1133 Values: 1134 + `SNES_QN_RESTART_NONE` - never restart 1135 . `SNES_QN_RESTART_POWELL` - restart based upon descent criteria 1136 - `SNES_QN_RESTART_PERIODIC` - restart after a fixed number of iterations 1137 1138 Options Database Keys: 1139 + -snes_qn_restart_type <powell,periodic,none> - set the restart type 1140 - -snes_qn_m <m> - sets the number of stored updates and the restart period for periodic 1141 1142 Level: intermediate 1143 1144 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNType`, `SNESQNSetType()`, `SNESQNSetRestartType()`, `SNESQNScaleType` 1145 M*/ 1146 typedef enum { 1147 SNES_QN_RESTART_DEFAULT = 0, 1148 SNES_QN_RESTART_NONE = 1, 1149 SNES_QN_RESTART_POWELL = 2, 1150 SNES_QN_RESTART_PERIODIC = 3 1151 } SNESQNRestartType; 1152 PETSC_EXTERN const char *const SNESQNRestartTypes[]; 1153 1154 /*MC 1155 SNESQNType - the type used by `SNESQN` 1156 1157 Values: 1158 + `SNES_QN_LBFGS` - LBFGS variant 1159 . `SNES_QN_BROYDEN` - Broyden variant 1160 - `SNES_QN_BADBROYDEN` - Bad Broyden variant 1161 1162 Options Database Key: 1163 . -snes_qn_type <lbfgs,broyden,badbroyden> - quasi-Newton type 1164 1165 Level: intermediate 1166 1167 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNSetType()`, `SNESQNScaleType`, `SNESQNRestartType`, `SNESQNSetRestartType()` 1168 M*/ 1169 typedef enum { 1170 SNES_QN_LBFGS = 0, 1171 SNES_QN_BROYDEN = 1, 1172 SNES_QN_BADBROYDEN = 2 1173 } SNESQNType; 1174 PETSC_EXTERN const char *const SNESQNTypes[]; 1175 1176 PETSC_EXTERN PetscErrorCode SNESQNSetType(SNES, SNESQNType); 1177 PETSC_EXTERN PetscErrorCode SNESQNSetScaleType(SNES, SNESQNScaleType); 1178 PETSC_EXTERN PetscErrorCode SNESQNSetRestartType(SNES, SNESQNRestartType); 1179 1180 PETSC_EXTERN PetscErrorCode SNESNASMGetType(SNES, PCASMType *); 1181 PETSC_EXTERN PetscErrorCode SNESNASMSetType(SNES, PCASMType); 1182 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomains(SNES, PetscInt *, SNES **, VecScatter **, VecScatter **, VecScatter **); 1183 PETSC_EXTERN PetscErrorCode SNESNASMSetSubdomains(SNES, PetscInt, SNES *, VecScatter *, VecScatter *, VecScatter *); 1184 PETSC_EXTERN PetscErrorCode SNESNASMSetDamping(SNES, PetscReal); 1185 PETSC_EXTERN PetscErrorCode SNESNASMGetDamping(SNES, PetscReal *); 1186 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomainVecs(SNES, PetscInt *, Vec **, Vec **, Vec **, Vec **); 1187 PETSC_EXTERN PetscErrorCode SNESNASMSetComputeFinalJacobian(SNES, PetscBool); 1188 PETSC_EXTERN PetscErrorCode SNESNASMGetSNES(SNES, PetscInt, SNES *); 1189 PETSC_EXTERN PetscErrorCode SNESNASMGetNumber(SNES, PetscInt *); 1190 PETSC_EXTERN PetscErrorCode SNESNASMSetWeight(SNES, Vec); 1191 1192 /*E 1193 SNESCompositeType - Determines how two or more preconditioners are composed with the `SNESType` of `SNESCOMPOSITE` 1194 1195 Values: 1196 + `SNES_COMPOSITE_ADDITIVE` - results from application of all preconditioners are added together 1197 . `SNES_COMPOSITE_MULTIPLICATIVE` - preconditioners are applied sequentially to the residual freshly 1198 computed after the previous preconditioner application 1199 - `SNES_COMPOSITE_ADDITIVEOPTIMAL` - uses a linear combination of the solutions obtained with each preconditioner that approximately minimize the function 1200 value at the new iteration. 1201 1202 Level: beginner 1203 1204 .seealso: [](sec_pc), `PCCOMPOSITE`, `PCFIELDSPLIT`, `PC`, `PCCompositeSetType()`, `PCCompositeType` 1205 E*/ 1206 typedef enum { 1207 SNES_COMPOSITE_ADDITIVE, 1208 SNES_COMPOSITE_MULTIPLICATIVE, 1209 SNES_COMPOSITE_ADDITIVEOPTIMAL 1210 } SNESCompositeType; 1211 PETSC_EXTERN const char *const SNESCompositeTypes[]; 1212 1213 PETSC_EXTERN PetscErrorCode SNESCompositeSetType(SNES, SNESCompositeType); 1214 PETSC_EXTERN PetscErrorCode SNESCompositeAddSNES(SNES, SNESType); 1215 PETSC_EXTERN PetscErrorCode SNESCompositeGetSNES(SNES, PetscInt, SNES *); 1216 PETSC_EXTERN PetscErrorCode SNESCompositeGetNumber(SNES, PetscInt *); 1217 PETSC_EXTERN PetscErrorCode SNESCompositeSetDamping(SNES, PetscInt, PetscReal); 1218 1219 PETSC_EXTERN PetscErrorCode SNESPatchSetDiscretisationInfo(SNES, PetscInt, DM *, PetscInt *, PetscInt *, const PetscInt **, const PetscInt *, PetscInt, const PetscInt *, PetscInt, const PetscInt *); 1220 PETSC_EXTERN PetscErrorCode SNESPatchSetComputeOperator(SNES, PetscErrorCode (*func)(PC, PetscInt, Vec, Mat, IS, PetscInt, const PetscInt *, const PetscInt *, void *), void *); 1221 PETSC_EXTERN PetscErrorCode SNESPatchSetComputeFunction(SNES, PetscErrorCode (*func)(PC, PetscInt, Vec, Vec, IS, PetscInt, const PetscInt *, const PetscInt *, void *), void *); 1222 PETSC_EXTERN PetscErrorCode SNESPatchSetConstructType(SNES, PCPatchConstructType, PetscErrorCode (*func)(PC, PetscInt *, IS **, IS *, void *), void *); 1223 PETSC_EXTERN PetscErrorCode SNESPatchSetCellNumbering(SNES, PetscSection); 1224 1225 /*E 1226 SNESFASType - Determines the type of nonlinear multigrid method that is run. 1227 1228 Values: 1229 + `SNES_FAS_MULTIPLICATIVE` (default) - traditional V or W cycle as determined by `SNESFASSetCycles()` 1230 . `SNES_FAS_ADDITIVE` - additive FAS cycle 1231 . `SNES_FAS_FULL` - full FAS cycle 1232 - `SNES_FAS_KASKADE` - Kaskade FAS cycle 1233 1234 Level: beginner 1235 1236 .seealso: [](ch_snes), `SNESFAS`, `PCMGSetType()`, `PCMGType` 1237 E*/ 1238 typedef enum { 1239 SNES_FAS_MULTIPLICATIVE, 1240 SNES_FAS_ADDITIVE, 1241 SNES_FAS_FULL, 1242 SNES_FAS_KASKADE 1243 } SNESFASType; 1244 PETSC_EXTERN const char *const SNESFASTypes[]; 1245 1246 /* called on the finest level FAS instance*/ 1247 PETSC_EXTERN PetscErrorCode SNESFASSetType(SNES, SNESFASType); 1248 PETSC_EXTERN PetscErrorCode SNESFASGetType(SNES, SNESFASType *); 1249 PETSC_EXTERN PetscErrorCode SNESFASSetLevels(SNES, PetscInt, MPI_Comm *); 1250 PETSC_EXTERN PetscErrorCode SNESFASGetLevels(SNES, PetscInt *); 1251 PETSC_EXTERN PetscErrorCode SNESFASGetCycleSNES(SNES, PetscInt, SNES *); 1252 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothUp(SNES, PetscInt); 1253 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothDown(SNES, PetscInt); 1254 PETSC_EXTERN PetscErrorCode SNESFASSetCycles(SNES, PetscInt); 1255 PETSC_EXTERN PetscErrorCode SNESFASSetMonitor(SNES, PetscViewerAndFormat *, PetscBool); 1256 PETSC_EXTERN PetscErrorCode SNESFASSetLog(SNES, PetscBool); 1257 1258 PETSC_EXTERN PetscErrorCode SNESFASSetGalerkin(SNES, PetscBool); 1259 PETSC_EXTERN PetscErrorCode SNESFASGetGalerkin(SNES, PetscBool *); 1260 PETSC_EXTERN PetscErrorCode SNESFASGalerkinFunctionDefault(SNES, Vec, Vec, void *); 1261 1262 /* called on any level -- "Cycle" FAS instance */ 1263 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmoother(SNES, SNES *); 1264 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherUp(SNES, SNES *); 1265 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherDown(SNES, SNES *); 1266 PETSC_EXTERN PetscErrorCode SNESFASCycleGetCorrection(SNES, SNES *); 1267 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInterpolation(SNES, Mat *); 1268 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRestriction(SNES, Mat *); 1269 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInjection(SNES, Mat *); 1270 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRScale(SNES, Vec *); 1271 PETSC_EXTERN PetscErrorCode SNESFASCycleSetCycles(SNES, PetscInt); 1272 PETSC_EXTERN PetscErrorCode SNESFASCycleIsFine(SNES, PetscBool *); 1273 1274 /* called on the (outer) finest level FAS to set/get parameters on any level instance */ 1275 PETSC_EXTERN PetscErrorCode SNESFASSetInterpolation(SNES, PetscInt, Mat); 1276 PETSC_EXTERN PetscErrorCode SNESFASGetInterpolation(SNES, PetscInt, Mat *); 1277 PETSC_EXTERN PetscErrorCode SNESFASSetRestriction(SNES, PetscInt, Mat); 1278 PETSC_EXTERN PetscErrorCode SNESFASGetRestriction(SNES, PetscInt, Mat *); 1279 PETSC_EXTERN PetscErrorCode SNESFASSetInjection(SNES, PetscInt, Mat); 1280 PETSC_EXTERN PetscErrorCode SNESFASGetInjection(SNES, PetscInt, Mat *); 1281 PETSC_EXTERN PetscErrorCode SNESFASSetRScale(SNES, PetscInt, Vec); 1282 PETSC_EXTERN PetscErrorCode SNESFASGetRScale(SNES, PetscInt, Vec *); 1283 PETSC_EXTERN PetscErrorCode SNESFASSetContinuation(SNES, PetscBool); 1284 1285 PETSC_EXTERN PetscErrorCode SNESFASGetSmoother(SNES, PetscInt, SNES *); 1286 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherUp(SNES, PetscInt, SNES *); 1287 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherDown(SNES, PetscInt, SNES *); 1288 PETSC_EXTERN PetscErrorCode SNESFASGetCoarseSolve(SNES, SNES *); 1289 1290 /* parameters for full FAS */ 1291 PETSC_EXTERN PetscErrorCode SNESFASFullSetDownSweep(SNES, PetscBool); 1292 PETSC_EXTERN PetscErrorCode SNESFASCreateCoarseVec(SNES, Vec *); 1293 PETSC_EXTERN PetscErrorCode SNESFASRestrict(SNES, Vec, Vec); 1294 PETSC_EXTERN PetscErrorCode SNESFASFullSetTotal(SNES, PetscBool); 1295 PETSC_EXTERN PetscErrorCode SNESFASFullGetTotal(SNES, PetscBool *); 1296 1297 PETSC_EXTERN PetscErrorCode DMSNESCheckDiscretization(SNES, DM, PetscReal, Vec, PetscReal, PetscReal[]); 1298 PETSC_EXTERN PetscErrorCode DMSNESCheckResidual(SNES, DM, Vec, PetscReal, PetscReal *); 1299 PETSC_EXTERN PetscErrorCode DMSNESCheckJacobian(SNES, DM, Vec, PetscReal, PetscBool *, PetscReal *); 1300 PETSC_EXTERN PetscErrorCode DMSNESCheckFromOptions(SNES, Vec); 1301 PETSC_EXTERN PetscErrorCode DMSNESComputeJacobianAction(DM, Vec, Vec, Vec, void *); 1302 PETSC_EXTERN PetscErrorCode DMSNESCreateJacobianMF(DM, Vec, void *, Mat *); 1303 1304 PETSC_EXTERN PetscErrorCode SNESNewtonALSetFunction(SNES, SNESFunctionFn *, void *ctx); 1305 PETSC_EXTERN PetscErrorCode SNESNewtonALGetFunction(SNES, SNESFunctionFn **, void **ctx); 1306 PETSC_EXTERN PetscErrorCode SNESNewtonALComputeFunction(SNES, Vec, Vec); 1307 PETSC_EXTERN PetscErrorCode SNESNewtonALGetLoadParameter(SNES, PetscReal *); 1308 1309 /*MC 1310 SNESNewtonALCorrectionType - the approach used by `SNESNEWTONAL` to determine 1311 the correction to the current increment. While the exact correction satisfies 1312 the constraint surface at every iteration, it also requires solving a quadratic 1313 equation which may not have real roots. Conversely, the normal correction is more 1314 efficient and always yields a real correction and is the default. 1315 1316 Values: 1317 + `SNES_NEWTONAL_CORRECTION_EXACT` - choose the correction which exactly satisfies the constraint 1318 - `SNES_NEWTONAL_CORRECTION_NORMAL` - choose the correction in the updated normal hyper-surface to the constraint surface 1319 1320 Options Database Key: 1321 . -snes_newtonal_correction_type <exact> - select type from <exact,normal> 1322 1323 Level: intermediate 1324 1325 .seealso: `SNES`, `SNESNEWTONAL`, `SNESNewtonALSetCorrectionType()` 1326 M*/ 1327 typedef enum { 1328 SNES_NEWTONAL_CORRECTION_EXACT = 0, 1329 SNES_NEWTONAL_CORRECTION_NORMAL = 1, 1330 } SNESNewtonALCorrectionType; 1331 PETSC_EXTERN const char *const SNESNewtonALCorrectionTypes[]; 1332 1333 PETSC_EXTERN PetscErrorCode SNESNewtonALSetCorrectionType(SNES, SNESNewtonALCorrectionType); 1334