Actual source code: petsc.h

  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: */

  9: /* ========================================================================== */
 10: /* 
 11:    Current PETSc version number and release date
 12: */
 13:  #include petscversion.h

 15: /* ========================================================================== */
 16: /* 
 17:    petscconf.h is contained in bmake/${PETSC_ARCH}/petscconf.h it is 
 18:    found automatically by the compiler due to the -I${PETSC_DIR}/bmake/${PETSC_ARCH}
 19:    in the bmake/common_variables definition of PETSC_INCLUDE
 20: */
 21: #include "petscconf.h"
 22: /*
 23:    Fixes for configure time choices which impact our interface. Currently only
 24:    calling conventions and extra compiler checking falls under this category.
 25: */
 26: #if !defined(PETSC_PRINTF_FORMAT_CHECK)
 27: #define PETSC_PRINTF_FORMAT_CHECK(a,b)
 28: #endif
 29: #if !defined (PETSC_STDCALL)
 30: #define PETSC_STDCALL
 31: #endif
 32: #if !defined (PETSC_TEMPLATE)
 33: #define PETSC_TEMPLATE
 34: #endif

 36: /* ========================================================================== */

 38: #include <stdio.h>
 39: /*
 40:     Defines the interface to MPI allowing the use of all MPI functions.
 41: */
 42: #include "mpi.h"

 44: /*
 45:     EXTERN indicates a PETSc function defined elsewhere
 46: */
 47: #if !defined(EXTERN)
 48: #define EXTERN extern
 49: #endif

 51: /*
 52:     Defines some elementary mathematics functions and constants.
 53: */
 54:  #include petscmath.h

 56: /*
 57:        Basic PETSc constants
 58: */

 60: /*E
 61:     PetscTruth - Logical variable. Actually an integer

 63:    Level: beginner

 65: E*/
 66: typedef enum { PETSC_FALSE,PETSC_TRUE } PetscTruth;

 68: /*M
 69:     PETSC_NULL - standard way of passing in a null or array or pointer

 71:    Level: beginner

 73:    Notes: accepted by many PETSc functions to not set a parameter and instead use
 74:           some default

 76:           This macro does not exist in Fortran; you must use PETSC_NULL_INTEGER, 
 77:           PETSC_NULL_DOUBLE_PRECISION etc

 79: .seealso: PETSC_DECIDE, PETSC_DEFAULT, PETSC_IGNORE, PETSC_DETERMINE

 81: M*/
 82: #define PETSC_NULL           0

 84: /*M
 85:     PETSC_DECIDE - standard way of passing in integer or floating point parameter
 86:        where you wish PETSc to use the default.

 88:    Level: beginner

 90: .seealso: PETSC_DECIDE, PETSC_DEFAULT, PETSC_IGNORE, PETSC_DETERMINE

 92: M*/
 93: #define PETSC_DECIDE         -1

 95: /*M
 96:     PETSC_DEFAULT - standard way of passing in integer or floating point parameter
 97:        where you wish PETSc to use the default.

 99:    Level: beginner

101: .seealso: PETSC_DECIDE, PETSC_DEFAULT, PETSC_IGNORE, PETSC_DETERMINE

103: M*/
104: #define PETSC_DEFAULT        -2

106: #define PETSC_YES            PETSC_TRUE
107: #define PETSC_NO             PETSC_FALSE

109: /*M
110:     PETSC_IGNORE - same as PETSC_NULL, means PETSc will ignore this argument

112:    Level: beginner

114:    Notes: accepted by many PETSc functions to not set a parameter and instead use
115:           some default

117:           This macro does not exist in Fortran; you must use PETSC_NULL_INTEGER, 
118:           PETSC_NULL_DOUBLE_PRECISION etc

120: .seealso: PETSC_DECIDE, PETSC_DEFAULT, PETSC_NULL, PETSC_DETERMINE

122: M*/
123: #define PETSC_IGNORE         PETSC_NULL

125: /*M
126:     PETSC_DETERMINE - standard way of passing in integer or floating point parameter
127:        where you wish PETSc to compute the required value.

129:    Level: beginner

131: .seealso: PETSC_DECIDE, PETSC_DEFAULT, PETSC_IGNORE, PETSC_DETERMINE, VecSetSizes()

133: M*/
134: #define PETSC_DETERMINE      PETSC_DECIDE

