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: */
  8: /* ========================================================================== */
  9: /* 
 10:    This facilitates using C version of PETSc from C++
 11: */

 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

 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

 47: /* ========================================================================== */

 49: #include <stdio.h>
 50: /*
 51:     Defines the interface to MPI allowing the use of all MPI functions.
 52: */
 53: #include "mpi.h"


 56: /*
 57:     Declare extern C stuff after incuding external header files
 58: */

 60: PETSC_EXTERN_CXX_BEGIN

 62: /*
 63:     EXTERN indicates a PETSc function defined elsewhere
 64: */
 65: #if !defined(EXTERN)
 66: #define EXTERN extern
 67: #endif

 69: /*
 70:     Defines some elementary mathematics functions and constants.
 71: */
 72:  #include petscmath.h

 74: /*
 75:        Basic PETSc constants
 76: */

 78: /*E
 79:     PetscTruth - Logical variable. Actually an integer

 81:    Level: beginner

 83: E*/
 84: typedef enum { PETSC_FALSE,PETSC_TRUE } PetscTruth;

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

 89:    Level: beginner

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

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

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

 99: M*/
100: #define PETSC_NULL           0

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

106:    Level: beginner

108: .seealso: PETSC_NULL, PETSC_DEFAULT, PETSC_IGNORE, PETSC_DETERMINE

110: M*/
111: #define PETSC_DECIDE         -1

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

117:    Level: beginner

119: .seealso: PETSC_DECIDE, PETSC_NULL, PETSC_IGNORE, PETSC_DETERMINE

121: M*/
122: #define PETSC_DEFAULT        -2

124: #define PETSC_YES            PETSC_TRUE
125: #define PETSC_NO             PETSC_FALSE

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

130:    Level: beginner

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

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

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

140: M*/
141: #define PETSC_IGNORE         PETSC_NULL

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

147:    Level: beginner

149: .seealso: PETSC_DECIDE, PETSC_DEFAULT, PETSC_IGNORE, PETSC_NULL, VecSetSizes()

151: M*/
152: #define PETSC_DETERMINE      PETSC_DECIDE

154: /*M
155:     PETSC_COMM_WORLD - a duplicate of the MPI_COMM_WORLD communicator which represents
156:            all the processs

158:    Level: beginner

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

164: .seealso: PETSC_COMM_SELF

166: M*/
167: extern MPI_Comm   PETSC_COMM_WORLD;

169: /*M
170:     PETSC_COMM_SELF - a duplicate of the MPI_COMM_SELF communicator which represents
171:            the current process

173:    Level: beginner

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

179: .seealso: PETSC_COMM_WORLD

181: M*/
182: extern MPI_Comm   PETSC_COMM_SELF;

184: extern PetscTruth PetscInitializeCalled;
185: EXTERN int        PetscSetCommWorld(MPI_Comm);
186: EXTERN int        PetscSetHelpVersionFunctions(int (*)(MPI_Comm),int (*)(MPI_Comm));
187: EXTERN int        PetscCommDuplicate(MPI_Comm,MPI_Comm*,int*);
188: EXTERN int        PetscCommDestroy(MPI_Comm*);

