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