136: /*M
137:     PETSC_COMM_WORLD - a duplicate of the MPI_COMM_WORLD communicator which represents
138:            all the processs

140:    Level: beginner

142:    Notes: PETSC_COMM_WORLD and MPI_COMM_WORLD are equivalent except that passint MPI_COMM_WORLD
143:           into PETSc object constructors will result in using more MPI resources since an MPI_Comm_dup()
144:           will be done on it internally. We recommend always using PETSC_COMM_WORLD

146: .seealso: PETSC_COMM_SELF

148: M*/
149: extern MPI_Comm   PETSC_COMM_WORLD;

151: /*M
152:     PETSC_COMM_SELF - a duplicate of the MPI_COMM_SELF communicator which represents
153:            the current process

155:    Level: beginner

157:    Notes: PETSC_COMM_SELF and MPI_COMM_SELF are equivalent except that passint MPI_COMM_SELF
158:           into PETSc object constructors will result in using more MPI resources since an MPI_Comm_dup()
159:           will be done on it internally. We recommend always using PETSC_COMM_SELF

161: .seealso: PETSC_COMM_WORLD

163: M*/
164: extern MPI_Comm   PETSC_COMM_SELF;

166: extern PetscTruth PetscInitializeCalled;
167: EXTERN int        PetscSetCommWorld(MPI_Comm);
168: EXTERN int        PetscSetHelpVersionFunctions(int (*)(MPI_Comm),int (*)(MPI_Comm));

170: /*MC
171:    PetscMalloc - Allocates memory

173:    Input Parameter:
174: .  m - number of bytes to allocate

176:    Output Parameter:
177: .  result - memory allocated

179:    Synopsis:
180:    int PetscMalloc(size_t m,void **result)

182:    Level: beginner

184:    Notes: Memory is always allocated at least double aligned

186: .seealso: PetscFree(), PetscNew()

188:   Concepts: memory allocation

190: M*/
191: #define PetscMalloc(a,b)     (*PetscTrMalloc)((a),__LINE__,__FUNCT__,__FILE__,__SDIR__,(void**)(b))
192: /*MC
193:    PetscNew - Allocates memory of a particular type

195:    Input Parameter:
196: . type - structure name of space to be allocated. Memory of size sizeof(type) is allocated

198:    Output Parameter:
199: .  result - memory allocated

201:    Synopsis:
202:    int PetscNew(struct type,((type *))result)

204:    Level: beginner

206: .seealso: PetscFree(), PetscMalloc()

208:   Concepts: memory allocation

210: M*/
211: #define PetscNew(A,b)        PetscMalloc(sizeof(A),(b))
212: /*MC
213:    PetscFree - Frees memory

215:    Input Parameter:
216: .   memory - memory to free

218:    Synopsis:
219:    int PetscFree(void *memory)

221:    Level: beginner

223:    Notes: Memory must have been obtained with PetscNew() or PetscMalloc()

225: .seealso: PetscNew(), PetscMalloc()

227:   Concepts: memory allocation

229: M*/
230: #define PetscFree(a)         (*PetscTrFree)((a),__LINE__,__FUNCT__,__FILE__,__SDIR__)
231: EXTERN int  (*PetscTrMalloc)(size_t,int,char*,char*,char*,void**);
232: EXTERN int  (*PetscTrFree)(void *,int,char*,char*,char*);
233: EXTERN int  PetscSetMalloc(int (*)(size_t,int,char*,char*,char*,void**),int (*)(void *,int,char*,char*,char*));
234: EXTERN int  PetscClearMalloc(void);

236: /*
237:    Routines for tracing memory corruption/bleeding with default PETSc 
238:    memory allocation
239: */
240: EXTERN int   PetscTrDump(FILE *);
241: EXTERN int   PetscTrSpace(PetscLogDouble *,PetscLogDouble *,PetscLogDouble *);
242: EXTERN int   PetscTrValid(int,const char[],const char[],const char[]);
243: EXTERN int   PetscTrDebugLevel(int);
244: EXTERN int   PetscTrLog(void);
245: EXTERN int   PetscTrLogDump(FILE *);
246: EXTERN int   PetscGetResidentSetSize(PetscLogDouble *);

248: /*
249:     Variable type where we stash PETSc object pointers in Fortran.
250:     Assumes that sizeof(long) == sizeof(void*)which is true on 
251:     all machines that we know.
252: */
253: #define PetscFortranAddr   long

