Actual source code: petsc.h
1: /*
2: This is the main PETSc include file (for C and C++). It is included by all
3: other PETSc include files, so it almost never has to be specifically included.
4: */
7: /* ========================================================================== */
8: /*
9: petscconf.h is contained in ${PETSC_ARCH}/include/petscconf.h it is
10: found automatically by the compiler due to the -I${PETSC_DIR}/${PETSC_ARCH}/include
11: in the conf/variables definition of PETSC_INCLUDE
12: */
13: #include "petscconf.h"
14: #include "petscfix.h"
16: /* ========================================================================== */
17: /*
18: This facilitates using C version of PETSc from C++ and
19: C++ version from C. Use --with-c-support --with-clanguage=c++ with config/configure.py for the latter)
20: */
22: #error "PETSc configured with --with-clanguage=c++ and NOT --with-c-support - it can be used only with a C++ compiler"
23: #endif
28: #else
31: #endif
32: /* ========================================================================== */
33: /*
34: Current PETSc version number and release date. Also listed in
35: Web page
36: src/docs/tex/manual/intro.tex,
37: src/docs/tex/manual/manual.tex.
38: src/docs/website/index.html.
39: */
40: #include petscversion.h
41: #define PETSC_AUTHOR_INFO "\
42: The PETSc Team\n\
43: petsc-maint@mcs.anl.gov\n\
44: http://www.mcs.anl.gov/petsc/\n"
45: #if (PETSC_VERSION_RELEASE == 1)
46: #define PetscGetVersion(version,len) (PetscSNPrintf(version,len,"Petsc Release Version %d.%d.%d, Patch %d, ", \
47: PETSC_VERSION_MAJOR,PETSC_VERSION_MINOR, PETSC_VERSION_SUBMINOR, \
48: PETSC_VERSION_PATCH),PetscStrcat(version,PETSC_VERSION_PATCH_DATE))
49: #else
50: #define PetscGetVersion(version,len) (PetscSNPrintf(version,len,"Petsc Development"), \
51: PetscStrcat(version," HG revision: "),PetscStrcat(version,PETSC_VERSION_HG), \
52: PetscStrcat(version," HG Date: "),PetscStrcat(version,PETSC_VERSION_DATE_HG))
53: #endif
55: /*MC
56: PetscGetVersion - Gets the PETSc version information in a string.
58: Input Parameter:
59: . len - length of the string
61: Output Parameter:
62: . version - version string
64: Level: developer
66: Usage:
67: char version[256];
68: PetscGetVersion(version,256);CHKERRQ(ierr)
70: Fortran Note:
71: This routine is not supported in Fortran.
73: .seealso: PetscGetProgramName()
75: M*/
77: /* ========================================================================== */
79: /*
80: Currently cannot check formatting for PETSc print statements because we have our
81: own format %D and %G
82: */
83: #undef PETSC_PRINTF_FORMAT_CHECK
84: #define PETSC_PRINTF_FORMAT_CHECK(a,b)
85: #undef PETSC_FPRINTF_FORMAT_CHECK
86: #define PETSC_FPRINTF_FORMAT_CHECK(a,b)
88: /*
89: Fixes for config/configure.py time choices which impact our interface. Currently only
90: calling conventions and extra compiler checking falls under this category.
91: */
92: #if !defined(PETSC_STDCALL)
93: #define PETSC_STDCALL
94: #endif
95: #if !defined(PETSC_TEMPLATE)
96: #define PETSC_TEMPLATE
97: #endif
98: #if !defined(PETSC_HAVE_DLL_EXPORT)
99: #define PETSC_DLL_EXPORT
100: #define PETSC_DLL_IMPORT
101: #endif
102: #if !defined()
103: #define
104: #endif
105: #if !defined()
106: #define
107: #endif
108: #if !defined()
109: #define
110: #endif
111: #if !defined()
112: #define
113: #endif
114: #if !defined()
115: #define
116: #endif
117: #if !defined()
118: #define
119: #endif
120: #if !defined()
121: #define
122: #endif
123: #if !defined()
124: #define
125: #endif
126: /* ========================================================================== */
128: /*
129: Defines the interface to MPI allowing the use of all MPI functions.
131: PETSc does not use the C++ binding of MPI at ALL. The following flag
132: makes sure the C++ bindings are not included. The C++ bindings REQUIRE
133: putting mpi.h before ANY C++ include files, we cannot control this
134: with all PETSc users. Users who want to use the MPI C++ bindings can include
135: mpicxx.h directly in their code
136: */
137: #define MPICH_SKIP_MPICXX 1
138: #define OMPI_SKIP_MPICXX 1
139: #include "mpi.h"
140: /*
141: Yuck, we need to put stdio.h AFTER mpi.h for MPICH2 with C++ compiler
142: see the top of mpicxx.h in the MPICH2 distribution.
144: The MPI STANDARD HAS TO BE CHANGED to prevent this nonsense.
145: */
146: #include <stdio.h>
148: /* MSMPI on 32bit windows requires this yukky hack - that breaks MPI standard compliance */
149: #if !defined(MPIAPI)
150: #define MPIAPI
151: #endif
153: /*MC
154: PetscErrorCode - datatype used for return error code from all PETSc functions
156: Level: beginner
158: .seealso: CHKERRQ, SETERRQ
159: M*/
160: typedef int PetscErrorCode;
162: /*MC
164: PetscCookie - A unique id used to identify each PETSc object.
165: (internal integer in the data structure used for error
166: checking). These are all defined by an offset from the lowest
167: one, PETSC_SMALLEST_COOKIE.
169: Level: advanced
171: .seealso: PetscCookieRegister(), PetscLogEventRegister(), PetscHeaderCreate()
172: M*/
173: typedef int PetscCookie;
175: /*MC
176: PetscLogEvent - id used to identify PETSc or user events - primarily for logging
178: Level: intermediate
180: .seealso: PetscLogEventRegister(), PetscLogEventBegin(), PetscLogEventEnd(), PetscLogStage
181: M*/
182: typedef int PetscLogEvent;
184: /*MC
185: PetscLogStage - id used to identify user stages of runs - for logging
187: Level: intermediate
189: .seealso: PetscLogStageRegister(), PetscLogStageBegin(), PetscLogStageEnd(), PetscLogEvent
190: M*/
191: typedef int PetscLogStage;
193: /*MC
194: PetscBLASInt - datatype used to represent 'int' parameters to BLAS/LAPACK functions.
196: Level: intermediate
198: Notes: usually this is the same as PetscInt, but if PETSc was built with --with-64-bit-indices but
199: standard C/Fortran integers are 32 bit then this is NOT the same as PetscInt
201: .seealso: PetscMPIInt, PetscInt
203: M*/
204: typedef int PetscBLASInt;
206: /*MC
207: PetscMPIInt - datatype used to represent 'int' parameters to MPI functions.
209: Level: intermediate
211: Notes: usually this is the same as PetscInt, but if PETSc was built with --with-64-bit-indices but
212: standard C/Fortran integers are 32 bit then this is NOT the same as PetscInt
214: PetscBLASIntCheck(a) checks if the given PetscInt a will fit in a PetscBLASInt, if not it generates a
215: PETSC_ERR_ARG_OUTOFRANGE.
217: PetscBLASInt b = PetscBLASIntCast(a) checks if the given PetscInt a will fit in a PetscBLASInt, if not it
218: generates a PETSC_ERR_ARG_OUTOFRANGE
220: .seealso: PetscBLASInt, PetscInt
222: M*/
223: typedef int PetscMPIInt;
225: /*MC
226: PetscEnum - datatype used to pass enum types within PETSc functions.
228: Level: intermediate
230: PetscMPIIntCheck(a) checks if the given PetscInt a will fit in a PetscMPIInt, if not it generates a
231: PETSC_ERR_ARG_OUTOFRANGE.
233: PetscMPIInt b = PetscMPIIntCast(a) checks if the given PetscInt a will fit in a PetscMPIInt, if not it
234: generates a PETSC_ERR_ARG_OUTOFRANGE
236: .seealso: PetscOptionsGetEnum(), PetscOptionsEnum(), PetscBagRegisterEnum()
237: M*/
238: typedef enum { ENUM_DUMMY } PetscEnum;
240: /*MC
241: PetscInt - PETSc type that represents integer - used primarily to
242: represent size of objects. Its size can be configured with the option
243: --with-64-bit-indices - to be either 32bit or 64bit [default 32 bit ints]
245: Level: intermediate
248: .seealso: PetscScalar, PetscBLASInt, PetscMPIInt
249: M*/
250: #if defined(PETSC_USE_64BIT_INDICES)
251: typedef long long PetscInt;
252: #define MPIU_INT MPI_LONG_LONG_INT
253: #else
254: typedef int PetscInt;
255: #define MPIU_INT MPI_INT
256: #endif
258: /* add in MPIU type for size_t */
259: #if (PETSC_SIZEOF_SIZE_T) == (PETSC_SIZEOF_INT)
260: #define MPIU_SIZE_T MPI_INT
261: #elif (PETSC_SIZEOF_SIZE_T) == (PETSC_SIZEOF_LONG)
262: #define MPIU_SIZE_T MPI_LONG
263: #else
264: #error "Unknown size for size_t! Send us a bugreport at petsc-maint@mcs.anl.gov"
265: #endif
268: /*
269: You can use PETSC_STDOUT as a replacement of stdout. You can also change
270: the value of PETSC_STDOUT to redirect all standard output elsewhere
271: */
275: /*
276: You can use PETSC_STDERR as a replacement of stderr. You can also change
277: the value of PETSC_STDERR to redirect all standard error elsewhere
278: */
281: /*
282: PETSC_ZOPEFD is used to send data to the PETSc webpage. It can be used
283: in conjunction with PETSC_STDOUT, or by itself.
284: */
288: /*MC
289: PetscPolymorphicSubroutine - allows defining a C++ polymorphic version of
290: a PETSc function that remove certain optional arguments for a simplier user interface
292: Not collective
294: Synopsis:
295: PetscPolymorphicSubroutine(Functionname,(arguments of C++ function),(arguments of C function))
296:
297: Level: developer
299: Example:
300: PetscPolymorphicSubroutine(VecNorm,(Vec x,PetscReal *r),(x,NORM_2,r)) generates the new routine
301: PetscErrorCode VecNorm(Vec x,PetscReal *r) = VecNorm(x,NORM_2,r)
303: .seealso: PetscPolymorphicFunction()
305: M*/
306: #define PetscPolymorphicSubroutine(A,B,C) PETSC_STATIC_INLINE PetscErrorCode A B {return A C;}
308: /*MC
309: PetscPolymorphicScalar - allows defining a C++ polymorphic version of
310: a PETSc function that replaces a PetscScalar * argument with a PetscScalar argument
312: Not collective
314: Synopsis:
315: PetscPolymorphicScalar(Functionname,(arguments of C++ function),(arguments of C function))
316:
317: Level: developer
319: Example:
320: PetscPolymorphicScalar(VecAXPY,(PetscScalar _val,Vec x,Vec y),(&_Val,x,y)) generates the new routine
321: PetscErrorCode VecAXPY(PetscScalar _val,Vec x,Vec y) = {PetscScalar _Val = _val; return VecAXPY(&_Val,x,y);}
323: .seealso: PetscPolymorphicFunction(),PetscPolymorphicSubroutine()
325: M*/
326: #define PetscPolymorphicScalar(A,B,C) PETSC_STATIC_INLINE PetscErrorCode A B {PetscScalar _Val = _val; return A C;}
328: /*MC
329: PetscPolymorphicFunction - allows defining a C++ polymorphic version of
330: a PETSc function that remove certain optional arguments for a simplier user interface
331: and returns the computed value (istead of an error code)
333: Not collective
335: Synopsis:
336: PetscPolymorphicFunction(Functionname,(arguments of C++ function),(arguments of C function),return type,return variable name)
337:
338: Level: developer
340: Example:
341: PetscPolymorphicFunction(VecNorm,(Vec x,NormType t),(x,t,&r),PetscReal,r) generates the new routine
342: PetscReal VecNorm(Vec x,NormType t) = {PetscReal r; VecNorm(x,t,&r); return r;}
344: .seealso: PetscPolymorphicSubroutine()
346: M*/
347: #define PetscPolymorphicFunction(A,B,C,D,E) PETSC_STATIC_INLINE D A B {D E; A C;return E;}
349: #else
350: #define PetscPolymorphicSubroutine(A,B,C)
351: #define PetscPolymorphicScalar(A,B,C)
352: #define PetscPolymorphicFunction(A,B,C,D,E)
353: #endif
355: /*
356: Extern indicates a PETSc function defined elsewhere
357: */
358: #if !defined(EXTERN)
359: #define EXTERN extern
360: #endif
362: /*
363: Defines some elementary mathematics functions and constants.
364: */
365: #include petscmath.h
367: /*
369: */
373: /*
374: Basic PETSc constants
375: */
377: /*E
378: PetscTruth - Logical variable. Actually an integer
380: Level: beginner
382: E*/
383: typedef enum { PETSC_FALSE,PETSC_TRUE } PetscTruth;
386: /*MC
387: PETSC_FALSE - False value of PetscTruth
389: Level: beginner
391: Note: Zero integer
393: .seealso: PetscTruth, PETSC_TRUE
394: M*/
396: /*MC
397: PETSC_TRUE - True value of PetscTruth
399: Level: beginner
401: Note: Nonzero integer
403: .seealso: PetscTruth, PETSC_FALSE
404: M*/
406: /*MC
407: PETSC_YES - Alias for PETSC_TRUE
409: Level: beginner
411: Note: Zero integer
413: .seealso: PetscTruth, PETSC_TRUE, PETSC_FALSE, PETSC_NO
414: M*/
415: #define PETSC_YES PETSC_TRUE
417: /*MC
418: PETSC_NO - Alias for PETSC_FALSE
420: Level: beginner
422: Note: Nonzero integer
424: .seealso: PetscTruth, PETSC_TRUE, PETSC_FALSE, PETSC_YES
425: M*/
426: #define PETSC_NO PETSC_FALSE
428: /*MC
429: PETSC_NULL - standard way of passing in a null or array or pointer
431: Level: beginner
433: Notes: accepted by many PETSc functions to not set a parameter and instead use
434: some default
436: This macro does not exist in Fortran; you must use PETSC_NULL_INTEGER,
437: PETSC_NULL_DOUBLE_PRECISION etc
439: .seealso: PETSC_DECIDE, PETSC_DEFAULT, PETSC_IGNORE, PETSC_DETERMINE
441: M*/
442: #define PETSC_NULL 0
444: /*MC
445: PETSC_DECIDE - standard way of passing in integer or floating point parameter
446: where you wish PETSc to use the default.
448: Level: beginner
450: .seealso: PETSC_NULL, PETSC_DEFAULT, PETSC_IGNORE, PETSC_DETERMINE
452: M*/
453: #define PETSC_DECIDE -1
455: /*MC
456: PETSC_DEFAULT - standard way of passing in integer or floating point parameter
457: where you wish PETSc to use the default.
459: Level: beginner
461: Fortran Notes: You need to use PETSC_DEFAULT_INTEGER or PETSC_DEFAULT_DOUBLE_PRECISION.
463: .seealso: PETSC_DECIDE, PETSC_NULL, PETSC_IGNORE, PETSC_DETERMINE
465: M*/
466: #define PETSC_DEFAULT -2
469: /*MC
470: PETSC_IGNORE - same as PETSC_NULL, means PETSc will ignore this argument
472: Level: beginner
474: Note: accepted by many PETSc functions to not set a parameter and instead use
475: some default
477: Fortran Notes: This macro does not exist in Fortran; you must use PETSC_NULL_INTEGER,
478: PETSC_NULL_DOUBLE_PRECISION etc
480: .seealso: PETSC_DECIDE, PETSC_DEFAULT, PETSC_NULL, PETSC_DETERMINE
482: M*/
483: #define PETSC_IGNORE PETSC_NULL
485: /*MC
486: PETSC_DETERMINE - standard way of passing in integer or floating point parameter
487: where you wish PETSc to compute the required value.
489: Level: beginner
491: .seealso: PETSC_DECIDE, PETSC_DEFAULT, PETSC_IGNORE, PETSC_NULL, VecSetSizes()
493: M*/
494: #define PETSC_DETERMINE PETSC_DECIDE
496: /*MC
497: PETSC_COMM_WORLD - the equivalent of the MPI_COMM_WORLD communicator which represents
498: all the processs that PETSc knows about.
500: Level: beginner
502: Notes: By default PETSC_COMM_WORLD and MPI_COMM_WORLD are identical unless you wish to
503: run PETSc on ONLY a subset of MPI_COMM_WORLD. In that case create your new (smaller)
504: communicator, call it, say comm, and set PETSC_COMM_WORLD = comm BEFORE calling
505: PetscInitialize()
507: .seealso: PETSC_COMM_SELF
509: M*/
512: /*MC
513: PETSC_COMM_SELF - a duplicate of the MPI_COMM_SELF communicator which represents
514: the current process
516: Level: beginner
518: Notes: PETSC_COMM_SELF and MPI_COMM_SELF are equivalent.
520: .seealso: PETSC_COMM_WORLD
522: M*/
523: #define PETSC_COMM_SELF MPI_COMM_SELF
528: EXTERN PetscErrorCode PetscSetHelpVersionFunctions(PetscErrorCode (*)(MPI_Comm),PetscErrorCode (*)(MPI_Comm));
529: EXTERN PetscErrorCode PetscCommDuplicate(MPI_Comm,MPI_Comm*,int*);
530: EXTERN PetscErrorCode PetscCommDestroy(MPI_Comm*);
532: /*MC
533: PetscMalloc - Allocates memory
535: Input Parameter:
536: . m - number of bytes to allocate
538: Output Parameter:
539: . result - memory allocated
541: Synopsis:
542: PetscErrorCode PetscMalloc(size_t m,void **result)
544: Level: beginner
546: Notes: Memory is always allocated at least double aligned
548: If you request memory of zero size it will allocate no space and assign the pointer to 0; PetscFree() will
549: properly handle not freeing the null pointer.
551: .seealso: PetscFree(), PetscNew()
553: Concepts: memory allocation
555: M*/
556: #define PetscMalloc(a,b) ((a != 0) ? (*PetscTrMalloc)((a),__LINE__,__FUNCT__,__FILE__,__SDIR__,(void**)(b)) : (*(b) = 0,0) )
558: /*MC
559: PetscMalloc2 - Allocates 2 chunks of memory
561: Input Parameter:
562: + m1 - number of elements to allocate in 1st chunk (may be zero)
563: . t1 - type of first memory elements
564: . m2 - number of elements to allocate in 2nd chunk (may be zero)
565: - t2 - type of second memory elements
567: Output Parameter:
568: + r1 - memory allocated in first chunk
569: - r2 - memory allocated in second chunk
571: Synopsis:
572: PetscErrorCode PetscMalloc2(size_t m1,type, t1,void **r1,size_t m2,type t2,void **r2)
574: Level: developer
576: Notes: Memory of first chunk is always allocated at least double aligned
578: .seealso: PetscFree(), PetscNew(), PetscMalloc()
580: Concepts: memory allocation
582: M*/
583: #if defined(PETSC_USE_DEBUG)
584: #define PetscMalloc2(m1,t1,r1,m2,t2,r2) (PetscMalloc((m1)*sizeof(t1),r1) || PetscMalloc((m2)*sizeof(t2),r2))
585: #else
586: #define PetscMalloc2(m1,t1,r1,m2,t2,r2) (PetscMalloc((m1)*sizeof(t1)+(m2)*sizeof(t2),r1) || (*(r2) = (t2*)(*(r1)+m1),0))
587: #endif
589: /*MC
590: PetscMalloc3 - Allocates 3 chunks of memory
592: Input Parameter:
593: + m1 - number of elements to allocate in 1st chunk (may be zero)
594: . t1 - type of first memory elements
595: . m2 - number of elements to allocate in 2nd chunk (may be zero)
596: . t2 - type of second memory elements
597: . m3 - number of elements to allocate in 3rd chunk (may be zero)
598: - t3 - type of third memory elements
600: Output Parameter:
601: + r1 - memory allocated in first chunk
602: . r2 - memory allocated in second chunk
603: - r3 - memory allocated in third chunk
605: Synopsis:
606: PetscErrorCode PetscMalloc3(size_t m1,type, t1,void **r1,size_t m2,type t2,void **r2,size_t m3,type t3,void **r3)
608: Level: developer
610: Notes: Memory of first chunk is always allocated at least double aligned
612: .seealso: PetscFree(), PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree3()
614: Concepts: memory allocation
616: M*/
617: #if defined(PETSC_USE_DEBUG)
618: #define PetscMalloc3(m1,t1,r1,m2,t2,r2,m3,t3,r3) (PetscMalloc((m1)*sizeof(t1),r1) || PetscMalloc((m2)*sizeof(t2),r2) || PetscMalloc((m3)*sizeof(t3),r3))
619: #else
620: #define PetscMalloc3(m1,t1,r1,m2,t2,r2,m3,t3,r3) (PetscMalloc((m1)*sizeof(t1)+(m2)*sizeof(t2)+(m3)*sizeof(t3),r1) || (*(r2) = (t2*)(*(r1)+m1),*(r3) = (t3*)(*(r2)+m2),0))
621: #endif
623: /*MC
624: PetscMalloc4 - Allocates 4 chunks of memory
626: Input Parameter:
627: + m1 - number of elements to allocate in 1st chunk (may be zero)
628: . t1 - type of first memory elements
629: . m2 - number of elements to allocate in 2nd chunk (may be zero)
630: . t2 - type of second memory elements
631: . m3 - number of elements to allocate in 3rd chunk (may be zero)
632: . t3 - type of third memory elements
633: . m4 - number of elements to allocate in 4th chunk (may be zero)
634: - t4 - type of fourth memory elements
636: Output Parameter:
637: + r1 - memory allocated in first chunk
638: . r2 - memory allocated in second chunk
639: . r3 - memory allocated in third chunk
640: - r4 - memory allocated in fourth chunk
642: Synopsis:
643: PetscErrorCode PetscMalloc4(size_t m1,type, t1,void **r1,size_t m2,type t2,void **r2,size_t m3,type t3,void **r3,size_t m4,type t4,void **r4)
645: Level: developer
647: Notes: Memory of first chunk is always allocated at least double aligned
649: .seealso: PetscFree(), PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree3(), PetscFree4()
651: Concepts: memory allocation
653: M*/
654: #if defined(PETSC_USE_DEBUG)
655: #define PetscMalloc4(m1,t1,r1,m2,t2,r2,m3,t3,r3,m4,t4,r4) (PetscMalloc((m1)*sizeof(t1),r1) || PetscMalloc((m2)*sizeof(t2),r2) || PetscMalloc((m3)*sizeof(t3),r3) || PetscMalloc((m4)*sizeof(t4),r4))
656: #else
657: #define PetscMalloc4(m1,t1,r1,m2,t2,r2,m3,t3,r3,m4,t4,r4) (PetscMalloc((m1)*sizeof(t1)+(m2)*sizeof(t2)+(m3)*sizeof(t3)+(m4)*sizeof(t4),r1) || (*(r2) = (t2*)(*(r1)+m1),*(r3) = (t3*)(*(r2)+m2),*(r4) = (t4*)(*(r3)+m3),0))
658: #endif
660: /*MC
661: PetscMalloc5 - Allocates 5 chunks of memory
663: Input Parameter:
664: + m1 - number of elements to allocate in 1st chunk (may be zero)
665: . t1 - type of first memory elements
666: . m2 - number of elements to allocate in 2nd chunk (may be zero)
667: . t2 - type of second memory elements
668: . m3 - number of elements to allocate in 3rd chunk (may be zero)
669: . t3 - type of third memory elements
670: . m4 - number of elements to allocate in 4th chunk (may be zero)
671: . t4 - type of fourth memory elements
672: . m5 - number of elements to allocate in 5th chunk (may be zero)
673: - t5 - type of fifth memory elements
675: Output Parameter:
676: + r1 - memory allocated in first chunk
677: . r2 - memory allocated in second chunk
678: . r3 - memory allocated in third chunk
679: . r4 - memory allocated in fourth chunk
680: - r5 - memory allocated in fifth chunk
682: Synopsis:
683: PetscErrorCode PetscMalloc5(size_t m1,type, t1,void **r1,size_t m2,type t2,void **r2,size_t m3,type t3,void **r3,size_t m4,type t4,void **r4,size_t m5,type t5,void **r5)
685: Level: developer
687: Notes: Memory of first chunk is always allocated at least double aligned
689: .seealso: PetscFree(), PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree3(), PetscFree4(), PetscFree5()
691: Concepts: memory allocation
693: M*/
694: #if defined(PETSC_USE_DEBUG)
695: #define PetscMalloc5(m1,t1,r1,m2,t2,r2,m3,t3,r3,m4,t4,r4,m5,t5,r5) (PetscMalloc((m1)*sizeof(t1),r1) || PetscMalloc((m2)*sizeof(t2),r2) || PetscMalloc((m3)*sizeof(t3),r3) || PetscMalloc((m4)*sizeof(t4),r4) || PetscMalloc((m5)*sizeof(t5),r5))
696: #else
697: #define PetscMalloc5(m1,t1,r1,m2,t2,r2,m3,t3,r3,m4,t4,r4,m5,t5,r5) (PetscMalloc((m1)*sizeof(t1)+(m2)*sizeof(t2)+(m3)*sizeof(t3)+(m4)*sizeof(t4)+(m5)*sizeof(t5),r1) || (*(r2) = (t2*)(*(r1)+m1),*(r3) = (t3*)(*(r2)+m2),*(r4) = (t4*)(*(r3)+m3),*(r5) = (t5*)(*(r4)+m4),0))
698: #endif
701: /*MC
702: PetscMalloc6 - Allocates 6 chunks of memory
704: Input Parameter:
705: + m1 - number of elements to allocate in 1st chunk (may be zero)
706: . t1 - type of first memory elements
707: . m2 - number of elements to allocate in 2nd chunk (may be zero)
708: . t2 - type of second memory elements
709: . m3 - number of elements to allocate in 3rd chunk (may be zero)
710: . t3 - type of third memory elements
711: . m4 - number of elements to allocate in 4th chunk (may be zero)
712: . t4 - type of fourth memory elements
713: . m5 - number of elements to allocate in 5th chunk (may be zero)
714: . t5 - type of fifth memory elements
715: . m6 - number of elements to allocate in 6th chunk (may be zero)
716: - t6 - type of sixth memory elements
718: Output Parameter:
719: + r1 - memory allocated in first chunk
720: . r2 - memory allocated in second chunk
721: . r3 - memory allocated in third chunk
722: . r4 - memory allocated in fourth chunk
723: . r5 - memory allocated in fifth chunk
724: - r6 - memory allocated in sixth chunk
726: Synopsis:
727: PetscErrorCode PetscMalloc6(size_t m1,type, t1,void **r1,size_t m2,type t2,void **r2,size_t m3,type t3,void **r3,size_t m4,type t4,void **r4,size_t m5,type t5,void **r5,size_t m6,type t6,void **r6)
729: Level: developer
731: Notes: Memory of first chunk is always allocated at least double aligned
733: .seealso: PetscFree(), PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree3(), PetscFree4(), PetscFree5(), PetscFree6()
735: Concepts: memory allocation
737: M*/
738: #if defined(PETSC_USE_DEBUG)
739: #define PetscMalloc6(m1,t1,r1,m2,t2,r2,m3,t3,r3,m4,t4,r4,m5,t5,r5,m6,t6,r6) (PetscMalloc((m1)*sizeof(t1),r1) || PetscMalloc((m2)*sizeof(t2),r2) || PetscMalloc((m3)*sizeof(t3),r3) || PetscMalloc((m4)*sizeof(t4),r4) || PetscMalloc((m5)*sizeof(t5),r5) || PetscMalloc((m6)*sizeof(t6),r6))
740: #else
741: #define PetscMalloc6(m1,t1,r1,m2,t2,r2,m3,t3,r3,m4,t4,r4,m5,t5,r5,m6,t6,r6) (PetscMalloc((m1)*sizeof(t1)+(m2)*sizeof(t2)+(m3)*sizeof(t3)+(m4)*sizeof(t4)+(m5)*sizeof(t5)+(m6)*sizeof(t6),r1) || (*(r2) = (t2*)(*(r1)+m1),*(r3) = (t3*)(*(r2)+m2),*(r4) = (t4*)(*(r3)+m3),*(r5) = (t5*)(*(r4)+m4),*(r6) = (t6*)(*(r5)+m5),0))
742: #endif
744: /*MC
745: PetscMalloc7 - Allocates 7 chunks of memory
747: Input Parameter:
748: + m1 - number of elements to allocate in 1st chunk (may be zero)
749: . t1 - type of first memory elements
750: . m2 - number of elements to allocate in 2nd chunk (may be zero)
751: . t2 - type of second memory elements
752: . m3 - number of elements to allocate in 3rd chunk (may be zero)
753: . t3 - type of third memory elements
754: . m4 - number of elements to allocate in 4th chunk (may be zero)
755: . t4 - type of fourth memory elements
756: . m5 - number of elements to allocate in 5th chunk (may be zero)
757: . t5 - type of fifth memory elements
758: . m6 - number of elements to allocate in 6th chunk (may be zero)
759: . t6 - type of sixth memory elements
760: . m7 - number of elements to allocate in 7th chunk (may be zero)
761: - t7 - type of sixth memory elements
763: Output Parameter:
764: + r1 - memory allocated in first chunk
765: . r2 - memory allocated in second chunk
766: . r3 - memory allocated in third chunk
767: . r4 - memory allocated in fourth chunk
768: . r5 - memory allocated in fifth chunk
769: . r6 - memory allocated in sixth chunk
770: - r7 - memory allocated in sixth chunk
772: Synopsis:
773: PetscErrorCode PetscMalloc7(size_t m1,type, t1,void **r1,size_t m2,type t2,void **r2,size_t m3,type t3,void **r3,size_t m4,type t4,void **r4,size_t m5,type t5,void **r5,size_t m6,type t6,void **r6,size_t m7,type t7,void **r7)
775: Level: developer
777: Notes: Memory of first chunk is always allocated at least double aligned
779: .seealso: PetscFree(), PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree3(), PetscFree4(), PetscFree5(), PetscFree6(), PetscFree7()
781: Concepts: memory allocation
783: M*/
784: #if defined(PETSC_USE_DEBUG)
785: #define PetscMalloc7(m1,t1,r1,m2,t2,r2,m3,t3,r3,m4,t4,r4,m5,t5,r5,m6,t6,r6,m7,t7,r7) (PetscMalloc((m1)*sizeof(t1),r1) || PetscMalloc((m2)*sizeof(t2),r2) || PetscMalloc((m3)*sizeof(t3),r3) || PetscMalloc((m4)*sizeof(t4),r4) || PetscMalloc((m5)*sizeof(t5),r5) || PetscMalloc((m6)*sizeof(t6),r6) || PetscMalloc((m7)*sizeof(t7),r7))
786: #else
787: #define PetscMalloc7(m1,t1,r1,m2,t2,r2,m3,t3,r3,m4,t4,r4,m5,t5,r5,m6,t6,r6,m7,t7,r7) (PetscMalloc((m1)*sizeof(t1)+(m2)*sizeof(t2)+(m3)*sizeof(t3)+(m4)*sizeof(t4)+(m5)*sizeof(t5)+(m6)*sizeof(t6)+(m7)*sizeof(t7),r1) || (*(r2) = (t2*)(*(r1)+m1),*(r3) = (t3*)(*(r2)+m2),*(r4) = (t4*)(*(r3)+m3),*(r5) = (t5*)(*(r4)+m4),*(r6) = (t6*)(*(r5)+m5),*(r7) = (t7*)(*(r6)+m6),0))
788: #endif
790: /*MC
791: PetscNew - Allocates memory of a particular type, zeros the memory!
793: Input Parameter:
794: . type - structure name of space to be allocated. Memory of size sizeof(type) is allocated
796: Output Parameter:
797: . result - memory allocated
799: Synopsis:
800: PetscErrorCode PetscNew(struct type,((type *))result)
802: Level: beginner
804: .seealso: PetscFree(), PetscMalloc()
806: Concepts: memory allocation
808: M*/
809: #define PetscNew(A,b) (PetscMalloc(sizeof(A),(b)) || PetscMemzero(*(b),sizeof(A)))
810: #define PetscNewLog(o,A,b) (PetscNew(A,b) || ((o) ? PetscLogObjectMemory(o,sizeof(A)) : 0))
812: /*MC
813: PetscFree - Frees memory
815: Input Parameter:
816: . memory - memory to free (the pointer is ALWAYS set to 0 upon sucess)
818: Synopsis:
819: PetscErrorCode PetscFree(void *memory)
821: Level: beginner
823: Notes: Memory must have been obtained with PetscNew() or PetscMalloc()
825: .seealso: PetscNew(), PetscMalloc(), PetscFreeVoid()
827: Concepts: memory allocation
829: M*/
830: #define PetscFree(a) ((a) ? ((*PetscTrFree)((void*)(a),__LINE__,__FUNCT__,__FILE__,__SDIR__) || ((a = 0),0)) : 0)
832: /*MC
833: PetscFreeVoid - Frees memory
835: Input Parameter:
836: . memory - memory to free
838: Synopsis:
839: void PetscFreeVoid(void *memory)
841: Level: beginner
843: Notes: This is different from PetscFree() in that no error code is returned
845: .seealso: PetscFree(), PetscNew(), PetscMalloc()
847: Concepts: memory allocation
849: M*/
850: #define PetscFreeVoid(a) ((*PetscTrFree)((a),__LINE__,__FUNCT__,__FILE__,__SDIR__),(a) = 0)
853: /*MC
854: PetscFree2 - Frees 2 chunks of memory obtained with PetscMalloc2()
856: Input Parameter:
857: + memory1 - memory to free
858: - memory2 - 2nd memory to free
861: Synopsis:
862: PetscErrorCode PetscFree2(void *memory1,void *memory2)
864: Level: developer
866: Notes: Memory must have been obtained with PetscMalloc2()
868: .seealso: PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree()
870: Concepts: memory allocation
872: M*/
873: #if defined(PETSC_USE_DEBUG)
874: #define PetscFree2(m1,m2) (PetscFree(m2) || PetscFree(m1))
875: #else
876: #define PetscFree2(m1,m2) (PetscFree(m1))
877: #endif
879: /*MC
880: PetscFree3 - Frees 3 chunks of memory obtained with PetscMalloc3()
882: Input Parameter:
883: + memory1 - memory to free
884: . memory2 - 2nd memory to free
885: - memory3 - 3rd memory to free
888: Synopsis:
889: PetscErrorCode PetscFree3(void *memory1,void *memory2,void *memory3)
891: Level: developer
893: Notes: Memory must have been obtained with PetscMalloc3()
895: .seealso: PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree(), PetscMalloc3()
897: Concepts: memory allocation
899: M*/
900: #if defined(PETSC_USE_DEBUG)
901: #define PetscFree3(m1,m2,m3) (PetscFree(m3) || PetscFree(m2) || PetscFree(m1))
902: #else
903: #define PetscFree3(m1,m2,m3) (PetscFree(m1))
904: #endif
906: /*MC
907: PetscFree4 - Frees 4 chunks of memory obtained with PetscMalloc4()
909: Input Parameter:
910: + m1 - memory to free
911: . m2 - 2nd memory to free
912: . m3 - 3rd memory to free
913: - m4 - 4th memory to free
916: Synopsis:
917: PetscErrorCode PetscFree4(void *m1,void *m2,void *m3,void *m4)
919: Level: developer
921: Notes: Memory must have been obtained with PetscMalloc4()
923: .seealso: PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree(), PetscMalloc3(), PetscMalloc4()
925: Concepts: memory allocation
927: M*/
928: #if defined(PETSC_USE_DEBUG)
929: #define PetscFree4(m1,m2,m3,m4) (PetscFree(m4) || PetscFree(m3) || PetscFree(m2) || PetscFree(m1))
930: #else
931: #define PetscFree4(m1,m2,m3,m4) (PetscFree(m1))
932: #endif
934: /*MC
935: PetscFree5 - Frees 5 chunks of memory obtained with PetscMalloc5()
937: Input Parameter:
938: + m1 - memory to free
939: . m2 - 2nd memory to free
940: . m3 - 3rd memory to free
941: . m4 - 4th memory to free
942: - m5 - 5th memory to free
945: Synopsis:
946: PetscErrorCode PetscFree5(void *m1,void *m2,void *m3,void *m4,void *m5)
948: Level: developer
950: Notes: Memory must have been obtained with PetscMalloc5()
952: .seealso: PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree(), PetscMalloc3(), PetscMalloc4(), PetscMalloc5()
954: Concepts: memory allocation
956: M*/
957: #if defined(PETSC_USE_DEBUG)
958: #define PetscFree5(m1,m2,m3,m4,m5) (PetscFree(m5) || PetscFree(m4) || PetscFree(m3) || PetscFree(m2) || PetscFree(m1))
959: #else
960: #define PetscFree5(m1,m2,m3,m4,m5) (PetscFree(m1))
961: #endif
964: /*MC
965: PetscFree6 - Frees 6 chunks of memory obtained with PetscMalloc6()
967: Input Parameter:
968: + m1 - memory to free
969: . m2 - 2nd memory to free
970: . m3 - 3rd memory to free
971: . m4 - 4th memory to free
972: . m5 - 5th memory to free
973: - m6 - 6th memory to free
976: Synopsis:
977: PetscErrorCode PetscFree6(void *m1,void *m2,void *m3,void *m4,void *m5,void *m6)
979: Level: developer
981: Notes: Memory must have been obtained with PetscMalloc6()
983: .seealso: PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree(), PetscMalloc3(), PetscMalloc4(), PetscMalloc5(), PetscMalloc6()
985: Concepts: memory allocation
987: M*/
988: #if defined(PETSC_USE_DEBUG)
989: #define PetscFree6(m1,m2,m3,m4,m5,m6) (PetscFree(m6) || PetscFree(m5) || PetscFree(m4) || PetscFree(m3) || PetscFree(m2) || PetscFree(m1))
990: #else
991: #define PetscFree6(m1,m2,m3,m4,m5,m6) (PetscFree(m1))
992: #endif
994: /*MC
995: PetscFree7 - Frees 7 chunks of memory obtained with PetscMalloc7()
997: Input Parameter:
998: + m1 - memory to free
999: . m2 - 2nd memory to free
1000: . m3 - 3rd memory to free
1001: . m4 - 4th memory to free
1002: . m5 - 5th memory to free
1003: . m6 - 6th memory to free
1004: - m7 - 7th memory to free
1007: Synopsis:
1008: PetscErrorCode PetscFree7(void *m1,void *m2,void *m3,void *m4,void *m5,void *m6,void *m7)
1010: Level: developer
1012: Notes: Memory must have been obtained with PetscMalloc7()
1014: .seealso: PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree(), PetscMalloc3(), PetscMalloc4(), PetscMalloc5(), PetscMalloc6(),
1015: PetscMalloc7()
1017: Concepts: memory allocation
1019: M*/
1020: #if defined(PETSC_USE_DEBUG)
1021: #define PetscFree7(m1,m2,m3,m4,m5,m6,m7) (PetscFree(m7) || PetscFree(m6) || PetscFree(m5) || PetscFree(m4) || PetscFree(m3) || PetscFree(m2) || PetscFree(m1))
1022: #else
1023: #define PetscFree7(m1,m2,m3,m4,m5,m6,m7) (PetscFree(m1))
1024: #endif
1026: EXTERN PetscErrorCode (*PetscTrMalloc)(size_t,int,const char[],const char[],const char[],void**);
1027: EXTERN PetscErrorCode (*PetscTrFree)(void*,int,const char[],const char[],const char[]);
1028: EXTERN PetscErrorCode PetscMallocSet(PetscErrorCode (*)(size_t,int,const char[],const char[],const char[],void**),PetscErrorCode (*)(void*,int,const char[],const char[],const char[]));
1029: EXTERN PetscErrorCode PetscMallocClear(void);
1031: /*
1032: Routines for tracing memory corruption/bleeding with default PETSc
1033: memory allocation
1034: */
1035: EXTERN PetscErrorCode PetscMallocDump(FILE *);
1036: EXTERN PetscErrorCode PetscMallocDumpLog(FILE *);
1037: EXTERN PetscErrorCode PetscMallocGetCurrentUsage(PetscLogDouble *);
1038: EXTERN PetscErrorCode PetscMallocGetMaximumUsage(PetscLogDouble *);
1039: EXTERN PetscErrorCode PetscMallocDebug(PetscTruth);
1040: EXTERN PetscErrorCode PetscMallocValidate(int,const char[],const char[],const char[]);
1041: EXTERN PetscErrorCode PetscMallocSetDumpLog(void);
1044: /*
1045: Variable type where we stash PETSc object pointers in Fortran.
1046: On most machines size(pointer) == sizeof(long) - except windows
1047: where its sizeof(long long)
1048: */
1050: #if (PETSC_SIZEOF_VOID_P) == (PETSC_SIZEOF_LONG)
1051: #define PetscFortranAddr long
1052: #elif (PETSC_SIZEOF_VOID_P) == (PETSC_SIZEOF_LONG_LONG)
1053: #define PetscFortranAddr long long
1054: #else
1055: #error "Unknown size for PetscFortranAddr! Send us a bugreport at petsc-maint@mcs.anl.gov"
1056: #endif
1058: /*E
1059: PetscDataType - Used for handling different basic data types.
1061: Level: beginner
1063: Developer comment: It would be nice if we could always just use MPI Datatypes, why can we not?
1065: .seealso: PetscBinaryRead(), PetscBinaryWrite(), PetscDataTypeToMPIDataType(),
1066: PetscDataTypeGetSize()
1068: E*/
1069: typedef enum {PETSC_INT = 0,PETSC_DOUBLE = 1,PETSC_COMPLEX = 2, PETSC_LONG = 3 ,PETSC_SHORT = 4,PETSC_FLOAT = 5,
1070: PETSC_CHAR = 6,PETSC_LOGICAL = 7,PETSC_ENUM = 8,PETSC_TRUTH=9, PETSC_LONG_DOUBLE = 10} PetscDataType;
1073: #if defined(PETSC_USE_COMPLEX)
1074: #define PETSC_SCALAR PETSC_COMPLEX
1075: #else
1076: #if defined(PETSC_USE_SINGLE)
1077: #define PETSC_SCALAR PETSC_FLOAT
1078: #elif defined(PETSC_USE_LONG_DOUBLE)
1079: #define PETSC_SCALAR PETSC_LONG_DOUBLE
1080: #elif defined(PETSC_USE_INT)
1081: #define PETSC_SCALAR PETSC_INT
1082: #else
1083: #define PETSC_SCALAR PETSC_DOUBLE
1084: #endif
1085: #endif
1086: #if defined(PETSC_USE_SINGLE)
1087: #define PETSC_REAL PETSC_FLOAT
1088: #elif defined(PETSC_USE_LONG_DOUBLE)
1089: #define PETSC_REAL PETSC_LONG_DOUBLE
1090: #elif defined(PETSC_USE_INT)
1091: #define PETSC_REAL PETSC_INT
1092: #else
1093: #define PETSC_REAL PETSC_DOUBLE
1094: #endif
1095: #define PETSC_FORTRANADDR PETSC_LONG
1097: EXTERN PetscErrorCode PetscDataTypeToMPIDataType(PetscDataType,MPI_Datatype*);
1098: EXTERN PetscErrorCode PetscMPIDataTypeToPetscDataType(MPI_Datatype,PetscDataType*);
1099: EXTERN PetscErrorCode PetscDataTypeGetSize(PetscDataType,size_t*);
1101: /*
1102: Basic memory and string operations. These are usually simple wrappers
1103: around the basic Unix system calls, but a few of them have additional
1104: functionality and/or error checking.
1105: */
1106: EXTERN PetscErrorCode PetscMemcpy(void*,const void *,size_t);
1107: EXTERN PetscErrorCode PetscBitMemcpy(void*,PetscInt,const void*,PetscInt,PetscInt,PetscDataType);
1108: EXTERN PetscErrorCode PetscMemmove(void*,void *,size_t);
1109: EXTERN PetscErrorCode PetscMemzero(void*,size_t);
1110: EXTERN PetscErrorCode PetscMemcmp(const void*,const void*,size_t,PetscTruth *);
1111: EXTERN PetscErrorCode PetscStrlen(const char[],size_t*);
1112: EXTERN PetscErrorCode PetscStrcmp(const char[],const char[],PetscTruth *);
1113: EXTERN PetscErrorCode PetscStrgrt(const char[],const char[],PetscTruth *);
1114: EXTERN PetscErrorCode PetscStrcasecmp(const char[],const char[],PetscTruth*);
1115: EXTERN PetscErrorCode PetscStrncmp(const char[],const char[],size_t,PetscTruth*);
1116: EXTERN PetscErrorCode PetscStrcpy(char[],const char[]);
1117: EXTERN PetscErrorCode PetscStrcat(char[],const char[]);
1118: EXTERN PetscErrorCode PetscStrncat(char[],const char[],size_t);
1119: EXTERN PetscErrorCode PetscStrncpy(char[],const char[],size_t);
1120: EXTERN PetscErrorCode PetscStrchr(const char[],char,char *[]);
1121: EXTERN PetscErrorCode PetscStrtolower(char[]);
1122: EXTERN PetscErrorCode PetscStrrchr(const char[],char,char *[]);
1123: EXTERN PetscErrorCode PetscStrstr(const char[],const char[],char *[]);
1124: EXTERN PetscErrorCode PetscStrrstr(const char[],const char[],char *[]);
1125: EXTERN PetscErrorCode PetscStrallocpy(const char[],char *[]);
1126: EXTERN PetscErrorCode PetscStrreplace(MPI_Comm,const char[],char[],size_t);
1127: #define PetscStrfree(a) ((a) ? PetscFree(a) : 0)
1129: /*S
1130: PetscToken - 'Token' used for managing tokenizing strings
1132: Level: intermediate
1134: .seealso: PetscTokenCreate(), PetscTokenFind(), PetscTokenDestroy()
1135: S*/
1136: typedef struct _p_PetscToken* PetscToken;
1138: EXTERN PetscErrorCode PetscTokenCreate(const char[],const char,PetscToken*);
1139: EXTERN PetscErrorCode PetscTokenFind(PetscToken,char *[]);
1140: EXTERN PetscErrorCode PetscTokenDestroy(PetscToken);
1142: /*
1143: These are MPI operations for MPI_Allreduce() etc
1144: */
1145: EXTERN MPI_Op PetscMaxSum_Op;
1146: #if defined(PETSC_USE_COMPLEX)
1147: EXTERN MPI_Op PetscSum_Op;
1148: #else
1149: #define PetscSum_Op MPI_SUM
1150: #endif
1151: EXTERN PetscErrorCode PetscMaxSum(MPI_Comm,const PetscInt[],PetscInt*,PetscInt*);
1153: /*S
1154: PetscObject - any PETSc object, PetscViewer, Mat, Vec, KSP etc
1156: Level: beginner
1158: Note: This is the base class from which all objects appear.
1160: .seealso: PetscObjectDestroy(), PetscObjectView(), PetscObjectGetName(), PetscObjectSetName()
1161: S*/
1162: typedef struct _p_PetscObject* PetscObject;
1164: /*S
1165: PetscFList - Linked list of functions, possibly stored in dynamic libraries, accessed
1166: by string name
1168: Level: advanced
1170: .seealso: PetscFListAdd(), PetscFListDestroy()
1171: S*/
1172: typedef struct _n_PetscFList *PetscFList;
1174: /*E
1175: PetscFileMode - Access mode for a file.
1177: Level: beginner
1179: FILE_MODE_READ - open a file at its beginning for reading
1181: FILE_MODE_WRITE - open a file at its beginning for writing (will create if the file does not exist)
1183: FILE_MODE_APPEND - open a file at end for writing
1185: FILE_MODE_UPDATE - open a file for updating, meaning for reading and writing
1187: FILE_MODE_APPEND_UPDATE - open a file for updating, meaning for reading and writing, at the end
1189: .seealso: PetscViewerFileSetMode()
1190: E*/
1191: typedef enum {FILE_MODE_READ, FILE_MODE_WRITE, FILE_MODE_APPEND, FILE_MODE_UPDATE, FILE_MODE_APPEND_UPDATE} PetscFileMode;
1193: #include petscviewer.h
1194: #include petscoptions.h
1196: #define PETSC_SMALLEST_COOKIE 1211211
1199: EXTERN PetscErrorCode PetscCookieRegister(const char[],PetscCookie *);
1201: /*
1202: Routines that get memory usage information from the OS
1203: */
1204: EXTERN PetscErrorCode PetscMemoryGetCurrentUsage(PetscLogDouble *);
1205: EXTERN PetscErrorCode PetscMemoryGetMaximumUsage(PetscLogDouble *);
1206: EXTERN PetscErrorCode PetscMemorySetGetMaximumUsage(void);
1207: EXTERN PetscErrorCode PetscMemoryShowUsage(PetscViewer,const char[]);
1209: EXTERN PetscErrorCode PetscInfoAllow(PetscTruth,const char []);
1210: EXTERN PetscErrorCode PetscGetTime(PetscLogDouble*);
1211: EXTERN PetscErrorCode PetscGetCPUTime(PetscLogDouble*);
1212: EXTERN PetscErrorCode PetscSleep(int);
1214: /*
1215: Initialization of PETSc
1216: */
1217: EXTERN PetscErrorCode PetscInitialize(int*,char***,const char[],const char[]);
1218: PetscPolymorphicSubroutine(PetscInitialize,(int *argc,char ***args),(argc,args,PETSC_NULL,PETSC_NULL))
1219: EXTERN PetscErrorCode PetscInitializeNoArguments(void);
1220: EXTERN PetscErrorCode PetscInitialized(PetscTruth *);
1221: EXTERN PetscErrorCode PetscFinalized(PetscTruth *);
1222: EXTERN PetscErrorCode PetscFinalize(void);
1223: EXTERN PetscErrorCode PetscInitializeFortran(void);
1224: EXTERN PetscErrorCode PetscGetArgs(int*,char ***);
1225: EXTERN PetscErrorCode PetscGetArguments(char ***);
1226: EXTERN PetscErrorCode PetscFreeArguments(char **);
1228: EXTERN PetscErrorCode PetscEnd(void);
1229: EXTERN PetscErrorCode PetscInitializePackage(const char[]);
1231: EXTERN PetscErrorCode PetscOpenMPMerge(PetscMPIInt);
1232: EXTERN PetscErrorCode PetscOpenMPSpawn(PetscMPIInt);
1233: EXTERN PetscErrorCode PetscOpenMPFinalize(void);
1234: EXTERN PetscErrorCode PetscOpenMPRun(MPI_Comm,PetscErrorCode (*)(MPI_Comm,void *),void*);
1235: EXTERN PetscErrorCode PetscOpenMPFree(MPI_Comm,void*);
1236: EXTERN PetscErrorCode PetscOpenMPNew(MPI_Comm,PetscInt,void**);
1238: EXTERN PetscErrorCode PetscPythonInitialize(const char[],const char[]);
1239: EXTERN PetscErrorCode PetscPythonFinalize(void);
1241: /*
1243: function pointers. Since the regular C++ code expects its function pointers to be
1244: C++.
1245: */
1246: typedef void (**PetscVoidStarFunction)(void);
1247: typedef void (*PetscVoidFunction)(void);
1248: typedef PetscErrorCode (*PetscErrorCodeFunction)(void);
1250: /*
1251: PetscTryMethod - Queries an object for a method, if it exists then calls it.
1252: These are intended to be used only inside PETSc functions.
1253: */
1254: #define PetscTryMethod(obj,A,B,C) \
1255: 0;{ PetscErrorCode (*f)B, __ierr; \
1256: __PetscObjectQueryFunction((PetscObject)obj,A,(PetscVoidStarFunction)&f);CHKERRQ(__ierr); \
1257: if (f) {__(*f)C;CHKERRQ(__ierr);}\
1258: }
1259: #define PetscUseMethod(obj,A,B,C) \
1260: 0;{ PetscErrorCode (*f)B, __ierr; \
1261: __PetscObjectQueryFunction((PetscObject)obj,A,(PetscVoidStarFunction)&f);CHKERRQ(__ierr); \
1262: if (f) {__(*f)C;CHKERRQ(__ierr);}\
1263: else {SETERRQ1(PETSC_ERR_SUP,"Cannot locate function %s in object",A);} \
1264: }
1265: /*
1266: Functions that can act on any PETSc object.
1267: */
1268: EXTERN PetscErrorCode PetscObjectCreate(MPI_Comm,PetscObject*);
1269: EXTERN PetscErrorCode PetscObjectCreateGeneric(MPI_Comm, PetscCookie, const char [], PetscObject *);
1270: EXTERN PetscErrorCode PetscObjectDestroy(PetscObject);
1271: EXTERN PetscErrorCode PetscObjectExists(PetscObject,PetscTruth*);
1272: EXTERN PetscErrorCode PetscObjectGetComm(PetscObject,MPI_Comm *);
1273: EXTERN PetscErrorCode PetscObjectGetCookie(PetscObject,PetscCookie *);
1274: EXTERN PetscErrorCode PetscObjectSetType(PetscObject,const char []);
1275: EXTERN PetscErrorCode PetscObjectGetType(PetscObject,const char *[]);
1276: EXTERN PetscErrorCode PetscObjectSetName(PetscObject,const char[]);
1277: EXTERN PetscErrorCode PetscObjectGetName(PetscObject,const char*[]);
1278: EXTERN PetscErrorCode PetscObjectSetTabLevel(PetscObject,PetscInt);
1279: EXTERN PetscErrorCode PetscObjectGetTabLevel(PetscObject,PetscInt*);
1280: EXTERN PetscErrorCode PetscObjectIncrementTabLevel(PetscObject,PetscObject,PetscInt);
1281: EXTERN PetscErrorCode PetscObjectReference(PetscObject);
1282: EXTERN PetscErrorCode PetscObjectGetReference(PetscObject,PetscInt*);
1283: EXTERN PetscErrorCode PetscObjectDereference(PetscObject);
1284: EXTERN PetscErrorCode PetscObjectGetNewTag(PetscObject,PetscMPIInt *);
1285: EXTERN PetscErrorCode PetscObjectView(PetscObject,PetscViewer);
1286: EXTERN PetscErrorCode PetscObjectCompose(PetscObject,const char[],PetscObject);
1287: EXTERN PetscErrorCode PetscObjectQuery(PetscObject,const char[],PetscObject *);
1288: EXTERN PetscErrorCode PetscObjectComposeFunction(PetscObject,const char[],const char[],void (*)(void));
1289: EXTERN PetscErrorCode PetscObjectSetFromOptions(PetscObject);
1290: EXTERN PetscErrorCode PetscObjectSetUp(PetscObject);
1291: EXTERN PetscErrorCode PetscCommGetNewTag(MPI_Comm,PetscMPIInt *);
1293: /*MC
1294: PetscObjectComposeFunctionDynamic - Associates a function with a given PETSc object.
1295:
1296: Collective on PetscObject
1298: Input Parameters:
1299: + obj - the PETSc object; this must be cast with a (PetscObject), for example,
1300: PetscObjectCompose((PetscObject)mat,...);
1301: . name - name associated with the child function
1302: . fname - name of the function
1303: - ptr - function pointer (or PETSC_NULL if using dynamic libraries)
1305: Level: advanced
1307: Synopsis:
1308: PetscErrorCode PetscObjectComposeFunctionDynamic(PetscObject obj,const char name[],const char fname[],void *ptr)
1310: Notes:
1311: To remove a registered routine, pass in a PETSC_NULL rname and fnc().
1313: PetscObjectComposeFunctionDynamic() can be used with any PETSc object (such as
1314: Mat, Vec, KSP, SNES, etc.) or any user-provided object.
1317: work in C++/complex with dynamic link libraries (config/configure.py options --with-shared --with-dynamic)
1318: enabled.
1320: Concepts: objects^composing functions
1321: Concepts: composing functions
1322: Concepts: functions^querying
1323: Concepts: objects^querying
1324: Concepts: querying objects
1326: .seealso: PetscObjectQueryFunction()
1327: M*/
1328: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
1329: #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,0)
1330: #else
1331: #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,(PetscVoidFunction)(d))
1332: #endif
1334: EXTERN PetscErrorCode PetscObjectQueryFunction(PetscObject,const char[],void (**)(void));
1335: EXTERN PetscErrorCode PetscObjectSetOptionsPrefix(PetscObject,const char[]);
1336: EXTERN PetscErrorCode PetscObjectAppendOptionsPrefix(PetscObject,const char[]);
1337: EXTERN PetscErrorCode PetscObjectPrependOptionsPrefix(PetscObject,const char[]);
1338: EXTERN PetscErrorCode PetscObjectGetOptionsPrefix(PetscObject,const char*[]);
1339: EXTERN PetscErrorCode PetscObjectPublish(PetscObject);
1340: EXTERN PetscErrorCode PetscObjectChangeTypeName(PetscObject,const char[]);
1341: EXTERN PetscErrorCode PetscObjectRegisterDestroy(PetscObject);
1342: EXTERN PetscErrorCode PetscObjectRegisterDestroyAll(void);
1343: EXTERN PetscErrorCode PetscObjectName(PetscObject);
1344: EXTERN PetscErrorCode PetscTypeCompare(PetscObject,const char[],PetscTruth*);
1345: EXTERN PetscErrorCode PetscRegisterFinalize(PetscErrorCode (*)(void));
1346: EXTERN PetscErrorCode PetscRegisterFinalizeAll(void);
1348: /*
1349: Defines PETSc error handling.
1350: */
1351: #include petscerror.h
1353: /*S
1354: PetscOList - Linked list of PETSc objects, accessable by string name
1356: Level: advanced
1358: .seealso: PetscOListAdd(), PetscOListDestroy(), PetscOListFind()
1359: S*/
1360: typedef struct _n_PetscOList *PetscOList;
1362: EXTERN PetscErrorCode PetscOListDestroy(PetscOList);
1363: EXTERN PetscErrorCode PetscOListFind(PetscOList,const char[],PetscObject*);
1364: EXTERN PetscErrorCode PetscOListReverseFind(PetscOList,PetscObject,char**);
1365: EXTERN PetscErrorCode PetscOListAdd(PetscOList *,const char[],PetscObject);
1366: EXTERN PetscErrorCode PetscOListDuplicate(PetscOList,PetscOList *);
1368: /*
1369: Dynamic library lists. Lists of names of routines in dynamic
1370: link libraries that will be loaded as needed.
1371: */
1372: EXTERN PetscErrorCode PetscFListAdd(PetscFList*,const char[],const char[],void (*)(void));
1373: EXTERN PetscErrorCode PetscFListDestroy(PetscFList*);
1374: EXTERN PetscErrorCode PetscFListFind(PetscFList,MPI_Comm,const char[],void (**)(void));
1375: EXTERN PetscErrorCode PetscFListPrintTypes(PetscFList,MPI_Comm,FILE*,const char[],const char[],const char[],const char[]);
1376: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
1377: #define PetscFListAddDynamic(a,b,p,c) PetscFListAdd(a,b,p,0)
1378: #else
1379: #define PetscFListAddDynamic(a,b,p,c) PetscFListAdd(a,b,p,(void (*)(void))c)
1380: #endif
1381: EXTERN PetscErrorCode PetscFListDuplicate(PetscFList,PetscFList *);
1382: EXTERN PetscErrorCode PetscFListView(PetscFList,PetscViewer);
1383: EXTERN PetscErrorCode PetscFListConcat(const char [],const char [],char []);
1384: EXTERN PetscErrorCode PetscFListGet(PetscFList,char ***,int*);
1386: /*S
1387: PetscDLLibrary - Linked list of dynamics libraries to search for functions
1389: Level: advanced
1391: --with-shared --with-dynamic must be used with config/configure.py to use dynamic libraries
1393: .seealso: PetscDLLibraryOpen()
1394: S*/
1395: typedef struct _n_PetscDLLibrary *PetscDLLibrary;
1397: EXTERN PetscErrorCode PetscDLLibraryAppend(MPI_Comm,PetscDLLibrary *,const char[]);
1398: EXTERN PetscErrorCode PetscDLLibraryPrepend(MPI_Comm,PetscDLLibrary *,const char[]);
1399: EXTERN PetscErrorCode PetscDLLibrarySym(MPI_Comm,PetscDLLibrary *,const char[],const char[],void **);
1400: EXTERN PetscErrorCode PetscDLLibraryPrintPath(PetscDLLibrary);
1401: EXTERN PetscErrorCode PetscDLLibraryRetrieve(MPI_Comm,const char[],char *,size_t,PetscTruth *);
1402: EXTERN PetscErrorCode PetscDLLibraryOpen(MPI_Comm,const char[],PetscDLLibrary *);
1403: EXTERN PetscErrorCode PetscDLLibraryClose(PetscDLLibrary);
1404: EXTERN PetscErrorCode PetscDLLibraryCCAAppend(MPI_Comm,PetscDLLibrary *,const char[]);
1406: /*
1407: Useful utility routines
1408: */
1409: EXTERN PetscErrorCode PetscSplitOwnership(MPI_Comm,PetscInt*,PetscInt*);
1410: EXTERN PetscErrorCode PetscSplitOwnershipBlock(MPI_Comm,PetscInt,PetscInt*,PetscInt*);
1411: EXTERN PetscErrorCode PetscSequentialPhaseBegin(MPI_Comm,PetscMPIInt);
1412: PetscPolymorphicSubroutine(PetscSequentialPhaseBegin,(MPI_Comm comm),(comm,1))
1413: PetscPolymorphicSubroutine(PetscSequentialPhaseBegin,(void),(PETSC_COMM_WORLD,1))
1414: EXTERN PetscErrorCode PetscSequentialPhaseEnd(MPI_Comm,PetscMPIInt);
1415: PetscPolymorphicSubroutine(PetscSequentialPhaseEnd,(MPI_Comm comm),(comm,1))
1416: PetscPolymorphicSubroutine(PetscSequentialPhaseEnd,(void),(PETSC_COMM_WORLD,1))
1417: EXTERN PetscErrorCode PetscBarrier(PetscObject);
1418: EXTERN PetscErrorCode PetscMPIDump(FILE*);
1420: #define PetscNot(a) ((a) ? PETSC_FALSE : PETSC_TRUE)
1421: /*
1422: Defines basic graphics available from PETSc.
1423: */
1424: #include petscdraw.h
1426: /*
1427: Defines the base data structures for all PETSc objects
1428: */
1429: #include private/petscimpl.h
1430: /*
1431: Defines PETSc profiling.
1432: */
1433: #include petsclog.h
1435: /*
1436: For locking, unlocking and destroying AMS memories associated with
1437: PETSc objects. Not currently used.
1438: */
1439: #define PetscPublishAll(v) 0
1440: #define PetscObjectTakeAccess(obj) 0
1441: #define PetscObjectGrantAccess(obj) 0
1442: #define PetscObjectDepublish(obj) 0
1444: /*
1445: Simple PETSc parallel IO for ASCII printing
1446: */
1447: EXTERN PetscErrorCode PetscFixFilename(const char[],char[]);
1448: EXTERN PetscErrorCode PetscFOpen(MPI_Comm,const char[],const char[],FILE**);
1449: EXTERN PetscErrorCode PetscFClose(MPI_Comm,FILE*);
1450: EXTERN PetscErrorCode PetscFPrintf(MPI_Comm,FILE*,const char[],...) PETSC_PRINTF_FORMAT_CHECK(3,4);
1451: EXTERN PetscErrorCode PetscPrintf(MPI_Comm,const char[],...) PETSC_PRINTF_FORMAT_CHECK(2,3);
1452: EXTERN PetscErrorCode PetscSNPrintf(char*,size_t,const char [],...);
1454: /* These are used internally by PETSc ASCII IO routines*/
1455: #include <stdarg.h>
1456: EXTERN PetscErrorCode PetscVSNPrintf(char*,size_t,const char[],int*,va_list);
1457: EXTERN PetscErrorCode (*PetscVFPrintf)(FILE*,const char[],va_list);
1458: EXTERN PetscErrorCode PetscVFPrintfDefault(FILE*,const char[],va_list);
1460: /*MC
1461: PetscErrorPrintf - Prints error messages.
1463: Not Collective
1465: Synopsis:
1466: PetscErrorCode (*PetscErrorPrintf)(const char format[],...);
1468: Input Parameters:
1469: . format - the usual printf() format string
1471: Options Database Keys:
1472: + -error_output_stdout - cause error messages to be printed to stdout instead of the
1473: (default) stderr
1474: - -error_output_none to turn off all printing of error messages (does not change the way the
1475: error is handled.)
1477: Notes: Use
1478: $ PetscErrorPrintf = PetscErrorPrintfNone; to turn off all printing of error messages (does not change the way the
1479: $ error is handled.) and
1480: $ PetscErrorPrintf = PetscErrorPrintfDefault; to turn it back on
1482: Use
1483: PETSC_STDERR = FILE* obtained from a file open etc. to have stderr printed to the file.
1484: PETSC_STDOUT = FILE* obtained from a file open etc. to have stdout printed to the file.
1486: Use
1487: PetscPushErrorHandler() to provide your own error handler that determines what kind of messages to print
1489: Level: developer
1491: Fortran Note:
1492: This routine is not supported in Fortran.
1494: Concepts: error messages^printing
1495: Concepts: printing^error messages
1497: .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscHelpPrintf(), PetscPrintf(), PetscErrorHandlerPush()
1498: M*/
1499: EXTERN PetscErrorCode (*PetscErrorPrintf)(const char[],...);
1501: /*MC
1502: PetscHelpPrintf - Prints help messages.
1504: Not Collective
1506: Synopsis:
1507: PetscErrorCode (*PetscHelpPrintf)(const char format[],...);
1509: Input Parameters:
1510: . format - the usual printf() format string
1512: Level: developer
1514: Fortran Note:
1515: This routine is not supported in Fortran.
1517: Concepts: help messages^printing
1518: Concepts: printing^help messages
1520: .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscErrorPrintf()
1521: M*/
1522: EXTERN PetscErrorCode (*PetscHelpPrintf)(MPI_Comm,const char[],...);
1524: EXTERN PetscErrorCode PetscErrorPrintfDefault(const char [],...);
1525: EXTERN PetscErrorCode PetscErrorPrintfNone(const char [],...);
1526: EXTERN PetscErrorCode PetscHelpPrintfDefault(MPI_Comm,const char [],...);
1528: #if defined(PETSC_HAVE_POPEN)
1529: EXTERN PetscErrorCode PetscPOpen(MPI_Comm,const char[],const char[],const char[],FILE **);
1530: EXTERN PetscErrorCode PetscPClose(MPI_Comm,FILE*);
1531: #endif
1533: EXTERN PetscErrorCode PetscSynchronizedPrintf(MPI_Comm,const char[],...) PETSC_PRINTF_FORMAT_CHECK(2,3);
1534: EXTERN PetscErrorCode PetscSynchronizedFPrintf(MPI_Comm,FILE*,const char[],...) PETSC_PRINTF_FORMAT_CHECK(3,4);
1535: EXTERN PetscErrorCode PetscSynchronizedFlush(MPI_Comm);
1536: EXTERN PetscErrorCode PetscSynchronizedFGets(MPI_Comm,FILE*,size_t,char[]);
1537: EXTERN PetscErrorCode PetscStartMatlab(MPI_Comm,const char[],const char[],FILE**);
1538: EXTERN PetscErrorCode PetscStartJava(MPI_Comm,const char[],const char[],FILE**);
1539: EXTERN PetscErrorCode PetscGetPetscDir(const char*[]);
1541: EXTERN PetscErrorCode PetscPopUpSelect(MPI_Comm,const char*,const char*,int,const char**,int*);
1543: /*S
1544: PetscContainer - Simple PETSc object that contains a pointer to any required data
1546: Level: advanced
1548: .seealso: PetscObject, PetscContainerCreate()
1549: S*/
1551: typedef struct _p_PetscContainer* PetscContainer;
1552: EXTERN PetscErrorCode PetscContainerGetPointer(PetscContainer,void **);
1553: EXTERN PetscErrorCode PetscContainerSetPointer(PetscContainer,void *);
1554: EXTERN PetscErrorCode PetscContainerDestroy(PetscContainer);
1555: EXTERN PetscErrorCode PetscContainerCreate(MPI_Comm,PetscContainer *);
1556: EXTERN PetscErrorCode PetscContainerSetUserDestroy(PetscContainer, PetscErrorCode (*)(void*));
1558: /*
1559: For use in debuggers
1560: */
1564: EXTERN PetscErrorCode PetscIntView(PetscInt,PetscInt[],PetscViewer);
1565: EXTERN PetscErrorCode PetscRealView(PetscInt,PetscReal[],PetscViewer);
1566: EXTERN PetscErrorCode PetscScalarView(PetscInt,PetscScalar[],PetscViewer);
1568: /*
1569: Allows accessing Matlab Engine
1570: */
1571: #include petscmatlab.h
1573: /*
1574: Determine if some of the kernel computation routines use
1575: Fortran (rather than C) for the numerical calculations. On some machines
1576: and compilers (like complex numbers) the Fortran version of the routines
1577: is faster than the C/C++ versions. The flag --with-fortran-kernels
1578: should be used with config/configure.py to turn these on.
1579: */
1580: #if defined(PETSC_USE_FORTRAN_KERNELS)
1582: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTCRL)
1583: #define PETSC_USE_FORTRAN_KERNEL_MULTCRL
1584: #endif
1586: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTCSRPERM)
1587: #define PETSC_USE_FORTRAN_KERNEL_MULTCSRPERM
1588: #endif
1590: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTAIJ)
1591: #define PETSC_USE_FORTRAN_KERNEL_MULTAIJ
1592: #endif
1594: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTTRANSPOSEAIJ)
1595: #define PETSC_USE_FORTRAN_KERNEL_MULTTRANSPOSEAIJ
1596: #endif
1598: #if !defined(PETSC_USE_FORTRAN_KERNEL_NORM)
1599: #define PETSC_USE_FORTRAN_KERNEL_NORM
1600: #endif
1602: #if !defined(PETSC_USE_FORTRAN_KERNEL_MAXPY)
1603: #define PETSC_USE_FORTRAN_KERNEL_MAXPY
1604: #endif
1606: #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ)
1607: #define PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ
1608: #endif
1610: #if !defined(PETSC_USE_FORTRAN_KERNEL_RELAXAIJ)
1611: #define PETSC_USE_FORTRAN_KERNEL_RELAXAIJ
1612: #endif
1614: #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ)
1615: #define PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ
1616: #endif
1618: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ)
1619: #define PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ
1620: #endif
1622: #if !defined(PETSC_USE_FORTRAN_KERNEL_MDOT)
1623: #define PETSC_USE_FORTRAN_KERNEL_MDOT
1624: #endif
1626: #if !defined(PETSC_USE_FORTRAN_KERNEL_XTIMESY)
1627: #define PETSC_USE_FORTRAN_KERNEL_XTIMESY
1628: #endif
1630: #if !defined(PETSC_USE_FORTRAN_KERNEL_AYPX)
1631: #define PETSC_USE_FORTRAN_KERNEL_AYPX
1632: #endif
1634: #if !defined(PETSC_USE_FORTRAN_KERNEL_WAXPY)
1635: #define PETSC_USE_FORTRAN_KERNEL_WAXPY
1636: #endif
1638: #endif
1640: /*
1641: Macros for indicating code that should be compiled with a C interface,
1642: rather than a C++ interface. Any routines that are dynamically loaded
1643: (such as the PCCreate_XXX() routines) must be wrapped so that the name
1644: mangler does not change the functions symbol name. This just hides the
1646: */
1647: #if defined(__cplusplus)
1650: #else
1653: #endif
1655: /* --------------------------------------------------------------------*/
1657: /*MC
1658: size - integer variable used to contain the number of processors in
1659: the relevent MPI_Comm
1661: Level: beginner
1663: .seealso: rank, comm
1664: M*/
1666: /*MC
1667: rank - integer variable used to contain the number of this processor relative
1668: to all in the relevent MPI_Comm
1670: Level: beginner
1672: .seealso: size, comm
1673: M*/
1675: /*MC
1676: comm - MPI_Comm used in the current routine or object
1678: Level: beginner
1680: .seealso: size, rank
1681: M*/
1683: /*MC
1684: MPI_Comm - the basic object used by MPI to determine which processes are involved in a
1685: communication
1687: Level: beginner
1689: Note: This manual page is a place-holder because MPICH does not have a manual page for MPI_Comm
1691: .seealso: size, rank, comm, PETSC_COMM_WORLD, PETSC_COMM_SELF
1692: M*/
1694: /*MC
1695: PetscScalar - PETSc type that represents either a double precision real number, a double precision
1696: complex number, a single precision real number, a long double or an int - if the code is configured
1697: with --with-scalar-type=real,complex --with-precision=single,double,longdouble,int,matsingle
1700: Level: beginner
1702: .seealso: PetscReal, PassiveReal, PassiveScalar, MPIU_SCALAR, PetscInt
1703: M*/
1705: /*MC
1706: PetscReal - PETSc type that represents a real number version of PetscScalar
1708: Level: beginner
1710: .seealso: PetscScalar, PassiveReal, PassiveScalar
1711: M*/
1713: /*MC
1714: PassiveScalar - PETSc type that represents a PetscScalar
1715: Level: beginner
1717: This is the same as a PetscScalar except in code that is automatically differentiated it is
1718: treated as a constant (not an indendent or dependent variable)
1720: .seealso: PetscReal, PassiveReal, PetscScalar
1721: M*/
1723: /*MC
1724: PassiveReal - PETSc type that represents a PetscReal
1726: Level: beginner
1728: This is the same as a PetscReal except in code that is automatically differentiated it is
1729: treated as a constant (not an indendent or dependent variable)
1731: .seealso: PetscScalar, PetscReal, PassiveScalar
1732: M*/
1734: /*MC
1735: MPIU_SCALAR - MPI datatype corresponding to PetscScalar
1737: Level: beginner
1739: Note: In MPI calls that require an MPI datatype that matches a PetscScalar or array of PetscScalars
1740: pass this value
1742: .seealso: PetscReal, PassiveReal, PassiveScalar, PetscScalar, MPIU_INT
1743: M*/
1745: #if defined(PETSC_HAVE_MPIIO)
1746: #if !defined(PETSC_WORDS_BIGENDIAN)
1749: #else
1750: #define MPIU_File_write_all(a,b,c,d,e) MPI_File_write_all(a,b,c,d,e)
1751: #define MPIU_File_read_all(a,b,c,d,e) MPI_File_read_all(a,b,c,d,e)
1752: #endif
1753: #endif
1755: /* the following petsc_static_inline require petscerror.h */
1757: /* Limit MPI to 32-bits */
1758: #define PETSC_MPI_INT_MAX 2147483647
1759: #define PETSC_MPI_INT_MIN -2147483647
1760: /* Limit BLAS to 32-bits */
1761: #define PETSC_BLAS_INT_MAX 2147483647
1762: #define PETSC_BLAS_INT_MIN -2147483647
1764: #if defined(PETSC_USE_64BIT_INDICES)
1765: #define PetscMPIIntCheck(a) if ((a) > PETSC_MPI_INT_MAX) SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Message too long for MPI")
1766: #define PetscBLASIntCheck(a) if ((a) > PETSC_BLAS_INT_MAX) SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Array too long for BLAS/LAPACK")
1767: #define PetscMPIIntCast(a) (a);PetscMPIIntCheck(a)
1768: #define PetscBLASIntCast(a) (a);PetscBLASIntCheck(a)
1769: #else
1770: #define PetscMPIIntCheck(a)
1771: #define PetscBLASIntCheck(a)
1772: #define PetscMPIIntCast(a) a
1773: #define PetscBLASIntCast(a) a
1774: #endif
1777: /*
1778: The IBM include files define hz, here we hide it so that it may be used
1779: as a regular user variable.
1780: */
1781: #if defined(hz)
1782: #undef hz
1783: #endif
1785: /* For arrays that contain filenames or paths */
1788: #if defined(PETSC_HAVE_LIMITS_H)
1789: #include <limits.h>
1790: #endif
1791: #if defined(PETSC_HAVE_SYS_PARAM_H)
1792: #include <sys/param.h>
1793: #endif
1794: #if defined(PETSC_HAVE_SYS_TYPES_H)
1795: #include <sys/types.h>
1796: #endif
1797: #if defined(MAXPATHLEN)
1798: # define PETSC_MAX_PATH_LEN MAXPATHLEN
1799: #elif defined(MAX_PATH)
1800: # define PETSC_MAX_PATH_LEN MAX_PATH
1801: #elif defined(_MAX_PATH)
1802: # define PETSC_MAX_PATH_LEN _MAX_PATH
1803: #else
1804: # define PETSC_MAX_PATH_LEN 4096
1805: #endif
1807: /* Special support for C++ */
1808: #include petsc.hh
1810: /*MC
1812: UsingFortran - Fortran can be used with PETSc in four distinct approaches
1814: $ 1) classic Fortran 77 style
1815: $#include "petscXXX.h" to work with material from the XXX component of PETSc
1816: $ XXX variablename
1817: $ You cannot use this approach if you wish to use the Fortran 90 specific PETSc routines
1818: $ which end in F90; such as VecGetArrayF90()
1819: $
1820: $ 2) classic Fortran 90 style
1821: $#include "petscXXX.h"
1822: $#include "petscXXX.h90" to work with material from the XXX component of PETSc
1823: $ XXX variablename
1824: $
1825: $ 3) Using Fortran modules
1826: $#include "petscXXXdef.h"
1827: $ use petscXXXX
1828: $ XXX variablename
1829: $
1830: $ 4) Use Fortran modules and Fortran data types for PETSc types
1831: $#include "petscXXXdef.h"
1832: $ use petscXXXX
1833: $ type(XXX) variablename
1834: $ To use this approach you must config/configure.py PETSc with the additional
1835: $ option --with-fortran-datatypes You cannot use the type(XXX) declaration approach without using Fortran modules
1837: Finally if you absolutely do not want to use any #include you can use either
1839: $ 3a) skip the #include BUT you cannot use any PETSc data type names like Vec, Mat, PetscInt, PetscErrorCode etc
1840: $ and you must declare the variables as integer, for example
1841: $ integer variablename
1842: $
1843: $ 4a) skip the #include, you use the object types like type(Vec) type(Mat) but cannot use the data type
1844: $ names like PetscErrorCode, PetscInt etc. again for those you must use integer
1846: We recommend either 2 or 3. Approaches 2 and 3 provide type checking for most PETSc function calls; 4 has type checking
1847: for only a few PETSc functions.
1849: Fortran type checking with interfaces is strick, this means you cannot pass a scalar value when an array value
1850: is expected (even though it is legal Fortran). For example when setting a single value in a matrix with MatSetValues()
1851: you cannot have something like
1852: $ PetscInt row,col
1853: $ PetscScalar val
1854: $ ...
1855: $ call MatSetValues(mat,1,row,1,col,val,INSERT_VALUES,ierr)
1856: You must instead have
1857: $ PetscInt row(1),col(1)
1858: $ PetscScalar val(1)
1859: $ ...
1860: $ call MatSetValues(mat,1,row,1,col,val,INSERT_VALUES,ierr)
1863: See the example src/vec/vec/examples/tutorials/ex20f90.F90 for an example that can use all four approaches
1865: Developer Notes: The finclude/petscXXXdef.h contain all the #defines (would be typedefs in C code) these
1866: automatically include their predecessors; for example finclude/petscvecdef.h includes finclude/petscisdef.h
1868: The finclude/petscXXXX.h contain all the parameter statements for that package. These automatically include
1869: their finclude/petscXXXdef.h file but DO NOT automatically include their predecessors; for example
1870: finclude/petscvec.h does NOT automatically include finclude/petscis.h
1872: The finclude/ftn-custom/petscXXXdef.h90 are not intended to be used directly in code, they define the
1873: Fortran data type type(XXX) (for example type(Vec)) when PETSc is config/configure.py with the --with-fortran-datatypes option.
1875: The finclude/ftn-custom/petscXXX.h90 (not included directly by code) contain interface definitions for
1876: the PETSc Fortran stubs that have different bindings then their C version (for example VecGetArrayF90).
1878: The finclude/ftn-auto/petscXXX.h90 (not included directly by code) contain interface definitions generated
1879: automatically by "make allfortranstubs".
1881: The finclude/petscXXX.h90 includes the custom finclude/ftn-custom/petscXXX.h90 and if config/configure.py
1882: was run with --with-fortran-interfaces it also includes the finclude/ftn-auto/petscXXX.h90 These DO NOT automatically
1883: include their predecessors
1885: Level: beginner
1887: M*/
1889: #endif