1 /* $Id: petsc.h,v 1.297 2001/09/07 20:13:16 bsmith Exp $ */ 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 This facilitates using C version of PETSc from C++ 11 */ 12 13 #if defined(PETSC_USE_EXTERN_CXX) && defined(__cplusplus) 14 #define PETSC_EXTERN_CXX_BEGIN extern "C" { 15 #define PETSC_EXTERN_CXX_END } 16 #else 17 #define PETSC_EXTERN_CXX_BEGIN 18 #define PETSC_EXTERN_CXX_END 19 #endif 20 /* ========================================================================== */ 21 /* 22 Current PETSc version number and release date 23 */ 24 #include "petscversion.h" 25 26 /* ========================================================================== */ 27 /* 28 petscconf.h is contained in bmake/${PETSC_ARCH}/petscconf.h it is 29 found automatically by the compiler due to the -I${PETSC_DIR}/bmake/${PETSC_ARCH} 30 in the bmake/common_variables definition of PETSC_INCLUDE 31 */ 32 #include "petscconf.h" 33 /* 34 Fixes for configure time choices which impact our interface. Currently only 35 calling conventions and extra compiler checking falls under this category. 36 */ 37 #if !defined(PETSC_PRINTF_FORMAT_CHECK) 38 #define PETSC_PRINTF_FORMAT_CHECK(a,b) 39 #endif 40 #if !defined (PETSC_STDCALL) 41 #define PETSC_STDCALL 42 #endif 43 #if !defined (PETSC_TEMPLATE) 44 #define PETSC_TEMPLATE 45 #endif 46 47 /* ========================================================================== */ 48 49 #include <stdio.h> 50 /* 51 Defines the interface to MPI allowing the use of all MPI functions. 52 */ 53 #include "mpi.h" 54 55 56 /* 57 Declare extern C stuff after incuding external header files 58 */ 59 60 PETSC_EXTERN_CXX_BEGIN 61 62 /* 63 EXTERN indicates a PETSc function defined elsewhere 64 */ 65 #if !defined(EXTERN) 66 #define EXTERN extern 67 #endif 68 69 /* 70 Defines some elementary mathematics functions and constants. 71 */ 72 #include "petscmath.h" 73 74 /* 75 Basic PETSc constants 76 */ 77 78 /*E 79 PetscTruth - Logical variable. Actually an integer 80 81 Level: beginner 82 83 E*/ 84 typedef enum { PETSC_FALSE,PETSC_TRUE } PetscTruth; 85 86 /*M 87 PETSC_FALSE - False value of PetscTruth 88 89 Level: beginner 90 91 Note: Zero integer 92 93 .seealso: PetscTruth 94 M*/ 95 96 /*M 97 PETSC_TRUE - True value of PetscTruth 98 99 Level: beginner 100 101 Note: Nonzero integer 102 103 .seealso: PetscTruth 104 M*/ 105 106 /*M 107 PETSC_YES - Alias for PETSC_TRUE 108 109 Level: beginner 110 111 Note: Zero integer 112 113 .seealso: PetscTruth 114 M*/ 115 116 /*M 117 PETSC_NO - Alias for PETSC_FALSE 118 119 Level: beginner 120 121 Note: Nonzero integer 122 123 .seealso: PetscTruth 124 M*/ 125 126 /*M 127 PETSC_NULL - standard way of passing in a null or array or pointer 128 129 Level: beginner 130 131 Notes: accepted by many PETSc functions to not set a parameter and instead use 132 some default 133 134 This macro does not exist in Fortran; you must use PETSC_NULL_INTEGER, 135 PETSC_NULL_DOUBLE_PRECISION etc 136 137 .seealso: PETSC_DECIDE, PETSC_DEFAULT, PETSC_IGNORE, PETSC_DETERMINE 138 139 M*/ 140 #define PETSC_NULL 0 141 142 /*M 143 PETSC_DECIDE - standard way of passing in integer or floating point parameter 144 where you wish PETSc to use the default. 145 146 Level: beginner 147 148 .seealso: PETSC_NULL, PETSC_DEFAULT, PETSC_IGNORE, PETSC_DETERMINE 149 150 M*/ 151 #define PETSC_DECIDE -1 152 153 /*M 154 PETSC_DEFAULT - standard way of passing in integer or floating point parameter 155 where you wish PETSc to use the default. 156 157 Level: beginner 158 159 .seealso: PETSC_DECIDE, PETSC_NULL, PETSC_IGNORE, PETSC_DETERMINE 160 161 M*/ 162 #define PETSC_DEFAULT -2 163 164 #define PETSC_YES PETSC_TRUE 165 #define PETSC_NO PETSC_FALSE 166 167 /*M 168 PETSC_IGNORE - same as PETSC_NULL, means PETSc will ignore this argument 169 170 Level: beginner 171 172 Notes: accepted by many PETSc functions to not set a parameter and instead use 173 some default 174 175 This macro does not exist in Fortran; you must use PETSC_NULL_INTEGER, 176 PETSC_NULL_DOUBLE_PRECISION etc 177 178 .seealso: PETSC_DECIDE, PETSC_DEFAULT, PETSC_NULL, PETSC_DETERMINE 179 180 M*/ 181 #define PETSC_IGNORE PETSC_NULL 182 183 /*M 184 PETSC_DETERMINE - standard way of passing in integer or floating point parameter 185 where you wish PETSc to compute the required value. 186 187 Level: beginner 188 189 .seealso: PETSC_DECIDE, PETSC_DEFAULT, PETSC_IGNORE, PETSC_NULL, VecSetSizes() 190 191 M*/ 192 #define PETSC_DETERMINE PETSC_DECIDE 193 194 /*M 195 PETSC_COMM_WORLD - a duplicate of the MPI_COMM_WORLD communicator which represents 196 all the processs 197 198 Level: beginner 199 200 Notes: PETSC_COMM_WORLD and MPI_COMM_WORLD are equivalent except that passing MPI_COMM_WORLD 201 into PETSc object constructors will result in using more MPI resources since an MPI_Comm_dup() 202 will be done on it internally. We recommend always using PETSC_COMM_WORLD 203 204 .seealso: PETSC_COMM_SELF 205 206 M*/ 207 extern MPI_Comm PETSC_COMM_WORLD; 208 209 /*M 210 PETSC_COMM_SELF - a duplicate of the MPI_COMM_SELF communicator which represents 211 the current process 212 213 Level: beginner 214 215 Notes: PETSC_COMM_SELF and MPI_COMM_SELF are equivalent except that passint MPI_COMM_SELF 216 into PETSc object constructors will result in using more MPI resources since an MPI_Comm_dup() 217 will be done on it internally. We recommend always using PETSC_COMM_SELF 218 219 .seealso: PETSC_COMM_WORLD 220 221 M*/ 222 extern MPI_Comm PETSC_COMM_SELF; 223 224 extern PetscTruth PetscInitializeCalled; 225 EXTERN int PetscSetCommWorld(MPI_Comm); 226 EXTERN int PetscSetHelpVersionFunctions(int (*)(MPI_Comm),int (*)(MPI_Comm)); 227 EXTERN int PetscCommDuplicate(MPI_Comm,MPI_Comm*,int*); 228 EXTERN int PetscCommDestroy(MPI_Comm*); 229 230 /*MC 231 PetscMalloc - Allocates memory 232 233 Input Parameter: 234 . m - number of bytes to allocate 235 236 Output Parameter: 237 . result - memory allocated 238 239 Synopsis: 240 int PetscMalloc(size_t m,void **result) 241 242 Level: beginner 243 244 Notes: Memory is always allocated at least double aligned 245 246 .seealso: PetscFree(), PetscNew() 247 248 Concepts: memory allocation 249 250 M*/ 251 #define PetscMalloc(a,b) (*PetscTrMalloc)((a),__LINE__,__FUNCT__,__FILE__,__SDIR__,(void**)(b)) 252 /*MC 253 PetscNew - Allocates memory of a particular type 254 255 Input Parameter: 256 . type - structure name of space to be allocated. Memory of size sizeof(type) is allocated 257 258 Output Parameter: 259 . result - memory allocated 260 261 Synopsis: 262 int PetscNew(struct type,((type *))result) 263 264 Level: beginner 265 266 .seealso: PetscFree(), PetscMalloc() 267 268 Concepts: memory allocation 269 270 M*/ 271 #define PetscNew(A,b) PetscMalloc(sizeof(A),(b)) 272 /*MC 273 PetscFree - Frees memory 274 275 Input Parameter: 276 . memory - memory to free 277 278 Synopsis: 279 int PetscFree(void *memory) 280 281 Level: beginner 282 283 Notes: Memory must have been obtained with PetscNew() or PetscMalloc() 284 285 .seealso: PetscNew(), PetscMalloc() 286 287 Concepts: memory allocation 288 289 M*/ 290 #define PetscFree(a) (*PetscTrFree)((a),__LINE__,__FUNCT__,__FILE__,__SDIR__) 291 EXTERN int (*PetscTrMalloc)(size_t,int,const char[],const char[],const char[],void**); 292 EXTERN int (*PetscTrFree)(void *,int,const char[],const char[],const char[]); 293 EXTERN int PetscSetMalloc(int (*)(size_t,int,const char[],const char[],const char[],void**),int (*)(void *,int,const char[],const char[],const char[])); 294 EXTERN int PetscClearMalloc(void); 295 296 /* 297 Routines for tracing memory corruption/bleeding with default PETSc 298 memory allocation 299 */ 300 EXTERN int PetscTrDump(FILE *); 301 EXTERN int PetscTrSpace(PetscLogDouble *,PetscLogDouble *,PetscLogDouble *); 302 EXTERN int PetscTrValid(int,const char[],const char[],const char[]); 303 EXTERN int PetscTrDebugLevel(int); 304 EXTERN int PetscTrLog(void); 305 EXTERN int PetscTrLogDump(FILE *); 306 EXTERN int PetscGetResidentSetSize(PetscLogDouble *); 307 308 /* 309 Variable type where we stash PETSc object pointers in Fortran. 310 Assumes that sizeof(long) == sizeof(void*)which is true on 311 all machines that we know. 312 */ 313 #define PetscFortranAddr long 314 315 /*E 316 PetscDataType - Used for handling different basic data types. 317 318 Level: beginner 319 320 .seealso: PetscBinaryRead(), PetscBinaryWrite(), PetscDataTypeToMPIDataType(), 321 PetscDataTypeGetSize(), PetscDataTypeGetName() 322 323 E*/ 324 typedef enum {PETSC_INT = 0,PETSC_DOUBLE = 1,PETSC_COMPLEX = 2, 325 PETSC_LONG =3 ,PETSC_SHORT = 4,PETSC_FLOAT = 5, 326 PETSC_CHAR = 6,PETSC_LOGICAL = 7} PetscDataType; 327 #if defined(PETSC_USE_COMPLEX) 328 #define PETSC_SCALAR PETSC_COMPLEX 329 #else 330 #if defined(PETSC_USE_SINGLE) 331 #define PETSC_SCALAR PETSC_FLOAT 332 #else 333 #define PETSC_SCALAR PETSC_DOUBLE 334 #endif 335 #endif 336 #if defined(PETSC_USE_SINGLE) 337 #define PETSC_REAL PETSC_FLOAT 338 #else 339 #define PETSC_REAL PETSC_DOUBLE 340 #endif 341 #define PETSC_FORTRANADDR PETSC_LONG 342 343 EXTERN int PetscDataTypeToMPIDataType(PetscDataType,MPI_Datatype*); 344 EXTERN int PetscDataTypeGetSize(PetscDataType,int*); 345 EXTERN int PetscDataTypeGetName(PetscDataType,const char*[]); 346 347 /* 348 Basic memory and string operations. These are usually simple wrappers 349 around the basic Unix system calls, but a few of them have additional 350 functionality and/or error checking. 351 */ 352 EXTERN int PetscMemcpy(void *,const void *,int); 353 EXTERN int PetscBitMemcpy(void*,int,const void*,int,int,PetscDataType); 354 EXTERN int PetscMemmove(void *,void *,int); 355 EXTERN int PetscMemzero(void *,int); 356 EXTERN int PetscMemcmp(const void*,const void*,int,PetscTruth *); 357 EXTERN int PetscStrlen(const char[],int*); 358 EXTERN int PetscStrcmp(const char[],const char[],PetscTruth *); 359 EXTERN int PetscStrgrt(const char[],const char[],PetscTruth *); 360 EXTERN int PetscStrcasecmp(const char[],const char[],PetscTruth*); 361 EXTERN int PetscStrncmp(const char[],const char[],int,PetscTruth*); 362 EXTERN int PetscStrcpy(char[],const char[]); 363 EXTERN int PetscStrcat(char[],const char[]); 364 EXTERN int PetscStrncat(char[],const char[],int); 365 EXTERN int PetscStrncpy(char[],const char[],int); 366 EXTERN int PetscStrchr(const char[],char,char *[]); 367 EXTERN int PetscStrtolower(char[]); 368 EXTERN int PetscStrrchr(const char[],char,char *[]); 369 EXTERN int PetscStrstr(const char[],const char[],char *[]); 370 EXTERN int PetscStrallocpy(const char[],char *[]); 371 EXTERN int PetscStrreplace(MPI_Comm,const char[],char[],int); 372 #define PetscStrfree(a) ((a) ? PetscFree(a) : 0) 373 typedef struct {char token;char *array;char *current;} PetscToken; 374 EXTERN int PetscTokenCreate(const char[],const char,PetscToken**); 375 EXTERN int PetscTokenFind(PetscToken*,char *[]); 376 EXTERN int PetscTokenDestroy(PetscToken*); 377 378 /* 379 These are MPI operations for MPI_Allreduce() etc 380 */ 381 EXTERN MPI_Op PetscMaxSum_Op; 382 #if defined(PETSC_USE_COMPLEX) 383 EXTERN MPI_Op PetscSum_Op; 384 #else 385 #define PetscSum_Op MPI_SUM 386 #endif 387 EXTERN int PetscMaxSum(MPI_Comm,const int[],int*,int*); 388 389 /*S 390 PetscObject - any PETSc object, PetscViewer, Mat, Vec, KSP etc 391 392 Level: beginner 393 394 Note: This is the base class from which all objects appear. 395 396 .seealso: PetscObjectDestroy(), PetscObjectView(), PetscObjectGetName(), PetscObjectSetName() 397 S*/ 398 typedef struct _p_PetscObject* PetscObject; 399 400 /*S 401 PetscFList - Linked list of functions, possibly stored in dynamic libraries, accessed 402 by string name 403 404 Level: advanced 405 406 .seealso: PetscFListAdd(), PetscFListDestroy() 407 S*/ 408 typedef struct _PetscFList *PetscFList; 409 410 #include "petscviewer.h" 411 #include "petscoptions.h" 412 413 EXTERN int PetscShowMemoryUsage(PetscViewer,const char[]); 414 EXTERN int PetscGetTime(PetscLogDouble*); 415 EXTERN int PetscGetCPUTime(PetscLogDouble*); 416 EXTERN int PetscSleep(int); 417 418 /* 419 Initialization of PETSc 420 */ 421 EXTERN int PetscInitialize(int*,char***,const char[],const char[]); 422 EXTERN int PetscInitializeNoArguments(void); 423 EXTERN int PetscFinalize(void); 424 EXTERN int PetscInitializeFortran(void); 425 EXTERN int PetscGetArgs(int*,char ***); 426 EXTERN int PetscEnd(void); 427 428 /* 429 ParameterDict is an abstraction for arguments to interface mechanisms 430 */ 431 extern int DICT_COOKIE; 432 typedef struct _p_Dict *ParameterDict; 433 434 typedef void (**PetscVoidFunction)(void); 435 436 /* 437 PetscTryMethod - Queries an object for a method, if it exists then calls it. 438 These are intended to be used only inside PETSc functions. 439 */ 440 #define PetscTryMethod(obj,A,B,C) \ 441 0;{ int (*f)B, __ierr; \ 442 __ierr = PetscObjectQueryFunction((PetscObject)obj,#A,(PetscVoidFunction)&f);CHKERRQ(__ierr); \ 443 if (f) {__ierr = (*f)C;CHKERRQ(__ierr);}\ 444 } 445 #define PetscUseMethod(obj,A,B,C) \ 446 0;{ int (*f)B, __ierr; \ 447 __ierr = PetscObjectQueryFunction((PetscObject)obj,A,(PetscVoidFunction)&f);CHKERRQ(__ierr); \ 448 if (f) {__ierr = (*f)C;CHKERRQ(__ierr);}\ 449 else {SETERRQ1(1,"Cannot locate function %s in object",A);} \ 450 } 451 /* 452 Functions that can act on any PETSc object. 453 */ 454 EXTERN int PetscObjectDestroy(PetscObject); 455 EXTERN int PetscObjectExists(PetscObject,PetscTruth*); 456 EXTERN int PetscObjectGetComm(PetscObject,MPI_Comm *); 457 EXTERN int PetscObjectGetCookie(PetscObject,int *); 458 EXTERN int PetscObjectGetType(PetscObject,int *); 459 EXTERN int PetscObjectSetName(PetscObject,const char[]); 460 EXTERN int PetscObjectGetName(PetscObject,char*[]); 461 EXTERN int PetscObjectReference(PetscObject); 462 EXTERN int PetscObjectGetReference(PetscObject,int*); 463 EXTERN int PetscObjectDereference(PetscObject); 464 EXTERN int PetscObjectGetNewTag(PetscObject,int *); 465 EXTERN int PetscObjectSetParameterDict(PetscObject,ParameterDict); 466 EXTERN int PetscObjectGetParameterDict(PetscObject,ParameterDict*); 467 EXTERN int PetscCommGetNewTag(MPI_Comm,int *); 468 EXTERN int PetscObjectView(PetscObject,PetscViewer); 469 EXTERN int PetscObjectCompose(PetscObject,const char[],PetscObject); 470 EXTERN int PetscObjectQuery(PetscObject,const char[],PetscObject *); 471 EXTERN int PetscObjectComposeFunction(PetscObject,const char[],const char[],void (*)(void)); 472 473 typedef void (*FCNVOID)(void); /* cast in next macro should never be extern C */ 474 typedef int (*FCNINTVOID)(void); /* used in casts to make sure they are not extern C */ 475 /*MC 476 PetscObjectComposeFunctionDynamic - Associates a function with a given PETSc object. 477 478 Collective on PetscObject 479 480 Input Parameters: 481 + obj - the PETSc object; this must be cast with a (PetscObject), for example, 482 PetscObjectCompose((PetscObject)mat,...); 483 . name - name associated with the child function 484 . fname - name of the function 485 - ptr - function pointer (or PETSC_NULL if using dynamic libraries) 486 487 Level: advanced 488 489 Synopsis: 490 int PetscObjectComposeFunctionDynamic(PetscObject obj,const char name[],const char fname[],void *ptr) 491 492 Notes: 493 PetscObjectComposeFunctionDynamic() can be used with any PETSc object (such as 494 Mat, Vec, KSP, SNES, etc.) or any user-provided object. 495 496 The composed function must be wrapped in a EXTERN_C_BEGIN/END for this to 497 work in C++/complex with dynamic link libraries (PETSC_USE_DYNAMIC_LIBRARIES) 498 enabled. 499 500 Concepts: objects^composing functions 501 Concepts: composing functions 502 Concepts: functions^querying 503 Concepts: objects^querying 504 Concepts: querying objects 505 506 .seealso: PetscObjectQueryFunction() 507 M*/ 508 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 509 #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,0) 510 #else 511 #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,(FCNVOID)(d)) 512 #endif 513 514 EXTERN int PetscObjectQueryFunction(PetscObject,const char[],void (**)(void)); 515 EXTERN int PetscObjectSetOptionsPrefix(PetscObject,const char[]); 516 EXTERN int PetscObjectAppendOptionsPrefix(PetscObject,const char[]); 517 EXTERN int PetscObjectPrependOptionsPrefix(PetscObject,const char[]); 518 EXTERN int PetscObjectGetOptionsPrefix(PetscObject,char*[]); 519 EXTERN int PetscObjectPublish(PetscObject); 520 EXTERN int PetscObjectChangeTypeName(PetscObject,const char[]); 521 EXTERN int PetscObjectRegisterDestroy(PetscObject); 522 EXTERN int PetscObjectRegisterDestroyAll(void); 523 EXTERN int PetscObjectName(PetscObject); 524 EXTERN int PetscTypeCompare(PetscObject,const char[],PetscTruth*); 525 526 /* 527 Defines PETSc error handling. 528 */ 529 #include "petscerror.h" 530 531 /*S 532 PetscOList - Linked list of PETSc objects, accessable by string name 533 534 Level: advanced 535 536 .seealso: PetscOListAdd(), PetscOListDestroy(), PetscOListFind() 537 S*/ 538 typedef struct _PetscOList *PetscOList; 539 540 EXTERN int PetscOListDestroy(PetscOList *); 541 EXTERN int PetscOListFind(PetscOList,const char[],PetscObject*); 542 EXTERN int PetscOListReverseFind(PetscOList,PetscObject,char**); 543 EXTERN int PetscOListAdd(PetscOList *,const char[],PetscObject); 544 EXTERN int PetscOListDuplicate(PetscOList,PetscOList *); 545 546 /* 547 Dynamic library lists. Lists of names of routines in dynamic 548 link libraries that will be loaded as needed. 549 */ 550 EXTERN int PetscFListAdd(PetscFList*,const char[],const char[],void (*)(void)); 551 EXTERN int PetscFListDestroy(PetscFList*); 552 EXTERN int PetscFListFind(MPI_Comm,PetscFList,const char[],void (**)(void)); 553 EXTERN int PetscFListPrintTypes(MPI_Comm,FILE*,const char[],const char[],const char[],const char[],PetscFList); 554 #if defined(PETSC_USE_DYNAMIC_LIBRARIES) 555 #define PetscFListAddDynamic(a,b,p,c) PetscFListAdd(a,b,p,0) 556 #else 557 #define PetscFListAddDynamic(a,b,p,c) PetscFListAdd(a,b,p,(void (*)(void))c) 558 #endif 559 EXTERN int PetscFListDuplicate(PetscFList,PetscFList *); 560 EXTERN int PetscFListView(PetscFList,PetscViewer); 561 EXTERN int PetscFListConcat(const char [],const char [],char []); 562 EXTERN int PetscFListGet(PetscFList,char ***,int*); 563 564 /*S 565 PetscDLLibraryList - Linked list of dynamics libraries to search for functions 566 567 Level: advanced 568 569 PETSC_USE_DYNAMIC_LIBRARIES must be defined in petscconf.h to use dynamic libraries 570 571 .seealso: PetscDLLibraryOpen() 572 S*/ 573 typedef struct _PetscDLLibraryList *PetscDLLibraryList; 574 extern PetscDLLibraryList DLLibrariesLoaded; 575 EXTERN int PetscDLLibraryRetrieve(MPI_Comm,const char[],char *,int,PetscTruth *); 576 EXTERN int PetscDLLibraryOpen(MPI_Comm,const char[],void **); 577 EXTERN int PetscDLLibrarySym(MPI_Comm,PetscDLLibraryList *,const char[],const char[],void **); 578 EXTERN int PetscDLLibraryAppend(MPI_Comm,PetscDLLibraryList *,const char[]); 579 EXTERN int PetscDLLibraryPrepend(MPI_Comm,PetscDLLibraryList *,const char[]); 580 EXTERN int PetscDLLibraryClose(PetscDLLibraryList); 581 EXTERN int PetscDLLibraryPrintPath(void); 582 EXTERN int PetscDLLibraryGetInfo(void *,const char[],const char *[]); 583 584 /* 585 Mechanism for translating PETSc object representations between languages 586 Not currently used. 587 */ 588 typedef enum {PETSC_LANGUAGE_C,PETSC_LANGUAGE_CPP} PetscLanguage; 589 #define PETSC_LANGUAGE_F77 PETSC_LANGUAGE_C 590 EXTERN int PetscObjectComposeLanguage(PetscObject,PetscLanguage,void *); 591 EXTERN int PetscObjectQueryLanguage(PetscObject,PetscLanguage,void **); 592 593 /* 594 Useful utility routines 595 */ 596 EXTERN int PetscSplitOwnership(MPI_Comm,int*,int*); 597 EXTERN int PetscSplitOwnershipBlock(MPI_Comm,int,int*,int*); 598 EXTERN int PetscSequentialPhaseBegin(MPI_Comm,int); 599 EXTERN int PetscSequentialPhaseEnd(MPI_Comm,int); 600 EXTERN int PetscBarrier(PetscObject); 601 EXTERN int PetscMPIDump(FILE*); 602 603 #define PetscNot(a) ((a) ? PETSC_FALSE : PETSC_TRUE) 604 /* 605 Defines basic graphics available from PETSc. 606 */ 607 #include "petscdraw.h" 608 609 /* 610 Defines the base data structures for all PETSc objects 611 */ 612 #include "petschead.h" 613 614 /* 615 Defines PETSc profiling. 616 */ 617 #include "petsclog.h" 618 619 /* 620 For locking, unlocking and destroying AMS memories associated with 621 PETSc objects 622 */ 623 #if defined(PETSC_HAVE_AMS) 624 625 extern PetscTruth PetscAMSPublishAll; 626 #define PetscPublishAll(v) (PetscAMSPublishAll ? PetscObjectPublish((PetscObject)v) : 0) 627 #define PetscObjectTakeAccess(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_take_access(((PetscObject)(obj))->amem)) 628 #define PetscObjectGrantAccess(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_grant_access(((PetscObject)(obj))->amem)) 629 #define PetscObjectDepublish(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_destroy(((PetscObject)(obj))->amem)); \ 630 ((PetscObject)(obj))->amem = -1; 631 632 #else 633 634 #define PetscPublishAll(v) 0 635 #define PetscObjectTakeAccess(obj) 0 636 #define PetscObjectGrantAccess(obj) 0 637 #define PetscObjectDepublish(obj) 0 638 639 #endif 640 641 642 643 /* 644 This code allows one to pass a MPI communicator between 645 C and Fortran. MPI 2.0 defines a standard API for doing this. 646 The code here is provided to allow PETSc to work with MPI 1.1 647 standard MPI libraries. 648 */ 649 EXTERN int MPICCommToFortranComm(MPI_Comm,int *); 650 EXTERN int MPIFortranCommToCComm(int,MPI_Comm*); 651 652 /* 653 Simple PETSc parallel IO for ASCII printing 654 */ 655 EXTERN int PetscFixFilename(const char[],char[]); 656 EXTERN int PetscFOpen(MPI_Comm,const char[],const char[],FILE**); 657 EXTERN int PetscFClose(MPI_Comm,FILE*); 658 EXTERN int PetscFPrintf(MPI_Comm,FILE*,const char[],...) PETSC_PRINTF_FORMAT_CHECK(3,4); 659 EXTERN int PetscPrintf(MPI_Comm,const char[],...) PETSC_PRINTF_FORMAT_CHECK(2,3); 660 661 /*MC 662 PetscErrorPrintf - Prints error messages. 663 664 Not Collective 665 666 Synopsis: 667 int (*PetscErrorPrintf)(const char format[],...); 668 669 Input Parameters: 670 . format - the usual printf() format string 671 672 Options Database Keys: 673 . -error_output_stderr - cause error messages to be printed to stderr instead of the 674 (default) stdout 675 676 677 Level: developer 678 679 Fortran Note: 680 This routine is not supported in Fortran. 681 682 Concepts: error messages^printing 683 Concepts: printing^error messages 684 685 .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscHelpPrintf() 686 M*/ 687 EXTERN int (*PetscErrorPrintf)(const char[],...); 688 689 /*MC 690 PetscHelpPrintf - Prints help messages. 691 692 Not Collective 693 694 Synopsis: 695 int (*PetscHelpPrintf)(const char format[],...); 696 697 Input Parameters: 698 . format - the usual printf() format string 699 700 Level: developer 701 702 Fortran Note: 703 This routine is not supported in Fortran. 704 705 Concepts: help messages^printing 706 Concepts: printing^help messages 707 708 .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscErrorPrintf() 709 M*/ 710 EXTERN int (*PetscHelpPrintf)(MPI_Comm,const char[],...); 711 712 EXTERN int PetscPOpen(MPI_Comm,const char[],const char[],const char[],FILE **); 713 EXTERN int PetscPClose(MPI_Comm,FILE*); 714 EXTERN int PetscSynchronizedPrintf(MPI_Comm,const char[],...) PETSC_PRINTF_FORMAT_CHECK(2,3); 715 EXTERN int PetscSynchronizedFPrintf(MPI_Comm,FILE*,const char[],...) PETSC_PRINTF_FORMAT_CHECK(3,4); 716 EXTERN int PetscSynchronizedFlush(MPI_Comm); 717 EXTERN int PetscSynchronizedFGets(MPI_Comm,FILE*,int,char[]); 718 EXTERN int PetscStartMatlab(MPI_Comm,const char[],const char[],FILE**); 719 EXTERN int PetscStartJava(MPI_Comm,const char[],const char[],FILE**); 720 EXTERN int PetscGetPetscDir(const char*[]); 721 722 EXTERN int PetscPopUpSelect(MPI_Comm,char*,char*,int,char**,int*); 723 /*S 724 PetscObjectContainer - Simple PETSc object that contains a pointer to any required data 725 726 Level: advanced 727 728 .seealso: PetscObject, PetscObjectContainerCreate() 729 S*/ 730 typedef struct _p_PetscObjectContainer* PetscObjectContainer; 731 EXTERN int PetscObjectContainerGetPointer(PetscObjectContainer,void **); 732 EXTERN int PetscObjectContainerSetPointer(PetscObjectContainer,void *); 733 EXTERN int PetscObjectContainerDestroy(PetscObjectContainer); 734 EXTERN int PetscObjectContainerCreate(MPI_Comm comm,PetscObjectContainer *); 735 736 /* 737 For incremental debugging 738 */ 739 extern PetscTruth PetscCompare; 740 EXTERN int PetscCompareDouble(double); 741 EXTERN int PetscCompareScalar(PetscScalar); 742 EXTERN int PetscCompareInt(int); 743 744 /* 745 For use in debuggers 746 */ 747 extern int PetscGlobalRank,PetscGlobalSize; 748 EXTERN int PetscIntView(int,int[],PetscViewer); 749 EXTERN int PetscRealView(int,PetscReal[],PetscViewer); 750 EXTERN int PetscScalarView(int,PetscScalar[],PetscViewer); 751 752 /* 753 Allows accessing Matlab Engine 754 */ 755 #include "petscmatlab.h" 756 757 /* 758 C code optimization is often enhanced by telling the compiler 759 that certain pointer arguments to functions are not aliased to 760 to other arguments. This is not yet ANSI C standard so we define 761 the macro "restrict" to indicate that the variable is not aliased 762 to any other argument. 763 */ 764 #if defined(PETSC_HAVE_RESTRICT) && !defined(__cplusplus) 765 #define restrict _Restrict 766 #else 767 #if defined(restrict) 768 #undef restrict 769 #endif 770 #define restrict 771 #endif 772 773 /* 774 Determine if some of the kernel computation routines use 775 Fortran (rather than C) for the numerical calculations. On some machines 776 and compilers (like complex numbers) the Fortran version of the routines 777 is faster than the C/C++ versions. The flag PETSC_USE_FORTRAN_KERNELS 778 would be set in the petscconf.h file 779 */ 780 #if defined(PETSC_USE_FORTRAN_KERNELS) 781 782 #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTAIJ) 783 #define PETSC_USE_FORTRAN_KERNEL_MULTAIJ 784 #endif 785 786 #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTTRANSPOSEAIJ) 787 #define PETSC_USE_FORTRAN_KERNEL_MULTTRANSPOSEAIJ 788 #endif 789 790 #if !defined(PETSC_USE_FORTRAN_KERNEL_NORM) 791 #define PETSC_USE_FORTRAN_KERNEL_NORM 792 #endif 793 794 #if !defined(PETSC_USE_FORTRAN_KERNEL_MAXPY) 795 #define PETSC_USE_FORTRAN_KERNEL_MAXPY 796 #endif 797 798 #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ) 799 #define PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ 800 #endif 801 802 #if !defined(PETSC_USE_FORTRAN_KERNEL_RELAXAIJ) 803 #define PETSC_USE_FORTRAN_KERNEL_RELAXAIJ 804 #endif 805 806 #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ) 807 #define PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ 808 #endif 809 810 #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ) 811 #define PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ 812 #endif 813 814 #if !defined(PETSC_USE_FORTRAN_KERNEL_MDOT) 815 #define PETSC_USE_FORTRAN_KERNEL_MDOT 816 #endif 817 818 #if !defined(PETSC_USE_FORTRAN_KERNEL_XTIMESY) 819 #define PETSC_USE_FORTRAN_KERNEL_XTIMESY 820 #endif 821 822 #if !defined(PETSC_USE_FORTRAN_KERNEL_AYPX) 823 #define PETSC_USE_FORTRAN_KERNEL_AYPX 824 #endif 825 826 #if !defined(PETSC_USE_FORTRAN_KERNEL_WAXPY) 827 #define PETSC_USE_FORTRAN_KERNEL_WAXPY 828 #endif 829 830 #endif 831 832 /* 833 Macros for indicating code that should be compiled with a C interface, 834 rather than a C++ interface. Any routines that are dynamically loaded 835 (such as the PCCreate_XXX() routines) must be wrapped so that the name 836 mangler does not change the functions symbol name. This just hides the 837 ugly extern "C" {} wrappers. 838 */ 839 #if defined(__cplusplus) 840 #define EXTERN_C_BEGIN extern "C" { 841 #define EXTERN_C_END } 842 #else 843 #define EXTERN_C_BEGIN 844 #define EXTERN_C_END 845 #endif 846 847 /* --------------------------------------------------------------------*/ 848 849 /*M 850 size - integer variable used to contain the number of processors in 851 the relevent MPI_Comm 852 853 Level: beginner 854 855 .seealso: rank, comm 856 M*/ 857 858 /*M 859 rank - integer variable used to contain the number of this processor relative 860 to all in the relevent MPI_Comm 861 862 Level: beginner 863 864 .seealso: size, comm 865 M*/ 866 867 /*M 868 comm - MPI_Comm used in the current routine or object 869 870 Level: beginner 871 872 .seealso: size, rank 873 M*/ 874 875 /*M 876 MPI_Comm - the basic object used by MPI to determine which processes are involved in a 877 communication 878 879 Level: beginner 880 881 Note: This manual page is a place-holder because MPICH does not have a manual page for MPI_Comm 882 883 .seealso: size, rank, comm, PETSC_COMM_WORLD, PETSC_COMM_SELF 884 M*/ 885 886 /*M 887 PetscScalar - PETSc type that represents either a double precision real number or 888 a double precision complex number if the code is compiled with BOPT=g_complex or O_complex 889 890 Level: beginner 891 892 .seealso: PetscReal, PassiveReal, PassiveScalar 893 M*/ 894 895 /*M 896 PetscReal - PETSc type that represents a double precision real number 897 898 Level: beginner 899 900 .seealso: PetscScalar, PassiveReal, PassiveScalar 901 M*/ 902 903 /*M 904 PassiveScalar - PETSc type that represents either a double precision real number or 905 a double precision complex number if the code is compiled with BOPT=g_complex or O_complex 906 907 Level: beginner 908 909 This is the same as a PetscScalar except in code that is automatically differentiated it is 910 treated as a constant (not an indendent or dependent variable) 911 912 .seealso: PetscReal, PassiveReal, PetscScalar 913 M*/ 914 915 /*M 916 PassiveReal - PETSc type that represents a double precision real number 917 918 Level: beginner 919 920 This is the same as a PetscReal except in code that is automatically differentiated it is 921 treated as a constant (not an indendent or dependent variable) 922 923 .seealso: PetscScalar, PetscReal, PassiveScalar 924 M*/ 925 926 /* 927 The IBM include files define hz, here we hide it so that it may be used 928 as a regular user variable. 929 */ 930 #if defined(hz) 931 #undef hz 932 #endif 933 934 /* For arrays that contain filenames or paths */ 935 936 937 #if defined(PETSC_HAVE_LIMITS_H) 938 #include <limits.h> 939 #endif 940 #if defined(PETSC_HAVE_SYS_PARAM_H) 941 #include <sys/param.h> 942 #endif 943 944 #if defined(MAXPATHLEN) 945 # define PETSC_MAX_PATH_LEN MAXPATHLEN 946 #elif defined(MAX_PATH) 947 # define PETSC_MAX_PATH_LEN MAX_PATH 948 #elif defined(_MAX_PATH) 949 # define PETSC_MAX_PATH_LEN _MAX_PATH 950 #else 951 # define PETSC_MAX_PATH_LEN 4096 952 #endif 953 954 PETSC_EXTERN_CXX_END 955 #endif 956 957 958