255: /*E
256:     PetscDataType - Used for handling different basic data types.

258:    Level: beginner

260: .seealso: PetscBinaryRead(), PetscBinaryWrite(), PetscDataTypeToMPIDataType(),
261:           PetscDataTypeGetSize(), PetscDataTypeGetName()

263: E*/
264: typedef enum {PETSC_INT = 0,PETSC_DOUBLE = 1,PETSC_COMPLEX = 2,
265:               PETSC_LONG =3 ,PETSC_SHORT = 4,PETSC_FLOAT = 5,
266:               PETSC_CHAR = 6,PETSC_LOGICAL = 7} PetscDataType;
267: #if defined(PETSC_USE_COMPLEX)
268: #define PETSC_SCALAR PETSC_COMPLEX
269: #else
270: #if defined(PETSC_USE_SINGLE)
271: #define PETSC_SCALAR PETSC_FLOAT
272: #else
273: #define PETSC_SCALAR PETSC_DOUBLE
274: #endif
275: #endif
276: #if defined(PETSC_USE_SINGLE)
277: #define PETSC_REAL PETSC_FLOAT
278: #else
279: #define PETSC_REAL PETSC_DOUBLE
280: #endif
281: #define PETSC_FORTRANADDR PETSC_LONG

283: EXTERN int PetscDataTypeToMPIDataType(PetscDataType,MPI_Datatype*);
284: EXTERN int PetscDataTypeGetSize(PetscDataType,int*);
285: EXTERN int PetscDataTypeGetName(PetscDataType,char*[]);

287: /*
288:     Basic memory and string operations. These are usually simple wrappers
289:    around the basic Unix system calls, but a few of them have additional
290:    functionality and/or error checking.
291: */
292: EXTERN int   PetscMemcpy(void *,const void *,int);
293: EXTERN int   PetscBitMemcpy(void*,int,const void*,int,int,PetscDataType);
294: EXTERN int   PetscMemmove(void *,void *,int);
295: EXTERN int   PetscMemzero(void *,int);
296: EXTERN int   PetscMemcmp(const void*,const void*,int,PetscTruth *);
297: EXTERN int   PetscStrlen(const char[],int*);
298: EXTERN int   PetscStrcmp(const char[],const char[],PetscTruth *);
299: EXTERN int   PetscStrgrt(const char[],const char[],PetscTruth *);
300: EXTERN int   PetscStrcasecmp(const char[],const char[],PetscTruth*);
301: EXTERN int   PetscStrncmp(const char[],const char[],int,PetscTruth*);
302: EXTERN int   PetscStrcpy(char[],const char[]);
303: EXTERN int   PetscStrcat(char[],const char[]);
304: EXTERN int   PetscStrncat(char[],const char[],int);
305: EXTERN int   PetscStrncpy(char[],const char[],int);
306: EXTERN int   PetscStrchr(const char[],char,char **);
307: EXTERN int   PetscStrtolower(char[]);
308: EXTERN int   PetscStrrchr(const char[],char,char **);
309: EXTERN int   PetscStrstr(const char[],const char[],char **);
310: EXTERN int   PetscStrallocpy(const char[],char **);
311: EXTERN int   PetscStrreplace(MPI_Comm,const char[],char*,int);
312: #define      PetscStrfree(a) ((a) ? PetscFree(a) : 0) 
313: typedef struct {char token;char *array;char *current;} PetscToken;
314: EXTERN int   PetscTokenCreate(const char[],const char,PetscToken**);
315: EXTERN int   PetscTokenFind(PetscToken*,char **);
316: EXTERN int   PetscTokenDestroy(PetscToken*);

318: /*
319:    These are  MPI operations for MPI_Allreduce() etc
320: */
321: EXTERN MPI_Op PetscMaxSum_Op;
322: #if defined(PETSC_USE_COMPLEX)
323: EXTERN MPI_Op PetscSum_Op;
324: #else
325: #define PetscSum_Op MPI_SUM
326: #endif
327: EXTERN int PetscMaxSum(MPI_Comm,const int[],int*,int*);

329: /*S
330:      PetscObject - any PETSc object, PetscViewer, Mat, Vec, SLES etc

332:    Level: beginner

334: .seealso:  PetscObjectDestroy(), PetscObjectView(), PetscObjectGetName(), PetscObjectSetName()
335: S*/
336: typedef struct _p_PetscObject* PetscObject;

338: /*S
339:      PetscFList - Linked list of functions, possibly stored in dynamic libraries, accessed
340:       by string name

342:    Level: advanced

344: .seealso:  PetscFListAdd(), PetscFListDestroy()
345: S*/
346: typedef struct _PetscFList *PetscFList;

348:  #include petscviewer.h
349:  #include petscoptions.h