190: /*MC
191:    PetscMalloc - Allocates memory

193:    Input Parameter:
194: .  m - number of bytes to allocate

196:    Output Parameter:
197: .  result - memory allocated

199:    Synopsis:
200:    int PetscMalloc(size_t m,void **result)

202:    Level: beginner

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

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

208:   Concepts: memory allocation

210: M*/
211: #define PetscMalloc(a,b)     (*PetscTrMalloc)((a),__LINE__,__FUNCT__,__FILE__,__SDIR__,(void**)(b))
212: /*MC
213:    PetscNew - Allocates memory of a particular type

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

218:    Output Parameter:
219: .  result - memory allocated

221:    Synopsis:
222:    int PetscNew(struct type,((type *))result)

224:    Level: beginner

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

228:   Concepts: memory allocation

230: M*/
231: #define PetscNew(A,b)        PetscMalloc(sizeof(A),(b))
232: /*MC
233:    PetscFree - Frees memory

235:    Input Parameter:
236: .   memory - memory to free

238:    Synopsis:
239:    int PetscFree(void *memory)

241:    Level: beginner

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

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

247:   Concepts: memory allocation

249: M*/
250: #define PetscFree(a)         (*PetscTrFree)((a),__LINE__,__FUNCT__,__FILE__,__SDIR__)
251: EXTERN int  (*PetscTrMalloc)(size_t,int,const char[],const char[],const char[],void**);
252: EXTERN int  (*PetscTrFree)(void *,int,const char[],const char[],const char[]);
253: EXTERN int  PetscSetMalloc(int (*)(size_t,int,const char[],const char[],const char[],void**),int (*)(void *,int,const char[],const char[],const char[]));
254: EXTERN int  PetscClearMalloc(void);

256: /*
257:    Routines for tracing memory corruption/bleeding with default PETSc 
258:    memory allocation
259: */
260: EXTERN int   PetscTrDump(FILE *);
261: EXTERN int   PetscTrSpace(PetscLogDouble *,PetscLogDouble *,PetscLogDouble *);
262: EXTERN int   PetscTrValid(int,const char[],const char[],const char[]);
263: EXTERN int   PetscTrDebugLevel(int);
264: EXTERN int   PetscTrLog(void);
265: EXTERN int   PetscTrLogDump(FILE *);
266: EXTERN int   PetscGetResidentSetSize(PetscLogDouble *);

268: /*
269:     Variable type where we stash PETSc object pointers in Fortran.
270:     Assumes that sizeof(long) == sizeof(void*)which is true on 
271:     all machines that we know.
272: */
273: #define PetscFortranAddr   long

275: /*E
276:     PetscDataType - Used for handling different basic data types.

278:    Level: beginner

280: .seealso: PetscBinaryRead(), PetscBinaryWrite(), PetscDataTypeToMPIDataType(),
281:           PetscDataTypeGetSize(), PetscDataTypeGetName()

283: E*/
284: typedef enum {PETSC_INT = 0,PETSC_DOUBLE = 1,PETSC_COMPLEX = 2,
285:               PETSC_LONG =3 ,PETSC_SHORT = 4,PETSC_FLOAT = 5,
286:               PETSC_CHAR = 6,PETSC_LOGICAL = 7} PetscDataType;
287: #if defined(PETSC_USE_COMPLEX)
288: #define PETSC_SCALAR PETSC_COMPLEX
289: #else
290: #if defined(PETSC_USE_SINGLE)
291: #define PETSC_SCALAR PETSC_FLOAT
292: #else
293: #define PETSC_SCALAR PETSC_DOUBLE
294: #endif
295: #endif
296: #if defined(PETSC_USE_SINGLE)
297: #define PETSC_REAL PETSC_FLOAT
298: #else
299: #define PETSC_REAL PETSC_DOUBLE
300: #endif
301: #define PETSC_FORTRANADDR PETSC_LONG

303: EXTERN int PetscDataTypeToMPIDataType(PetscDataType,MPI_Datatype*);
304: EXTERN int PetscDataTypeGetSize(PetscDataType,int*);
305: EXTERN int PetscDataTypeGetName(PetscDataType,const char*[]);

