1 /* $Id: petscsnes.h,v 1.111 2001/08/06 21:17:05 bsmith Exp $ */ 2 /* 3 User interface for the nonlinear solvers package. 4 */ 5 #if !defined(__PETSCSNES_H) 6 #define __PETSCSNES_H 7 #include "petscsles.h" 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, SLES, 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 typedef char *SNESType; 33 34 /* Logging support */ 35 extern int SNES_COOKIE; 36 extern int SNES_Solve, SNES_LineSearch, SNES_FunctionEval, SNES_JacobianEval; 37 38 39 EXTERN int SNESInitializePackage(char *); 40 41 EXTERN int SNESCreate(MPI_Comm,SNES*); 42 EXTERN int SNESDestroy(SNES); 43 EXTERN int SNESSetType(SNES,SNESType); 44 EXTERN int SNESSetMonitor(SNES,int(*)(SNES,int,PetscReal,void*),void *,int (*)(void *)); 45 EXTERN int SNESClearMonitor(SNES); 46 EXTERN int SNESSetConvergenceHistory(SNES,PetscReal*,int *,int,PetscTruth); 47 EXTERN int SNESGetConvergenceHistory(SNES,PetscReal**,int **,int *); 48 EXTERN int SNESSetUp(SNES,Vec); 49 EXTERN int SNESSolve(SNES,Vec,int*); 50 51 EXTERN int SNESAddOptionsChecker(int (*)(SNES)); 52 53 EXTERN int SNESSetRhsBC(SNES, int (*)(SNES, Vec, void *)); 54 EXTERN int SNESDefaultRhsBC(SNES, Vec, void *); 55 EXTERN int SNESSetSolutionBC(SNES, int (*)(SNES, Vec, void *)); 56 EXTERN int SNESDefaultSolutionBC(SNES, Vec, void *); 57 EXTERN int SNESSetUpdate(SNES, int (*)(SNES, int)); 58 EXTERN int SNESDefaultUpdate(SNES, int); 59 60 extern PetscFList SNESList; 61 EXTERN int SNESRegisterDestroy(void); 62 EXTERN int SNESRegisterAll(char *); 63 64 EXTERN int SNESRegister(char*,char*,char*,int(*)(SNES)); 65 66 /*MC 67 SNESRegisterDynamic - Adds a method to the nonlinear solver package. 68 69 Synopsis: 70 int SNESRegisterDynamic(char *name_solver,char *path,char *name_create,int (*routine_create)(SNES)) 71 72 Not collective 73 74 Input Parameters: 75 + name_solver - name of a new user-defined solver 76 . path - path (either absolute or relative) the library containing this solver 77 . name_create - name of routine to create method context 78 - routine_create - routine to create method context 79 80 Notes: 81 SNESRegisterDynamic() may be called multiple times to add several user-defined solvers. 82 83 If dynamic libraries are used, then the fourth input argument (routine_create) 84 is ignored. 85 86 Environmental variables such as ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR}, ${BOPT}, 87 and others of the form ${any_environmental_variable} occuring in pathname will be 88 replaced with appropriate values. 89 90 Sample usage: 91 .vb 92 SNESRegisterDynamic("my_solver",/home/username/my_lib/lib/libg/solaris/mylib.a, 93 "MySolverCreate",MySolverCreate); 94 .ve 95 96 Then, your solver can be chosen with the procedural interface via 97 $ SNESSetType(snes,"my_solver") 98 or at runtime via the option 99 $ -snes_type my_solver 100 101 Level: advanced 102 103 Note: If your function is not being put into a shared library then use SNESRegister() instead 104 105 .keywords: SNES, nonlinear, register 106 107 .seealso: SNESRegisterAll(), SNESRegisterDestroy() 108 M*/ 109 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 110 #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,0) 111 #else 112 #define SNESRegisterDynamic(a,b,c,d) SNESRegister(a,b,c,d) 113 #endif 114 115 EXTERN int SNESGetSLES(SNES,SLES*); 116 EXTERN int SNESGetSolution(SNES,Vec*); 117 EXTERN int SNESGetSolutionUpdate(SNES,Vec*); 118 EXTERN int SNESGetFunction(SNES,Vec*,void**,int(**)(SNES,Vec,Vec,void*)); 119 EXTERN int SNESView(SNES,PetscViewer); 120 121 EXTERN int SNESSetOptionsPrefix(SNES,char*); 122 EXTERN int SNESAppendOptionsPrefix(SNES,char*); 123 EXTERN int SNESGetOptionsPrefix(SNES,char**); 124 EXTERN int SNESSetFromOptions(SNES); 125 126 EXTERN int MatCreateSNESMF(SNES,Vec,Mat*); 127 EXTERN int MatCreateMF(Vec,Mat*); 128 EXTERN int MatSNESMFSetBase(Mat,Vec); 129 EXTERN int MatSNESMFComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 130 EXTERN int MatSNESMFSetFunction(Mat,Vec,int(*)(SNES,Vec,Vec,void*),void*); 131 EXTERN int MatSNESMFSetFunctioni(Mat,int (*)(int,Vec,PetscScalar*,void*)); 132 EXTERN int MatSNESMFSetFunctioniBase(Mat,int (*)(Vec,void*)); 133 EXTERN int MatSNESMFAddNullSpace(Mat,MatNullSpace); 134 EXTERN int MatSNESMFSetHHistory(Mat,PetscScalar *,int); 135 EXTERN int MatSNESMFResetHHistory(Mat); 136 EXTERN int MatSNESMFSetFunctionError(Mat,PetscReal); 137 EXTERN int MatSNESMFSetPeriod(Mat,int); 138 EXTERN int MatSNESMFGetH(Mat,PetscScalar *); 139 EXTERN int MatSNESMFKSPMonitor(KSP,int,PetscReal,void *); 140 EXTERN int MatSNESMFSetFromOptions(Mat); 141 EXTERN int MatSNESMFCheckPositivity(Vec,Vec,PetscScalar*,void*); 142 EXTERN int MatSNESMFSetCheckh(Mat,int (*)(Vec,Vec,PetscScalar*,void*),void*); 143 144 typedef struct _p_MatSNESMFCtx *MatSNESMFCtx; 145 146 #define MATSNESMF_DEFAULT "default" 147 #define MATSNESMF_WP "wp" 148 typedef char* MatSNESMFType; 149 EXTERN int MatSNESMFSetType(Mat,MatSNESMFType); 150 EXTERN int MatSNESMFRegister(char *,char *,char *,int (*)(MatSNESMFCtx)); 151 152 /*MC 153 MatSNESMFRegisterDynamic - Adds a method to the MatSNESMF registry. 154 155 Synopsis: 156 int MatSNESMFRegisterDynamic(char *name_solver,char *path,char *name_create,int (*routine_create)(MatSNESMF)) 157 158 Not Collective 159 160 Input Parameters: 161 + name_solver - name of a new user-defined compute-h module 162 . path - path (either absolute or relative) the library containing this solver 163 . name_create - name of routine to create method context 164 - routine_create - routine to create method context 165 166 Level: developer 167 168 Notes: 169 MatSNESMFRegisterDynamic) may be called multiple times to add several user-defined solvers. 170 171 If dynamic libraries are used, then the fourth input argument (routine_create) 172 is ignored. 173 174 Sample usage: 175 .vb 176 MatSNESMFRegisterDynamic"my_h",/home/username/my_lib/lib/libO/solaris/mylib.a, 177 "MyHCreate",MyHCreate); 178 .ve 179 180 Then, your solver can be chosen with the procedural interface via 181 $ MatSNESMFSetType(mfctx,"my_h") 182 or at runtime via the option 183 $ -snes_mf_type my_h 184 185 .keywords: MatSNESMF, register 186 187 .seealso: MatSNESMFRegisterAll(), MatSNESMFRegisterDestroy() 188 M*/ 189 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 190 #define MatSNESMFRegisterDynamic(a,b,c,d) MatSNESMFRegister(a,b,c,0) 191 #else 192 #define MatSNESMFRegisterDynamic(a,b,c,d) MatSNESMFRegister(a,b,c,d) 193 #endif 194 195 EXTERN int MatSNESMFRegisterAll(char *); 196 EXTERN int MatSNESMFRegisterDestroy(void); 197 EXTERN int MatSNESMFDefaultSetUmin(Mat,PetscReal); 198 EXTERN int MatSNESMFWPSetComputeNormA(Mat,PetscTruth); 199 EXTERN int MatSNESMFWPSetComputeNormU(Mat,PetscTruth); 200 201 EXTERN int MatDAADSetSNES(Mat,SNES); 202 203 EXTERN int SNESGetType(SNES,SNESType*); 204 EXTERN int SNESDefaultMonitor(SNES,int,PetscReal,void *); 205 EXTERN int SNESRatioMonitor(SNES,int,PetscReal,void *); 206 EXTERN int SNESSetRatioMonitor(SNES); 207 EXTERN int SNESVecViewMonitor(SNES,int,PetscReal,void *); 208 EXTERN int SNESVecViewResidualMonitor(SNES,int,PetscReal,void *); 209 EXTERN int SNESVecViewUpdateMonitor(SNES,int,PetscReal,void *); 210 EXTERN int SNESDefaultSMonitor(SNES,int,PetscReal,void *); 211 EXTERN int SNESSetTolerances(SNES,PetscReal,PetscReal,PetscReal,int,int); 212 EXTERN int SNESGetTolerances(SNES,PetscReal*,PetscReal*,PetscReal*,int*,int*); 213 EXTERN int SNESSetTrustRegionTolerance(SNES,PetscReal); 214 EXTERN int SNESGetIterationNumber(SNES,int*); 215 EXTERN int SNESGetFunctionNorm(SNES,PetscScalar*); 216 EXTERN int SNESGetNumberUnsuccessfulSteps(SNES,int*); 217 EXTERN int SNESSetMaximumUnsuccessfulSteps(SNES,int); 218 EXTERN int SNESGetMaximumUnsuccessfulSteps(SNES,int*); 219 EXTERN int SNESGetNumberLinearIterations(SNES,int*); 220 EXTERN int SNES_KSP_SetParametersEW(SNES,int,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal,PetscReal); 221 EXTERN int SNES_KSP_SetConvergenceTestEW(SNES); 222 223 /* 224 Reuse the default KSP monitor routines for SNES 225 */ 226 EXTERN int SNESLGMonitorCreate(char*,char*,int,int,int,int,PetscDrawLG*); 227 EXTERN int SNESLGMonitor(SNES,int,PetscReal,void*); 228 EXTERN int SNESLGMonitorDestroy(PetscDrawLG); 229 230 EXTERN int SNESSetApplicationContext(SNES,void *); 231 EXTERN int SNESGetApplicationContext(SNES,void **); 232 233 /*E 234 SNESConvergedReason - reason a SNES method was said to 235 have converged or diverged 236 237 Level: beginner 238 239 Notes: this must match finclude/petscsnes.h 240 241 .seealso: SNESSolve(), SNESGetConvergedReason(), KSPConvergedReason, SNESSetConvergenceTest() 242 E*/ 243 typedef enum {/* converged */ 244 SNES_CONVERGED_FNORM_ABS = 2, /* F < F_minabs */ 245 SNES_CONVERGED_FNORM_RELATIVE = 3, /* F < F_mintol*F_initial */ 246 SNES_CONVERGED_PNORM_RELATIVE = 4, /* step size small */ 247 SNES_CONVERGED_GNORM_ABS = 5, /* grad F < grad F_min */ 248 SNES_CONVERGED_TR_REDUCTION = 6, 249 SNES_CONVERGED_TR_DELTA = 7, 250 /* diverged */ 251 SNES_DIVERGED_FUNCTION_COUNT = -2, 252 SNES_DIVERGED_FNORM_NAN = -4, 253 SNES_DIVERGED_MAX_IT = -5, 254 SNES_DIVERGED_LS_FAILURE = -6, 255 SNES_DIVERGED_TR_REDUCTION = -7, 256 SNES_DIVERGED_LOCAL_MIN = -8, /* || J^T b || is small, implies converged to local minimum of F() */ 257 SNES_CONVERGED_ITERATING = 0} SNESConvergedReason; 258 259 EXTERN int SNESSetConvergenceTest(SNES,int (*)(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*),void*); 260 EXTERN int SNESConverged_LS(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*); 261 EXTERN int SNESConverged_TR(SNES,PetscReal,PetscReal,PetscReal,SNESConvergedReason*,void*); 262 EXTERN int SNESGetConvergedReason(SNES,SNESConvergedReason*); 263 264 EXTERN int SNESDAFormFunction(SNES,Vec,Vec,void*); 265 EXTERN int SNESDAComputeJacobianWithAdic(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 266 EXTERN int SNESDAComputeJacobianWithAdifor(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 267 EXTERN int SNESDAComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 268 269 /* --------- Solving systems of nonlinear equations --------------- */ 270 EXTERN int SNESSetFunction(SNES,Vec,int(*)(SNES,Vec,Vec,void*),void *); 271 EXTERN int SNESComputeFunction(SNES,Vec,Vec); 272 EXTERN int SNESSetJacobian(SNES,Mat,Mat,int(*)(SNES,Vec,Mat*,Mat*,MatStructure*,void*),void *); 273 EXTERN int SNESGetJacobian(SNES,Mat*,Mat*,void **,int(**)(SNES,Vec,Mat*,Mat*,MatStructure*,void*)); 274 EXTERN int SNESDefaultComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 275 EXTERN int SNESDefaultComputeJacobianColor(SNES,Vec,Mat*,Mat*,MatStructure*,void*); 276 EXTERN int SNESSetLineSearch(SNES,int(*)(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,int*),void*); 277 EXTERN int SNESNoLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,int*); 278 EXTERN int SNESNoLineSearchNoNorms(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,int*); 279 EXTERN int SNESCubicLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,int*); 280 EXTERN int SNESQuadraticLineSearch(SNES,void*,Vec,Vec,Vec,Vec,Vec,PetscReal,PetscReal*,PetscReal*,int*); 281 EXTERN int SNESSetLineSearchCheck(SNES,int(*)(SNES,void*,Vec,PetscTruth*),void*); 282 EXTERN int SNESSetLineSearchParams(SNES,PetscReal,PetscReal,PetscReal); 283 EXTERN int SNESGetLineSearchParams(SNES,PetscReal*,PetscReal*,PetscReal*); 284 285 EXTERN int SNESTestLocalMin(SNES snes); 286 287 /* Should this routine be private? */ 288 EXTERN int SNESComputeJacobian(SNES,Vec,Mat*,Mat*,MatStructure*); 289 290 #endif 291 292