351: EXTERN int PetscShowMemoryUsage(PetscViewer,char*);
352: EXTERN int PetscGetTime(PetscLogDouble*);
353: EXTERN int PetscGetCPUTime(PetscLogDouble*);
354: EXTERN int PetscSleep(int);

356: /*
357:     Initialization of PETSc
358: */
359: EXTERN int  PetscInitialize(int*,char***,char[],const char[]);
360: EXTERN int  PetscInitializeNoArguments(void);
361: EXTERN int  PetscFinalize(void);
362: EXTERN int  PetscInitializeFortran(void);
363: EXTERN int  PetscGetArgs(int*,char ***);
364: EXTERN int  PetscEnd(void);

366: /*
367:    ParameterDict is an abstraction for arguments to interface mechanisms
368: */
369: extern int DICT_COOKIE;
370: typedef struct _p_Dict *ParameterDict;

372: typedef void (**PetscVoidFunction)(void);

374: /*
375:    PetscTryMethod - Queries an object for a method, if it exists then calls it.
376:           Can support argument checking 
377: */
378: #if defined(PETSC_FORTRAN_STUBS)
379: #define  PetscTryMethod(obj,A,B,C) \
380:   0;{ int (*f)B; \
381:    *PetscObjectQueryFunction((PetscObject)obj,#A,(PetscVoidFunction)&f);if (*ierr) return; \
382:     if (f) {*(*f)C;if (*ierr) return;}\
383:   }
384: #else
385: #define  PetscTryMethod(obj,A,B,C) \
386:   0;{ int (*f)B, __ierr; \
387:     __PetscObjectQueryFunction((PetscObject)obj,#A,(PetscVoidFunction)&f);CHKERRQ(__ierr); \
388:     if (f) {__(*f)C;CHKERRQ(__ierr);}\
389:   }
390: #endif

392: /*
393:     Functions that can act on any PETSc object.
394: */
395: EXTERN int PetscObjectDestroy(PetscObject);
396: EXTERN int PetscObjectExists(PetscObject,PetscTruth*);
397: EXTERN int PetscObjectGetComm(PetscObject,MPI_Comm *);
398: EXTERN int PetscObjectGetCookie(PetscObject,int *);
399: EXTERN int PetscObjectGetType(PetscObject,int *);
400: EXTERN int PetscObjectSetName(PetscObject,const char[]);
401: EXTERN int PetscObjectGetName(PetscObject,char*[]);
402: EXTERN int PetscObjectReference(PetscObject);
403: EXTERN int PetscObjectGetReference(PetscObject,int*);
404: EXTERN int PetscObjectDereference(PetscObject);
405: EXTERN int PetscObjectGetNewTag(PetscObject,int *);
406: EXTERN int PetscObjectSetParameterDict(PetscObject,ParameterDict);
407: EXTERN int PetscObjectGetParameterDict(PetscObject,ParameterDict*);
408: EXTERN int PetscCommGetNewTag(MPI_Comm,int *);
409: EXTERN int PetscObjectView(PetscObject,PetscViewer);
410: EXTERN int PetscObjectCompose(PetscObject,const char[],PetscObject);
411: EXTERN int PetscObjectQuery(PetscObject,const char[],PetscObject *);
412: EXTERN int PetscObjectComposeFunction(PetscObject,const char[],const char[],void (*)(void));

414: /*MC
415:    PetscObjectComposeFunctionDynamic - Associates a function with a given PETSc object. 
416:                        
417:    Collective on PetscObject

419:    Input Parameters:
420: +  obj - the PETSc object; this must be cast with a (PetscObject), for example, 
421:          PetscObjectCompose((PetscObject)mat,...);
422: .  name - name associated with the child function
423: .  fname - name of the function
424: -  ptr - function pointer (or PETSC_NULL if using dynamic libraries)

426:    Level: advanced

428:     Synopsis:
429:     int PetscObjectComposeFunctionDynamic(PetscObject obj,char *name,char *fname,void *ptr)

431:    Notes:
432:    PetscObjectComposeFunctionDynamic() can be used with any PETSc object (such as
433:    Mat, Vec, KSP, SNES, etc.) or any user-provided object. 

435:    The composed function must be wrapped in a EXTERN_C_BEGIN/END for this to
436:    work in C++/complex with dynamic link libraries (PETSC_USE_DYNAMIC_LIBRARIES)
437:    enabled.

439:    Concepts: objects^composing functions
440:    Concepts: composing functions
441:    Concepts: functions^querying
442:    Concepts: objects^querying
443:    Concepts: querying objects

445: .seealso: PetscObjectQueryFunction()
446: M*/
447: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
448: #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,0)
449: #else
450: #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,(void (*)(void))(d))
451: #endif

453: EXTERN int PetscObjectQueryFunction(PetscObject,const char[],void (**)(void));
454: EXTERN int PetscObjectSetOptionsPrefix(PetscObject,const char[]);
455: EXTERN int PetscObjectAppendOptionsPrefix(PetscObject,const char[]);
456: EXTERN int PetscObjectPrependOptionsPrefix(PetscObject,const char[]);
457: EXTERN int PetscObjectGetOptionsPrefix(PetscObject,char*[]);
458: EXTERN int PetscObjectPublish(PetscObject);
459: EXTERN int PetscObjectChangeTypeName(PetscObject,char *);
460: EXTERN int PetscObjectChangeSerializeName(PetscObject,char *);
461: EXTERN int PetscObjectRegisterDestroy(PetscObject);
462: EXTERN int PetscObjectRegisterDestroyAll(void);
463: EXTERN int PetscObjectName(PetscObject);
464: EXTERN int PetscTypeCompare(PetscObject,char*,PetscTruth*);
465: EXTERN int PetscSerializeCompare(PetscObject,char*,PetscTruth*);

467: /*
468:     Defines PETSc error handling.
469: */
470:  #include petscerror.h

472: /*S
473:      PetscOList - Linked list of PETSc objects, accessable by string name

475:    Level: advanced

477: .seealso:  PetscOListAdd(), PetscOListDestroy(), PetscOListFind()
478: S*/
479: typedef struct _PetscOList *PetscOList;

481: EXTERN int PetscOListDestroy(PetscOList *);
482: EXTERN int PetscOListFind(PetscOList,const char[],PetscObject*);
483: EXTERN int PetscOListReverseFind(PetscOList,PetscObject,char**);
484: EXTERN int PetscOListAdd(PetscOList *,const char[],PetscObject);
485: EXTERN int PetscOListDuplicate(PetscOList,PetscOList *);

487: /*
488:     Dynamic library lists. Lists of names of routines in dynamic 
489:   link libraries that will be loaded as needed.
490: */
491: EXTERN int PetscFListAdd(PetscFList*,const char[],const char[],void (*)(void));
492: EXTERN int PetscFListDestroy(PetscFList*);
493: EXTERN int PetscFListFind(MPI_Comm,PetscFList,const char[],void (**)(void));
494: EXTERN int PetscFListPrintTypes(MPI_Comm,FILE*,const char[],const char[],char *,char *,PetscFList);
495: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
496: #define    PetscFListAddDynamic(a,b,p,c) PetscFListAdd(a,b,p,0)
497: #else
498: #define    PetscFListAddDynamic(a,b,p,c) PetscFListAdd(a,b,p,(void (*)(void))c)
499: #endif
500: EXTERN int PetscFListDuplicate(PetscFList,PetscFList *);
501: EXTERN int PetscFListView(PetscFList,PetscViewer);
502: EXTERN int PetscFListConcat(const char [],const char [],char []);
503: EXTERN int PetscFListGet(PetscFList,char ***,int*);

505: /*S
506:      PetscDLLibraryList - Linked list of dynamics libraries to search for functions

508:    Level: advanced

510:    PETSC_USE_DYNAMIC_LIBRARIES must be defined in petscconf.h to use dynamic libraries

512: .seealso:  PetscDLLibraryOpen()
513: S*/
514: typedef struct _PetscDLLibraryList *PetscDLLibraryList;
515: extern PetscDLLibraryList DLLibrariesLoaded;
516: EXTERN int PetscDLLibraryRetrieve(MPI_Comm,const char[],char *,int,PetscTruth *);
517: EXTERN int PetscDLLibraryOpen(MPI_Comm,const char[],void **);
518: EXTERN int PetscDLLibrarySym(MPI_Comm,PetscDLLibraryList *,const char[],const char[],void **);
519: EXTERN int PetscDLLibraryAppend(MPI_Comm,PetscDLLibraryList *,const char[]);
520: EXTERN int PetscDLLibraryPrepend(MPI_Comm,PetscDLLibraryList *,const char[]);
521: EXTERN int PetscDLLibraryClose(PetscDLLibraryList);
522: EXTERN int PetscDLLibraryPrintPath(void);
523: EXTERN int PetscDLLibraryGetInfo(void *,char *,char **);

525: /*
526:     Mechanism for translating PETSc object representations between languages
527:     Not currently used.
528: */
529: typedef enum {PETSC_LANGUAGE_C,PETSC_LANGUAGE_CPP} PetscLanguage;
530: #define PETSC_LANGUAGE_F77 PETSC_LANGUAGE_C
531: EXTERN int PetscObjectComposeLanguage(PetscObject,PetscLanguage,void *);
532: EXTERN int PetscObjectQueryLanguage(PetscObject,PetscLanguage,void **);

534: /*
535:      Useful utility routines
536: */
537: EXTERN int PetscSplitOwnership(MPI_Comm,int*,int*);
538: EXTERN int PetscSplitOwnershipBlock(MPI_Comm,int,int*,int*);
539: EXTERN int PetscSequentialPhaseBegin(MPI_Comm,int);
540: EXTERN int PetscSequentialPhaseEnd(MPI_Comm,int);
541: EXTERN int PetscBarrier(PetscObject);
542: EXTERN int PetscMPIDump(FILE*);

544: #define PetscNot(a) ((a) ? PETSC_FALSE : PETSC_TRUE)
545: /*
546:     Defines basic graphics available from PETSc.
547: */
548:  #include petscdraw.h

550: /*
551:     Defines the base data structures for all PETSc objects
552: */
553:  #include petschead.h

555: /*
556:      Defines PETSc profiling.
557: */
558:  #include petsclog.h

560: /*
561:           For locking, unlocking and destroying AMS memories associated with 
562:     PETSc objects
563: */
564: #if defined(PETSC_HAVE_AMS)

566: extern PetscTruth PetscAMSPublishAll;
567: #define PetscPublishAll(v) (PetscAMSPublishAll ? PetscObjectPublish((PetscObject)v) : 0)
568: #define PetscObjectTakeAccess(obj)  ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_take_access(((PetscObject)(obj))->amem))
569: #define PetscObjectGrantAccess(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_grant_access(((PetscObject)(obj))->amem))
570: #define PetscObjectDepublish(obj)   ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_destroy(((PetscObject)(obj))->amem)); \
571:     ((PetscObject)(obj))->amem = -1;

573: #else

575: #define PetscPublishAll(v)           0
576: #define PetscObjectTakeAccess(obj)   0
577: #define PetscObjectGrantAccess(obj)  0
578: #define PetscObjectDepublish(obj)      0

580: #endif



584: /*
585:       This code allows one to pass a MPI communicator between 
586:     C and Fortran. MPI 2.0 defines a standard API for doing this.
587:     The code here is provided to allow PETSc to work with MPI 1.1
588:     standard MPI libraries.
589: */
590: EXTERN int  MPICCommToFortranComm(MPI_Comm,int *);
591: EXTERN int  MPIFortranCommToCComm(int,MPI_Comm*);

593: /*
594:       Simple PETSc parallel IO for ASCII printing
595: */
596: EXTERN int  PetscFixFilename(const char[],char[]);
597: EXTERN int  PetscFOpen(MPI_Comm,const char[],const char[],FILE**);
598: EXTERN int  PetscFClose(MPI_Comm,FILE*);
599: EXTERN int  PetscFPrintf(MPI_Comm,FILE*,const char[],...) PETSC_PRINTF_FORMAT_CHECK(3,4);
600: EXTERN int  PetscPrintf(MPI_Comm,const char[],...)  PETSC_PRINTF_FORMAT_CHECK(2,3);

602: /*MC
603:     PetscErrorPrintf - Prints error messages.

605:     Not Collective

607:    Synopsis:
608:      int (*PetscErrorPrintf)(const char format[],...);

610:     Input Parameters:
611: .   format - the usual printf() format string 

613:    Options Database Keys:
614: .    -error_output_stderr - cause error messages to be printed to stderr instead of the
615:          (default) stdout


618:    Level: developer

620:     Fortran Note:
621:     This routine is not supported in Fortran.

623:     Concepts: error messages^printing
624:     Concepts: printing^error messages

626: .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscHelpPrintf()
627: M*/
628: EXTERN int  (*PetscErrorPrintf)(const char[],...);

630: /*MC
631:     PetscHelpPrintf - Prints help messages.

633:     Not Collective

635:    Synopsis:
636:      int (*PetscHelpPrintf)(const char format[],...);

638:     Input Parameters:
639: .   format - the usual printf() format string 

641:    Level: developer

643:     Fortran Note:
644:     This routine is not supported in Fortran.

646:     Concepts: help messages^printing
647:     Concepts: printing^help messages

649: .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscErrorPrintf()
650: M*/
651: EXTERN int  (*PetscHelpPrintf)(MPI_Comm,const char[],...);

653: EXTERN int  PetscPOpen(MPI_Comm,char *,char*,const char[],FILE **);
654: EXTERN int  PetscPClose(MPI_Comm,FILE*);
655: EXTERN int  PetscSynchronizedPrintf(MPI_Comm,const char[],...) PETSC_PRINTF_FORMAT_CHECK(2,3);
656: EXTERN int  PetscSynchronizedFPrintf(MPI_Comm,FILE*,const char[],...) PETSC_PRINTF_FORMAT_CHECK(3,4);
657: EXTERN int  PetscSynchronizedFlush(MPI_Comm);
658: EXTERN int  PetscSynchronizedFGets(MPI_Comm,FILE*,int,char[]);
659: EXTERN int  PetscStartMatlab(MPI_Comm,char *,char*,FILE**);
660: EXTERN int  PetscStartJava(MPI_Comm,char *,char*,FILE**);
661: EXTERN int  PetscGetPetscDir(char**);

663: EXTERN int  PetscPopUpSelect(MPI_Comm,char*,char*,int,char**,int*);
664: /*S
665:      PetscObjectContainer - Simple PETSc object that contains a pointer to any required data

667:    Level: advanced

669: .seealso:  PetscObject, PetscObjectContainerCreate()
670: S*/
671: typedef struct _p_PetscObjectContainer*  PetscObjectContainer;
672: EXTERN int PetscObjectContainerGetPointer(PetscObjectContainer,void **);
673: EXTERN int PetscObjectContainerSetPointer(PetscObjectContainer,void *);
674: EXTERN int PetscObjectContainerDestroy(PetscObjectContainer);
675: EXTERN int PetscObjectContainerCreate(MPI_Comm comm,PetscObjectContainer *);

677: /*
678:    For incremental debugging
679: */
680: extern PetscTruth PetscCompare;
681: EXTERN int        PetscCompareDouble(double);
682: EXTERN int        PetscCompareScalar(PetscScalar);
683: EXTERN int        PetscCompareInt(int);

685: /*
686:    For use in debuggers 
687: */
688: extern int PetscGlobalRank,PetscGlobalSize;
689: EXTERN int PetscIntView(int,int[],PetscViewer);
690: EXTERN int PetscRealView(int,PetscReal[],PetscViewer);
691: EXTERN int PetscScalarView(int,PetscScalar[],PetscViewer);

693: /*
694:     Allows accessing Matlab Engine
695: */
696:  #include petscengine.h

698: /*
699:     C code optimization is often enhanced by telling the compiler 
700:   that certain pointer arguments to functions are not aliased to 
701:   to other arguments. This is not yet ANSI C standard so we define 
702:   the macro "restrict" to indicate that the variable is not aliased 
703:   to any other argument.
704: */
705: #if defined(PETSC_HAVE_RESTRICT) && !defined(__cplusplus)
706: #define restrict _Restrict
707: #else
708: #if defined(restrict)
709: #undef restrict
710: #endif
711: #define restrict
712: #endif

714: /*
715:       Determine if some of the kernel computation routines use
716:    Fortran (rather than C) for the numerical calculations. On some machines
717:    and compilers (like complex numbers) the Fortran version of the routines
718:    is faster than the C/C++ versions. The flag PETSC_USE_FORTRAN_KERNELS  
719:    would be set in the petscconf.h file
720: */
721: #if defined(PETSC_USE_FORTRAN_KERNELS)

723: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTAIJ)
724: #define PETSC_USE_FORTRAN_KERNEL_MULTAIJ
725: #endif

727: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTTRANSPOSEAIJ)
728: #define PETSC_USE_FORTRAN_KERNEL_MULTTRANSPOSEAIJ
729: #endif