307: /*
308:     Basic memory and string operations. These are usually simple wrappers
309:    around the basic Unix system calls, but a few of them have additional
310:    functionality and/or error checking.
311: */
312: EXTERN int   PetscMemcpy(void *,const void *,int);
313: EXTERN int   PetscBitMemcpy(void*,int,const void*,int,int,PetscDataType);
314: EXTERN int   PetscMemmove(void *,void *,int);
315: EXTERN int   PetscMemzero(void *,int);
316: EXTERN int   PetscMemcmp(const void*,const void*,int,PetscTruth *);
317: EXTERN int   PetscStrlen(const char[],int*);
318: EXTERN int   PetscStrcmp(const char[],const char[],PetscTruth *);
319: EXTERN int   PetscStrgrt(const char[],const char[],PetscTruth *);
320: EXTERN int   PetscStrcasecmp(const char[],const char[],PetscTruth*);
321: EXTERN int   PetscStrncmp(const char[],const char[],int,PetscTruth*);
322: EXTERN int   PetscStrcpy(char[],const char[]);
323: EXTERN int   PetscStrcat(char[],const char[]);
324: EXTERN int   PetscStrncat(char[],const char[],int);
325: EXTERN int   PetscStrncpy(char[],const char[],int);
326: EXTERN int   PetscStrchr(const char[],char,char *[]);
327: EXTERN int   PetscStrtolower(char[]);
328: EXTERN int   PetscStrrchr(const char[],char,char *[]);
329: EXTERN int   PetscStrstr(const char[],const char[],char *[]);
330: EXTERN int   PetscStrallocpy(const char[],char *[]);
331: EXTERN int   PetscStrreplace(MPI_Comm,const char[],char[],int);
332: #define      PetscStrfree(a) ((a) ? PetscFree(a) : 0) 
333: typedef struct {char token;char *array;char *current;} PetscToken;
334: EXTERN int   PetscTokenCreate(const char[],const char,PetscToken**);
335: EXTERN int   PetscTokenFind(PetscToken*,char *[]);
336: EXTERN int   PetscTokenDestroy(PetscToken*);

338: /*
339:    These are  MPI operations for MPI_Allreduce() etc
340: */
341: EXTERN MPI_Op PetscMaxSum_Op;
342: #if defined(PETSC_USE_COMPLEX)
343: EXTERN MPI_Op PetscSum_Op;
344: #else
345: #define PetscSum_Op MPI_SUM
346: #endif
347: EXTERN int PetscMaxSum(MPI_Comm,const int[],int*,int*);

349: /*S
350:      PetscObject - any PETSc object, PetscViewer, Mat, Vec, KSP etc

352:    Level: beginner

354:    Note: This is the base class from which all objects appear.

356: .seealso:  PetscObjectDestroy(), PetscObjectView(), PetscObjectGetName(), PetscObjectSetName()
357: S*/
358: typedef struct _p_PetscObject* PetscObject;

360: /*S
361:      PetscFList - Linked list of functions, possibly stored in dynamic libraries, accessed
362:       by string name

364:    Level: advanced

366: .seealso:  PetscFListAdd(), PetscFListDestroy()
367: S*/
368: typedef struct _PetscFList *PetscFList;

370:  #include petscviewer.h
371:  #include petscoptions.h

373: EXTERN int PetscShowMemoryUsage(PetscViewer,const char[]);
374: EXTERN int PetscGetTime(PetscLogDouble*);
375: EXTERN int PetscGetCPUTime(PetscLogDouble*);
376: EXTERN int PetscSleep(int);

378: /*
379:     Initialization of PETSc
380: */
381: EXTERN int  PetscInitialize(int*,char***,const char[],const char[]);
382: EXTERN int  PetscInitializeNoArguments(void);
383: EXTERN int  PetscFinalize(void);
384: EXTERN int  PetscInitializeFortran(void);
385: EXTERN int  PetscGetArgs(int*,char ***);
386: EXTERN int  PetscEnd(void);

388: /*
389:    ParameterDict is an abstraction for arguments to interface mechanisms
390: */
391: extern int DICT_COOKIE;
392: typedef struct _p_Dict *ParameterDict;

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

