1 /* 2 User interface for the nonlinear solvers package. 3 */ 4 #if !defined(__PETSCSNES_H) 5 #define __PETSCSNES_H 6 #include "petscksp.h" 7 #include "petscdmda.h" 8 PETSC_EXTERN_CXX_BEGIN 9 10 /*S 11 SNES - Abstract PETSc object that manages all nonlinear solves 12 13 Level: beginner 14 15 Concepts: nonlinear solvers 16 17 .seealso: SNESCreate(), SNESSetType(), SNESType, TS, KSP, KSP, PC 18 S*/ 19 typedef struct _p_SNES* SNES; 20 21 /*J 22 SNESType - String with the name of a PETSc SNES method or the creation function 23 with an optional dynamic library name, for example 24 http://www.mcs.anl.gov/petsc/lib.a:mysnescreate() 25 26 Level: beginner 27 28 .seealso: SNESSetType(), SNES 29 J*/ 30 #define SNESType char* 31 #define SNESLS "ls" 32 #define SNESTR "tr" 33 #define SNESPYTHON "python" 34 #define SNESTEST "test" 35 #define SNESNRICHARDSON "nrichardson" 36 #define SNESKSPONLY "ksponly" 37 #define SNESVIRS "virs" 38 #define SNESVISS "viss" 39 #define SNESNGMRES "ngmres" 40 #define SNESQN "qn" 41 #define SNESSHELL "shell" 42 #define SNESGS "gs" 43 #define SNESNCG "ncg" 44 #define SNESSORQN "sorqn" 45 #define SNESFAS "fas" 46 #define SNESMS "ms" 47 48 /* Logging support */ 49 extern PetscClassId SNES_CLASSID; 50 51 extern PetscErrorCode SNESInitializePackage(const char[]); 52 53 extern PetscErrorCode SNESCreate(MPI_Comm,SNES*); 54 extern PetscErrorCode SNESReset(SNES); 55 extern PetscErrorCode SNESDestroy(SNES*); 56 extern PetscErrorCode SNESSetType(SNES,const SNESType); 57 extern PetscErrorCode SNESMonitor(SNES,PetscInt,PetscReal); 58 extern PetscErrorCode SNESMonitorSet(SNES,PetscErrorCode(*)(SNES,PetscInt,PetscReal,void*),void *,PetscErrorCode (*)(void**)); 59 extern PetscErrorCode SNESMonitorCancel(SNES); 60 extern PetscErrorCode SNESSetConvergenceHistory(SNES,PetscReal[],PetscInt[],PetscInt,PetscBool ); 61 extern PetscErrorCode SNESGetConvergenceHistory(SNES,PetscReal*[],PetscInt *[],PetscInt *); 62 extern PetscErrorCode SNESSetUp(SNES); 63 extern PetscErrorCode SNESSolve(SNES,Vec,Vec); 64 extern PetscErrorCode SNESSetErrorIfNotConverged(SNES,PetscBool ); 65 extern PetscErrorCode SNESGetErrorIfNotConverged(SNES,PetscBool *); 66 67 68 extern PetscErrorCode SNESAddOptionsChecker(PetscErrorCode (*)(SNES)); 69 70 extern PetscErrorCode SNESSetUpdate(SNES, PetscErrorCode (*)(SNES, PetscInt)); 71 extern PetscErrorCode SNESDefaultUpdate(SNES, PetscInt); 72 73 extern PetscFList SNESList; 74 extern PetscErrorCode SNESRegisterDestroy(void); 75 extern PetscErrorCode SNESRegisterAll(const char[]); 76 77 extern PetscErrorCode SNESRegister(const char[],const char[],const char[],PetscErrorCode (*)(SNES)); 78 79 /*MC 80 SNESRegisterDynamic - Adds a method to the nonlinear solver package. 81 82 Synopsis: 83 PetscErrorCode SNESRegisterDynamic(const char *name_solver,const char *path,const char *name_create,PetscErrorCode (*routine_create)(SNES)) 84 85 Not collective 86 87 Input Parameters: 88 + name_solver - name of a new user-defined solver 89 . path - path (either absolute or relative) the library containing this solver 90 . name_create - name of routine to create method context 91 - routine_create - routine to create method context 92 93 Notes: 94 SNESRegisterDynamic() may be called multiple times to add several user-defined solvers. 95 96 If dynamic libraries are used, then the fourth input argument (routine_create) 97 is ignored. 98 99 Environmental variables such as ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR}, 100 and others of the form ${any_environmental_variable} occuring in pathname will be 101 replaced with appropriate values. 102 103 Sample usage: 104 .vb 105 SNESRegisterDynamic("my_solver",/home/username/my_lib/lib/libg/solaris/mylib.a, 106 "MySolverCreate",MySolverCreate); 107 .ve 108 109 Then, your solver can be chosen with the procedural interface via 110 $ SNESSetType(snes,"my_solver") 111 or at runtime via the option 112 $ -snes_type my_solver 113 114 Level: advanced 115 116 Note: If your function is not being put into a shared library then use SNESRegister() instead 117 118 .keywords: SNES, nonlinear, register 119 120 .seealso: SNESRegisterAll(), SNESRegisterDestroy() 121 M*/ 122 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 123 #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,0) 124 #else 125 #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,d) 126 #endif 127 128 extern PetscErrorCode SNESGetKSP(SNES,KSP*); 129 extern PetscErrorCode SNESSetKSP(SNES,KSP); 130 extern PetscErrorCode SNESGetSolution(SNES,Vec*); 131 extern PetscErrorCode SNESGetSolutionUpdate(SNES,Vec*); 132 extern PetscErrorCode SNESGetRhs(SNES,Vec*); 133 extern PetscErrorCode SNESView(SNES,PetscViewer); 134 135 extern PetscErrorCode SNESSetOptionsPrefix(SNES,const char[]); 136 extern PetscErrorCode SNESAppendOptionsPrefix(SNES,const char[]); 137 extern PetscErrorCode SNESGetOptionsPrefix(SNES,const char*[]); 138 extern PetscErrorCode SNESSetFromOptions(SNES); 139 extern PetscErrorCode SNESDefaultGetWork(SNES,PetscInt); 140 141 extern PetscErrorCode MatCreateSNESMF(SNES,Mat*); 142 extern PetscErrorCode MatMFFDComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 143 144 extern PetscErrorCode MatDAADSetSNES(Mat,SNES); 145 146 extern PetscErrorCode SNESGetType(SNES,const SNESType*); 147 extern PetscErrorCode SNESMonitorDefault(SNES,PetscInt,PetscReal,void *); 148 extern PetscErrorCode SNESMonitorRange(SNES,PetscInt,PetscReal,void *); 149 extern PetscErrorCode SNESMonitorRatio(SNES,PetscInt,PetscReal,void *); 150 extern PetscErrorCode SNESMonitorSetRatio(SNES,PetscViewer); 151 extern PetscErrorCode SNESMonitorSolution(SNES,PetscInt,PetscReal,void *); 152 extern PetscErrorCode SNESMonitorResidual(SNES,PetscInt,PetscReal,void *); 153 extern PetscErrorCode SNESMonitorSolutionUpdate(SNES,PetscInt,PetscReal,void *); 154 extern PetscErrorCode SNESMonitorDefaultShort(SNES,PetscInt,PetscReal,void *); 155 extern PetscErrorCode SNESSetTolerances(SNES,PetscReal,PetscReal,PetscReal,PetscInt,PetscInt); 156 extern PetscErrorCode SNESGetTolerances(SNES,PetscReal*,PetscReal*,PetscReal*,PetscInt*,PetscInt*); 157 extern PetscErrorCode SNESSetTrustRegionTolerance(SNES,PetscReal); 158 extern PetscErrorCode SNESGetFunctionNorm(SNES,PetscReal*); 159 extern PetscErrorCode SNESSetFunctionNorm(SNES,PetscReal); 160 extern PetscErrorCode SNESGetIterationNumber(SNES,PetscInt*); 161 extern PetscErrorCode SNESSetIterationNumber(SNES,PetscInt); 162 163 extern PetscErrorCode SNESGetNonlinearStepFailures(SNES,PetscInt*); 164 extern PetscErrorCode SNESSetMaxNonlinearStepFailures(SNES,PetscInt); 165 extern PetscErrorCode SNESGetMaxNonlinearStepFailures(SNES,PetscInt*); 166 extern PetscErrorCode SNESGetNumberFunctionEvals(SNES,PetscInt*); 167 168 extern PetscErrorCode SNESSetLagPreconditioner(SNES,PetscInt); 169 extern PetscErrorCode SNESGetLagPreconditioner(SNES,PetscInt*); 170 extern PetscErrorCode SNESSetLagJacobian(SNES,PetscInt); 171 extern PetscErrorCode SNESGetLagJacobian(SNES,PetscInt*); 172 extern PetscErrorCode SNESSetGridSequence(SNES,PetscInt); 173 174 extern PetscErrorCode SNESGetLinearSolveIterations(SNES,PetscInt*); 175 extern PetscErrorCode SNESGetLinearSolveFailures(SNES,PetscInt*); 176 extern PetscErrorCode SNESSetMaxLinearSolveFailures(SNES,PetscInt); 177 extern PetscErrorCode SNESGetMaxLinearSolveFailures(SNES,PetscInt*); 178 179 extern PetscErrorCode SNESKSPSetUseEW(SNES,PetscBool ); 180 extern PetscErrorCode SNESKSPGetUseEW(SNES,PetscBool *); 181 extern PetscErrorCode SNESKSPSetParametersEW(SNES,PetscInt,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal); 182 extern PetscErrorCode SNESKSPGetParametersEW(SNES,PetscInt*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*); 183 184 extern PetscErrorCode SNESMonitorLGCreate(const char[],const char[],int,int,int,int,PetscDrawLG*); 185 extern PetscErrorCode SNESMonitorLG(SNES,PetscInt,PetscReal,void*); 186 extern PetscErrorCode SNESMonitorLGDestroy(PetscDrawLG*); 187 extern PetscErrorCode SNESMonitorLGRangeCreate(const char[],const char[],int,int,int,int,PetscDrawLG*); 188 extern PetscErrorCode SNESMonitorLGRange(SNES,PetscInt,PetscReal,void*); 189 extern PetscErrorCode SNESMonitorLGRangeDestroy(PetscDrawLG*); 190 191 extern PetscErrorCode SNESSetApplicationContext(SNES,void *); 192 extern PetscErrorCode SNESGetApplicationContext(SNES,void *); 193 extern PetscErrorCode SNESSetComputeApplicationContext(SNES,PetscErrorCode (*)(SNES,void**),PetscErrorCode (*)(void**)); 194 195 extern PetscErrorCode SNESPythonSetType(SNES,const char[]); 196 197 extern PetscErrorCode SNESSetFunctionDomainError(SNES); 198 extern PetscErrorCode SNESGetFunctionDomainError(SNES, PetscBool *); 199 200 /*E 201 SNESConvergedReason - reason a SNES method was said to 202 have converged or diverged 203 204 Level: beginner 205 206 The two most common reasons for divergence are 207 $ 1) an incorrectly coded or computed Jacobian or 208 $ 2) failure or lack of convergence in the linear system (in this case we recommend 209 $ testing with -pc_type lu to eliminate the linear solver as the cause of the problem). 210 211 Diverged Reasons: 212 . SNES_DIVERGED_LOCAL_MIN - this can only occur when using the line-search variant of SNES. 213 The line search wants to minimize Q(alpha) = 1/2 || F(x + alpha s) ||^2_2 this occurs 214 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 215 you get Q'(alpha) = -F(x)^T F'(x)^(-1)^T F'(x+alpha s)F(x+alpha s); when alpha = 0 216 Q'(0) = - ||F(x)||^2_2 which is always NEGATIVE if F'(x) is invertible. This means the Newton 217 direction is a descent direction and the line search should succeed if alpha is small enough. 218 219 If F'(x) is NOT invertible AND F'(x)^T F(x) = 0 then Q'(0) = 0 and the Newton direction 220 is NOT a descent direction so the line search will fail. All one can do at this point 221 is change the initial guess and try again. 222 223 An alternative explanation: Newton's method can be regarded as replacing the function with 224 its linear approximation and minimizing the 2-norm of that. That is F(x+s) approx F(x) + F'(x)s 225 so we minimize || F(x) + F'(x) s ||^2_2; do this using Least Squares. If F'(x) is invertible then 226 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 227 exists a nontrival (that is F'(x)s != 0) solution to the equation and this direction is 228 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) 229 = - (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 230 and F'(x)^T F'(x) has no negative eigenvalues Q'(0) < 0 so s is a descent direction and the line 231 search should succeed for small enough alpha. 232 233 Note that this RARELY happens in practice. Far more likely the linear system is not being solved 234 (well enough?) or the Jacobian is wrong. 235 236 SNES_DIVERGED_MAX_IT means that the solver reached the maximum number of iterations without satisfying any 237 convergence criteria. SNES_CONVERGED_ITS means that SNESSkipConverged() was chosen as the convergence test; 238 thus the usual convergence criteria have not been checked and may or may not be satisfied. 239 240 Developer Notes: this must match finclude/petscsnes.h 241 242 The string versions of these are in SNESConvergedReason, if you change any value here you must 243 also adjust that array. 244 245 Each reason has its own manual page. 246 247 .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest() 248 E*/ 249 typedef enum {/* converged */ 250 SNES_CONVERGED_FNORM_ABS = 2, /* ||F|| < atol */ 251 SNES_CONVERGED_FNORM_RELATIVE = 3, /* ||F|| < rtol*||F_initial|| */ 252 SNES_CONVERGED_SNORM_RELATIVE = 4, /* Newton computed step size small; || delta x || < stol */ 253 SNES_CONVERGED_ITS = 5, /* maximum iterations reached */ 254 SNES_CONVERGED_TR_DELTA = 7, 255 /* diverged */ 256 SNES_DIVERGED_FUNCTION_DOMAIN = -1, /* the new x location passed the function is not in the domain of F */ 257 SNES_DIVERGED_FUNCTION_COUNT = -2, 258 SNES_DIVERGED_LINEAR_SOLVE = -3, /* the linear solve failed */ 259 SNES_DIVERGED_FNORM_NAN = -4, 260 SNES_DIVERGED_MAX_IT = -5, 261 SNES_DIVERGED_LINE_SEARCH = -6, /* the line search failed */ 262 SNES_DIVERGED_INNER = -7, /* inner solve failed */ 263 SNES_DIVERGED_LOCAL_MIN = -8, /* || J^T b || is small, implies converged to local minimum of F() */ 264 SNES_CONVERGED_ITERATING = 0} SNESConvergedReason; 265 extern const char *const*SNESConvergedReasons; 266 267 /*MC 268 SNES_CONVERGED_FNORM_ABS - 2-norm(F) <= abstol 269 270 Level: beginner 271 272 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 273 274 M*/ 275 276 /*MC 277 SNES_CONVERGED_FNORM_RELATIVE - 2-norm(F) <= rtol*2-norm(F(x_0)) where x_0 is the initial guess 278 279 Level: beginner 280 281 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 282 283 M*/ 284 285 /*MC 286 SNES_CONVERGED_SNORM_RELATIVE - The 2-norm of the last step <= stol * 2-norm(x) where x is the current 287 solution and stol is the 4th argument to SNESSetTolerances() 288 289 Options Database Keys: 290 -snes_stol <stol> - the step tolerance 291 292 Level: beginner 293 294 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 295 296 M*/ 297 298 /*MC 299 SNES_DIVERGED_FUNCTION_COUNT - The user provided function has been called more times then the final 300 argument to SNESSetTolerances() 301 302 Level: beginner 303 304 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 305 306 M*/ 307 308 /*MC 309 SNES_DIVERGED_FNORM_NAN - the 2-norm of the current function evaluation is not-a-number (NaN), this 310 is usually caused by a division of 0 by 0. 311 312 Level: beginner 313 314 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 315 316 M*/ 317 318 /*MC 319 SNES_DIVERGED_MAX_IT - SNESSolve() has reached the maximum number of iterations requested 320 321 Level: beginner 322 323 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 324 325 M*/ 326 327 /*MC 328 SNES_DIVERGED_LINE_SEARCH - The line search has failed. This only occurs for a SNESType of SNESLS 329 330 Level: beginner 331 332 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 333 334 M*/ 335 336 /*MC 337 SNES_DIVERGED_LOCAL_MIN - the algorithm seems to have stagnated at a local minimum that is not zero. 338 See the manual page for SNESConvergedReason for more details 339 340 Level: beginner 341 342 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 343 344 M*/ 345 346 /*MC 347 SNES_CONERGED_ITERATING - this only occurs if SNESGetConvergedReason() is called during the SNESSolve() 348 349 Level: beginner 350 351 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 352 353 M*/ 354 355 extern PetscErrorCode SNESSetConvergenceTest(SNES,PetscErrorCode (*)(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*),void*,PetscErrorCode (*)(void*)); 356 extern PetscErrorCode SNESDefaultConverged(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*); 357 extern PetscErrorCode SNESSkipConverged(SNES,PetscInt,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*); 358 extern PetscErrorCode SNESGetConvergedReason(SNES,SNESConvergedReason*); 359 360 extern PetscErrorCode SNESDMDAComputeFunction(SNES,Vec,Vec,void*); 361 extern PetscErrorCode SNESDMDAComputeJacobianWithAdic(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 362 extern PetscErrorCode SNESDMDAComputeJacobianWithAdifor(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 363 extern PetscErrorCode SNESDMDAComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 364 365 extern PetscErrorCode SNESDMMeshComputeFunction(SNES,Vec,Vec,void*); 366 extern PetscErrorCode SNESDMMeshComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 367 extern PetscErrorCode SNESDMComplexComputeFunction(SNES,Vec,Vec,void *); 368 extern PetscErrorCode SNESDMComplexComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 369 370 /* --------- Solving systems of nonlinear equations --------------- */ 371 typedef PetscErrorCode (*SNESFunction)(SNES,Vec,Vec,void*); 372 typedef PetscErrorCode (*SNESJacobian)(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 373 typedef PetscErrorCode (*SNESGSFunction)(SNES,Vec,Vec,void*); 374 extern PetscErrorCode SNESSetFunction(SNES,Vec,SNESFunction,void*); 375 extern PetscErrorCode SNESGetFunction(SNES,Vec*,SNESFunction*,void**); 376 extern PetscErrorCode SNESComputeFunction(SNES,Vec,Vec); 377 extern PetscErrorCode SNESSetJacobian(SNES,Mat,Mat,SNESJacobian,void*); 378 extern PetscErrorCode SNESGetJacobian(SNES,Mat*,Mat*,SNESJacobian*,void**); 379 extern PetscErrorCode SNESDefaultComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 380 extern PetscErrorCode SNESDefaultComputeJacobianColor(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 381 extern PetscErrorCode SNESSetComputeInitialGuess(SNES,PetscErrorCode (*)(SNES,Vec,void*),void*); 382 extern PetscErrorCode SNESSetPicard(SNES,Vec,SNESFunction,Mat,Mat,SNESJacobian,void*); 383 extern PetscErrorCode SNESGetPicard(SNES,Vec*,SNESFunction*,Mat*,SNESJacobian*,void**); 384 extern PetscErrorCode SNESSetInitialFunction(SNES,Vec); 385 extern PetscErrorCode SNESSetInitialFunctionNorm(SNES,PetscReal); 386 387 /*E 388 SNESNormType - Norm that is passed in the Krylov convergence 389 test routines. 390 391 Level: advanced 392 393 Support for these is highly dependent on the solver. 394 395 Notes: 396 This is primarily used to turn off extra norm and function computation 397 when the solvers are composed. 398 399 .seealso: SNESSolve(), SNESGetConvergedReason(), KSPSetNormType(), 400 KSPSetConvergenceTest(), KSPSetPCSide() 401 E*/ 402 403 typedef enum {SNES_NORM_DEFAULT = -1, 404 SNES_NORM_NONE = 0, 405 SNES_NORM_FUNCTION = 1, 406 SNES_NORM_INITIAL_ONLY = 2, 407 SNES_NORM_FINAL_ONLY = 3, 408 SNES_NORM_INITIAL_FINAL_ONLY = 4} SNESNormType; 409 extern const char *const*const SNESNormTypes; 410 /*MC 411 SNES_NORM_NONE - Don't compute function and its L2 norm. 412 413 Level: advanced 414 415 Notes: 416 This is most useful for stationary solvers with a fixed number of iterations used as smoothers. 417 418 .seealso: SNESNormType, SNESSetNormType(), SNES_NORM_DEFAULT 419 M*/ 420 421 /*MC 422 SNES_NORM_FUNCTION - Compute the function and its L2 norm at each iteration. 423 424 Level: advanced 425 426 Notes: 427 Most solvers will use this no matter what norm type is passed to them. 428 429 .seealso: SNESNormType, SNESSetNormType(), SNES_NORM_NONE 430 M*/ 431 432 /*MC 433 SNES_NORM_INITIAL_ONLY - Compute the function and its L2 at iteration 0, but do not update it. 434 435 Level: advanced 436 437 Notes: 438 This method is useful in composed methods, when a true solution might actually be found before SNESSolve() is called. 439 This option enables the solve to abort on the zeroth iteration if this is the case. 440 441 For solvers that require the computation of the L2 norm of the function as part of the method, this merely cancels 442 the norm computation at the last iteration (if possible). 443 444 .seealso: SNESNormType, SNESSetNormType(), SNES_NORM_FINAL_ONLY, SNES_NORM_INITIAL_FINAL_ONLY 445 M*/ 446 447 /*MC 448 SNES_NORM_FINAL_ONLY - Compute the function and its L2 norm on only the final iteration. 449 450 Level: advanced 451 452 Notes: 453 For solvers that require the computation of the L2 norm of the function as part of the method, behaves 454 exactly as SNES_NORM_DEFAULT. This method is useful when the function is gotten after SNESSolve and 455 used in subsequent computation for methods that do not need the norm computed during the rest of the 456 solution procedure. 457 458 .seealso: SNESNormType, SNESSetNormType(), SNES_NORM_INITIAL_ONLY, SNES_NORM_INITIAL_FINAL_ONLY 459 M*/ 460 461 /*MC 462 SNES_NORM_INITIAL_FINAL_ONLY - Compute the function and its L2 norm on only the initial and final iterations. 463 464 Level: advanced 465 466 Notes: 467 This method combines the benefits of SNES_NORM_INITIAL_ONLY and SNES_NORM_FINAL_ONLY. 468 469 .seealso: SNESNormType, SNESSetNormType(), SNES_NORM_SNES_NORM_INITIAL_ONLY, SNES_NORM_FINAL_ONLY 470 M*/ 471 472 473 extern PetscErrorCode SNESSetNormType(SNES,SNESNormType); 474 extern PetscErrorCode SNESGetNormType(SNES,SNESNormType*); 475 476 extern PetscErrorCode SNESSetGS(SNES,SNESGSFunction,void*); 477 extern PetscErrorCode SNESGetGS(SNES,SNESGSFunction*,void**); 478 extern PetscErrorCode SNESSetUseGS(SNES,PetscBool); 479 extern PetscErrorCode SNESGetUseGS(SNES,PetscBool *); 480 extern PetscErrorCode SNESSetGSSweeps(SNES,PetscInt); 481 extern PetscErrorCode SNESGetGSSweeps(SNES,PetscInt *); 482 extern PetscErrorCode SNESComputeGS(SNES,Vec,Vec); 483 484 extern PetscErrorCode SNESShellGetContext(SNES,void**); 485 extern PetscErrorCode SNESShellSetContext(SNES,void*); 486 extern PetscErrorCode SNESShellSetSolve(SNES,PetscErrorCode (*)(SNES,Vec)); 487 488 /* --------- Routines specifically for line search methods --------------- */ 489 490 typedef struct _p_LineSearch* SNESLineSearch; 491 492 /*S 493 SNESLineSearch - Abstract PETSc object that manages line-search operations 494 495 Level: beginner 496 497 Concepts: nonlinear solvers, line search 498 499 .seealso: SNESLineSearchCreate(), SNESLineSearchSetType(), SNES 500 S*/ 501 502 /*J 503 SNESLineSearchType - String with the name of a PETSc line search method 504 505 Level: beginner 506 507 .seealso: SNESLineSearchSetType(), SNES 508 J*/ 509 510 #define SNESLineSearchType char* 511 #define SNESLINESEARCHBT "bt" 512 #define SNESLINESEARCHBASIC "basic" 513 #define SNESLINESEARCHL2 "l2" 514 #define SNESLINESEARCHCP "cp" 515 #define SNESLINESEARCHSHELL "shell" 516 517 extern PetscClassId SNESLINESEARCH_CLASSID; 518 extern PetscBool SNESLineSearchRegisterAllCalled; 519 extern PetscFList SNESLineSearchList; 520 extern PetscLogEvent SNESLineSearch_Apply; 521 522 #define SNES_LINESEARCH_ORDER_LINEAR 1 523 #define SNES_LINESEARCH_ORDER_QUADRATIC 2 524 #define SNES_LINESEARCH_ORDER_CUBIC 3 525 526 typedef PetscErrorCode (*SNESLineSearchPreCheckFunc)(SNESLineSearch,Vec,Vec,PetscBool*,void*); 527 typedef PetscErrorCode (*SNESLineSearchVIProjectFunc)(SNES,Vec); 528 typedef PetscErrorCode (*SNESLineSearchVINormFunc)(SNES,Vec,Vec,PetscReal *); 529 typedef PetscErrorCode (*SNESLineSearchPostCheckFunc)(SNESLineSearch,Vec,Vec,Vec,PetscBool *,PetscBool *,void*); 530 typedef PetscErrorCode (*SNESLineSearchApplyFunc)(SNESLineSearch); 531 typedef PetscErrorCode (*SNESLineSearchUserFunc)(SNESLineSearch, void *); 532 533 extern PetscErrorCode SNESLineSearchCreate(MPI_Comm, SNESLineSearch*); 534 extern PetscErrorCode SNESLineSearchReset(SNESLineSearch); 535 extern PetscErrorCode SNESLineSearchView(SNESLineSearch,PetscViewer); 536 extern PetscErrorCode SNESLineSearchDestroy(SNESLineSearch *); 537 extern PetscErrorCode SNESLineSearchSetType(SNESLineSearch, const SNESLineSearchType); 538 extern PetscErrorCode SNESLineSearchSetFromOptions(SNESLineSearch); 539 extern PetscErrorCode SNESLineSearchSetUp(SNESLineSearch); 540 extern PetscErrorCode SNESLineSearchApply(SNESLineSearch, Vec, Vec, PetscReal *, Vec); 541 extern PetscErrorCode SNESLineSearchPreCheck(SNESLineSearch, PetscBool *); 542 extern PetscErrorCode SNESLineSearchPostCheck(SNESLineSearch, PetscBool *, PetscBool *); 543 extern PetscErrorCode SNESLineSearchGetWork(SNESLineSearch, PetscInt); 544 545 /* set the functions for precheck and postcheck */ 546 547 extern PetscErrorCode SNESLineSearchSetPreCheck(SNESLineSearch, SNESLineSearchPreCheckFunc, void *ctx); 548 extern PetscErrorCode SNESLineSearchSetPostCheck(SNESLineSearch, SNESLineSearchPostCheckFunc, void *ctx); 549 550 extern PetscErrorCode SNESLineSearchGetPreCheck(SNESLineSearch, SNESLineSearchPreCheckFunc*, void **ctx); 551 extern PetscErrorCode SNESLineSearchGetPostCheck(SNESLineSearch, SNESLineSearchPostCheckFunc*, void **ctx); 552 553 /* set the functions for VI-specific line search operations */ 554 555 extern PetscErrorCode SNESLineSearchSetVIFunctions(SNESLineSearch, SNESLineSearchVIProjectFunc, SNESLineSearchVINormFunc); 556 extern PetscErrorCode SNESLineSearchGetVIFunctions(SNESLineSearch, SNESLineSearchVIProjectFunc*, SNESLineSearchVINormFunc*); 557 558 /* pointers to the associated SNES in order to be able to get the function evaluation out */ 559 extern PetscErrorCode SNESLineSearchSetSNES(SNESLineSearch,SNES); 560 extern PetscErrorCode SNESLineSearchGetSNES(SNESLineSearch,SNES*); 561 562 /* set and get the parameters and vectors */ 563 extern PetscErrorCode SNESLineSearchGetTolerances(SNESLineSearch,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscReal*,PetscInt*); 564 extern PetscErrorCode SNESLineSearchSetTolerances(SNESLineSearch,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscInt); 565 566 extern PetscErrorCode SNESLineSearchPreCheckPicard(SNESLineSearch,Vec,Vec,PetscBool*,void*); 567 568 extern PetscErrorCode SNESLineSearchGetLambda(SNESLineSearch,PetscReal*); 569 extern PetscErrorCode SNESLineSearchSetLambda(SNESLineSearch,PetscReal); 570 571 extern PetscErrorCode SNESLineSearchGetDamping(SNESLineSearch,PetscReal*); 572 extern PetscErrorCode SNESLineSearchSetDamping(SNESLineSearch,PetscReal); 573 574 extern PetscErrorCode SNESLineSearchGetOrder(SNESLineSearch,PetscInt *order); 575 extern PetscErrorCode SNESLineSearchSetOrder(SNESLineSearch,PetscInt order); 576 577 extern PetscErrorCode SNESLineSearchGetSuccess(SNESLineSearch, PetscBool*); 578 extern PetscErrorCode SNESLineSearchSetSuccess(SNESLineSearch, PetscBool); 579 580 extern PetscErrorCode SNESLineSearchGetVecs(SNESLineSearch,Vec*,Vec*,Vec*,Vec*,Vec*); 581 extern PetscErrorCode SNESLineSearchSetVecs(SNESLineSearch,Vec,Vec,Vec,Vec,Vec); 582 583 extern PetscErrorCode SNESLineSearchGetNorms(SNESLineSearch, PetscReal *, PetscReal *, PetscReal *); 584 extern PetscErrorCode SNESLineSearchSetNorms(SNESLineSearch, PetscReal, PetscReal, PetscReal); 585 extern PetscErrorCode SNESLineSearchComputeNorms(SNESLineSearch); 586 extern PetscErrorCode SNESLineSearchSetComputeNorms(SNESLineSearch, PetscBool); 587 588 extern PetscErrorCode SNESLineSearchSetMonitor(SNESLineSearch, PetscBool); 589 extern PetscErrorCode SNESLineSearchGetMonitor(SNESLineSearch, PetscViewer*); 590 591 extern PetscErrorCode SNESLineSearchAppendOptionsPrefix(SNESLineSearch, const char prefix[]); 592 extern PetscErrorCode SNESLineSearchGetOptionsPrefix(SNESLineSearch, const char *prefix[]); 593 594 595 /* Shell interface functions */ 596 extern PetscErrorCode SNESLineSearchShellSetUserFunc(SNESLineSearch,SNESLineSearchUserFunc,void*); 597 extern PetscErrorCode SNESLineSearchShellGetUserFunc(SNESLineSearch,SNESLineSearchUserFunc*,void**); 598 599 /* BT interface functions */ 600 extern PetscErrorCode SNESLineSearchBTSetAlpha(SNESLineSearch, PetscReal); 601 extern PetscErrorCode SNESLineSearchBTGetAlpha(SNESLineSearch, PetscReal*); 602 603 /*register line search types */ 604 extern PetscErrorCode SNESLineSearchRegister(const char[],const char[],const char[],PetscErrorCode(*)(SNESLineSearch)); 605 extern PetscErrorCode SNESLineSearchRegisterAll(const char path[]); 606 extern PetscErrorCode SNESLineSearchRegisterDestroy(void); 607 608 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 609 #define SNESLineSearchRegisterDynamic(a,b,c,d) SNESLineSearchRegister(a,b,c,0) 610 #else 611 #define SNESLineSearchRegisterDynamic(a,b,c,d) SNESLineSearchRegister(a,b,c,d) 612 #endif 613 614 /* Routines for VI solver */ 615 extern PetscErrorCode SNESVISetVariableBounds(SNES,Vec,Vec); 616 extern PetscErrorCode SNESVISetComputeVariableBounds(SNES, PetscErrorCode (*)(SNES,Vec,Vec)); 617 extern PetscErrorCode SNESVIGetInactiveSet(SNES,IS*); 618 extern PetscErrorCode SNESVIGetActiveSetIS(SNES,Vec,Vec,IS*); 619 extern PetscErrorCode SNESVIComputeInactiveSetFnorm(SNES,Vec,Vec,PetscReal*); 620 extern PetscErrorCode SNESVISetRedundancyCheck(SNES,PetscErrorCode(*)(SNES,IS,IS*,void*),void*); 621 #define SNES_VI_INF 1.0e20 622 #define SNES_VI_NINF -1.0e20 623 624 extern PetscErrorCode SNESTestLocalMin(SNES); 625 626 /* Should this routine be private? */ 627 extern PetscErrorCode SNESComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*); 628 629 extern PetscErrorCode SNESSetDM(SNES,DM); 630 extern PetscErrorCode SNESGetDM(SNES,DM*); 631 extern PetscErrorCode SNESSetPC(SNES,SNES); 632 extern PetscErrorCode SNESGetPC(SNES,SNES*); 633 extern PetscErrorCode SNESSetSNESLineSearch(SNES,SNESLineSearch); 634 extern PetscErrorCode SNESGetSNESLineSearch(SNES,SNESLineSearch*); 635 extern PetscErrorCode SNESRestrictHookAdd(SNES,PetscErrorCode (*)(SNES,SNES,void*),void*); 636 extern PetscErrorCode SNESRestrictHooksRun(SNES,SNES); 637 638 extern PetscErrorCode SNESSetUpMatrices(SNES); 639 extern PetscErrorCode DMSNESSetFunction(DM,PetscErrorCode(*)(SNES,Vec,Vec,void*),void*); 640 extern PetscErrorCode DMSNESGetFunction(DM,PetscErrorCode(**)(SNES,Vec,Vec,void*),void**); 641 extern PetscErrorCode DMSNESSetGS(DM,PetscErrorCode(*)(SNES,Vec,Vec,void*),void*); 642 extern PetscErrorCode DMSNESGetGS(DM,PetscErrorCode(**)(SNES,Vec,Vec,void*),void**); 643 extern PetscErrorCode DMSNESSetJacobian(DM,PetscErrorCode(*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void*); 644 extern PetscErrorCode DMSNESGetJacobian(DM,PetscErrorCode(**)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void**); 645 646 extern PetscErrorCode DMDASNESSetFunctionLocal(DM,PetscErrorCode(*)(DMDALocalInfo*,void*,void*,void*),void*); 647 extern PetscErrorCode DMDASNESSetJacobianLocal(DM,PetscErrorCode(*)(DMDALocalInfo*,void*,Mat,Mat,MatStructure*,void*),void*); 648 649 /* Routines for Multiblock solver */ 650 extern PetscErrorCode SNESMultiblockSetFields(SNES, const char [], PetscInt, const PetscInt *); 651 extern PetscErrorCode SNESMultiblockSetIS(SNES, const char [], IS); 652 extern PetscErrorCode SNESMultiblockSetBlockSize(SNES, PetscInt); 653 extern PetscErrorCode SNESMultiblockSetType(SNES, PCCompositeType); 654 655 /*J 656 SNESMSType - String with the name of a PETSc SNESMS method. 657 658 Level: intermediate 659 660 .seealso: SNESMSSetType(), SNES 661 J*/ 662 #define SNESMSType char* 663 #define SNESMSM62 "m62" 664 #define SNESMSEULER "euler" 665 #define SNESMSJAMESON83 "jameson83" 666 #define SNESMSVLTP21 "vltp21" 667 #define SNESMSVLTP31 "vltp31" 668 #define SNESMSVLTP41 "vltp41" 669 #define SNESMSVLTP51 "vltp51" 670 #define SNESMSVLTP61 "vltp61" 671 672 extern PetscErrorCode SNESMSRegister(const SNESMSType,PetscInt,PetscInt,PetscReal,const PetscReal[],const PetscReal[],const PetscReal[]); 673 extern PetscErrorCode SNESMSSetType(SNES,const SNESMSType); 674 extern PetscErrorCode SNESMSFinalizePackage(void); 675 extern PetscErrorCode SNESMSInitializePackage(const char path[]); 676 extern PetscErrorCode SNESMSRegisterDestroy(void); 677 extern PetscErrorCode SNESMSRegisterAll(void); 678 679 /* routines for NGMRES solver */ 680 681 typedef enum { 682 SNES_NGMRES_RESTART_NONE = 0, 683 SNES_NGMRES_RESTART_PERIODIC = 1, 684 SNES_NGMRES_RESTART_DIFFERENCE = 2} SNESNGMRESRestartType; 685 extern const char *SNESNGMRESRestartTypes[]; 686 687 typedef enum { 688 SNES_NGMRES_SELECT_NONE = 0, 689 SNES_NGMRES_SELECT_DIFFERENCE = 1, 690 SNES_NGMRES_SELECT_LINESEARCH = 2} SNESNGMRESSelectType; 691 extern const char *SNESNGMRESSelectTypes[]; 692 693 extern PetscErrorCode SNESNGMRESSetRestartType(SNES, SNESNGMRESRestartType); 694 extern PetscErrorCode SNESNGMRESSetSelectType(SNES, SNESNGMRESSelectType); 695 696 /* routines for NCG solver */ 697 698 typedef enum { 699 SNES_NCG_FR, 700 SNES_NCG_PRP, 701 SNES_NCG_HS, 702 SNES_NCG_DY, 703 SNES_NCG_CD} SNESNCGType; 704 extern const char *SNESNCGTypes[]; 705 706 extern PetscErrorCode SNESNCGSetType(SNES, SNESNCGType); 707 708 /* routines for QN solver */ 709 710 typedef enum {SNES_QN_SEQUENTIAL, SNES_QN_COMPOSED} SNESQNCompositionType; 711 extern const char *SNESQNCompositionTypes[]; 712 typedef enum {SNES_QN_SCALE_NONE, SNES_QN_SCALE_SHANNO, SNES_QN_SCALE_LINESEARCH, SNES_QN_SCALE_JACOBIAN} SNESQNScaleType; 713 extern const char *SNESQNScaleTypes[]; 714 typedef enum {SNES_QN_RESTART_NONE, SNES_QN_RESTART_POWELL, SNES_QN_RESTART_PERIODIC} SNESQNRestartType; 715 extern const char *SNESQNRestartTypes[]; 716 717 extern PetscErrorCode SNESQNSetCompositionType(SNES, SNESQNCompositionType); 718 extern PetscErrorCode SNESQNSetScaleType(SNES, SNESQNScaleType); 719 extern PetscErrorCode SNESQNSetRestartType(SNES, SNESQNRestartType); 720 721 722 PETSC_EXTERN_CXX_END 723 #endif 724