1 /* $Id: petsc.h,v 1.270 2000/04/27 04:17:52 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 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 extern int PetscSetHelpVersionFunctions(int (*)(MPI_Comm),int (*)(MPI_Comm)); 63 64 /* 65 Defines the malloc employed by PETSc. Users may use these routines as well. 66 */ 67 #define PetscMalloc(a) (*PetscTrMalloc)(a,__LINE__,__FUNC__,__FILE__,__SDIR__) 68 #define PetscNew(A) (A*)PetscMalloc(sizeof(A)) 69 #define PetscFree(a) (*PetscTrFree)(a,__LINE__,__FUNC__,__FILE__,__SDIR__) 70 extern void *(*PetscTrMalloc)(int,int,char*,char*,char*); 71 extern int (*PetscTrFree)(void *,int,char*,char*,char*); 72 extern int PetscSetMalloc(void *(*)(int,int,char*,char*,char*), 73 int (*)(void *,int,char*,char*,char*)); 74 extern int PetscClearMalloc(void); 75 76 /* 77 Routines for tracing memory corruption/bleeding with default PETSc 78 memory allocation 79 */ 80 extern int PetscTrDump(FILE *); 81 extern int PetscTrSpace(PLogDouble *,PLogDouble *,PLogDouble *); 82 extern int PetscTrValid(int,const char[],const char[],const char[]); 83 extern int PetscTrDebugLevel(int); 84 extern int PetscTrLog(void); 85 extern int PetscTrLogDump(FILE *); 86 extern int PetscGetResidentSetSize(PLogDouble *); 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 PetscShowMemoryUsage(Viewer,char*); 171 extern int PetscGetTime(PLogDouble*); 172 extern int PetscGetCPUTime(PLogDouble*); 173 extern int PetscSleep(int); 174 175 /* 176 Initialization of PETSc 177 */ 178 extern int PetscInitialize(int*,char***,char[],const char[]); 179 extern int PetscInitializeNoArguments(void); 180 extern int PetscFinalize(void); 181 extern int PetscInitializeFortran(void); 182 183 /* 184 Functions that can act on any PETSc object. 185 */ 186 extern int PetscObjectDestroy(PetscObject); 187 extern int PetscObjectExists(PetscObject,PetscTruth*); 188 extern int PetscObjectGetComm(PetscObject,MPI_Comm *); 189 extern int PetscObjectGetCookie(PetscObject,int *); 190 extern int PetscObjectGetType(PetscObject,int *); 191 extern int PetscObjectSetName(PetscObject,const char[]); 192 extern int PetscObjectGetName(PetscObject,char*[]); 193 extern int PetscObjectReference(PetscObject); 194 extern int PetscObjectGetReference(PetscObject,int*); 195 extern int PetscObjectDereference(PetscObject); 196 extern int PetscObjectGetNewTag(PetscObject,int *); 197 extern int PetscObjectRestoreNewTag(PetscObject,int *); 198 extern int PetscCommGetNewTag(MPI_Comm,int *); 199 extern int PetscCommRestoreNewTag(MPI_Comm,int *); 200 extern int PetscObjectView(PetscObject,Viewer); 201 extern int PetscObjectCompose(PetscObject,const char[],PetscObject); 202 extern int PetscObjectQuery(PetscObject,const char[],PetscObject *); 203 extern int PetscObjectComposeFunction(PetscObject,const char[],const char[],void *); 204 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 205 #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,0) 206 #else 207 #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,d) 208 #endif 209 extern int PetscObjectQueryFunction(PetscObject,const char[],void **); 210 extern int PetscObjectSetOptionsPrefix(PetscObject,const char[]); 211 extern int PetscObjectAppendOptionsPrefix(PetscObject,const char[]); 212 extern int PetscObjectPrependOptionsPrefix(PetscObject,const char[]); 213 extern int PetscObjectGetOptionsPrefix(PetscObject,char*[]); 214 extern int PetscObjectPublish(PetscObject); 215 extern int PetscObjectChangeTypeName(PetscObject,char *); 216 extern int PetscObjectRegisterDestroy(PetscObject); 217 extern int PetscObjectRegisterDestroyAll(void); 218 extern int PetscTypeCompare(PetscObject,char*,PetscTruth*); 219 220 /* 221 Defines PETSc error handling. 222 */ 223 #include "petscerror.h" 224 225 /* 226 Mechanism for managing lists of objects attached (composed) with 227 a PETSc object. 228 */ 229 typedef struct _OList *OList; 230 extern int OListDestroy(OList *); 231 extern int OListFind(OList,const char[],PetscObject*); 232 extern int OListReverseFind(OList,PetscObject,char**); 233 extern int OListAdd(OList *,const char[],PetscObject); 234 extern int OListDuplicate(OList,OList *); 235 236 /* 237 Dynamic library lists. Lists of names of routines in dynamic 238 link libraries that will be loaded as needed. 239 */ 240 extern int FListAdd(FList*,const char[],const char[],int (*)(void *)); 241 extern int FListDestroy(FList); 242 extern int FListFind(MPI_Comm,FList,const char[],int (**)(void*)); 243 extern int FListPrintTypes(MPI_Comm,FILE*,const char[],const char[],FList); 244 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 245 #define FListAddDynamic(a,b,p,c) FListAdd(a,b,p,0) 246 #else 247 #define FListAddDynamic(a,b,p,c) FListAdd(a,b,p,(int (*)(void *))c) 248 #endif 249 extern int FListDuplicate(FList,FList *); 250 extern int FListView(FList,Viewer); 251 extern int FListConcat(const char [],const char [],char []); 252 extern int FListGet(FList,char ***,int*); 253 254 /* 255 Routines for handling dynamic libraries. PETSc uses dynamic libraries 256 by default on most machines (except IBM). This is controlled by the 257 flag PETSC_USE_DYNAMIC_LIBRARIES in petscconf.h 258 */ 259 typedef struct _DLLibraryList *DLLibraryList; 260 extern DLLibraryList DLLibrariesLoaded; 261 extern int DLLibraryRetrieve(MPI_Comm,const char[],char *,int,PetscTruth *); 262 extern int DLLibraryOpen(MPI_Comm,const char[],void **); 263 extern int DLLibrarySym(MPI_Comm,DLLibraryList *,const char[],const char[],void **); 264 extern int DLLibraryAppend(MPI_Comm,DLLibraryList *,const char[]); 265 extern int DLLibraryPrepend(MPI_Comm,DLLibraryList *,const char[]); 266 extern int DLLibraryClose(DLLibraryList); 267 extern int DLLibraryPrintPath(void); 268 extern int DLLibraryGetInfo(void *,char *,char **); 269 270 /* 271 Mechanism for translating PETSc object representations between languages 272 Not currently used. 273 */ 274 typedef enum {PETSC_LANGUAGE_C,PETSC_LANGUAGE_CPP} PetscLanguage; 275 #define PETSC_LANGUAGE_F77 PETSC_LANGUAGE_C 276 extern int PetscObjectComposeLanguage(PetscObject,PetscLanguage,void *); 277 extern int PetscObjectQueryLanguage(PetscObject,PetscLanguage,void **); 278 279 /* 280 Useful utility routines 281 */ 282 extern int PetscSplitOwnership(MPI_Comm,int*,int*); 283 extern int PetscSequentialPhaseBegin(MPI_Comm,int); 284 extern int PetscSequentialPhaseEnd(MPI_Comm,int); 285 extern int PetscBarrier(PetscObject); 286 extern int PetscMPIDump(FILE*); 287 288 #define PetscNot(a) ((a) ? PETSC_FALSE : PETSC_TRUE) 289 /* 290 Defines basic graphics available from PETSc. 291 */ 292 #include "draw.h" 293 294 /* 295 Defines the base data structures for all PETSc objects 296 */ 297 #include "petschead.h" 298 299 /* 300 Defines PETSc profiling. 301 */ 302 #include "petsclog.h" 303 304 /* 305 For locking, unlocking and destroying AMS memories associated with 306 PETSc objects 307 */ 308 #if defined(PETSC_HAVE_AMS) 309 310 extern PetscTruth PetscAMSPublishAll; 311 #define PetscPublishAll(v)\ 312 { if (PetscAMSPublishAll) { \ 313 int __ierr; __ierr = PetscObjectPublish((PetscObject)v);CHKERRQ(__ierr);\ 314 }} 315 #define PetscObjectTakeAccess(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_take_access(((PetscObject)(obj))->amem)) 316 #define PetscObjectGrantAccess(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_grant_access(((PetscObject)(obj))->amem)) 317 #define PetscObjectDepublish(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_destroy(((PetscObject)(obj))->amem)); \ 318 ((PetscObject)(obj))->amem = -1; 319 320 #else 321 322 #define PetscPublishAll(v) 323 #define PetscObjectTakeAccess(obj) 0 324 #define PetscObjectGrantAccess(obj) 0 325 #define PetscObjectDepublish(obj) 0 326 327 #endif 328 329 330 331 /* 332 This code allows one to pass a MPI communicator between 333 C and Fortran. MPI 2.0 defines a standard API for doing this. 334 The code here is provided to allow PETSc to work with MPI 1.1 335 standard MPI libraries. 336 */ 337 extern int MPICCommToFortranComm(MPI_Comm,int *); 338 extern int MPIFortranCommToCComm(int,MPI_Comm*); 339 340 /* 341 Simple PETSc parallel IO for ASCII printing 342 */ 343 extern int PetscFixFilename(const char[],char[]); 344 extern int PetscFOpen(MPI_Comm,const char[],const char[],FILE**); 345 extern int PetscFClose(MPI_Comm,FILE*); 346 extern int PetscFPrintf(MPI_Comm,FILE*,const char[],...); 347 extern int PetscPrintf(MPI_Comm,const char[],...); 348 extern int (*PetscErrorPrintf)(const char[],...); 349 extern int (*PetscHelpPrintf)(MPI_Comm,const char[],...); 350 extern int PetscPOpen(MPI_Comm,char *,char*,const char[],FILE **); 351 extern int PetscPClose(MPI_Comm,FILE*); 352 extern int PetscSynchronizedPrintf(MPI_Comm,const char[],...); 353 extern int PetscSynchronizedFPrintf(MPI_Comm,FILE*,const char[],...); 354 extern int PetscSynchronizedFlush(MPI_Comm); 355 extern int PetscSynchronizedFGets(MPI_Comm,FILE*,int,char[]); 356 extern int PetscStartMatlab(MPI_Comm,char *,char*,FILE**); 357 extern int PetscStartJava(MPI_Comm,char *,char*,FILE**); 358 359 extern int PetscPopUpSelect(MPI_Comm,char*,char*,int,char**,int*); 360 /* 361 Simple PETSc object that contains a pointer to any required data 362 */ 363 typedef struct _p_PetscObjectContainer* PetscObjectContainer; 364 extern int PetscObjectContainerGetPointer(PetscObjectContainer,void **); 365 extern int PetscObjectContainerSetPointer(PetscObjectContainer,void *); 366 extern int PetscObjectContainerDestroy(PetscObjectContainer); 367 extern int PetscObjectContainerCreate(MPI_Comm comm,PetscObjectContainer *); 368 369 /* 370 For incremental debugging 371 */ 372 extern PetscTruth PetscCompare; 373 extern int PetscCompareDouble(double); 374 extern int PetscCompareScalar(Scalar); 375 extern int PetscCompareInt(int); 376 377 /* 378 For use in debuggers 379 */ 380 extern int PetscGlobalRank,PetscGlobalSize; 381 extern int PetscIntView(int,int[],Viewer); 382 extern int PetscDoubleView(int,double[],Viewer); 383 extern int PetscScalarView(int,Scalar[],Viewer); 384 385 /* 386 Allows accessing Matlab Engine 387 */ 388 #include "petscengine.h" 389 390 /* 391 C code optimization is often enhanced by telling the compiler 392 that certain pointer arguments to functions are not aliased to 393 to other arguments. This is not yet ANSI C standard so we define 394 the macro "restrict" to indicate that the variable is not aliased 395 to any other argument. 396 */ 397 #if defined(PETSC_HAVE_RESTRICT) && !defined(__cplusplus) 398 #define restrict _Restrict 399 #else 400 #define restrict 401 #endif 402 403 /* 404 Determine if some of the kernel computation routines use 405 Fortran (rather than C) for the numerical calculations. On some machines 406 and compilers (like complex numbers) the Fortran version of the routines 407 is faster than the C/C++ versions. The flag PETSC_USE_FORTRAN_KERNELS 408 would be set in the petscconf.h file 409 */ 410 #if defined(PETSC_USE_FORTRAN_KERNELS) 411 412 #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTAIJ) 413 #define PETSC_USE_FORTRAN_KERNEL_MULTAIJ 414 #endif 415 416 #if !defined(PETSC_USE_FORTRAN_KERNEL_NORMSQR) 417 #define PETSC_USE_FORTRAN_KERNEL_NORMSQR 418 #endif 419 420 #if !defined(PETSC_USE_FORTRAN_KERNEL_MAXPY) 421 #define PETSC_USE_FORTRAN_KERNEL_MAXPY 422 #endif 423 424 #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ) 425 #define PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ 426 #endif 427 428 #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ) 429 #define PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ 430 #endif 431 432 #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ) 433 #define PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ 434 #endif 435 436 #if !defined(PETSC_USE_FORTRAN_KERNEL_MDOT) 437 #define PETSC_USE_FORTRAN_KERNEL_MDOT 438 #endif 439 440 #if !defined(PETSC_USE_FORTRAN_KERNEL_XTIMESY) 441 #define PETSC_USE_FORTRAN_KERNEL_XTIMESY 442 #endif 443 444 #endif 445 446 /* 447 Macros for indicating code that should be compiled with a C interface, 448 rather than a C++ interface. Any routines that are dynamically loaded 449 (such as the PCCreate_XXX() routines) must be wrapped so that the name 450 mangler does not change the functions symbol name. This just hides the 451 ugly extern "C" {} wrappers. 452 */ 453 #if defined(__cplusplus) 454 #define EXTERN_C_BEGIN extern "C" { 455 #define EXTERN_C_END } 456 #else 457 #define EXTERN_C_BEGIN 458 #define EXTERN_C_END 459 #endif 460 461 /* --------------------------------------------------------------------*/ 462 /* 463 DVF (win32) uses STDCALL calling convention by default. 464 The following is used by the fortran interface. 465 */ 466 #if defined (PETSC_USE_FORTRAN_STDCALL) 467 #define PETSC_STDCALL __stdcall 468 #else 469 #define PETSC_STDCALL 470 #endif 471 472 #endif 473