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