1 /* $Id: petsc.h,v 1.281 2001/01/15 21:50:04 bsmith Exp bsmith $ */ 2 /* 3 This is the main PETSc include file (for C and C++). It is included by all 4 other PETSc include files, so it almost never has to be specifically included. 5 */ 6 #if !defined(__PETSC_H) 7 #define __PETSC_H 8 9 /* ========================================================================== */ 10 /* 11 Current PETSc version number and release date 12 */ 13 #include "petscversion.h" 14 15 /* ========================================================================== */ 16 /* 17 The PETSc configuration file. Contains various definitions that 18 handle portability issues and the presence of machine features. 19 20 petscconf.h is contained in bmake/${PETSC_ARCH}/petscconf.h it is 21 found automatically by the compiler due to the -I${PETSC_DIR}/bmake/${PETSC_ARCH} 22 in the bmake/common_variables definition of PETSC_INCLUDE 23 */ 24 #include "petscconf.h" 25 26 /* ========================================================================== */ 27 28 #include <stdio.h> 29 /* 30 Defines the interface to MPI allowing the use of all MPI functions. 31 */ 32 #include "mpi.h" 33 34 /* 35 EXTERN indicates a PETSc function defined elsewhere 36 */ 37 #define EXTERN extern 38 39 /* 40 Defines some elementary mathematics functions and constants. 41 */ 42 #include "petscmath.h" 43 44 /* 45 Basic PETSc constants 46 */ 47 typedef enum { PETSC_FALSE,PETSC_TRUE } PetscTruth; 48 #define PETSC_YES PETSC_TRUE 49 #define PETSC_NO PETSC_FALSE 50 #define PETSC_NULL 0 51 #define PETSC_IGNORE PETSC_NULL 52 #define PETSC_DECIDE -1 53 #define PETSC_DETERMINE PETSC_DECIDE 54 #define PETSC_DEFAULT -2 55 56 extern MPI_Comm PETSC_COMM_WORLD; 57 extern MPI_Comm PETSC_COMM_SELF; 58 extern PetscTruth PetscInitializeCalled; 59 EXTERN int PetscSetCommWorld(MPI_Comm); 60 EXTERN int PetscSetHelpVersionFunctions(int (*)(MPI_Comm),int (*)(MPI_Comm)); 61 62 /* 63 Defines the malloc employed by PETSc. Users may use these routines as well. 64 */ 65 #define PetscMalloc(a,b) (*PetscTrMalloc)(a,__LINE__,__FUNC__,__FILE__,__SDIR__,(void**)b) 66 #define PetscNew(A,b) PetscMalloc(sizeof(A),b) 67 #define PetscFree(a) (*PetscTrFree)(a,__LINE__,__FUNC__,__FILE__,__SDIR__) 68 EXTERN int (*PetscTrMalloc)(int,int,char*,char*,char*,void**); 69 EXTERN int (*PetscTrFree)(void *,int,char*,char*,char*); 70 EXTERN int PetscSetMalloc(int (*)(int,int,char*,char*,char*,void**),int (*)(void *,int,char*,char*,char*)); 71 EXTERN int PetscClearMalloc(void); 72 73 /* 74 Routines for tracing memory corruption/bleeding with default PETSc 75 memory allocation 76 */ 77 EXTERN int PetscTrDump(FILE *); 78 EXTERN int PetscTrSpace(PetscLogDouble *,PetscLogDouble *,PetscLogDouble *); 79 EXTERN int PetscTrValid(int,const char[],const char[],const char[]); 80 EXTERN int PetscTrDebugLevel(int); 81 EXTERN int PetscTrLog(void); 82 EXTERN int PetscTrLogDump(FILE *); 83 EXTERN int PetscGetResidentSetSize(PetscLogDouble *); 84 85 86 /* 87 Variable type where we stash PETSc object pointers in Fortran. 88 Assumes that sizeof(long) == sizeof(void*)which is true on 89 all machines that we know. 90 */ 91 #define PetscFortranAddr long 92 93 /* 94 Constants and functions used for handling different basic data types. 95 These are used, for example, in binary IO routines 96 */ 97 typedef enum {PETSC_INT = 0,PETSC_DOUBLE = 1,PETSC_COMPLEX = 2, 98 PETSC_LONG =3 ,PETSC_SHORT = 4,PETSC_FLOAT = 5, 99 PETSC_CHAR = 6,PETSC_LOGICAL = 7} PetscDataType; 100 #if defined(PETSC_USE_COMPLEX) 101 #define PETSC_SCALAR PETSC_COMPLEX 102 #else 103 #define PETSC_SCALAR PETSC_DOUBLE 104 #endif 105 #if defined(PETSC_USE_SINGLE) 106 #define PETSC_REAL PETSC_FLOAT 107 #else 108 #define PETSC_REAL PETSC_DOUBLE 109 #endif 110 #define PETSC_FORTRANADDR PETSC_LONG 111 112 typedef enum {PETSC_INT_SIZE = sizeof(int),PETSC_DOUBLE_SIZE = sizeof(double), 113 PETSC_COMPLEX_SIZE = sizeof(Scalar),PETSC_LONG_SIZE=sizeof(long), 114 PETSC_SHORT_SIZE = sizeof(short),PETSC_FLOAT_SIZE = sizeof(float), 115 PETSC_CHAR_SIZE = sizeof(char),PETSC_LOGICAL_SIZE = 1} PetscDataTypeSize; 116 117 #if defined(PETSC_USE_COMPLEX) 118 #define PETSC_SCALAR_SIZE PETSC_COMPLEX_SIZE 119 #else 120 #define PETSC_SCALAR_SIZE PETSC_DOUBLE_SIZE 121 #endif 122 #if defined(PETSC_USE_SINGLE) 123 #define PETSC_REAL_SIZE PETSC_FLOAT_SIZE 124 #else 125 #define PETSC_REAL_SIZE PETSC_DOUBLE_SIZE 126 #endif 127 #define PETSC_FORTRANADDR_SIZE PETSC_LONG_SIZE 128 129 130 EXTERN int PetscDataTypeToMPIDataType(PetscDataType,MPI_Datatype*); 131 EXTERN int PetscDataTypeGetSize(PetscDataType,int*); 132 EXTERN int PetscDataTypeGetName(PetscDataType,char*[]); 133 134 /* 135 Basic memory and string operations. These are usually simple wrappers 136 around the basic Unix system calls, but a few of them have additional 137 functionality and/or error checking. 138 */ 139 EXTERN int PetscMemcpy(void *,const void *,int); 140 EXTERN int PetscBitMemcpy(void*,int,const void*,int,int,PetscDataType); 141 EXTERN int PetscMemmove(void *,void *,int); 142 EXTERN int PetscMemzero(void *,int); 143 EXTERN int PetscMemcmp(const void*,const void*,int,PetscTruth *); 144 EXTERN int PetscStrlen(const char[],int*); 145 EXTERN int PetscStrcmp(const char[],const char[],PetscTruth *); 146 EXTERN int PetscStrgrt(const char[],const char[],PetscTruth *); 147 EXTERN int PetscStrcasecmp(const char[],const char[],PetscTruth*); 148 EXTERN int PetscStrncmp(const char[],const char[],int,PetscTruth*); 149 EXTERN int PetscStrcpy(char[],const char[]); 150 EXTERN int PetscStrcat(char[],const char[]); 151 EXTERN int PetscStrncat(char[],const char[],int); 152 EXTERN int PetscStrncpy(char[],const char[],int); 153 EXTERN int PetscStrchr(const char[],char,char **); 154 EXTERN int PetscStrtolower(char[]); 155 EXTERN int PetscStrrchr(const char[],char,char **); 156 EXTERN int PetscStrstr(const char[],const char[],char **); 157 EXTERN int PetscStrtok(const char[],const char[],char **); 158 EXTERN int PetscStrallocpy(const char[],char **); 159 EXTERN int PetscStrreplace(MPI_Comm,const char[],char*,int); 160 #define PetscStrfree(a) ((a) ? PetscFree(a) : 0) 161 162 /* 163 These are MPI operations for MPI_Allreduce() etc 164 */ 165 EXTERN MPI_Op PetscMaxSum_Op; 166 #if defined(PETSC_USE_COMPLEX) 167 EXTERN MPI_Op PetscSum_Op; 168 #else 169 #define PetscSum_Op MPI_SUM 170 #endif 171 172 /* 173 Each PETSc object class has it's own cookie (internal integer in the 174 data structure used for error checking). These are all defined by an offset 175 from the lowest one, PETSC_COOKIE. 176 */ 177 #define PETSC_COOKIE 1211211 178 #define PETSC_MAX_COOKIES 60 179 #define PETSC_LARGEST_COOKIE_PREDEFINED PETSC_COOKIE + 30 180 #define PETSC_LARGEST_COOKIE_ALLOWED PETSC_COOKIE + PETSC_MAX_COOKIES 181 extern int PETSC_LARGEST_COOKIE; 182 183 /*S 184 PetscObject - any PETSc object, PetscViewer, Mat, Vec, SLES etc 185 186 Level: beginner 187 188 .seealso: PetscObjectDestroy(), PetscObjectView(), PetscObjectGetName(), PetscObjectSetName() 189 S*/ 190 typedef struct _p_PetscObject* PetscObject; 191 192 /*S 193 PetscFList - Linked list of functions, possibly stored in dynamic libraries, accessed 194 by string name 195 196 Level: advanced 197 198 .seealso: PetscFListAdd(), PetscFListDestroy() 199 S*/ 200 typedef struct _PetscFList *PetscFList; 201 202 #include "petscviewer.h" 203 #include "petscoptions.h" 204 205 EXTERN int PetscShowMemoryUsage(PetscViewer,char*); 206 EXTERN int PetscGetTime(PetscLogDouble*); 207 EXTERN int PetscGetCPUTime(PetscLogDouble*); 208 EXTERN int PetscSleep(int); 209 210 /* 211 Initialization of PETSc 212 */ 213 EXTERN int PetscInitialize(int*,char***,char[],const char[]); 214 EXTERN int PetscInitializeNoArguments(void); 215 EXTERN int PetscFinalize(void); 216 EXTERN int PetscInitializeFortran(void); 217 218 /* 219 Functions that can act on any PETSc object. 220 */ 221 EXTERN int PetscObjectDestroy(PetscObject); 222 EXTERN int PetscObjectExists(PetscObject,PetscTruth*); 223 EXTERN int PetscObjectGetComm(PetscObject,MPI_Comm *); 224 EXTERN int PetscObjectGetCookie(PetscObject,int *); 225 EXTERN int PetscObjectGetType(PetscObject,int *); 226 EXTERN int PetscObjectSetName(PetscObject,const char[]); 227 EXTERN int PetscObjectGetName(PetscObject,char*[]); 228 EXTERN int PetscObjectReference(PetscObject); 229 EXTERN int PetscObjectGetReference(PetscObject,int*); 230 EXTERN int PetscObjectDereference(PetscObject); 231 EXTERN int PetscObjectGetNewTag(PetscObject,int *); 232 EXTERN int PetscCommGetNewTag(MPI_Comm,int *); 233 EXTERN int PetscObjectView(PetscObject,PetscViewer); 234 EXTERN int PetscObjectCompose(PetscObject,const char[],PetscObject); 235 EXTERN int PetscObjectQuery(PetscObject,const char[],PetscObject *); 236 EXTERN int PetscObjectComposeFunction(PetscObject,const char[],const char[],void *); 237 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 238 #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,0) 239 #else 240 #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,(void*)(d)) 241 #endif 242 EXTERN int PetscObjectQueryFunction(PetscObject,const char[],void **); 243 EXTERN int PetscObjectSetOptionsPrefix(PetscObject,const char[]); 244 EXTERN int PetscObjectAppendOptionsPrefix(PetscObject,const char[]); 245 EXTERN int PetscObjectPrependOptionsPrefix(PetscObject,const char[]); 246 EXTERN int PetscObjectGetOptionsPrefix(PetscObject,char*[]); 247 EXTERN int PetscObjectPublish(PetscObject); 248 EXTERN int PetscObjectChangeTypeName(PetscObject,char *); 249 EXTERN int PetscObjectRegisterDestroy(PetscObject); 250 EXTERN int PetscObjectRegisterDestroyAll(void); 251 EXTERN int PetscObjectName(PetscObject); 252 EXTERN int PetscTypeCompare(PetscObject,char*,PetscTruth*); 253 254 /* 255 Defines PETSc error handling. 256 */ 257 #include "petscerror.h" 258 259 /*S 260 PetscOList - Linked list of PETSc objects, accessable by string name 261 262 Level: advanced 263 264 .seealso: PetscOListAdd(), PetscOListDestroy(), PetscOListFind() 265 S*/ 266 typedef struct _PetscOList *PetscOList; 267 268 EXTERN int PetscOListDestroy(PetscOList *); 269 EXTERN int PetscOListFind(PetscOList,const char[],PetscObject*); 270 EXTERN int PetscOListReverseFind(PetscOList,PetscObject,char**); 271 EXTERN int PetscOListAdd(PetscOList *,const char[],PetscObject); 272 EXTERN int PetscOListDuplicate(PetscOList,PetscOList *); 273 274 /* 275 Dynamic library lists. Lists of names of routines in dynamic 276 link libraries that will be loaded as needed. 277 */ 278 EXTERN int PetscFListAdd(PetscFList*,const char[],const char[],int (*)(void *)); 279 EXTERN int PetscFListDestroy(PetscFList*); 280 EXTERN int PetscFListFind(MPI_Comm,PetscFList,const char[],int (**)(void*)); 281 EXTERN int PetscFListPrintTypes(MPI_Comm,FILE*,const char[],const char[],char *,char *,PetscFList); 282 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 283 #define PetscFListAddDynamic(a,b,p,c) PetscFListAdd(a,b,p,0) 284 #else 285 #define PetscFListAddDynamic(a,b,p,c) PetscFListAdd(a,b,p,(int (*)(void *))c) 286 #endif 287 EXTERN int PetscFListDuplicate(PetscFList,PetscFList *); 288 EXTERN int PetscFListView(PetscFList,PetscViewer); 289 EXTERN int PetscFListConcat(const char [],const char [],char []); 290 EXTERN int PetscFListGet(PetscFList,char ***,int*); 291 292 /*S 293 PetscDLLibraryList - Linked list of dynamics libraries to search for functions 294 295 Level: advanced 296 297 PETSC_USE_DYNAMIC_LIBRARIES must be defined in petscconf.h to use dynamic libraries 298 299 .seealso: PetscDLLibraryOpen() 300 S*/ 301 typedef struct _PetscDLLibraryList *PetscDLLibraryList; 302 extern PetscDLLibraryList DLLibrariesLoaded; 303 EXTERN int PetscDLLibraryRetrieve(MPI_Comm,const char[],char *,int,PetscTruth *); 304 EXTERN int PetscDLLibraryOpen(MPI_Comm,const char[],void **); 305 EXTERN int PetscDLLibrarySym(MPI_Comm,PetscDLLibraryList *,const char[],const char[],void **); 306 EXTERN int PetscDLLibraryAppend(MPI_Comm,PetscDLLibraryList *,const char[]); 307 EXTERN int PetscDLLibraryPrepend(MPI_Comm,PetscDLLibraryList *,const char[]); 308 EXTERN int PetscDLLibraryClose(PetscDLLibraryList); 309 EXTERN int PetscDLLibraryPrintPath(void); 310 EXTERN int PetscDLLibraryGetInfo(void *,char *,char **); 311 312 /* 313 Mechanism for translating PETSc object representations between languages 314 Not currently used. 315 */ 316 typedef enum {PETSC_LANGUAGE_C,PETSC_LANGUAGE_CPP} PetscLanguage; 317 #define PETSC_LANGUAGE_F77 PETSC_LANGUAGE_C 318 EXTERN int PetscObjectComposeLanguage(PetscObject,PetscLanguage,void *); 319 EXTERN int PetscObjectQueryLanguage(PetscObject,PetscLanguage,void **); 320 321 /* 322 Useful utility routines 323 */ 324 EXTERN int PetscSplitOwnership(MPI_Comm,int*,int*); 325 EXTERN int PetscSplitOwnershipBlock(MPI_Comm,int,int*,int*); 326 EXTERN int PetscSequentialPhaseBegin(MPI_Comm,int); 327 EXTERN int PetscSequentialPhaseEnd(MPI_Comm,int); 328 EXTERN int PetscBarrier(PetscObject); 329 EXTERN int PetscMPIDump(FILE*); 330 331 #define PetscNot(a) ((a) ? PETSC_FALSE : PETSC_TRUE) 332 /* 333 Defines basic graphics available from PETSc. 334 */ 335 #include "petscdraw.h" 336 337 /* 338 Defines the base data structures for all PETSc objects 339 */ 340 #include "petschead.h" 341 342 /* 343 Defines PETSc profiling. 344 */ 345 #include "petsclog.h" 346 347 /* 348 For locking, unlocking and destroying AMS memories associated with 349 PETSc objects 350 */ 351 #if defined(PETSC_HAVE_AMS) 352 353 extern PetscTruth PetscAMSPublishAll; 354 #define PetscPublishAll(v) (PetscAMSPublishAll ? PetscObjectPublish((PetscObject)v) : 0) 355 #define PetscObjectTakeAccess(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_take_access(((PetscObject)(obj))->amem)) 356 #define PetscObjectGrantAccess(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_grant_access(((PetscObject)(obj))->amem)) 357 #define PetscObjectDepublish(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_destroy(((PetscObject)(obj))->amem)); \ 358 ((PetscObject)(obj))->amem = -1; 359 360 #else 361 362 #define PetscPublishAll(v) 0 363 #define PetscObjectTakeAccess(obj) 0 364 #define PetscObjectGrantAccess(obj) 0 365 #define PetscObjectDepublish(obj) 0 366 367 #endif 368 369 370 371 /* 372 This code allows one to pass a MPI communicator between 373 C and Fortran. MPI 2.0 defines a standard API for doing this. 374 The code here is provided to allow PETSc to work with MPI 1.1 375 standard MPI libraries. 376 */ 377 EXTERN int MPICCommToFortranComm(MPI_Comm,int *); 378 EXTERN int MPIFortranCommToCComm(int,MPI_Comm*); 379 380 /* 381 Simple PETSc parallel IO for ASCII printing 382 */ 383 EXTERN int PetscFixFilename(const char[],char[]); 384 EXTERN int PetscFOpen(MPI_Comm,const char[],const char[],FILE**); 385 EXTERN int PetscFClose(MPI_Comm,FILE*); 386 EXTERN int PetscFPrintf(MPI_Comm,FILE*,const char[],...); 387 EXTERN int PetscPrintf(MPI_Comm,const char[],...); 388 EXTERN int (*PetscErrorPrintf)(const char[],...); 389 EXTERN int (*PetscHelpPrintf)(MPI_Comm,const char[],...); 390 EXTERN int PetscPOpen(MPI_Comm,char *,char*,const char[],FILE **); 391 EXTERN int PetscPClose(MPI_Comm,FILE*); 392 EXTERN int PetscSynchronizedPrintf(MPI_Comm,const char[],...); 393 EXTERN int PetscSynchronizedFPrintf(MPI_Comm,FILE*,const char[],...); 394 EXTERN int PetscSynchronizedFlush(MPI_Comm); 395 EXTERN int PetscSynchronizedFGets(MPI_Comm,FILE*,int,char[]); 396 EXTERN int PetscStartMatlab(MPI_Comm,char *,char*,FILE**); 397 EXTERN int PetscStartJava(MPI_Comm,char *,char*,FILE**); 398 399 EXTERN int PetscPopUpSelect(MPI_Comm,char*,char*,int,char**,int*); 400 /*S 401 PetscObjectContainer - Simple PETSc object that contains a pointer to any required data 402 403 Level: advanced 404 405 .seealso: PetscObject, PetscObjectContainerCreate() 406 S*/ 407 typedef struct _p_PetscObjectContainer* PetscObjectContainer; 408 EXTERN int PetscObjectContainerGetPointer(PetscObjectContainer,void **); 409 EXTERN int PetscObjectContainerSetPointer(PetscObjectContainer,void *); 410 EXTERN int PetscObjectContainerDestroy(PetscObjectContainer); 411 EXTERN int PetscObjectContainerCreate(MPI_Comm comm,PetscObjectContainer *); 412 413 /* 414 For incremental debugging 415 */ 416 extern PetscTruth PetscCompare; 417 EXTERN int PetscCompareDouble(double); 418 EXTERN int PetscCompareScalar(Scalar); 419 EXTERN int PetscCompareInt(int); 420 421 /* 422 For use in debuggers 423 */ 424 extern int PetscGlobalRank,PetscGlobalSize; 425 EXTERN int PetscIntView(int,int[],PetscViewer); 426 EXTERN int PetscDoubleView(int,double[],PetscViewer); 427 EXTERN int PetscScalarView(int,Scalar[],PetscViewer); 428 429 /* 430 Allows accessing Matlab Engine 431 */ 432 #include "petscengine.h" 433 434 /* 435 C code optimization is often enhanced by telling the compiler 436 that certain pointer arguments to functions are not aliased to 437 to other arguments. This is not yet ANSI C standard so we define 438 the macro "restrict" to indicate that the variable is not aliased 439 to any other argument. 440 */ 441 #if defined(PETSC_HAVE_RESTRICT) && !defined(__cplusplus) 442 #define restrict _Restrict 443 #else 444 #define restrict 445 #endif 446 447 /* 448 Determine if some of the kernel computation routines use 449 Fortran (rather than C) for the numerical calculations. On some machines 450 and compilers (like complex numbers) the Fortran version of the routines 451 is faster than the C/C++ versions. The flag PETSC_USE_FORTRAN_KERNELS 452 would be set in the petscconf.h file 453 */ 454 #if defined(PETSC_USE_FORTRAN_KERNELS) 455 456 #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTAIJ) 457 #define PETSC_USE_FORTRAN_KERNEL_MULTAIJ 458 #endif 459 460 #if !defined(PETSC_USE_FORTRAN_KERNEL_NORMSQR) 461 #define PETSC_USE_FORTRAN_KERNEL_NORMSQR 462 #endif 463 464 #if !defined(PETSC_USE_FORTRAN_KERNEL_MAXPY) 465 #define PETSC_USE_FORTRAN_KERNEL_MAXPY 466 #endif 467 468 #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ) 469 #define PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ 470 #endif 471 472 #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ) 473 #define PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ 474 #endif 475 476 #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ) 477 #define PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ 478 #endif 479 480 #if !defined(PETSC_USE_FORTRAN_KERNEL_MDOT) 481 #define PETSC_USE_FORTRAN_KERNEL_MDOT 482 #endif 483 484 #if !defined(PETSC_USE_FORTRAN_KERNEL_XTIMESY) 485 #define PETSC_USE_FORTRAN_KERNEL_XTIMESY 486 #endif 487 488 #endif 489 490 /* 491 Macros for indicating code that should be compiled with a C interface, 492 rather than a C++ interface. Any routines that are dynamically loaded 493 (such as the PCCreate_XXX() routines) must be wrapped so that the name 494 mangler does not change the functions symbol name. This just hides the 495 ugly extern "C" {} wrappers. 496 */ 497 #if defined(__cplusplus) 498 #define EXTERN_C_BEGIN extern "C" { 499 #define EXTERN_C_END } 500 #else 501 #define EXTERN_C_BEGIN 502 #define EXTERN_C_END 503 #endif 504 505 /* --------------------------------------------------------------------*/ 506 /* 507 DVF (win32) uses STDCALL calling convention by default. 508 The following is used by the fortran interface. 509 */ 510 #if defined (PETSC_USE_FORTRAN_STDCALL) 511 #define PETSC_STDCALL __stdcall 512 #else 513 #define PETSC_STDCALL 514 #endif 515 516 #endif 517 518