1 /* $Id: petsc.h,v 1.280 2000/11/29 21:44:12 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 typedef struct _p_PetscObject* PetscObject; 184 typedef struct _PetscFList *PetscFList; 185 186 #include "petscviewer.h" 187 #include "petscoptions.h" 188 189 EXTERN int PetscShowMemoryUsage(PetscViewer,char*); 190 EXTERN int PetscGetTime(PetscLogDouble*); 191 EXTERN int PetscGetCPUTime(PetscLogDouble*); 192 EXTERN int PetscSleep(int); 193 194 /* 195 Initialization of PETSc 196 */ 197 EXTERN int PetscInitialize(int*,char***,char[],const char[]); 198 EXTERN int PetscInitializeNoArguments(void); 199 EXTERN int PetscFinalize(void); 200 EXTERN int PetscInitializeFortran(void); 201 202 /* 203 Functions that can act on any PETSc object. 204 */ 205 EXTERN int PetscObjectDestroy(PetscObject); 206 EXTERN int PetscObjectExists(PetscObject,PetscTruth*); 207 EXTERN int PetscObjectGetComm(PetscObject,MPI_Comm *); 208 EXTERN int PetscObjectGetCookie(PetscObject,int *); 209 EXTERN int PetscObjectGetType(PetscObject,int *); 210 EXTERN int PetscObjectSetName(PetscObject,const char[]); 211 EXTERN int PetscObjectGetName(PetscObject,char*[]); 212 EXTERN int PetscObjectReference(PetscObject); 213 EXTERN int PetscObjectGetReference(PetscObject,int*); 214 EXTERN int PetscObjectDereference(PetscObject); 215 EXTERN int PetscObjectGetNewTag(PetscObject,int *); 216 EXTERN int PetscCommGetNewTag(MPI_Comm,int *); 217 EXTERN int PetscObjectView(PetscObject,PetscViewer); 218 EXTERN int PetscObjectCompose(PetscObject,const char[],PetscObject); 219 EXTERN int PetscObjectQuery(PetscObject,const char[],PetscObject *); 220 EXTERN int PetscObjectComposeFunction(PetscObject,const char[],const char[],void *); 221 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 222 #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,0) 223 #else 224 #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,(void*)(d)) 225 #endif 226 EXTERN int PetscObjectQueryFunction(PetscObject,const char[],void **); 227 EXTERN int PetscObjectSetOptionsPrefix(PetscObject,const char[]); 228 EXTERN int PetscObjectAppendOptionsPrefix(PetscObject,const char[]); 229 EXTERN int PetscObjectPrependOptionsPrefix(PetscObject,const char[]); 230 EXTERN int PetscObjectGetOptionsPrefix(PetscObject,char*[]); 231 EXTERN int PetscObjectPublish(PetscObject); 232 EXTERN int PetscObjectChangeTypeName(PetscObject,char *); 233 EXTERN int PetscObjectRegisterDestroy(PetscObject); 234 EXTERN int PetscObjectRegisterDestroyAll(void); 235 EXTERN int PetscObjectName(PetscObject); 236 EXTERN int PetscTypeCompare(PetscObject,char*,PetscTruth*); 237 238 /* 239 Defines PETSc error handling. 240 */ 241 #include "petscerror.h" 242 243 /* 244 Mechanism for managing lists of objects attached (composed) with 245 a PETSc object. 246 */ 247 typedef struct _PetscOList *PetscOList; 248 EXTERN int PetscOListDestroy(PetscOList *); 249 EXTERN int PetscOListFind(PetscOList,const char[],PetscObject*); 250 EXTERN int PetscOListReverseFind(PetscOList,PetscObject,char**); 251 EXTERN int PetscOListAdd(PetscOList *,const char[],PetscObject); 252 EXTERN int PetscOListDuplicate(PetscOList,PetscOList *); 253 254 /* 255 Dynamic library lists. Lists of names of routines in dynamic 256 link libraries that will be loaded as needed. 257 */ 258 EXTERN int PetscFListAdd(PetscFList*,const char[],const char[],int (*)(void *)); 259 EXTERN int PetscFListDestroy(PetscFList*); 260 EXTERN int PetscFListFind(MPI_Comm,PetscFList,const char[],int (**)(void*)); 261 EXTERN int PetscFListPrintTypes(MPI_Comm,FILE*,const char[],const char[],char *,char *,PetscFList); 262 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 263 #define PetscFListAddDynamic(a,b,p,c) PetscFListAdd(a,b,p,0) 264 #else 265 #define PetscFListAddDynamic(a,b,p,c) PetscFListAdd(a,b,p,(int (*)(void *))c) 266 #endif 267 EXTERN int PetscFListDuplicate(PetscFList,PetscFList *); 268 EXTERN int PetscFListView(PetscFList,PetscViewer); 269 EXTERN int PetscFListConcat(const char [],const char [],char []); 270 EXTERN int PetscFListGet(PetscFList,char ***,int*); 271 272 /* 273 Routines for handling dynamic libraries. PETSc uses dynamic libraries 274 by default on most machines (except IBM). This is controlled by the 275 flag PETSC_USE_DYNAMIC_LIBRARIES in petscconf.h 276 */ 277 typedef struct _PetscDLLibraryList *PetscDLLibraryList; 278 extern PetscDLLibraryList DLLibrariesLoaded; 279 EXTERN int PetscDLLibraryRetrieve(MPI_Comm,const char[],char *,int,PetscTruth *); 280 EXTERN int PetscDLLibraryOpen(MPI_Comm,const char[],void **); 281 EXTERN int PetscDLLibrarySym(MPI_Comm,PetscDLLibraryList *,const char[],const char[],void **); 282 EXTERN int PetscDLLibraryAppend(MPI_Comm,PetscDLLibraryList *,const char[]); 283 EXTERN int PetscDLLibraryPrepend(MPI_Comm,PetscDLLibraryList *,const char[]); 284 EXTERN int PetscDLLibraryClose(PetscDLLibraryList); 285 EXTERN int PetscDLLibraryPrintPath(void); 286 EXTERN int PetscDLLibraryGetInfo(void *,char *,char **); 287 288 /* 289 Mechanism for translating PETSc object representations between languages 290 Not currently used. 291 */ 292 typedef enum {PETSC_LANGUAGE_C,PETSC_LANGUAGE_CPP} PetscLanguage; 293 #define PETSC_LANGUAGE_F77 PETSC_LANGUAGE_C 294 EXTERN int PetscObjectComposeLanguage(PetscObject,PetscLanguage,void *); 295 EXTERN int PetscObjectQueryLanguage(PetscObject,PetscLanguage,void **); 296 297 /* 298 Useful utility routines 299 */ 300 EXTERN int PetscSplitOwnership(MPI_Comm,int*,int*); 301 EXTERN int PetscSplitOwnershipBlock(MPI_Comm,int,int*,int*); 302 EXTERN int PetscSequentialPhaseBegin(MPI_Comm,int); 303 EXTERN int PetscSequentialPhaseEnd(MPI_Comm,int); 304 EXTERN int PetscBarrier(PetscObject); 305 EXTERN int PetscMPIDump(FILE*); 306 307 #define PetscNot(a) ((a) ? PETSC_FALSE : PETSC_TRUE) 308 /* 309 Defines basic graphics available from PETSc. 310 */ 311 #include "petscdraw.h" 312 313 /* 314 Defines the base data structures for all PETSc objects 315 */ 316 #include "petschead.h" 317 318 /* 319 Defines PETSc profiling. 320 */ 321 #include "petsclog.h" 322 323 /* 324 For locking, unlocking and destroying AMS memories associated with 325 PETSc objects 326 */ 327 #if defined(PETSC_HAVE_AMS) 328 329 extern PetscTruth PetscAMSPublishAll; 330 #define PetscPublishAll(v) (PetscAMSPublishAll ? PetscObjectPublish((PetscObject)v) : 0) 331 #define PetscObjectTakeAccess(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_take_access(((PetscObject)(obj))->amem)) 332 #define PetscObjectGrantAccess(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_grant_access(((PetscObject)(obj))->amem)) 333 #define PetscObjectDepublish(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_destroy(((PetscObject)(obj))->amem)); \ 334 ((PetscObject)(obj))->amem = -1; 335 336 #else 337 338 #define PetscPublishAll(v) 0 339 #define PetscObjectTakeAccess(obj) 0 340 #define PetscObjectGrantAccess(obj) 0 341 #define PetscObjectDepublish(obj) 0 342 343 #endif 344 345 346 347 /* 348 This code allows one to pass a MPI communicator between 349 C and Fortran. MPI 2.0 defines a standard API for doing this. 350 The code here is provided to allow PETSc to work with MPI 1.1 351 standard MPI libraries. 352 */ 353 EXTERN int MPICCommToFortranComm(MPI_Comm,int *); 354 EXTERN int MPIFortranCommToCComm(int,MPI_Comm*); 355 356 /* 357 Simple PETSc parallel IO for ASCII printing 358 */ 359 EXTERN int PetscFixFilename(const char[],char[]); 360 EXTERN int PetscFOpen(MPI_Comm,const char[],const char[],FILE**); 361 EXTERN int PetscFClose(MPI_Comm,FILE*); 362 EXTERN int PetscFPrintf(MPI_Comm,FILE*,const char[],...); 363 EXTERN int PetscPrintf(MPI_Comm,const char[],...); 364 EXTERN int (*PetscErrorPrintf)(const char[],...); 365 EXTERN int (*PetscHelpPrintf)(MPI_Comm,const char[],...); 366 EXTERN int PetscPOpen(MPI_Comm,char *,char*,const char[],FILE **); 367 EXTERN int PetscPClose(MPI_Comm,FILE*); 368 EXTERN int PetscSynchronizedPrintf(MPI_Comm,const char[],...); 369 EXTERN int PetscSynchronizedFPrintf(MPI_Comm,FILE*,const char[],...); 370 EXTERN int PetscSynchronizedFlush(MPI_Comm); 371 EXTERN int PetscSynchronizedFGets(MPI_Comm,FILE*,int,char[]); 372 EXTERN int PetscStartMatlab(MPI_Comm,char *,char*,FILE**); 373 EXTERN int PetscStartJava(MPI_Comm,char *,char*,FILE**); 374 375 EXTERN int PetscPopUpSelect(MPI_Comm,char*,char*,int,char**,int*); 376 /* 377 Simple PETSc object that contains a pointer to any required data 378 */ 379 typedef struct _p_PetscObjectContainer* PetscObjectContainer; 380 EXTERN int PetscObjectContainerGetPointer(PetscObjectContainer,void **); 381 EXTERN int PetscObjectContainerSetPointer(PetscObjectContainer,void *); 382 EXTERN int PetscObjectContainerDestroy(PetscObjectContainer); 383 EXTERN int PetscObjectContainerCreate(MPI_Comm comm,PetscObjectContainer *); 384 385 /* 386 For incremental debugging 387 */ 388 extern PetscTruth PetscCompare; 389 EXTERN int PetscCompareDouble(double); 390 EXTERN int PetscCompareScalar(Scalar); 391 EXTERN int PetscCompareInt(int); 392 393 /* 394 For use in debuggers 395 */ 396 extern int PetscGlobalRank,PetscGlobalSize; 397 EXTERN int PetscIntView(int,int[],PetscViewer); 398 EXTERN int PetscDoubleView(int,double[],PetscViewer); 399 EXTERN int PetscScalarView(int,Scalar[],PetscViewer); 400 401 /* 402 Allows accessing Matlab Engine 403 */ 404 #include "petscengine.h" 405 406 /* 407 C code optimization is often enhanced by telling the compiler 408 that certain pointer arguments to functions are not aliased to 409 to other arguments. This is not yet ANSI C standard so we define 410 the macro "restrict" to indicate that the variable is not aliased 411 to any other argument. 412 */ 413 #if defined(PETSC_HAVE_RESTRICT) && !defined(__cplusplus) 414 #define restrict _Restrict 415 #else 416 #define restrict 417 #endif 418 419 /* 420 Determine if some of the kernel computation routines use 421 Fortran (rather than C) for the numerical calculations. On some machines 422 and compilers (like complex numbers) the Fortran version of the routines 423 is faster than the C/C++ versions. The flag PETSC_USE_FORTRAN_KERNELS 424 would be set in the petscconf.h file 425 */ 426 #if defined(PETSC_USE_FORTRAN_KERNELS) 427 428 #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTAIJ) 429 #define PETSC_USE_FORTRAN_KERNEL_MULTAIJ 430 #endif 431 432 #if !defined(PETSC_USE_FORTRAN_KERNEL_NORMSQR) 433 #define PETSC_USE_FORTRAN_KERNEL_NORMSQR 434 #endif 435 436 #if !defined(PETSC_USE_FORTRAN_KERNEL_MAXPY) 437 #define PETSC_USE_FORTRAN_KERNEL_MAXPY 438 #endif 439 440 #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ) 441 #define PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ 442 #endif 443 444 #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ) 445 #define PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ 446 #endif 447 448 #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ) 449 #define PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ 450 #endif 451 452 #if !defined(PETSC_USE_FORTRAN_KERNEL_MDOT) 453 #define PETSC_USE_FORTRAN_KERNEL_MDOT 454 #endif 455 456 #if !defined(PETSC_USE_FORTRAN_KERNEL_XTIMESY) 457 #define PETSC_USE_FORTRAN_KERNEL_XTIMESY 458 #endif 459 460 #endif 461 462 /* 463 Macros for indicating code that should be compiled with a C interface, 464 rather than a C++ interface. Any routines that are dynamically loaded 465 (such as the PCCreate_XXX() routines) must be wrapped so that the name 466 mangler does not change the functions symbol name. This just hides the 467 ugly extern "C" {} wrappers. 468 */ 469 #if defined(__cplusplus) 470 #define EXTERN_C_BEGIN extern "C" { 471 #define EXTERN_C_END } 472 #else 473 #define EXTERN_C_BEGIN 474 #define EXTERN_C_END 475 #endif 476 477 /* --------------------------------------------------------------------*/ 478 /* 479 DVF (win32) uses STDCALL calling convention by default. 480 The following is used by the fortran interface. 481 */ 482 #if defined (PETSC_USE_FORTRAN_STDCALL) 483 #define PETSC_STDCALL __stdcall 484 #else 485 #define PETSC_STDCALL 486 #endif 487 488 #endif 489 490