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