396: /*
397:    PetscTryMethod - Queries an object for a method, if it exists then calls it.
398:               These are intended to be used only inside PETSc functions.
399: */
400: #define  PetscTryMethod(obj,A,B,C) \
401:   0;{ int (*f)B, __ierr; \
402:     __PetscObjectQueryFunction((PetscObject)obj,#A,(PetscVoidFunction)&f);CHKERRQ(__ierr); \
403:     if (f) {__(*f)C;CHKERRQ(__ierr);}\
404:   }
405: #define  PetscUseMethod(obj,A,B,C) \
406:   0;{ int (*f)B, __ierr; \
407:     __PetscObjectQueryFunction((PetscObject)obj,A,(PetscVoidFunction)&f);CHKERRQ(__ierr); \
408:     if (f) {__(*f)C;CHKERRQ(__ierr);}\
409:     else {SETERRQ1(1,"Cannot locate function %s in object",A);} \
410:   }
411: /*
412:     Functions that can act on any PETSc object.
413: */
414: EXTERN int PetscObjectDestroy(PetscObject);
415: EXTERN int PetscObjectExists(PetscObject,PetscTruth*);
416: EXTERN int PetscObjectGetComm(PetscObject,MPI_Comm *);
417: EXTERN int PetscObjectGetCookie(PetscObject,int *);
418: EXTERN int PetscObjectGetType(PetscObject,int *);
419: EXTERN int PetscObjectSetName(PetscObject,const char[]);
420: EXTERN int PetscObjectGetName(PetscObject,char*[]);
421: EXTERN int PetscObjectReference(PetscObject);
422: EXTERN int PetscObjectGetReference(PetscObject,int*);
423: EXTERN int PetscObjectDereference(PetscObject);
424: EXTERN int PetscObjectGetNewTag(PetscObject,int *);
425: EXTERN int PetscObjectSetParameterDict(PetscObject,ParameterDict);
426: EXTERN int PetscObjectGetParameterDict(PetscObject,ParameterDict*);
427: EXTERN int PetscCommGetNewTag(MPI_Comm,int *);
428: EXTERN int PetscObjectView(PetscObject,PetscViewer);
429: EXTERN int PetscObjectCompose(PetscObject,const char[],PetscObject);
430: EXTERN int PetscObjectQuery(PetscObject,const char[],PetscObject *);
431: EXTERN int PetscObjectComposeFunction(PetscObject,const char[],const char[],void (*)(void));

433: typedef void (*FCNVOID)(void); /* cast in next macro should never be extern C */
434: typedef int  (*FCNINTVOID)(void); /* used in casts to make sure they are not extern C */
435: /*MC
436:    PetscObjectComposeFunctionDynamic - Associates a function with a given PETSc object. 
437:                        
438:    Collective on PetscObject

440:    Input Parameters:
441: +  obj - the PETSc object; this must be cast with a (PetscObject), for example, 
442:          PetscObjectCompose((PetscObject)mat,...);
443: .  name - name associated with the child function
444: .  fname - name of the function
445: -  ptr - function pointer (or PETSC_NULL if using dynamic libraries)

447:    Level: advanced

449:     Synopsis:
450:     int PetscObjectComposeFunctionDynamic(PetscObject obj,const char name[],const char fname[],void *ptr)

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

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

460:    Concepts: objects^composing functions
461:    Concepts: composing functions
462:    Concepts: functions^querying
463:    Concepts: objects^querying
464:    Concepts: querying objects

466: .seealso: PetscObjectQueryFunction()
467: M*/
468: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
469: #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,0)
470: #else
471: #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,(FCNVOID)(d))
472: #endif

474: EXTERN int PetscObjectQueryFunction(PetscObject,const char[],void (**)(void));
475: EXTERN int PetscObjectSetOptionsPrefix(PetscObject,const char[]);
476: EXTERN int PetscObjectAppendOptionsPrefix(PetscObject,const char[]);
477: EXTERN int PetscObjectPrependOptionsPrefix(PetscObject,const char[]);
478: EXTERN int PetscObjectGetOptionsPrefix(PetscObject,char*[]);
479: EXTERN int PetscObjectPublish(PetscObject);
480: EXTERN int PetscObjectChangeTypeName(PetscObject,const char[]);
481: EXTERN int PetscObjectRegisterDestroy(PetscObject);
482: EXTERN int PetscObjectRegisterDestroyAll(void);
483: EXTERN int PetscObjectName(PetscObject);
484: EXTERN int PetscTypeCompare(PetscObject,const char[],PetscTruth*);

486: /*
487:     Defines PETSc error handling.
488: */
489:  #include petscerror.h

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

494:    Level: advanced

496: .seealso:  PetscOListAdd(), PetscOListDestroy(), PetscOListFind()
497: S*/
498: typedef struct _PetscOList *PetscOList;

500: EXTERN int PetscOListDestroy(PetscOList *);
501: EXTERN int PetscOListFind(PetscOList,const char[],PetscObject*);
502: EXTERN int PetscOListReverseFind(PetscOList,PetscObject,char**);
503: EXTERN int PetscOListAdd(PetscOList *,const char[],PetscObject);
504: EXTERN int PetscOListDuplicate(PetscOList,PetscOList *);

506: /*
507:     Dynamic library lists. Lists of names of routines in dynamic 
508:   link libraries that will be loaded as needed.
509: */
510: EXTERN int PetscFListAdd(PetscFList*,const char[],const char[],void (*)(void));
511: EXTERN int PetscFListDestroy(PetscFList*);
512: EXTERN int PetscFListFind(MPI_Comm,PetscFList,const char[],void (**)(void));
513: EXTERN int PetscFListPrintTypes(MPI_Comm,FILE*,const char[],const char[],const char[],const char[],PetscFList);
514: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
515: #define    PetscFListAddDynamic(a,b,p,c) PetscFListAdd(a,b,p,0)
516: #else
517: #define    PetscFListAddDynamic(a,b,p,c) PetscFListAdd(a,b,p,(void (*)(void))c)
518: #endif
519: EXTERN int PetscFListDuplicate(PetscFList,PetscFList *);
520: EXTERN int PetscFListView(PetscFList,PetscViewer);
521: EXTERN int PetscFListConcat(const char [],const char [],char []);
522: EXTERN int PetscFListGet(PetscFList,char ***,int*);

524: /*S
525:      PetscDLLibraryList - Linked list of dynamics libraries to search for functions

527:    Level: advanced

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

531: .seealso:  PetscDLLibraryOpen()
532: S*/
533: typedef struct _PetscDLLibraryList *PetscDLLibraryList;
534: extern PetscDLLibraryList DLLibrariesLoaded;
535: EXTERN int PetscDLLibraryRetrieve(MPI_Comm,const char[],char *,int,PetscTruth *);
536: EXTERN int PetscDLLibraryOpen(MPI_Comm,const char[],void **);
537: EXTERN int PetscDLLibrarySym(MPI_Comm,PetscDLLibraryList *,const char[],const char[],void **);
538: EXTERN int PetscDLLibraryAppend(MPI_Comm,PetscDLLibraryList *,const char[]);
539: EXTERN int PetscDLLibraryPrepend(MPI_Comm,PetscDLLibraryList *,const char[]);
540: EXTERN int PetscDLLibraryClose(PetscDLLibraryList);
541: EXTERN int PetscDLLibraryPrintPath(void);
542: EXTERN int PetscDLLibraryGetInfo(void *,const char[],const char *[]);

544: /*
545:     Mechanism for translating PETSc object representations between languages
546:     Not currently used.
547: */
548: typedef enum {PETSC_LANGUAGE_C,PETSC_LANGUAGE_CPP} PetscLanguage;
549: #define PETSC_LANGUAGE_F77 PETSC_LANGUAGE_C
550: EXTERN int PetscObjectComposeLanguage(PetscObject,PetscLanguage,void *);
551: EXTERN int PetscObjectQueryLanguage(PetscObject,PetscLanguage,void **);

553: /*
554:      Useful utility routines
555: */
556: EXTERN int PetscSplitOwnership(MPI_Comm,int*,int*);
557: EXTERN int PetscSplitOwnershipBlock(MPI_Comm,int,int*,int*);
558: EXTERN int PetscSequentialPhaseBegin(MPI_Comm,int);
559: EXTERN int PetscSequentialPhaseEnd(MPI_Comm,int);
560: EXTERN int PetscBarrier(PetscObject);
561: EXTERN int PetscMPIDump(FILE*);

563: #define PetscNot(a) ((a) ? PETSC_FALSE : PETSC_TRUE)
564: /*
565:     Defines basic graphics available from PETSc.
566: */
567:  #include petscdraw.h

569: /*
570:     Defines the base data structures for all PETSc objects
571: */
572:  #include petschead.h

574: /*
575:      Defines PETSc profiling.
576: */
577:  #include petsclog.h

579: /*
580:           For locking, unlocking and destroying AMS memories associated with 
581:     PETSc objects
582: */
583: #if defined(PETSC_HAVE_AMS)

585: extern PetscTruth PetscAMSPublishAll;
586: #define PetscPublishAll(v) (PetscAMSPublishAll ? PetscObjectPublish((PetscObject)v) : 0)
587: #define PetscObjectTakeAccess(obj)  ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_take_access(((PetscObject)(obj))->amem))
588: #define PetscObjectGrantAccess(obj) ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_grant_access(((PetscObject)(obj))->amem))
589: #define PetscObjectDepublish(obj)   ((((PetscObject)(obj))->amem == -1) ? 0 : AMS_Memory_destroy(((PetscObject)(obj))->amem)); \
590:     ((PetscObject)(obj))->amem = -1;

592: #else

594: #define PetscPublishAll(v)           0
595: #define PetscObjectTakeAccess(obj)   0
596: #define PetscObjectGrantAccess(obj)  0
597: #define PetscObjectDepublish(obj)      0

599: #endif



603: /*
604:       This code allows one to pass a MPI communicator between 
605:     C and Fortran. MPI 2.0 defines a standard API for doing this.
606:     The code here is provided to allow PETSc to work with MPI 1.1
607:     standard MPI libraries.
608: */
609: EXTERN int  MPICCommToFortranComm(MPI_Comm,int *);
610: EXTERN int  MPIFortranCommToCComm(int,MPI_Comm*);

612: /*
613:       Simple PETSc parallel IO for ASCII printing
614: */
615: EXTERN int  PetscFixFilename(const char[],char[]);
616: EXTERN int  PetscFOpen(MPI_Comm,const char[],const char[],FILE**);
617: EXTERN int  PetscFClose(MPI_Comm,FILE*);
618: EXTERN int  PetscFPrintf(MPI_Comm,FILE*,const char[],...) PETSC_PRINTF_FORMAT_CHECK(3,4);
619: EXTERN int  PetscPrintf(MPI_Comm,const char[],...)  PETSC_PRINTF_FORMAT_CHECK(2,3);

621: /*MC
622:     PetscErrorPrintf - Prints error messages.

624:     Not Collective

626:    Synopsis:
627:      int (*PetscErrorPrintf)(const char format[],...);

629:     Input Parameters:
630: .   format - the usual printf() format string 

632:    Options Database Keys:
633: .    -error_output_stderr - cause error messages to be printed to stderr instead of the
634:          (default) stdout


637:    Level: developer

639:     Fortran Note:
640:     This routine is not supported in Fortran.

642:     Concepts: error messages^printing
643:     Concepts: printing^error messages

645: .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscHelpPrintf()
646: M*/
647: EXTERN int  (*PetscErrorPrintf)(const char[],...);

649: /*MC
650:     PetscHelpPrintf - Prints help messages.

652:     Not Collective

654:    Synopsis:
655:      int (*PetscHelpPrintf)(const char format[],...);

657:     Input Parameters:
658: .   format - the usual printf() format string 

660:    Level: developer

662:     Fortran Note:
663:     This routine is not supported in Fortran.

665:     Concepts: help messages^printing
666:     Concepts: printing^help messages

668: .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscErrorPrintf()
669: M*/
670: EXTERN int  (*PetscHelpPrintf)(MPI_Comm,const char[],...);

672: EXTERN int  PetscPOpen(MPI_Comm,const char[],const char[],const char[],FILE **);
673: EXTERN int  PetscPClose(MPI_Comm,FILE*);
674: EXTERN int  PetscSynchronizedPrintf(MPI_Comm,const char[],...) PETSC_PRINTF_FORMAT_CHECK(2,3);
675: EXTERN int  PetscSynchronizedFPrintf(MPI_Comm,FILE*,const char[],...) PETSC_PRINTF_FORMAT_CHECK(3,4);
676: EXTERN int  PetscSynchronizedFlush(MPI_Comm);
677: EXTERN int  PetscSynchronizedFGets(MPI_Comm,FILE*,int,char[]);
678: EXTERN int  PetscStartMatlab(MPI_Comm,const char[],const char[],FILE**);
679: EXTERN int  PetscStartJava(MPI_Comm,const char[],const char[],FILE**);
680: EXTERN int  PetscGetPetscDir(const char*[]);

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

686:    Level: advanced

688: .seealso:  PetscObject, PetscObjectContainerCreate()
689: S*/
690: typedef struct _p_PetscObjectContainer*  PetscObjectContainer;
691: EXTERN int PetscObjectContainerGetPointer(PetscObjectContainer,void **);
692: EXTERN int PetscObjectContainerSetPointer(PetscObjectContainer,void *);
693: EXTERN int PetscObjectContainerDestroy(PetscObjectContainer);
694: EXTERN int PetscObjectContainerCreate(MPI_Comm comm,PetscObjectContainer *);

696: /*
697:    For incremental debugging
698: */
699: extern PetscTruth PetscCompare;
700: EXTERN int        PetscCompareDouble(double);
701: EXTERN int        PetscCompareScalar(PetscScalar);
702: EXTERN int        PetscCompareInt(int);

704: /*
705:    For use in debuggers 
706: */
707: extern int PetscGlobalRank,PetscGlobalSize;
708: EXTERN int PetscIntView(int,int[],PetscViewer);
709: EXTERN int PetscRealView(int,PetscReal[],PetscViewer);
710: EXTERN int PetscScalarView(int,PetscScalar[],PetscViewer);

712: /*
713:     Allows accessing Matlab Engine
714: */
715:  #include petscmatlab.h

717: /*
718:     C code optimization is often enhanced by telling the compiler 
719:   that certain pointer arguments to functions are not aliased to 
720:   to other arguments. This is not yet ANSI C standard so we define 
721:   the macro "restrict" to indicate that the variable is not aliased 
722:   to any other argument.
723: */
724: #if defined(PETSC_HAVE_RESTRICT) && !defined(__cplusplus)
725: #define restrict _Restrict
726: #else
727: #if defined(restrict)
728: #undef restrict
729: #endif
730: #define restrict
731: #endif

733: /*
734:       Determine if some of the kernel computation routines use
735:    Fortran (rather than C) for the numerical calculations. On some machines
736:    and compilers (like complex numbers) the Fortran version of the routines
737:    is faster than the C/C++ versions. The flag PETSC_USE_FORTRAN_KERNELS  
738:    would be set in the petscconf.h file
739: */
740: #if defined(PETSC_USE_FORTRAN_KERNELS)

742: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTAIJ)
743: #define PETSC_USE_FORTRAN_KERNEL_MULTAIJ
744: #endif

