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