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