746: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTTRANSPOSEAIJ)
747: #define PETSC_USE_FORTRAN_KERNEL_MULTTRANSPOSEAIJ
748: #endif

750: #if !defined(PETSC_USE_FORTRAN_KERNEL_NORM)
751: #define PETSC_USE_FORTRAN_KERNEL_NORM
752: #endif

754: #if !defined(PETSC_USE_FORTRAN_KERNEL_MAXPY)
755: #define PETSC_USE_FORTRAN_KERNEL_MAXPY
756: #endif

758: #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ)
759: #define PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ
760: #endif

762: #if !defined(PETSC_USE_FORTRAN_KERNEL_RELAXAIJ)
763: #define PETSC_USE_FORTRAN_KERNEL_RELAXAIJ
764: #endif

766: #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ)
767: #define PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ
768: #endif

770: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ)
771: #define PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ
772: #endif

774: #if !defined(PETSC_USE_FORTRAN_KERNEL_MDOT)
775: #define PETSC_USE_FORTRAN_KERNEL_MDOT
776: #endif

778: #if !defined(PETSC_USE_FORTRAN_KERNEL_XTIMESY)
779: #define PETSC_USE_FORTRAN_KERNEL_XTIMESY
780: #endif

782: #if !defined(PETSC_USE_FORTRAN_KERNEL_AYPX)
783: #define PETSC_USE_FORTRAN_KERNEL_AYPX
784: #endif

