1 /* $Id: petsc.h,v 1.268 2000/03/24 18:09:12 balay 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 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 Defines some elementary mathematics functions and constants. 36 */ 37 #include "petscmath.h" 38 39 /* 40 Variable type where we stash PETSc object pointers in Fortran. 41 Assumes that sizeof(long) == sizeof(void*)which is true on 42 all machines that we know. 43 */ 44 #define PetscFortranAddr long 45 46 /* 47 Basic PETSc constants 48 */ 49 typedef enum { PETSC_FALSE,PETSC_TRUE } PetscTruth; 50 #define PETSC_YES PETSC_TRUE 51 #define PETSC_NO PETSC_FALSE 52 #define PETSC_NULL 0 53 #define PETSC_IGNORE PETSC_NULL 54 #define PETSC_DECIDE -1 55 #define PETSC_DETERMINE PETSC_DECIDE 56 #define PETSC_DEFAULT -2 57 58 extern MPI_Comm PETSC_COMM_WORLD; 59 extern MPI_Comm PETSC_COMM_SELF; 60 extern PetscTruth PetscInitializeCalled; 61 extern int PetscSetCommWorld(MPI_Comm); 62 63 /* 64 Defines the malloc employed by PETSc. Users may use these routines as well. 65 */ 66 #define PetscMalloc(a) (*PetscTrMalloc)(a,__LINE__,__FUNC__,__FILE__,__SDIR__) 67 #define PetscNew(A) (A*)PetscMalloc(sizeof(A)) 68 #define PetscFree(a) (*PetscTrFree)(a,__LINE__,__FUNC__,__FILE__,__SDIR__) 69 extern void *(*PetscTrMalloc)(int,int,char*,char*,char*); 70 extern int (*PetscTrFree)(void *,int,char*,char*,char*); 71 extern int PetscSetMalloc(void *(*)(int,int,char*,char*,char*), 72 int (*)(void *,int,char*,char*,char*)); 73 extern int PetscClearMalloc(void); 74 75 /* 76 Routines for tracing memory corruption/bleeding with default PETSc 77 memory allocation 78 */ 79 extern int PetscTrDump(FILE *); 80 extern int PetscTrSpace(PLogDouble *,PLogDouble *,PLogDouble *); 81 extern int PetscTrValid(int,const char[],const char[],const char[]); 82 extern int PetscTrDebugLevel(int); 83 extern int PetscTrLog(void); 84 extern int PetscTrLogDump(FILE *); 85 extern int PetscGetResidentSetSize(PLogDouble *); 86 extern int PetscShowMemoryUsage(Viewer); 87 /* 88 Constants and functions used for handling different basic data types. 89 These are used, for example, in binary IO routines 90 */ 91 typedef enum {PETSC_INT = 0,PETSC_DOUBLE = 1,PETSC_SHORT = 2,PETSC_FLOAT = 3, 92 PETSC_COMPLEX = 4,PETSC_CHAR = 5,PETSC_LOGICAL = 6} PetscDataType; 93 #if defined(PETSC_USE_COMPLEX) 94 #define PETSC_SCALAR PETSC_COMPLEX 95 #else 96 #define PETSC_SCALAR PETSC_DOUBLE 97 #endif 98 #if defined(PETSC_USE_SINGLE) 99 #define PETSC_REAL PETSC_FLOAT 100 #else 101 #define PETSC_REAL PETSC_DOUBLE 102 #endif 103 104 typedef enum {PETSC_INT_SIZE = sizeof(int),PETSC_DOUBLE_SIZE = sizeof(double), 105 PETSC_SCALAR_SIZE = sizeof(Scalar),PETSC_COMPLEX_SIZE = sizeof(double), 106 PETSC_CHAR_SIZE = sizeof(char),PETSC_LOGICAL_SIZE = 1} PetscDataTypeSize; 107 #if defined(PETSC_USE_SINGLE) 108 #define PETSC_REAL_SIZE PETSC_FLOAT_SIZE 109 #else 110 #define PETSC_REAL_SIZE PETSC_DOUBLE_SIZE 111 #endif 112 113 extern int PetscDataTypeToMPIDataType(PetscDataType,MPI_Datatype*); 114 extern int PetscDataTypeGetSize(PetscDataType,int*); 115 extern int PetscDataTypeGetName(PetscDataType,char*[]); 116 117 118 /* 119 Basic memory and string operations. These are usually simple wrappers 120 around the basic Unix system calls, but a few of them have additional 121 functionality and/or error checking. 122 */ 123 extern int PetscMemcpy(void *,const void *,int); 124 extern int PetscBitMemcpy(void*,int,const void*,int,int,PetscDataType); 125 extern int PetscMemmove(void *,void *,int); 126 extern int PetscMemzero(void *,int); 127 extern int PetscMemcmp(const void*,const void*,int,PetscTruth *); 128 extern int PetscStrlen(const char[],int*); 129 extern int PetscStrcmp(const char[],const char[],PetscTruth *); 130 extern int PetscStrgrt(const char[],const char[],PetscTruth *); 131 extern int PetscStrcasecmp(const char[],const char[],PetscTruth*); 132 extern int PetscStrncmp(const char[],const char[],int,PetscTruth*); 133 extern int PetscStrcpy(char[],const char[]); 134 extern int PetscStrcat(char[],const char[]); 135 extern int PetscStrncat(char[],const char[],int); 136 extern int PetscStrncpy(char[],const char[],int); 137 extern int PetscStrchr(const char[],char,char **); 138 extern int PetscStrtolower(char[]); 139 extern int PetscStrrchr(const char[],char,char **); 140 extern int PetscStrstr(const char[],const char[],char **); 141 extern int PetscStrtok(const char[],const char[],char **); 142 extern int PetscStrallocpy(const char[],char **); 143 extern int PetscStrreplace(MPI_Comm,const char[],char*,int); 144 #define PetscStrfree(a) ((a) ? PetscFree(a) : 0) 145 146 extern MPI_Op PetscMaxSum_Op; 147 #if defined(PETSC_USE_COMPLEX) 148 extern MPI_Op PetscSum_Op; 149 #else 150 #define PetscSum_Op MPI_SUM 151 #endif 152 153 /* 154 Each PETSc object class has it's own cookie (internal integer in the 155 data structure used for error checking). These are all defined by an offset 156 from the lowest one, PETSC_COOKIE. 157 */ 158 #define PETSC_COOKIE 1211211 159 #define PETSC_MAX_COOKIES 60 160 #define LARGEST_PETSC_COOKIE_PREDEFINED PETSC_COOKIE + 30 161 #define LARGEST_PETSC_COOKIE_ALLOWED PETSC_COOKIE + PETSC_MAX_COOKIES 162 extern int LARGEST_PETSC_COOKIE; 163 164 typedef struct _p_PetscObject* PetscObject; 165 typedef struct _FList *FList; 166 167 #include "viewer.h" 168 #include "options.h" 169 170 extern int PetscGetTime(PLogDouble*); 171 extern int PetscGetCPUTime(PLogDouble*); 172 extern int PetscSleep(int); 173 174 /* 175 Initialization of PETSc 176 */ 177 extern int PetscInitialize(int*,char***,char[],const char[]); 178 extern int PetscInitializeNoArguments(void); 179 extern int PetscFinalize(void); 180 extern int PetscInitializeFortran(void); 181 182 /* 183 Functions that can act on any PETSc object. 184 */ 185 extern int PetscObjectDestroy(PetscObject); 186 extern int PetscObjectExists(PetscObject,PetscTruth*); 187 extern int PetscObjectGetComm(PetscObject,MPI_Comm *); 188 extern int PetscObjectGetCookie(PetscObject,int *); 189 extern int PetscObjectGetType(PetscObject,int *); 190 extern int PetscObjectSetName(PetscObject,const char[]); 191 extern int PetscObjectGetName(PetscObject,char*[]); 192 extern int PetscObjectReference(PetscObject); 193 extern int PetscObjectGetReference(PetscObject,int*); 194 extern int PetscObjectDereference(PetscObject); 195 extern int PetscObjectGetNewTag(PetscObject,int *); 196 extern int PetscObjectRestoreNewTag(PetscObject,int *); 197 extern int PetscCommGetNewTag(MPI_Comm,int *); 198 extern int PetscCommRestoreNewTag(MPI_Comm,int *); 199 extern int PetscObjectView(PetscObject,Viewer); 200 extern int PetscObjectCompose(PetscObject,const char[],PetscObject); 201 extern int PetscObjectQuery(PetscObject,const char[],PetscObject *); 202 extern int PetscObjectComposeFunction(PetscObject,const char[],const char[],void *); 203 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 204 #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,0) 205 #else 206 #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,d) 207 #endif 208 extern int PetscObjectQueryFunction(PetscObject,const char[],void **); 209 extern int PetscObjectSetOptionsPrefix(PetscObject,const char[]); 210 extern int PetscObjectAppendOptionsPrefix(PetscObject,const char[]); 211 extern int PetscObjectPrependOptionsPrefix(PetscObject,const char[]); 212 extern int PetscObjectGetOptionsPrefix(PetscObject,char*[]); 213 extern int PetscObjectPublish(PetscObject); 214 extern int PetscObjectChangeTypeName(PetscObject,char *); 215 extern int PetscTypeCompare(PetscObject,char*,PetscTruth*); 216 217 /* 218 Defines PETSc error handling. 219 */ 220 #include "petscerror.h" 221 222 /* 223 Mechanism for managing lists of objects attached (composed) with 224 a PETSc object. 225 */ 226 typedef struct _OList *OList; 227 extern int OListDestroy(OList *); 228 extern int OListFind(OList,const char[],PetscObject*); 229 extern int OListReverseFind(OList,PetscObject,char**); 230 extern int OListAdd(OList *,const char[],PetscObject); 231 extern int OListDuplicate(OList,OList *); 232 233 /* 234 Dynamic library lists. Lists of names of routines in dynamic 235 link libraries that will be loaded as needed. 236 */ 237 extern int FListAdd(FList*,const char[],const char[],int (*)(void *)); 238 extern int FListDestroy(FList); 239 extern int FListFind(MPI_Comm,FList,const char[],int (**)(void*)); 240 extern int FListPrintTypes(MPI_Comm,FILE*,const char[],const char[],FList); 241 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 242 #define FListAddDynamic(a,b,p,c) FListAdd(a,b,p,0) 243 #else 244 #define FListAddDynamic(a,b,p,c) FListAdd(a,b,p,(int (*)(void *))c) 245 #endif 246 extern int FListDuplicate(FList,FList *); 247 extern int FListView(FList,Viewer); 248 extern int FListConcat(const char [],const char [],char []); 249 extern int FListGet(FList,char ***,int*); 250 251 /* 252 Routines for handling dynamic libraries. PETSc uses dynamic libraries 253 by default on most machines (except IBM). This is controlled by the 254 flag PETSC_USE_DYNAMIC_LIBRARIES in petscconf.h 255 */ 256 typedef struct _DLLibraryList *DLLibraryList; 257 extern DLLibraryList DLLibrariesLoaded; 258 extern int DLLibraryRetrieve(MPI_Comm,const char[],char *,int,PetscTruth *); 259 extern int DLLibraryOpen(MPI_Comm,const char[],void **); 260 extern int DLLibrarySym(MPI_Comm,DLLibraryList *,const char[],const char[],void **); 261 extern int DLLibraryAppend(MPI_Comm,DLLibraryList *,const char[]); 262 extern int DLLibraryPrepend(MPI_Comm,DLLibraryList *,const char[]); 263 extern int DLLibraryClose(DLLibraryList); 264 extern int DLLibraryPrintPath(void); 265 extern int DLLibraryGetInfo(void *,char *,char **); 266 267 /* 268 Mechanism for translating PETSc object representations between languages 269 Not currently used. 270 */ 271 typedef enum {PETSC_LANGUAGE_C,PETSC_LANGUAGE_CPP} PetscLanguage; 272 #define PETSC_LANGUAGE_F77 PETSC_LANGUAGE_C 273 extern int PetscObjectComposeLanguage(PetscObject,PetscLanguage,void *); 274 extern int PetscObjectQueryLanguage(PetscObject,PetscLanguage,void **); 275 276 /* 277 Useful utility routines 278 */ 279 extern int PetscSplitOwnership(MPI_Comm,int*,int*); 280 extern int PetscSequentialPhaseBegin(MPI_Comm,int); 281 extern int PetscSequentialPhaseEnd(MPI_Comm,int); 282 extern int PetscBarrier(PetscObject); 283 extern int PetscMPIDump(FILE*); 284 285 #define PetscNot(a) ((a) ? PETSC_FALSE : PETSC_TRUE) 286 /* 287 Defines basic graphics available from PETSc. 288 */ 289 #include "draw.h" 290 291 /* 292 Defines the base data structures for all PETSc objects 293 */ 294 #include "petschead.h" 295 296 /* 297 Defines PETSc profiling. 298 */ 299 #include "petsclog.h" 300 301 /* 302 For locking, unlocking and destroying AMS memories associated with 303 PETSc objects 304 */ 305 #if defined(PETSC_HAVE_AMS) 306 307 extern PetscTruth PetscAMSPublishAll; 308 #define PetscPublishAll(v)\ 309 { if (PetscAMSPublishAll) { \ 310 int __ierr; __ierr = PetscObjectPublish((PetscObject)v);CHKERRQ(__ierr);\ 311 }} 312 #define PetscObjectTakeAccess(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_take_access(((PetscObject)(obj))->amem)) 313 #define PetscObjectGrantAccess(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_grant_access(((PetscObject)(obj))->amem)) 314 #define PetscObjectDepublish(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_destroy(((PetscObject)(obj))->amem)); \ 315 ((PetscObject)(obj))->amem = -1; 316 317 #else 318 319 #define PetscPublishAll(v) 320 #define PetscObjectTakeAccess(obj) 0 321 #define PetscObjectGrantAccess(obj) 0 322 #define PetscObjectDepublish(obj) 0 323 324 #endif 325 326 327 328 /* 329 This code allows one to pass a MPI communicator between 330 C and Fortran. MPI 2.0 defines a standard API for doing this. 331 The code here is provided to allow PETSc to work with MPI 1.1 332 standard MPI libraries. 333 */ 334 extern int MPICCommToFortranComm(MPI_Comm,int *); 335 extern int MPIFortranCommToCComm(int,MPI_Comm*); 336 337 /* 338 Simple PETSc parallel IO for ASCII printing 339 */ 340 extern int PetscFixFilename(const char[],char[]); 341 extern int PetscFOpen(MPI_Comm,const char[],const char[],FILE**); 342 extern int PetscFClose(MPI_Comm,FILE*); 343 extern int PetscFPrintf(MPI_Comm,FILE*,const char[],...); 344 extern int PetscPrintf(MPI_Comm,const char[],...); 345 extern int (*PetscErrorPrintf)(const char[],...); 346 extern int (*PetscHelpPrintf)(MPI_Comm,const char[],...); 347 extern int PetscPOpen(MPI_Comm,char *,char*,const char[],FILE **); 348 extern int PetscPClose(MPI_Comm,FILE*); 349 extern int PetscSynchronizedPrintf(MPI_Comm,const char[],...); 350 extern int PetscSynchronizedFPrintf(MPI_Comm,FILE*,const char[],...); 351 extern int PetscSynchronizedFlush(MPI_Comm); 352 extern int PetscStartMatlab(MPI_Comm,char *,char*,FILE**); 353 extern int PetscStartJava(MPI_Comm,char *,char*,FILE**); 354 355 /* 356 Simple PETSc object that contains a pointer to any required data 357 */ 358 typedef struct _p_PetscObjectContainer* PetscObjectContainer; 359 extern int PetscObjectContainerGetPointer(PetscObjectContainer,void **); 360 extern int PetscObjectContainerSetPointer(PetscObjectContainer,void *); 361 extern int PetscObjectContainerDestroy(PetscObjectContainer); 362 extern int PetscObjectContainerCreate(MPI_Comm comm,PetscObjectContainer *); 363 364 /* 365 For incremental debugging 366 */ 367 extern int PetscCompare; 368 extern int PetscCompareDouble(double); 369 extern int PetscCompareScalar(Scalar); 370 extern int PetscCompareInt(int); 371 372 /* 373 For use in debuggers 374 */ 375 extern int PetscGlobalRank,PetscGlobalSize; 376 extern int PetscIntView(int,int[],Viewer); 377 extern int PetscDoubleView(int,double[],Viewer); 378 extern int PetscScalarView(int,Scalar[],Viewer); 379 380 /* 381 C code optimization is often enhanced by telling the compiler 382 that certain pointer arguments to functions are not aliased to 383 to other arguments. This is not yet ANSI C standard so we define 384 the macro "restrict" to indicate that the variable is not aliased 385 to any other argument. 386 */ 387 #if defined(PETSC_HAVE_RESTRICT) && !defined(__cplusplus) 388 #define restrict _Restrict 389 #else 390 #define restrict 391 #endif 392 393 /* 394 Determine if some of the kernel computation routines use 395 Fortran (rather than C) for the numerical calculations. On some machines 396 and compilers (like complex numbers) the Fortran version of the routines 397 is faster than the C/C++ versions. The flag PETSC_USE_FORTRAN_KERNELS 398 would be set in the petscconf.h file 399 */ 400 #if defined(PETSC_USE_FORTRAN_KERNELS) 401 402 #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTAIJ) 403 #define PETSC_USE_FORTRAN_KERNEL_MULTAIJ 404 #endif 405 406 #if !defined(PETSC_USE_FORTRAN_KERNEL_NORMSQR) 407 #define PETSC_USE_FORTRAN_KERNEL_NORMSQR 408 #endif 409 410 #if !defined(PETSC_USE_FORTRAN_KERNEL_MAXPY) 411 #define PETSC_USE_FORTRAN_KERNEL_MAXPY 412 #endif 413 414 #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ) 415 #define PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ 416 #endif 417 418 #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ) 419 #define PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ 420 #endif 421 422 #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ) 423 #define PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ 424 #endif 425 426 #if !defined(PETSC_USE_FORTRAN_KERNEL_MDOT) 427 #define PETSC_USE_FORTRAN_KERNEL_MDOT 428 #endif 429 430 #if !defined(PETSC_USE_FORTRAN_KERNEL_XTIMESY) 431 #define PETSC_USE_FORTRAN_KERNEL_XTIMESY 432 #endif 433 434 #endif 435 436 /* 437 Macros for indicating code that should be compiled with a C interface, 438 rather than a C++ interface. Any routines that are dynamically loaded 439 (such as the PCCreate_XXX() routines) must be wrapped so that the name 440 mangler does not change the functions symbol name. This just hides the 441 ugly extern "C" {} wrappers. 442 */ 443 #if defined(__cplusplus) 444 #define EXTERN_C_BEGIN extern "C" { 445 #define EXTERN_C_END } 446 #else 447 #define EXTERN_C_BEGIN 448 #define EXTERN_C_END 449 #endif 450 451 /* --------------------------------------------------------------------*/ 452 /* 453 DVF (win32) uses STDCALL calling convention by default. 454 The following is used by the fortran interface. 455 */ 456 #if defined (PETSC_USE_FORTRAN_STDCALL) 457 #define PETSC_STDCALL __stdcall 458 #else 459 #define PETSC_STDCALL 460 #endif 461 462 #endif 463