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