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