731: #if !defined(PETSC_USE_FORTRAN_KERNEL_NORM)
732: #define PETSC_USE_FORTRAN_KERNEL_NORM
733: #endif

735: #if !defined(PETSC_USE_FORTRAN_KERNEL_MAXPY)
736: #define PETSC_USE_FORTRAN_KERNEL_MAXPY
737: #endif

739: #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ)
740: #define PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ
741: #endif

743: #if !defined(PETSC_USE_FORTRAN_KERNEL_RELAXAIJ)
744: #define PETSC_USE_FORTRAN_KERNEL_RELAXAIJ
745: #endif

747: #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ)
748: #define PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ
749: #endif

751: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ)
752: #define PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ
753: #endif

755: #if !defined(PETSC_USE_FORTRAN_KERNEL_MDOT)
756: #define PETSC_USE_FORTRAN_KERNEL_MDOT
757: #endif

759: #if !defined(PETSC_USE_FORTRAN_KERNEL_XTIMESY)
760: #define PETSC_USE_FORTRAN_KERNEL_XTIMESY
761: #endif

763: #if !defined(PETSC_USE_FORTRAN_KERNEL_AYPX)
764: #define PETSC_USE_FORTRAN_KERNEL_AYPX
765: #endif

767: #if !defined(PETSC_USE_FORTRAN_KERNEL_WAXPY)
768: #define PETSC_USE_FORTRAN_KERNEL_WAXPY
769: #endif