786: #if !defined(PETSC_USE_FORTRAN_KERNEL_WAXPY)
787: #define PETSC_USE_FORTRAN_KERNEL_WAXPY
788: #endif

790: #endif

792: /*
793:     Macros for indicating code that should be compiled with a C interface,
794:    rather than a C++ interface. Any routines that are dynamically loaded
795:    (such as the PCCreate_XXX() routines) must be wrapped so that the name
796:    mangler does not change the functions symbol name. This just hides the 
797:    ugly extern "C" {} wrappers.
798: */
799: #if defined(__cplusplus)
800: #define EXTERN_C_BEGIN extern "C" {
801: #define EXTERN_C_END }
802: #else
803: #define EXTERN_C_BEGIN 
804: #define EXTERN_C_END 
805: #endif

807: /* --------------------------------------------------------------------*/

809: /*M
810:     size - integer variable used to contain the number of processors in
811:            the relevent MPI_Comm

813:    Level: beginner

815: .seealso: rank, comm
816: M*/

818: /*M
819:     rank - integer variable used to contain the number of this processor relative
820:            to all in the relevent MPI_Comm

822:    Level: beginner

824: .seealso: size, comm
825: M*/

827: /*M
828:     comm - MPI_Comm used in the current routine or object

830:    Level: beginner

832: .seealso: size, rank
833: M*/

