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