771: #endif

773: /*
774:     Macros for indicating code that should be compiled with a C interface,
775:    rather than a C++ interface. Any routines that are dynamically loaded
776:    (such as the PCCreate_XXX() routines) must be wrapped so that the name
777:    mangler does not change the functions symbol name. This just hides the 
778:    ugly extern "C" {} wrappers.
779: */
780: #if defined(__cplusplus)
781: #define EXTERN_C_BEGIN extern "C" {
782: #define EXTERN_C_END }
783: #else
784: #define EXTERN_C_BEGIN 
785: #define EXTERN_C_END 
786: #endif

788: /* --------------------------------------------------------------------*/

790: /*M
791:     size - integer variable used to contain the number of processors in
792:            the relevent MPI_Comm

794:    Level: beginner

796: .seealso: rank, comm
797: M*/

799: /*M
800:     rank - integer variable used to contain the number of this processor relative
801:            to all in the relevent MPI_Comm

803:    Level: beginner

805: .seealso: size, comm
806: M*/

808: /*M
809:     comm - MPI_Comm used in the current routine or object

811:    Level: beginner

813: .seealso: size, rank
814: M*/

816: /*M
817:     MPI_Comm - the basic object used by MPI to determine which processes are involved in a 
818:         communication

820:    Level: beginner

822:    Note: This manual page is a place-holder because MPICH does not have a manual page for MPI_Comm

824: .seealso: size, rank, comm, PETSC_COMM_WORLD, PETSC_COMM_SELF
825: M*/

