1 /* 2 User interface for the nonlinear solvers package. 3 */ 4 #if !defined(__PETSCSNES_H) 5 #define __PETSCSNES_H 6 #include "petscksp.h" 7 PETSC_EXTERN_CXX_BEGIN 8 9 /*S 10 SNES - Abstract PETSc object that manages all nonlinear solves 11 12 Level: beginner 13 14 Concepts: nonlinear solvers 15 16 .seealso: SNESCreate(), SNESSetType(), SNESType, TS, KSP, KSP, PC 17 S*/ 18 typedef struct _p_SNES* SNES; 19 20 /*E 21 SNESType - String with the name of a PETSc SNES method or the creation function 22 with an optional dynamic library name, for example 23 http://www.mcs.anl.gov/petsc/lib.a:mysnescreate() 24 25 Level: beginner 26 27 .seealso: SNESSetType(), SNES 28 E*/ 29 #define SNESLS "ls" 30 #define SNESTR "tr" 31 #define SNESTEST "test" 32 #define SNESType char* 33 34 /* Logging support */ 35 extern PetscCookie SNES_COOKIE; 36 extern PetscEvent SNES_Solve, SNES_LineSearch, SNES_FunctionEval, SNES_JacobianEval; 37 extern PetscCookie MATSNESMFCTX_COOKIE; 38 extern PetscEvent MATSNESMF_Mult; 39 40 EXTERN PetscErrorCode SNESInitializePackage(const char[]); 41 42 EXTERN PetscErrorCode SNESCreate(MPI_Comm,SNES*); 43 EXTERN PetscErrorCode SNESDestroy(SNES); 44 EXTERN PetscErrorCode SNESSetType(SNES,const SNESType); 45 EXTERN PetscErrorCode SNESSetMonitor(SNES,PetscErrorCode(*)(SNES,PetscInt,PetscReal,void*),void *,PetscErrorCode (*)(void*)); 46 EXTERN PetscErrorCode SNESClearMonitor(SNES); 47 EXTERN PetscErrorCode SNESSetConvergenceHistory(SNES,PetscReal[],PetscInt[],PetscInt,PetscTruth); 48 EXTERN PetscErrorCode SNESGetConvergenceHistory(SNES,PetscReal*[],PetscInt *[],PetscInt *); 49 EXTERN PetscErrorCode SNESSetUp(SNES,Vec); 50 EXTERN PetscErrorCode SNESSolve(SNES,Vec); 51 52 EXTERN PetscErrorCode SNESAddOptionsChecker(PetscErrorCode (*)(SNES)); 53 54 EXTERN PetscErrorCode SNESSetRhsBC(SNES, PetscErrorCode (*)(SNES, Vec, void *)); 55 EXTERN PetscErrorCode SNESDefaultRhsBC(SNES, Vec, void *); 56 EXTERN PetscErrorCode SNESSetSolutionBC(SNES, PetscErrorCode (*)(SNES, Vec, void *)); 57 EXTERN PetscErrorCode SNESDefaultSolutionBC(SNES, Vec, void *); 58 EXTERN PetscErrorCode SNESSetUpdate(SNES, PetscErrorCode (*)(SNES, PetscInt)); 59 EXTERN PetscErrorCode SNESDefaultUpdate(SNES, PetscInt); 60 61 extern PetscFList SNESList; 62 EXTERN PetscErrorCode SNESRegisterDestroy(void); 63 EXTERN PetscErrorCode SNESRegisterAll(const char[]); 64 65 EXTERN PetscErrorCode SNESRegister(const char[],const char[],const char[],PetscErrorCode (*)(SNES)); 66 67 /*MC 68 SNESRegisterDynamic - Adds a method to the nonlinear solver package. 69 70 Synopsis: 71 PetscErrorCode SNESRegisterDynamic(char *name_solver,char *path,char *name_create,PetscErrorCode (*routine_create)(SNES)) 72 73 Not collective 74 75 Input Parameters: 76 + name_solver - name of a new user-defined solver 77 . path - path (either absolute or relative) the library containing this solver 78 . name_create - name of routine to create method context 79 - routine_create - routine to create method context 80 81 Notes: 82 SNESRegisterDynamic() may be called multiple times to add several user-defined solvers. 83 84 If dynamic libraries are used, then the fourth input argument (routine_create) 85 is ignored. 86 87 Environmental variables such as ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR}, 88 and others of the form ${any_environmental_variable} occuring in pathname will be 89 replaced with appropriate values. 90 91 Sample usage: 92 .vb 93 SNESRegisterDynamic("my_solver",/home/username/my_lib/lib/libg/solaris/mylib.a, 94 "MySolverCreate",MySolverCreate); 95 .ve 96 97 Then, your solver can be chosen with the procedural interface via 98 $ SNESSetType(snes,"my_solver") 99 or at runtime via the option 100 $ -snes_type my_solver 101 102 Level: advanced 103 104 Note: If your function is not being put into a shared library then use SNESRegister() instead 105 106 .keywords: SNES, nonlinear, register 107 108 .seealso: SNESRegisterAll(), SNESRegisterDestroy() 109 M*/ 110 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 111 #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,0) 112 #else 113 #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,d) 114 #endif 115 116 EXTERN PetscErrorCode SNESGetKSP(SNES,KSP*); 117 EXTERN PetscErrorCode SNESGetSolution(SNES,Vec*); 118 EXTERN PetscErrorCode SNESGetSolutionUpdate(SNES,Vec*); 119 EXTERN PetscErrorCode SNESGetFunction(SNES,Vec*,void**,PetscErrorCode(**)(SNES,Vec,Vec,void*)); 120 EXTERN PetscErrorCode SNESView(SNES,PetscViewer); 121 122 EXTERN PetscErrorCode SNESSetOptionsPrefix(SNES,const char[]); 123 EXTERN PetscErrorCode SNESAppendOptionsPrefix(SNES,const char[]); 124 EXTERN PetscErrorCode SNESGetOptionsPrefix(SNES,char*[]); 125 EXTERN PetscErrorCode SNESSetFromOptions(SNES); 126 127 EXTERN PetscErrorCode MatCreateSNESMF(SNES,Vec,Mat*); 128 EXTERN PetscErrorCode MatCreateMF(Vec,Mat*); 129 EXTERN PetscErrorCode MatSNESMFSetBase(Mat,Vec); 130 EXTERN PetscErrorCode MatSNESMFComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 131 EXTERN PetscErrorCode MatSNESMFSetFunction(Mat,Vec,PetscErrorCode(*)(SNES,Vec,Vec,void*),void*); 132 EXTERN PetscErrorCode MatSNESMFSetFunctioni(Mat,PetscErrorCode (*)(PetscInt,Vec,PetscScalar*,void*)); 133 EXTERN PetscErrorCode MatSNESMFSetFunctioniBase(Mat,PetscErrorCode (*)(Vec,void*)); 134 EXTERN PetscErrorCode MatSNESMFAddNullSpace(Mat,MatNullSpace); 135 EXTERN PetscErrorCode MatSNESMFSetHHistory(Mat,PetscScalar[],PetscInt); 136 EXTERN PetscErrorCode MatSNESMFResetHHistory(Mat); 137 EXTERN PetscErrorCode MatSNESMFSetFunctionError(Mat,PetscReal); 138 EXTERN PetscErrorCode MatSNESMFSetPeriod(Mat,PetscInt); 139 EXTERN PetscErrorCode MatSNESMFGetH(Mat,PetscScalar *); 140 EXTERN PetscErrorCode MatSNESMFKSPMonitor(KSP,PetscInt,PetscReal,void *); 141 EXTERN PetscErrorCode MatSNESMFSetFromOptions(Mat); 142 EXTERN PetscErrorCode MatSNESMFCheckPositivity(Vec,Vec,PetscScalar*,void*); 143 EXTERN PetscErrorCode MatSNESMFSetCheckh(Mat,PetscErrorCode (*)(Vec,Vec,PetscScalar*,void*),void*); 144 145 typedef struct _p_MatSNESMFCtx *MatSNESMFCtx; 146 147 #define MATSNESMF_DEFAULT "default" 148 #define MATSNESMF_WP "wp" 149 #define MatSNESMFType char* 150 EXTERN PetscErrorCode MatSNESMFSetType(Mat,const MatSNESMFType); 151 EXTERN PetscErrorCode MatSNESMFRegister(const char[],const char[],const char[],PetscErrorCode (*)(MatSNESMFCtx)); 152 153 /*MC 154 MatSNESMFRegisterDynamic - Adds a method to the MatSNESMF registry. 155 156 Synopsis: 157 PetscErrorCode MatSNESMFRegisterDynamic(char *name_solver,char *path,char *name_create,PetscErrorCode (*routine_create)(MatSNESMF)) 158 159 Not Collective 160 161 Input Parameters: 162 + name_solver - name of a new user-defined compute-h module 163 . path - path (either absolute or relative) the library containing this solver 164 . name_create - name of routine to create method context 165 - routine_create - routine to create method context 166 167 Level: developer 168 169 Notes: 170 MatSNESMFRegisterDynamic) may be called multiple times to add several user-defined solvers. 171 172 If dynamic libraries are used, then the fourth input argument (routine_create) 173 is ignored. 174 175 Sample usage: 176 .vb 177 MatSNESMFRegisterDynamic"my_h",/home/username/my_lib/lib/libO/solaris/mylib.a, 178 "MyHCreate",MyHCreate); 179 .ve 180 181 Then, your solver can be chosen with the procedural interface via 182 $ MatSNESMFSetType(mfctx,"my_h") 183 or at runtime via the option 184 $ -snes_mf_type my_h 185 186 .keywords: MatSNESMF, register 187 188 .seealso: MatSNESMFRegisterAll(), MatSNESMFRegisterDestroy() 189 M*/ 190 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 191 #define MatSNESMFRegisterDynamic(a,b,c,d) MatSNESMFRegister(a,b,c,0) 192 #else 193 #define MatSNESMFRegisterDynamic(a,b,c,d) MatSNESMFRegister(a,b,c,d) 194 #endif 195 196 EXTERN PetscErrorCode MatSNESMFRegisterAll(const char[]); 197 EXTERN PetscErrorCode MatSNESMFRegisterDestroy(void); 198 EXTERN PetscErrorCode MatSNESMFDefaultSetUmin(Mat,PetscReal); 199 EXTERN PetscErrorCode MatSNESMFWPSetComputeNormA(Mat,PetscTruth); 200 EXTERN PetscErrorCode MatSNESMFWPSetComputeNormU(Mat,PetscTruth); 201 202 EXTERN PetscErrorCode MatDAADSetSNES(Mat,SNES); 203 204 EXTERN PetscErrorCode SNESGetType(SNES,SNESType*); 205 EXTERN PetscErrorCode SNESDefaultMonitor(SNES,PetscInt,PetscReal,void *); 206 EXTERN PetscErrorCode SNESRatioMonitor(SNES,PetscInt,PetscReal,void *); 207 EXTERN PetscErrorCode SNESSetRatioMonitor(SNES); 208 EXTERN PetscErrorCode SNESVecViewMonitor(SNES,PetscInt,PetscReal,void *); 209 EXTERN PetscErrorCode SNESVecViewResidualMonitor(SNES,PetscInt,PetscReal,void *); 210 EXTERN PetscErrorCode SNESVecViewUpdateMonitor(SNES,PetscInt,PetscReal,void *); 211 EXTERN PetscErrorCode SNESDefaultSMonitor(SNES,PetscInt,PetscReal,void *); 212 EXTERN PetscErrorCode SNESSetTolerances(SNES,PetscReal,PetscReal,PetscReal,PetscInt,PetscInt); 213 EXTERN PetscErrorCode SNESGetTolerances(SNES,PetscReal*,PetscReal*,PetscReal*,PetscInt*,PetscInt*); 214 EXTERN PetscErrorCode SNESSetTrustRegionTolerance(SNES,PetscReal); 215 EXTERN PetscErrorCode SNESGetIterationNumber(SNES,PetscInt*); 216 EXTERN PetscErrorCode SNESGetFunctionNorm(SNES,PetscScalar*); 217 EXTERN PetscErrorCode SNESGetNumberUnsuccessfulSteps(SNES,PetscInt*); 218 EXTERN PetscErrorCode SNESSetMaximumUnsuccessfulSteps(SNES,PetscInt); 219 EXTERN PetscErrorCode SNESGetMaximumUnsuccessfulSteps(SNES,PetscInt*); 220 EXTERN PetscErrorCode SNESGetNumberLinearIterations(SNES,PetscInt*); 221 EXTERN PetscErrorCode SNES_KSP_SetParametersEW(SNES,PetscInt,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal); 222 EXTERN PetscErrorCode SNES_KSP_SetConvergenceTestEW(SNES); 223 224 /* 225 Reuse the default KSP monitor routines for SNES 226 */ 227 EXTERN PetscErrorCode SNESLGMonitorCreate(const char[],const char[],int,int,int,int,PetscDrawLG*); 228 EXTERN PetscErrorCode SNESLGMonitor(SNES,PetscInt,PetscReal,void*); 229 EXTERN PetscErrorCode SNESLGMonitorDestroy(PetscDrawLG); 230 231 EXTERN PetscErrorCode SNESSetApplicationContext(SNES,void *); 232 EXTERN PetscErrorCode SNESGetApplicationContext(SNES,void **); 233 234 /*E 235 SNESConvergedReason - reason a SNES method was said to 236 have converged or diverged 237 238 Level: beginner 239 240 Notes: this must match finclude/petscsnes.h 241 242 Developer note: The string versions of these are in 243 src/snes/interface/snes.c called convergedreasons. 244 If these enums are changed you much change those. 245 246 .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest() 247 E*/ 248 typedef enum {/* converged */ 249 SNES_CONVERGED_FNORM_ABS = 2, /* F < F_minabs */ 250 SNES_CONVERGED_FNORM_RELATIVE = 3, /* F < F_mintol*F_initial */ 251 SNES_CONVERGED_PNORM_RELATIVE = 4, /* step size small */ 252 SNES_CONVERGED_TR_DELTA = 7, 253 /* diverged */ 254 SNES_DIVERGED_FUNCTION_COUNT = -2, 255 SNES_DIVERGED_FNORM_NAN = -4, 256 SNES_DIVERGED_MAX_IT = -5, 257 SNES_DIVERGED_LS_FAILURE = -6, 258 SNES_DIVERGED_LOCAL_MIN = -8, /* || J^T b || is small, implies converged to local minimum of F() */ 259 SNES_CONVERGED_ITERATING = 0} SNESConvergedReason; 260 261 /*MC 262 SNES_CONVERGED_FNORM_ABS - 2-norm(F) <= abstol 263 264 Level: beginner 265 266 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 267 268 M*/ 269 270 /*MC 271 SNES_CONVERGED_FNORM_RELATIVE - 2-norm(F) <= rtol*2-norm(F(x_0)) where x_0 is the initial guess 272 273 Level: beginner 274 275 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 276 277 M*/ 278 279 /*MC 280 SNES_CONVERGED_PNORM_RELATIVE - The 2-norm of the last step <= xtol * 2-norm(x) where x is the current 281 solution and xtol is the 4th argument to SNESSetTolerances() 282 283 Level: beginner 284 285 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 286 287 M*/ 288 289 /*MC 290 SNES_DIVERGED_FUNCTION_COUNT - The user provided function has been called more times then the final 291 argument to SNESSetTolerances() 292 293 Level: beginner 294 295 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 296 297 M*/ 298 299 /*MC 300 SNES_DIVERGED_FNORM_NAN - the 2-norm of the current function evaluation is not-a-number (NaN), this 301 is usually caused by a division of 0 by 0. 302 303 Level: beginner 304 305 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 306 307 M*/ 308 309 /*MC 310 SNES_DIVERGED_MAX_IT - SNESSolve() has reached the maximum number of iterations requested 311 312 Level: beginner 313 314 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 315 316 M*/ 317 318 /*MC 319 SNES_DIVERGED_LS_FAILURE - The line search has failed. This only occurs for a SNESType of SNESLS 320 321 Level: beginner 322 323 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 324 325 M*/ 326 327 /*MC 328 SNES_DIVERGED_LOCAL_MIN - the algorithm seems to have stagnated at a local minimum that is not zero 329 330 Level: beginner 331 332 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 333 334 M*/ 335 336 /*MC 337 SNES_CONERGED_ITERATING - this only occurs if SNESGetConvergedReason() is called during the SNESSolve() 338 339 Level: beginner 340 341 .seealso: SNESSolve(), SNESGetConvergedReason(), SNESConvergedReason, SNESSetTolerances() 342 343 M*/ 344 345 EXTERN PetscErrorCode SNESSetConvergenceTest(SNES,PetscErrorCode (*)(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*),void*); 346 EXTERN PetscErrorCode SNESConverged_LS(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*); 347 EXTERN PetscErrorCode SNESConverged_TR(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*); 348 EXTERN PetscErrorCode SNESGetConvergedReason(SNES,SNESConvergedReason*); 349 350 EXTERN PetscErrorCode SNESDAFormFunction(SNES,Vec,Vec,void*); 351 EXTERN PetscErrorCode SNESDAComputeJacobianWithAdic(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 352 EXTERN PetscErrorCode SNESDAComputeJacobianWithAdifor(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 353 EXTERN PetscErrorCode SNESDAComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 354 355 /* --------- Solving systems of nonlinear equations --------------- */ 356 EXTERN PetscErrorCode SNESSetFunction(SNES,Vec,PetscErrorCode(*)(SNES,Vec,Vec,void*),void *); 357 EXTERN PetscErrorCode SNESComputeFunction(SNES,Vec,Vec); 358 EXTERN PetscErrorCode SNESSetJacobian(SNES,Mat,Mat,PetscErrorCode(*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void *); 359 EXTERN PetscErrorCode SNESGetJacobian(SNES,Mat*,Mat*,void **,PetscErrorCode(**)(SNES,Vec,Mat*,Mat*,MatStructure*,void*)); 360 EXTERN PetscErrorCode SNESDefaultComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 361 EXTERN PetscErrorCode SNESDefaultComputeJacobianColor(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 362 EXTERN PetscErrorCode SNESSetRhs(SNES,Vec); 363 EXTERN PetscErrorCode SNESSetLineSearch(SNES,PetscErrorCode(*)(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*),void*); 364 EXTERN PetscErrorCode SNESNoLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*); 365 EXTERN PetscErrorCode SNESNoLineSearchNoNorms(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*); 366 EXTERN PetscErrorCode SNESCubicLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*); 367 EXTERN PetscErrorCode SNESQuadraticLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,PetscTruth*); 368 369 EXTERN PetscErrorCode SNESSetLineSearchCheck(SNES,PetscErrorCode(*)(SNES,void*,Vec,PetscTruth*),void*); 370 EXTERN PetscErrorCode SNESSetLineSearchParams(SNES,PetscReal,PetscReal,PetscReal); 371 EXTERN PetscErrorCode SNESGetLineSearchParams(SNES,PetscReal*,PetscReal*,PetscReal*); 372 373 EXTERN PetscErrorCode SNESTestLocalMin(SNES snes); 374 375 /* Should this routine be private? */ 376 EXTERN PetscErrorCode SNESComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*); 377 378 PETSC_EXTERN_CXX_END 379 #endif 380