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 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 825 /*J 826 SNESMSType - String with the name of a PETSc `SNESMS` method. 827 828 Level: intermediate 829 830 .seealso: [](ch_snes), `SNESMS`, `SNESMSGetType()`, `SNESMSSetType()`, `SNES` 831 J*/ 832 typedef const char *SNESMSType; 833 #define SNESMSM62 "m62" 834 #define SNESMSEULER "euler" 835 #define SNESMSJAMESON83 "jameson83" 836 #define SNESMSVLTP11 "vltp11" 837 #define SNESMSVLTP21 "vltp21" 838 #define SNESMSVLTP31 "vltp31" 839 #define SNESMSVLTP41 "vltp41" 840 #define SNESMSVLTP51 "vltp51" 841 #define SNESMSVLTP61 "vltp61" 842 843 PETSC_EXTERN PetscErrorCode SNESMSRegister(SNESMSType, PetscInt, PetscInt, PetscReal, const PetscReal[], const PetscReal[], const PetscReal[]); 844 PETSC_EXTERN PetscErrorCode SNESMSGetType(SNES, SNESMSType *); 845 PETSC_EXTERN PetscErrorCode SNESMSSetType(SNES, SNESMSType); 846 PETSC_EXTERN PetscErrorCode SNESMSGetDamping(SNES, PetscReal *); 847 PETSC_EXTERN PetscErrorCode SNESMSSetDamping(SNES, PetscReal); 848 PETSC_EXTERN PetscErrorCode SNESMSFinalizePackage(void); 849 PETSC_EXTERN PetscErrorCode SNESMSInitializePackage(void); 850 PETSC_EXTERN PetscErrorCode SNESMSRegisterDestroy(void); 851 852 /*MC 853 SNESNGMRESRestartType - the restart approach used by `SNESNGMRES` 854 855 Level: intermediate 856 857 Values: 858 + `SNES_NGMRES_RESTART_NONE` - never restart 859 . `SNES_NGMRES_RESTART_DIFFERENCE` - restart based upon difference criteria 860 - `SNES_NGMRES_RESTART_PERIODIC` - restart after a fixed number of iterations 861 862 Options Database Keys: 863 + -snes_ngmres_restart_type<difference,periodic,none> - set the restart type 864 - -snes_ngmres_restart[30] - sets the number of iterations before restart for periodic 865 866 .seealso: `SNES, `SNESNGMRES`, `SNESNGMRESSetSelectType()`, `SNESNGMRESGetSelectType()`, `SNESNGMRESSetRestartType()`, 867 `SNESNGMRESGetRestartType()`, `SNESNGMRESSelectType` 868 M*/ 869 typedef enum { 870 SNES_NGMRES_RESTART_NONE = 0, 871 SNES_NGMRES_RESTART_PERIODIC = 1, 872 SNES_NGMRES_RESTART_DIFFERENCE = 2 873 } SNESNGMRESRestartType; 874 PETSC_EXTERN const char *const SNESNGMRESRestartTypes[]; 875 876 /*MC 877 SNESNGMRESSelectType - the approach used by `SNESNGMRES` to determine how the candidate solution and 878 combined solution are used to create the next iterate. 879 880 Level: intermediate 881 882 Values: 883 + `SNES_NGMRES_SELECT_NONE` - choose the combined solution all the time 884 . `SNES_NGMRES_SELECT_DIFFERENCE` - choose based upon the selection criteria 885 - `SNES_NGMRES_SELECT_LINESEARCH` - choose based upon line search combination 886 887 Options Database Key: 888 . -snes_ngmres_select_type<difference,none,linesearch> - select type 889 890 .seealso: `SNES, `SNESNGMRES`, `SNESNGMRESSetSelectType()`, `SNESNGMRESGetSelectType()`, `SNESNGMRESSetRestartType()`, 891 `SNESNGMRESGetRestartType()`, `SNESNGMRESRestartType` 892 M*/ 893 typedef enum { 894 SNES_NGMRES_SELECT_NONE = 0, 895 SNES_NGMRES_SELECT_DIFFERENCE = 1, 896 SNES_NGMRES_SELECT_LINESEARCH = 2 897 } SNESNGMRESSelectType; 898 PETSC_EXTERN const char *const SNESNGMRESSelectTypes[]; 899 900 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartType(SNES, SNESNGMRESRestartType); 901 PETSC_EXTERN PetscErrorCode SNESNGMRESSetSelectType(SNES, SNESNGMRESSelectType); 902 PETSC_EXTERN PetscErrorCode SNESNGMRESSetRestartFmRise(SNES, PetscBool); 903 PETSC_EXTERN PetscErrorCode SNESNGMRESGetRestartFmRise(SNES, PetscBool *); 904 905 /*MC 906 SNESNCGType - the conjugate update approach for `SNESNCG` 907 908 Level: intermediate 909 910 Values: 911 + `SNES_NCG_FR` - Fletcher-Reeves update 912 . `SNES_NCG_PRP` - Polak-Ribiere-Polyak update, the default and the only one that tolerates generalized search directions 913 . `SNES_NCG_HS` - Hestenes-Steifel update 914 . `SNES_NCG_DY` - Dai-Yuan update 915 - `SNES_NCG_CD` - Conjugate Descent update 916 917 Options Database Key: 918 . -snes_ncg_type<fr,prp,hs,dy,cd> - select type 919 920 .seealso: `SNES, `SNESNCG`, `SNESNCGSetType()` 921 M*/ 922 typedef enum { 923 SNES_NCG_FR = 0, 924 SNES_NCG_PRP = 1, 925 SNES_NCG_HS = 2, 926 SNES_NCG_DY = 3, 927 SNES_NCG_CD = 4 928 } SNESNCGType; 929 PETSC_EXTERN const char *const SNESNCGTypes[]; 930 931 PETSC_EXTERN PetscErrorCode SNESNCGSetType(SNES, SNESNCGType); 932 933 /*MC 934 SNESQNScaleType - the scaling type used by `SNESQN` 935 936 Level: intermediate 937 938 Values: 939 + `SNES_QN_SCALE_NONE` - don't scale the problem 940 . `SNES_QN_SCALE_SCALAR` - use Shanno scaling 941 . `SNES_QN_SCALE_DIAGONAL` - scale with a diagonalized BFGS formula (see Gilbert and Lemarechal 1989), available 942 - `SNES_QN_SCALE_JACOBIAN` - scale by solving a linear system coming from the Jacobian you provided with `SNESSetJacobian()` 943 computed at the first iteration of `SNESQN` and at ever restart. 944 945 Options Database Key: 946 . -snes_qn_scale_type <diagonal,none,scalar,jacobian> - Scaling type 947 948 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNType`, `SNESQNSetType()`, `SNESQNSetRestartType()`, `SNESQNRestartType` 949 M*/ 950 typedef enum { 951 SNES_QN_SCALE_DEFAULT = 0, 952 SNES_QN_SCALE_NONE = 1, 953 SNES_QN_SCALE_SCALAR = 2, 954 SNES_QN_SCALE_DIAGONAL = 3, 955 SNES_QN_SCALE_JACOBIAN = 4 956 } SNESQNScaleType; 957 PETSC_EXTERN const char *const SNESQNScaleTypes[]; 958 959 /*MC 960 SNESQNRestartType - the restart approached used by `SNESQN` 961 962 Level: intermediate 963 964 Values: 965 + `SNES_QN_RESTART_NONE` - never restart 966 . `SNES_QN_RESTART_POWELL` - restart based upon descent criteria 967 - `SNES_QN_RESTART_PERIODIC` - restart after a fixed number of iterations 968 969 Options Database Keys: 970 + -snes_qn_restart_type <powell,periodic,none> - set the restart type 971 - -snes_qn_m <m> - sets the number of stored updates and the restart period for periodic 972 973 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNType`, `SNESQNSetType()`, `SNESQNSetRestartType()`, `SNESQNScaleType` 974 M*/ 975 typedef enum { 976 SNES_QN_RESTART_DEFAULT = 0, 977 SNES_QN_RESTART_NONE = 1, 978 SNES_QN_RESTART_POWELL = 2, 979 SNES_QN_RESTART_PERIODIC = 3 980 } SNESQNRestartType; 981 PETSC_EXTERN const char *const SNESQNRestartTypes[]; 982 983 /*MC 984 SNESQNType - the type used by `SNESQN` 985 986 Level: intermediate 987 988 Values: 989 + `SNES_QN_LBFGS` - LBFGS variant 990 . `SNES_QN_BROYDEN` - Broyden variant 991 - `SNES_QN_BADBROYDEN` - Bad Broyden variant 992 993 Options Database Key: 994 . -snes_qn_type <lbfgs,broyden,badbroyden> - quasi-Newton type 995 996 .seealso: `SNES, `SNESQN`, `SNESQNSetScaleType()`, `SNESQNSetType()`, `SNESQNScaleType`, `SNESQNRestartType`, `SNESQNSetRestartType()` 997 M*/ 998 typedef enum { 999 SNES_QN_LBFGS = 0, 1000 SNES_QN_BROYDEN = 1, 1001 SNES_QN_BADBROYDEN = 2 1002 } SNESQNType; 1003 PETSC_EXTERN const char *const SNESQNTypes[]; 1004 1005 PETSC_EXTERN PetscErrorCode SNESQNSetType(SNES, SNESQNType); 1006 PETSC_EXTERN PetscErrorCode SNESQNSetScaleType(SNES, SNESQNScaleType); 1007 PETSC_EXTERN PetscErrorCode SNESQNSetRestartType(SNES, SNESQNRestartType); 1008 1009 PETSC_EXTERN PetscErrorCode SNESNASMGetType(SNES, PCASMType *); 1010 PETSC_EXTERN PetscErrorCode SNESNASMSetType(SNES, PCASMType); 1011 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomains(SNES, PetscInt *, SNES **, VecScatter **, VecScatter **, VecScatter **); 1012 PETSC_EXTERN PetscErrorCode SNESNASMSetSubdomains(SNES, PetscInt, SNES *, VecScatter *, VecScatter *, VecScatter *); 1013 PETSC_EXTERN PetscErrorCode SNESNASMSetDamping(SNES, PetscReal); 1014 PETSC_EXTERN PetscErrorCode SNESNASMGetDamping(SNES, PetscReal *); 1015 PETSC_EXTERN PetscErrorCode SNESNASMGetSubdomainVecs(SNES, PetscInt *, Vec **, Vec **, Vec **, Vec **); 1016 PETSC_EXTERN PetscErrorCode SNESNASMSetComputeFinalJacobian(SNES, PetscBool); 1017 PETSC_EXTERN PetscErrorCode SNESNASMGetSNES(SNES, PetscInt, SNES *); 1018 PETSC_EXTERN PetscErrorCode SNESNASMGetNumber(SNES, PetscInt *); 1019 PETSC_EXTERN PetscErrorCode SNESNASMSetWeight(SNES, Vec); 1020 1021 typedef enum { 1022 SNES_COMPOSITE_ADDITIVE, 1023 SNES_COMPOSITE_MULTIPLICATIVE, 1024 SNES_COMPOSITE_ADDITIVEOPTIMAL 1025 } SNESCompositeType; 1026 PETSC_EXTERN const char *const SNESCompositeTypes[]; 1027 1028 PETSC_EXTERN PetscErrorCode SNESCompositeSetType(SNES, SNESCompositeType); 1029 PETSC_EXTERN PetscErrorCode SNESCompositeAddSNES(SNES, SNESType); 1030 PETSC_EXTERN PetscErrorCode SNESCompositeGetSNES(SNES, PetscInt, SNES *); 1031 PETSC_EXTERN PetscErrorCode SNESCompositeGetNumber(SNES, PetscInt *); 1032 PETSC_EXTERN PetscErrorCode SNESCompositeSetDamping(SNES, PetscInt, PetscReal); 1033 1034 PETSC_EXTERN PetscErrorCode SNESPatchSetDiscretisationInfo(SNES, PetscInt, DM *, PetscInt *, PetscInt *, const PetscInt **, const PetscInt *, PetscInt, const PetscInt *, PetscInt, const PetscInt *); 1035 PETSC_EXTERN PetscErrorCode SNESPatchSetComputeOperator(SNES, PetscErrorCode (*func)(PC, PetscInt, Vec, Mat, IS, PetscInt, const PetscInt *, const PetscInt *, void *), void *); 1036 PETSC_EXTERN PetscErrorCode SNESPatchSetComputeFunction(SNES, PetscErrorCode (*func)(PC, PetscInt, Vec, Vec, IS, PetscInt, const PetscInt *, const PetscInt *, void *), void *); 1037 PETSC_EXTERN PetscErrorCode SNESPatchSetConstructType(SNES, PCPatchConstructType, PetscErrorCode (*func)(PC, PetscInt *, IS **, IS *, void *), void *); 1038 PETSC_EXTERN PetscErrorCode SNESPatchSetCellNumbering(SNES, PetscSection); 1039 1040 /*E 1041 SNESFASType - Determines the type of nonlinear multigrid method that is run. 1042 1043 Values: 1044 + `SNES_FAS_MULTIPLICATIVE` (default) - traditional V or W cycle as determined by `SNESFASSetCycles()` 1045 . `SNES_FAS_ADDITIVE` - additive FAS cycle 1046 . `SNES_FAS_FULL` - full FAS cycle 1047 - `SNES_FAS_KASKADE` - Kaskade FAS cycle 1048 1049 Level: beginner 1050 1051 .seealso: [](ch_snes), `SNESFAS`, `PCMGSetType()`, `PCMGType` 1052 E*/ 1053 typedef enum { 1054 SNES_FAS_MULTIPLICATIVE, 1055 SNES_FAS_ADDITIVE, 1056 SNES_FAS_FULL, 1057 SNES_FAS_KASKADE 1058 } SNESFASType; 1059 PETSC_EXTERN const char *const SNESFASTypes[]; 1060 1061 /* called on the finest level FAS instance*/ 1062 PETSC_EXTERN PetscErrorCode SNESFASSetType(SNES, SNESFASType); 1063 PETSC_EXTERN PetscErrorCode SNESFASGetType(SNES, SNESFASType *); 1064 PETSC_EXTERN PetscErrorCode SNESFASSetLevels(SNES, PetscInt, MPI_Comm *); 1065 PETSC_EXTERN PetscErrorCode SNESFASGetLevels(SNES, PetscInt *); 1066 PETSC_EXTERN PetscErrorCode SNESFASGetCycleSNES(SNES, PetscInt, SNES *); 1067 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothUp(SNES, PetscInt); 1068 PETSC_EXTERN PetscErrorCode SNESFASSetNumberSmoothDown(SNES, PetscInt); 1069 PETSC_EXTERN PetscErrorCode SNESFASSetCycles(SNES, PetscInt); 1070 PETSC_EXTERN PetscErrorCode SNESFASSetMonitor(SNES, PetscViewerAndFormat *, PetscBool); 1071 PETSC_EXTERN PetscErrorCode SNESFASSetLog(SNES, PetscBool); 1072 1073 PETSC_EXTERN PetscErrorCode SNESFASSetGalerkin(SNES, PetscBool); 1074 PETSC_EXTERN PetscErrorCode SNESFASGetGalerkin(SNES, PetscBool *); 1075 PETSC_EXTERN PetscErrorCode SNESFASGalerkinFunctionDefault(SNES, Vec, Vec, void *); 1076 1077 /* called on any level -- "Cycle" FAS instance */ 1078 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmoother(SNES, SNES *); 1079 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherUp(SNES, SNES *); 1080 PETSC_EXTERN PetscErrorCode SNESFASCycleGetSmootherDown(SNES, SNES *); 1081 PETSC_EXTERN PetscErrorCode SNESFASCycleGetCorrection(SNES, SNES *); 1082 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInterpolation(SNES, Mat *); 1083 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRestriction(SNES, Mat *); 1084 PETSC_EXTERN PetscErrorCode SNESFASCycleGetInjection(SNES, Mat *); 1085 PETSC_EXTERN PetscErrorCode SNESFASCycleGetRScale(SNES, Vec *); 1086 PETSC_EXTERN PetscErrorCode SNESFASCycleSetCycles(SNES, PetscInt); 1087 PETSC_EXTERN PetscErrorCode SNESFASCycleIsFine(SNES, PetscBool *); 1088 1089 /* called on the (outer) finest level FAS to set/get parameters on any level instance */ 1090 PETSC_EXTERN PetscErrorCode SNESFASSetInterpolation(SNES, PetscInt, Mat); 1091 PETSC_EXTERN PetscErrorCode SNESFASGetInterpolation(SNES, PetscInt, Mat *); 1092 PETSC_EXTERN PetscErrorCode SNESFASSetRestriction(SNES, PetscInt, Mat); 1093 PETSC_EXTERN PetscErrorCode SNESFASGetRestriction(SNES, PetscInt, Mat *); 1094 PETSC_EXTERN PetscErrorCode SNESFASSetInjection(SNES, PetscInt, Mat); 1095 PETSC_EXTERN PetscErrorCode SNESFASGetInjection(SNES, PetscInt, Mat *); 1096 PETSC_EXTERN PetscErrorCode SNESFASSetRScale(SNES, PetscInt, Vec); 1097 PETSC_EXTERN PetscErrorCode SNESFASGetRScale(SNES, PetscInt, Vec *); 1098 PETSC_EXTERN PetscErrorCode SNESFASSetContinuation(SNES, PetscBool); 1099 1100 PETSC_EXTERN PetscErrorCode SNESFASGetSmoother(SNES, PetscInt, SNES *); 1101 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherUp(SNES, PetscInt, SNES *); 1102 PETSC_EXTERN PetscErrorCode SNESFASGetSmootherDown(SNES, PetscInt, SNES *); 1103 PETSC_EXTERN PetscErrorCode SNESFASGetCoarseSolve(SNES, SNES *); 1104 1105 /* parameters for full FAS */ 1106 PETSC_EXTERN PetscErrorCode SNESFASFullSetDownSweep(SNES, PetscBool); 1107 PETSC_EXTERN PetscErrorCode SNESFASCreateCoarseVec(SNES, Vec *); 1108 PETSC_EXTERN PetscErrorCode SNESFASRestrict(SNES, Vec, Vec); 1109 PETSC_EXTERN PetscErrorCode SNESFASFullSetTotal(SNES, PetscBool); 1110 PETSC_EXTERN PetscErrorCode SNESFASFullGetTotal(SNES, PetscBool *); 1111 1112 PETSC_EXTERN PetscErrorCode DMSNESCheckDiscretization(SNES, DM, PetscReal, Vec, PetscReal, PetscReal[]); 1113 PETSC_EXTERN PetscErrorCode DMSNESCheckResidual(SNES, DM, Vec, PetscReal, PetscReal *); 1114 PETSC_EXTERN PetscErrorCode DMSNESCheckJacobian(SNES, DM, Vec, PetscReal, PetscBool *, PetscReal *); 1115 PETSC_EXTERN PetscErrorCode DMSNESCheckFromOptions(SNES, Vec); 1116 PETSC_EXTERN PetscErrorCode DMSNESComputeJacobianAction(DM, Vec, Vec, Vec, void *); 1117 PETSC_EXTERN PetscErrorCode DMSNESCreateJacobianMF(DM, Vec, void *, Mat *); 1118 1119 #endif 1120