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