1 /* $Id: petsc.h,v 1.255 1999/10/04 23:56:31 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_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 230 /* 231 Routines for handling dynamic libraries. PETSc uses dynamic libraries 232 by default on most machines (except IBM). This is controlled by the 233 flag PETSC_USE_DYNAMIC_LIBRARIES in petscconf.h 234 */ 235 typedef struct _DLLibraryList *DLLibraryList; 236 extern DLLibraryList DLLibrariesLoaded; 237 extern int DLLibraryRetrieve(MPI_Comm,const char[],char *,int,PetscTruth *); 238 extern int DLLibraryOpen(MPI_Comm,const char[],void **); 239 extern int DLLibrarySym(MPI_Comm,DLLibraryList *,const char[],const char[],void **); 240 extern int DLLibraryAppend(MPI_Comm,DLLibraryList *,const char[]); 241 extern int DLLibraryPrepend(MPI_Comm,DLLibraryList *,const char[]); 242 extern int DLLibraryClose(DLLibraryList); 243 extern int DLLibraryPrintPath(void); 244 extern int DLLibraryGetInfo(void *,char *,char **); 245 246 /* 247 Mechanism for translating PETSc object representations between languages 248 Not currently used. 249 */ 250 typedef enum {PETSC_LANGUAGE_C,PETSC_LANGUAGE_CPP} PetscLanguage; 251 #define PETSC_LANGUAGE_F77 PETSC_LANGUAGE_C 252 extern int PetscObjectComposeLanguage(PetscObject,PetscLanguage,void *); 253 extern int PetscObjectQueryLanguage(PetscObject,PetscLanguage,void **); 254 255 /* 256 Useful utility routines 257 */ 258 extern int PetscSplitOwnership(MPI_Comm,int*,int*); 259 extern int PetscSequentialPhaseBegin(MPI_Comm,int); 260 extern int PetscSequentialPhaseEnd(MPI_Comm,int); 261 extern int PetscBarrier(PetscObject); 262 extern int PetscMPIDump(FILE*); 263 264 /* 265 Defines basic graphics available from PETSc. 266 */ 267 #include "draw.h" 268 269 /* 270 Defines the base data structures for all PETSc objects 271 */ 272 #include "petschead.h" 273 274 /* 275 Defines PETSc profiling. 276 */ 277 #include "petsclog.h" 278 279 #if defined(PETSC_HAVE_AMS) 280 extern PetscTruth PetscAMSPublishAll; 281 #define PetscPublishAll(v)\ 282 { if (PetscAMSPublishAll) { \ 283 int __ierr;\ 284 __ierr = PetscObjectPublish((PetscObject)v);CHKERRQ(__ierr);\ 285 }} 286 #else 287 #define PetscPublishAll(v) 288 #endif 289 290 /* 291 This code allows one to pass a MPI communicator between 292 C and Fortran. MPI 2.0 defines a standard API for doing this. 293 The code here is provided to allow PETSc to work with MPI 1.1 294 standard MPI libraries. 295 */ 296 extern int MPICCommToFortranComm(MPI_Comm,int *); 297 extern int MPIFortranCommToCComm(int,MPI_Comm*); 298 299 /* 300 Simple PETSc parallel IO for ASCII printing 301 */ 302 extern int PetscFixFilename(const char[],char[]); 303 extern FILE *PetscFOpen(MPI_Comm,const char[],const char[]); 304 extern int PetscFClose(MPI_Comm,FILE*); 305 extern int PetscFPrintf(MPI_Comm,FILE*,const char[],...); 306 extern int PetscPrintf(MPI_Comm,const char[],...); 307 extern int (*PetscErrorPrintf)(const char[],...); 308 extern int (*PetscHelpPrintf)(MPI_Comm,const char[],...); 309 310 extern int PetscSynchronizedPrintf(MPI_Comm,const char[],...); 311 extern int PetscSynchronizedFPrintf(MPI_Comm,FILE*,const char[],...); 312 extern int PetscSynchronizedFlush(MPI_Comm); 313 314 /* 315 Simple PETSc object that contains a pointer to any required data 316 */ 317 typedef struct _p_PetscObjectContainer* PetscObjectContainer; 318 extern int PetscObjectContainerGetPointer(PetscObjectContainer,void **); 319 extern int PetscObjectContainerSetPointer(PetscObjectContainer,void *); 320 extern int PetscObjectContainerDestroy(PetscObjectContainer); 321 extern int PetscObjectContainerCreate(MPI_Comm comm,PetscObjectContainer *); 322 323 /* 324 For incremental debugging 325 */ 326 extern int PetscCompare; 327 extern int PetscCompareDouble(double); 328 extern int PetscCompareScalar(Scalar); 329 extern int PetscCompareInt(int); 330 331 /* 332 For use in debuggers 333 */ 334 extern int PetscGlobalRank,PetscGlobalSize; 335 extern int PetscIntView(int,int[],Viewer); 336 extern int PetscDoubleView(int,double[],Viewer); 337 extern int PetscScalarView(int,Scalar[],Viewer); 338 339 /* 340 C code optimization is often enhanced by telling the compiler 341 that certain pointer arguments to functions are not aliased to 342 to other arguments. This is not yet ANSI C standard so we define 343 the macro "restrict" to indicate that the variable is not aliased 344 to any other argument. 345 */ 346 #if defined(PETSC_HAVE_RESTRICT) && !defined(__cplusplus) 347 #define restrict _Restrict 348 #else 349 #define restrict 350 #endif 351 352 /* 353 Determine if some of the kernel computation routines use 354 Fortran (rather than C) for the numerical calculations. On some machines 355 and compilers (like complex numbers) the Fortran version of the routines 356 is faster than the C/C++ versions. The flag PETSC_USE_FORTRAN_KERNELS 357 would be set in the petscconf.h file 358 */ 359 #if defined(PETSC_USE_FORTRAN_KERNELS) 360 361 #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTAIJ) 362 #define PETSC_USE_FORTRAN_KERNEL_MULTAIJ 363 #endif 364 365 #if !defined(PETSC_USE_FORTRAN_KERNEL_NORMSQR) 366 #define PETSC_USE_FORTRAN_KERNEL_NORMSQR 367 #endif 368 369 #if !defined(PETSC_USE_FORTRAN_KERNEL_MAXPY) 370 #define PETSC_USE_FORTRAN_KERNEL_MAXPY 371 #endif 372 373 #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ) 374 #define PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ 375 #endif 376 377 #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ) 378 #define PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ 379 #endif 380 381 #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ) 382 #define PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ 383 #endif 384 385 #if !defined(PETSC_USE_FORTRAN_KERNEL_MDOT) 386 #define PETSC_USE_FORTRAN_KERNEL_MDOT 387 #endif 388 389 #if !defined(PETSC_USE_FORTRAN_KERNEL_XTIMESY) 390 #define PETSC_USE_FORTRAN_KERNEL_XTIMESY 391 #endif 392 393 #endif 394 395 /* 396 Macros for indicating code that should be compiled with a C interface, 397 rather than a C++ interface. Any routines that are dynamically loaded 398 (such as the PCCreate_XXX() routines) must be wrapped so that the name 399 mangler does not change the functions symbol name. This just hides the 400 ugly extern "C" {} wrappers. 401 */ 402 #if defined(__cplusplus) 403 #define EXTERN_C_BEGIN extern "C" { 404 #define EXTERN_C_END } 405 #else 406 #define EXTERN_C_BEGIN 407 #define EXTERN_C_END 408 #endif 409 410 /* --------------------------------------------------------------------*/ 411 /* 412 DVF (win32) uses STDCALL calling convention by default. 413 The following is used by the fortran interface. 414 */ 415 #if defined (PETSC_USE_FORTRAN_STDCALL) 416 #define PETSC_STDCALL __stdcall 417 #else 418 #define PETSC_STDCALL 419 #endif 420 421 #endif 422