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