835: /*M
836:     MPI_Comm - the basic object used by MPI to determine which processes are involved in a 
837:         communication

839:    Level: beginner

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

843: .seealso: size, rank, comm, PETSC_COMM_WORLD, PETSC_COMM_SELF
844: M*/

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

850:    Level: beginner

852: .seealso: PetscReal, PassiveReal, PassiveScalar
853: M*/

855: /*M
856:     PetscReal - PETSc type that represents a double precision real number

858:    Level: beginner

860: .seealso: PetscScalar, PassiveReal, PassiveScalar
861: M*/

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

867:    Level: beginner

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

872: .seealso: PetscReal, PassiveReal, PetscScalar
873: M*/

875: /*M
876:     PassiveReal - PETSc type that represents a double precision real number

878:    Level: beginner

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

883: .seealso: PetscScalar, PetscReal, PassiveScalar
884: M*/

886: /*
887:      The IBM include files define hz, here we hide it so that it may be used
888:    as a regular user variable.
889: */
890: #if defined(hz)
891: #undef hz
892: #endif

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


897: #if defined(PETSC_HAVE_LIMITS_H)
898: #include <limits.h>
899: #endif
900: #if defined(PETSC_HAVE_SYS_PARAM_H)
901: #include <sys/param.h>
902: #endif

904: #if defined(MAXPATHLEN)
905: #  define PETSC_MAX_PATH_LEN     MAXPATHLEN
906: #elif defined(MAX_PATH)
907: #  define PETSC_MAX_PATH_LEN     MAX_PATH
908: #elif defined(_MAX_PATH)
909: #  define PETSC_MAX_PATH_LEN     _MAX_PATH
910: #else
911: #  define PETSC_MAX_PATH_LEN     4096
912: #endif

914: PETSC_EXTERN_CXX_END
915: #endif