827: /*M
828:     PetscScalar - PETSc type that represents either a double precision real number or 
829:        a double precision complex number if the code is compiled with BOPT=g_complex or O_complex

831:    Level: beginner

833: .seealso: PetscReal, PassiveReal, PassiveScalar
834: M*/

836: /*M
837:     PetscReal - PETSc type that represents a double precision real number

839:    Level: beginner

841: .seealso: PetscScalar, PassiveReal, PassiveScalar
842: M*/

844: /*M
845:     PassiveScalar - PETSc type that represents either a double precision real number or 
846:        a double precision complex number if the code is compiled with BOPT=g_complex or O_complex

848:    Level: beginner

850:     This is the same as a PetscScalar except in code that is automatically differentiated it is
851:    treated as a constant (not an indendent or dependent variable)

853: .seealso: PetscReal, PassiveReal, PetscScalar
854: M*/

856: /*M
857:     PassiveReal - PETSc type that represents a double precision real number

859:    Level: beginner

861:     This is the same as a PetscReal except in code that is automatically differentiated it is
862:    treated as a constant (not an indendent or dependent variable)

864: .seealso: PetscScalar, PetscReal, PassiveScalar
865: M*/

867: /*
868:      The IBM include files define hz, here we hide it so that it may be used
869:    as a regular user variable.
870: */
871: #if defined(hz)
872: #undef hz
873: #endif

875: /*  For arrays that contain filenames or paths */

877: #if defined(PETSC_HAVE_LIMITS_H)
878: #include <limits.h>
879: #endif
880: #if defined(PETSC_HAVE_SYS_PARAM_H)
881: #include <sys/param.h>
882: #endif

884: #if defined(MAXPATHLEN)
885: #  define PETSC_MAX_PATH_LEN     MAXPATHLEN
886: #elif defined(MAX_PATH)
887: #  define PETSC_MAX_PATH_LEN     MAX_PATH
888: #elif defined(_MAX_PATH)
889: #  define PETSC_MAX_PATH_LEN     _MAX_PATH
890: #else
891: #  define PETSC_MAX_PATH_LEN     4096
892: #endif

894: #endif