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