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 bmake/${PETSC_ARCH}/petscconf.h it is 
 10:    found automatically by the compiler due to the -I${PETSC_DIR}/bmake/${PETSC_ARCH}
 11:    in the bmake/common_variables definition of PETSC_INCLUDE
 12: */
 13: #include "petscconf.h"

 15: /* ========================================================================== */
 16: /* 
 17:    This facilitates using C version of PETSc from C++
 18: */

 23: #else
 26: #endif
 27: /* ========================================================================== */
 28: /* 
 29:    Current PETSc version number and release date
 30: */
 31:  #include petscversion.h

 33: /*
 34:    Currently cannot check formatting for PETSc print statements because we have our
 35:    own format %D
 36: */
 37: #undef  PETSC_PRINTF_FORMAT_CHECK
 38: #define PETSC_PRINTF_FORMAT_CHECK(a,b)
 39: #undef  PETSC_FPRINTF_FORMAT_CHECK
 40: #define PETSC_FPRINTF_FORMAT_CHECK(a,b)

 42: /*
 43:    Fixes for configure time choices which impact our interface. Currently only
 44:    calling conventions and extra compiler checking falls under this category.
 45: */
 46: #if !defined(PETSC_STDCALL)
 47: #define PETSC_STDCALL
 48: #endif
 49: #if !defined(PETSC_TEMPLATE)
 50: #define PETSC_TEMPLATE
 51: #endif
 52: #if !defined(PETSC_HAVE_DLL_EXPORT)
 53: #define PETSC_DLL_EXPORT
 54: #define PETSC_DLL_IMPORT
 55: #endif
 56: #if !defined(PETSC_DLLEXPORT)
 57: #define PETSC_DLLEXPORT
 58: #endif
 59: #if !defined(PETSCVEC_DLLEXPORT)
 60: #define PETSCVEC_DLLEXPORT
 61: #endif
 62: #if !defined(PETSCMAT_DLLEXPORT)
 63: #define PETSCMAT_DLLEXPORT
 64: #endif
 65: #if !defined(PETSCDM_DLLEXPORT)
 66: #define PETSCDM_DLLEXPORT
 67: #endif
 68: #if !defined(PETSCKSP_DLLEXPORT)
 69: #define PETSCKSP_DLLEXPORT
 70: #endif
 71: #if !defined(PETSCSNES_DLLEXPORT)
 72: #define PETSCSNES_DLLEXPORT
 73: #endif
 74: #if !defined(PETSCTS_DLLEXPORT)
 75: #define PETSCTS_DLLEXPORT
 76: #endif
 77: #if !defined(PETSCFORTRAN_DLLEXPORT)
 78: #define PETSCFORTRAN_DLLEXPORT
 79: #endif
 80: /* ========================================================================== */

 82: /*
 83:     Defines the interface to MPI allowing the use of all MPI functions.
 84: */
 85: #include "mpi.h"
 86: /*
 87:     Yuck, we need to put stdio.h AFTER mpi.h for MPICH2 with C++ compiler 
 88:     see the top of mpicxx.h

 90:     The MPI STANDARD HAS TO BE CHANGED to prevent this nonsense.
 91: */
 92: #include <stdio.h>

 94: /*
 95:     All PETSc C functions return this error code, it is the final argument of
 96:    all Fortran subroutines
 97: */
 98: typedef int PetscErrorCode;
 99: typedef int PetscCookie;
100: typedef int PetscEvent;
101: typedef int PetscBLASInt;
102: typedef int PetscMPIInt;
103: typedef enum { ENUM_DUMMY } PetscEnum;
104: #if defined(PETSC_USE_64BIT_INT)
105: typedef long long PetscInt;
106: #define MPIU_INT MPI_LONG_LONG_INT
107: #else
108: typedef int PetscInt;
109: #define MPIU_INT MPI_INT
110: #endif  

113: /*MC
114:       PetscPolymorphicSubroutine - allows defining a C++ polymorphic version of 
115:             a PETSc function that remove certain optional arguments for a simplier user interface

117:      Not collective

119:    Synopsis:
120:    PetscPolymorphicSubroutine(Functionname,(arguments of C++ function),(arguments of C function))
121:  
122:    Level: developer

124:     Example:
125:       PetscPolymorphicSubroutine(VecNorm,(Vec x,PetscReal *r),(x,NORM_2,r)) generates the new routine
126:            PetscErrorCode VecNorm(Vec x,PetscReal *r) = VecNorm(x,NORM_2,r)

128: .seealso: PetscPolymorphicFunction()

130: M*/
131: #define PetscPolymorphicSubroutine(A,B,C) PETSC_STATIC_INLINE PetscErrorCode A B {return A C;}

133: /*MC
134:       PetscPolymorphicScalar - allows defining a C++ polymorphic version of 
135:             a PETSc function that replaces a PetscScalar * argument with a PetscScalar argument

137:      Not collective

139:    Synopsis:
140:    PetscPolymorphicScalar(Functionname,(arguments of C++ function),(arguments of C function))
141:  
142:    Level: developer

144:     Example:
145:       PetscPolymorphicScalar(VecAXPY,(PetscScalar _t,Vec x,Vec y),(&_T,x,y)) generates the new routine
146:            PetscErrorCode VecAXPY(PetscScalar _t,Vec x,Vec y) = {PetscScalar _T = _t; return VecAXPY(&_T,x,y);}

148: .seealso: PetscPolymorphicFunction(),PetscPolymorphicSubroutine()

150: M*/
151: #define PetscPolymorphicScalar(A,B,C) PETSC_STATIC_INLINE PetscErrorCode A B {PetscScalar _T = _t; return A C;}

153: /*MC
154:       PetscPolymorphicFunction - allows defining a C++ polymorphic version of 
155:             a PETSc function that remove certain optional arguments for a simplier user interface
156:             and returns the computed value (istead of an error code)

158:      Not collective

160:    Synopsis:
161:    PetscPolymorphicFunction(Functionname,(arguments of C++ function),(arguments of C function),return type,return variable name)
162:  
163:    Level: developer

165:     Example:
166:       PetscPolymorphicFunction(VecNorm,(Vec x,NormType t),(x,t,&r),PetscReal,r) generates the new routine
167:          PetscReal VecNorm(Vec x,NormType t) = {PetscReal r; VecNorm(x,t,&r); return r;}

169: .seealso: PetscPolymorphicSubroutine()

171: M*/
172: #define PetscPolymorphicFunction(A,B,C,D,E) PETSC_STATIC_INLINE D A B {D E; A C;return E;}

174: #else
175: #define PetscPolymorphicSubroutine(A,B,C)
176: #define PetscPolymorphicScalar(A,B,C)
177: #define PetscPolymorphicFunction(A,B,C,D,E)
178: #endif

180: /*
181:     Extern indicates a PETSc function defined elsewhere
182: */
183: #if !defined(EXTERN)
184: #define EXTERN extern
185: #endif

187: /*
188:     Defines some elementary mathematics functions and constants.
189: */
190:  #include petscmath.h

192: /*
194: */


198: /*
199:        Basic PETSc constants
200: */

202: /*E
203:     PetscTruth - Logical variable. Actually an integer

205:    Level: beginner

207: E*/
208: typedef enum { PETSC_FALSE,PETSC_TRUE } PetscTruth;

211: /*M
212:     PETSC_FALSE - False value of PetscTruth

214:     Level: beginner

216:     Note: Zero integer

218: .seealso: PetscTruth
219: M*/

221: /*M
222:     PETSC_TRUE - True value of PetscTruth

224:     Level: beginner

226:     Note: Nonzero integer

228: .seealso: PetscTruth
229: M*/

231: /*M
232:     PETSC_YES - Alias for PETSC_TRUE

234:     Level: beginner

236:     Note: Zero integer

238: .seealso: PetscTruth
239: M*/
240: #define PETSC_YES            PETSC_TRUE

242: /*M
243:     PETSC_NO - Alias for PETSC_FALSE

245:     Level: beginner

247:     Note: Nonzero integer

249: .seealso: PetscTruth
250: M*/
251: #define PETSC_NO             PETSC_FALSE

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

256:    Level: beginner

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

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

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

266: M*/
267: #define PETSC_NULL           0

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

273:    Level: beginner

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

277: M*/
278: #define PETSC_DECIDE         -1

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

284:    Level: beginner

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

288: M*/
289: #define PETSC_DEFAULT        -2


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

295:    Level: beginner

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

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

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

305: M*/
306: #define PETSC_IGNORE         PETSC_NULL

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

312:    Level: beginner

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

316: M*/
317: #define PETSC_DETERMINE      PETSC_DECIDE

319: /*M
320:     PETSC_COMM_WORLD - the equivalent of the MPI_COMM_WORLD communicator which represents
321:            all the processs that PETSc knows about. 

323:    Level: beginner

325:    Notes: By default PETSC_COMM_WORLD and MPI_COMM_WORLD are identical unless you wish to 
326:           run PETSc on ONLY a subset of MPI_COMM_WORLD. In that case create your new (smaller)
327:           communicator, call it, say comm, and set PETSC_COMM_WORLD = comm BEFORE calling
328:           PetscInitialize()

330: .seealso: PETSC_COMM_SELF

332: M*/

335: /*M
336:     PETSC_COMM_SELF - a duplicate of the MPI_COMM_SELF communicator which represents
337:            the current process

339:    Level: beginner

341:    Notes: PETSC_COMM_SELF and MPI_COMM_SELF are equivalent.

343: .seealso: PETSC_COMM_WORLD

345: M*/
346: #define PETSC_COMM_SELF MPI_COMM_SELF


351: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscSetHelpVersionFunctions(PetscErrorCode (*)(MPI_Comm),PetscErrorCode (*)(MPI_Comm));
352: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscCommDuplicate(MPI_Comm,MPI_Comm*,int*);
353: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscCommDestroy(MPI_Comm*);

355: /*MC
356:    PetscMalloc - Allocates memory

358:    Input Parameter:
359: .  m - number of bytes to allocate

361:    Output Parameter:
362: .  result - memory allocated

364:    Synopsis:
365:    PetscErrorCode PetscMalloc(size_t m,void **result)

367:    Level: beginner

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

371:           If you request memory of zero size it will allocate no space and assign the pointer to 0; PetscFree() will 
372:           properly handle not freeing the null pointer.

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

376:   Concepts: memory allocation

378: M*/
379: #define PetscMalloc(a,b)  ((a != 0) ? (*PetscTrMalloc)((a),__LINE__,__FUNCT__,__FILE__,__SDIR__,(void**)(b)) : (*(b) = 0,0) )

381: /*MC
382:    PetscMalloc2 - Allocates 2 chunks of  memory

384:    Input Parameter:
385: +  m1 - number of elements to allocate in 1st chunk  (may be zero)
386: .  t1 - type of first memory elements 
387: .  m2 - number of elements to allocate in 2nd chunk  (may be zero)
388: -  t2 - type of second memory elements

390:    Output Parameter:
391: +  r1 - memory allocated in first chunk
392: -  r2 - memory allocated in second chunk

394:    Synopsis:
395:    PetscErrorCode PetscMalloc2(size_t m1,type, t1,void **r1,size_t m2,type t2,void **r2)

397:    Level: developer

399:    Notes: Memory of first chunk is always allocated at least double aligned

401: .seealso: PetscFree(), PetscNew(), PetscMalloc()

403:   Concepts: memory allocation

405: M*/
406: #if defined(PETSC_USE_DEBUG)
407: #define PetscMalloc2(m1,t1,r1,m2,t2,r2) (PetscMalloc((m1)*sizeof(t1),r1) || PetscMalloc((m2)*sizeof(t2),r2))
408: #else
409: #define PetscMalloc2(m1,t1,r1,m2,t2,r2) (PetscMalloc((m1)*sizeof(t1)+(m2)*sizeof(t2),r1) || (*(r2) = (t2*)(*(r1)+m1),0))
410: #endif

412: /*MC
413:    PetscMalloc3 - Allocates 3 chunks of  memory

415:    Input Parameter:
416: +  m1 - number of elements to allocate in 1st chunk  (may be zero)
417: .  t1 - type of first memory elements 
418: .  m2 - number of elements to allocate in 2nd chunk  (may be zero)
419: .  t2 - type of second memory elements
420: .  m3 - number of elements to allocate in 3rd chunk  (may be zero)
421: -  t3 - type of third memory elements

423:    Output Parameter:
424: +  r1 - memory allocated in first chunk
425: .  r2 - memory allocated in second chunk
426: -  r3 - memory allocated in third chunk

428:    Synopsis:
429:    PetscErrorCode PetscMalloc3(size_t m1,type, t1,void **r1,size_t m2,type t2,void **r2,size_t m3,type t3,void **r3)

431:    Level: developer

433:    Notes: Memory of first chunk is always allocated at least double aligned

435: .seealso: PetscFree(), PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree3()

437:   Concepts: memory allocation

439: M*/
440: #if defined(PETSC_USE_DEBUG)
441: #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))
442: #else
443: #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))
444: #endif

446: /*MC
447:    PetscMalloc4 - Allocates 4 chunks of  memory

449:    Input Parameter:
450: +  m1 - number of elements to allocate in 1st chunk  (may be zero)
451: .  t1 - type of first memory elements 
452: .  m2 - number of elements to allocate in 2nd chunk  (may be zero)
453: .  t2 - type of second memory elements
454: .  m3 - number of elements to allocate in 3rd chunk  (may be zero)
455: .  t3 - type of third memory elements
456: .  m4 - number of elements to allocate in 4th chunk  (may be zero)
457: -  t4 - type of fourth memory elements

459:    Output Parameter:
460: +  r1 - memory allocated in first chunk
461: .  r2 - memory allocated in second chunk
462: .  r3 - memory allocated in third chunk
463: -  r4 - memory allocated in fourth chunk

465:    Synopsis:
466:    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)

468:    Level: developer

470:    Notes: Memory of first chunk is always allocated at least double aligned

472: .seealso: PetscFree(), PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree3(), PetscFree4()

474:   Concepts: memory allocation

476: M*/
477: #if defined(PETSC_USE_DEBUG)
478: #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))
479: #else
480: #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))
481: #endif

483: /*MC
484:    PetscMalloc5 - Allocates 5 chunks of  memory

486:    Input Parameter:
487: +  m1 - number of elements to allocate in 1st chunk  (may be zero)
488: .  t1 - type of first memory elements 
489: .  m2 - number of elements to allocate in 2nd chunk  (may be zero)
490: .  t2 - type of second memory elements
491: .  m3 - number of elements to allocate in 3rd chunk  (may be zero)
492: .  t3 - type of third memory elements
493: .  m4 - number of elements to allocate in 4th chunk  (may be zero)
494: .  t4 - type of fourth memory elements
495: .  m5 - number of elements to allocate in 5th chunk  (may be zero)
496: -  t5 - type of fifth memory elements

498:    Output Parameter:
499: +  r1 - memory allocated in first chunk
500: .  r2 - memory allocated in second chunk
501: .  r3 - memory allocated in third chunk
502: .  r4 - memory allocated in fourth chunk
503: -  r5 - memory allocated in fifth chunk

505:    Synopsis:
506:    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)

508:    Level: developer

510:    Notes: Memory of first chunk is always allocated at least double aligned

512: .seealso: PetscFree(), PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree3(), PetscFree4(), PetscFree5()

514:   Concepts: memory allocation

516: M*/
517: #if defined(PETSC_USE_DEBUG)
518: #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))
519: #else
520: #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))
521: #endif


524: /*MC
525:    PetscMalloc6 - Allocates 6 chunks of  memory

527:    Input Parameter:
528: +  m1 - number of elements to allocate in 1st chunk  (may be zero)
529: .  t1 - type of first memory elements 
530: .  m2 - number of elements to allocate in 2nd chunk  (may be zero)
531: .  t2 - type of second memory elements
532: .  m3 - number of elements to allocate in 3rd chunk  (may be zero)
533: .  t3 - type of third memory elements
534: .  m4 - number of elements to allocate in 4th chunk  (may be zero)
535: .  t4 - type of fourth memory elements
536: .  m5 - number of elements to allocate in 5th chunk  (may be zero)
537: .  t5 - type of fifth memory elements
538: .  m6 - number of elements to allocate in 6th chunk  (may be zero)
539: -  t6 - type of sixth memory elements

541:    Output Parameter:
542: +  r1 - memory allocated in first chunk
543: .  r2 - memory allocated in second chunk
544: .  r3 - memory allocated in third chunk
545: .  r4 - memory allocated in fourth chunk
546: .  r5 - memory allocated in fifth chunk
547: -  r6 - memory allocated in sixth chunk

549:    Synopsis:
550:    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)

552:    Level: developer

554:    Notes: Memory of first chunk is always allocated at least double aligned

556: .seealso: PetscFree(), PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree3(), PetscFree4(), PetscFree5(), PetscFree6()

558:   Concepts: memory allocation

560: M*/
561: #if defined(PETSC_USE_DEBUG)
562: #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))
563: #else
564: #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))
565: #endif

567: /*MC
568:    PetscMalloc7 - Allocates 7 chunks of  memory

570:    Input Parameter:
571: +  m1 - number of elements to allocate in 1st chunk  (may be zero)
572: .  t1 - type of first memory elements 
573: .  m2 - number of elements to allocate in 2nd chunk  (may be zero)
574: .  t2 - type of second memory elements
575: .  m3 - number of elements to allocate in 3rd chunk  (may be zero)
576: .  t3 - type of third memory elements
577: .  m4 - number of elements to allocate in 4th chunk  (may be zero)
578: .  t4 - type of fourth memory elements
579: .  m5 - number of elements to allocate in 5th chunk  (may be zero)
580: .  t5 - type of fifth memory elements
581: .  m6 - number of elements to allocate in 6th chunk  (may be zero)
582: .  t6 - type of sixth memory elements
583: .  m7 - number of elements to allocate in 7th chunk  (may be zero)
584: -  t7 - type of sixth memory elements

586:    Output Parameter:
587: +  r1 - memory allocated in first chunk
588: .  r2 - memory allocated in second chunk
589: .  r3 - memory allocated in third chunk
590: .  r4 - memory allocated in fourth chunk
591: .  r5 - memory allocated in fifth chunk
592: .  r6 - memory allocated in sixth chunk
593: -  r7 - memory allocated in sixth chunk

595:    Synopsis:
596:    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)

598:    Level: developer

600:    Notes: Memory of first chunk is always allocated at least double aligned

602: .seealso: PetscFree(), PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree3(), PetscFree4(), PetscFree5(), PetscFree6(), PetscFree7()

604:   Concepts: memory allocation

606: M*/
607: #if defined(PETSC_USE_DEBUG)
608: #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))
609: #else
610: #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))
611: #endif

613: /*MC
614:    PetscNew - Allocates memory of a particular type, Zeros the memory!

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

619:    Output Parameter:
620: .  result - memory allocated

622:    Synopsis:
623:    PetscErrorCode PetscNew(struct type,((type *))result)

625:    Level: beginner

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

629:   Concepts: memory allocation

631: M*/
632: #define PetscNew(A,b)        (PetscMalloc(sizeof(A),(b)) || PetscMemzero(*(b),sizeof(A)))

634: /*MC
635:    PetscFree - Frees memory

637:    Input Parameter:
638: .   memory - memory to free

640:    Synopsis:
641:    PetscErrorCode PetscFree(void *memory)

643:    Level: beginner

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

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

649:   Concepts: memory allocation

651: M*/
652: #define PetscFree(a)   ((a) ? ((*PetscTrFree)((a),__LINE__,__FUNCT__,__FILE__,__SDIR__) || ((a = 0),0)) : 0)

654: /*MC
655:    PetscFreeVoid - Frees memory

657:    Input Parameter:
658: .   memory - memory to free

660:    Synopsis:
661:    void PetscFreeVoid(void *memory)

663:    Level: beginner

665:    Notes: This is different from PetscFree() in that no error code is returned

667: .seealso: PetscFree(), PetscNew(), PetscMalloc()

669:   Concepts: memory allocation

671: M*/
672: #define PetscFreeVoid(a) ((*PetscTrFree)((a),__LINE__,__FUNCT__,__FILE__,__SDIR__),(a) = 0)


675: /*MC
676:    PetscFree2 - Frees 2 chunks of memory obtained with PetscMalloc2()

678:    Input Parameter:
679: +   memory1 - memory to free
680: -   memory2 - 2nd memory to free


683:    Synopsis:
684:    PetscErrorCode PetscFree2(void *memory1,void *memory2)

686:    Level: developer

688:    Notes: Memory must have been obtained with PetscMalloc2()

690: .seealso: PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree()

692:   Concepts: memory allocation

694: M*/
695: #if defined(PETSC_USE_DEBUG)
696: #define PetscFree2(m1,m2)   (PetscFree(m2) || PetscFree(m1))
697: #else
698: #define PetscFree2(m1,m2)   (PetscFree(m1))
699: #endif

701: /*MC
702:    PetscFree3 - Frees 3 chunks of memory obtained with PetscMalloc3()

704:    Input Parameter:
705: +   memory1 - memory to free
706: .   memory2 - 2nd memory to free
707: -   memory3 - 3rd memory to free


710:    Synopsis:
711:    PetscErrorCode PetscFree3(void *memory1,void *memory2,void *memory3)

713:    Level: developer

715:    Notes: Memory must have been obtained with PetscMalloc3()

717: .seealso: PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree(), PetscMalloc3()

719:   Concepts: memory allocation

721: M*/
722: #if defined(PETSC_USE_DEBUG)
723: #define PetscFree3(m1,m2,m3)   (PetscFree(m3) || PetscFree(m2) || PetscFree(m1))
724: #else
725: #define PetscFree3(m1,m2,m3)   (PetscFree(m1))
726: #endif

728: /*MC
729:    PetscFree4 - Frees 4 chunks of memory obtained with PetscMalloc4()

731:    Input Parameter:
732: +   m1 - memory to free
733: .   m2 - 2nd memory to free
734: .   m3 - 3rd memory to free
735: -   m4 - 4th memory to free


738:    Synopsis:
739:    PetscErrorCode PetscFree4(void *m1,void *m2,void *m3,void *m4)

741:    Level: developer

743:    Notes: Memory must have been obtained with PetscMalloc4()

745: .seealso: PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree(), PetscMalloc3(), PetscMalloc4()

747:   Concepts: memory allocation

749: M*/
750: #if defined(PETSC_USE_DEBUG)
751: #define PetscFree4(m1,m2,m3,m4)   (PetscFree(m4) || PetscFree(m3) || PetscFree(m2) || PetscFree(m1))
752: #else
753: #define PetscFree4(m1,m2,m3,m4)   (PetscFree(m1))
754: #endif

756: /*MC
757:    PetscFree5 - Frees 5 chunks of memory obtained with PetscMalloc5()

759:    Input Parameter:
760: +   m1 - memory to free
761: .   m2 - 2nd memory to free
762: .   m3 - 3rd memory to free
763: .   m4 - 4th memory to free
764: -   m5 - 5th memory to free


767:    Synopsis:
768:    PetscErrorCode PetscFree5(void *m1,void *m2,void *m3,void *m4,void *m5)

770:    Level: developer

772:    Notes: Memory must have been obtained with PetscMalloc5()

774: .seealso: PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree(), PetscMalloc3(), PetscMalloc4(), PetscMalloc5()

776:   Concepts: memory allocation

778: M*/
779: #if defined(PETSC_USE_DEBUG)
780: #define PetscFree5(m1,m2,m3,m4,m5)   (PetscFree(m5) || PetscFree(m4) || PetscFree(m3) || PetscFree(m2) || PetscFree(m1))
781: #else
782: #define PetscFree5(m1,m2,m3,m4,m5)   (PetscFree(m1))
783: #endif


786: /*MC
787:    PetscFree6 - Frees 6 chunks of memory obtained with PetscMalloc6()

789:    Input Parameter:
790: +   m1 - memory to free
791: .   m2 - 2nd memory to free
792: .   m3 - 3rd memory to free
793: .   m4 - 4th memory to free
794: .   m5 - 5th memory to free
795: -   m6 - 6th memory to free


798:    Synopsis:
799:    PetscErrorCode PetscFree6(void *m1,void *m2,void *m3,void *m4,void *m5,void *m6)

801:    Level: developer

803:    Notes: Memory must have been obtained with PetscMalloc6()

805: .seealso: PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree(), PetscMalloc3(), PetscMalloc4(), PetscMalloc5(), PetscMalloc6()

807:   Concepts: memory allocation

809: M*/
810: #if defined(PETSC_USE_DEBUG)
811: #define PetscFree6(m1,m2,m3,m4,m5,m6)   (PetscFree(m6) || PetscFree(m5) || PetscFree(m4) || PetscFree(m3) || PetscFree(m2) || PetscFree(m1))
812: #else
813: #define PetscFree6(m1,m2,m3,m4,m5,m6)   (PetscFree(m1))
814: #endif

816: /*MC
817:    PetscFree7 - Frees 7 chunks of memory obtained with PetscMalloc7()

819:    Input Parameter:
820: +   m1 - memory to free
821: .   m2 - 2nd memory to free
822: .   m3 - 3rd memory to free
823: .   m4 - 4th memory to free
824: .   m5 - 5th memory to free
825: .   m6 - 6th memory to free
826: -   m7 - 7th memory to free


829:    Synopsis:
830:    PetscErrorCode PetscFree7(void *m1,void *m2,void *m3,void *m4,void *m5,void *m6,void *m7)

832:    Level: developer

834:    Notes: Memory must have been obtained with PetscMalloc6()

836: .seealso: PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree(), PetscMalloc3(), PetscMalloc4(), PetscMalloc5(), PetscMalloc6(),
837:           PetscMalloc7()

839:   Concepts: memory allocation

841: M*/
842: #if defined(PETSC_USE_DEBUG)
843: #define PetscFree7(m1,m2,m3,m4,m5,m6,m7)   (PetscFree(m7) || PetscFree(m6) || PetscFree(m5) || PetscFree(m4) || PetscFree(m3) || PetscFree(m2) || PetscFree(m1))
844: #else
845: #define PetscFree7(m1,m2,m3,m4,m5,m6,m7)   (PetscFree(m1))
846: #endif

848: EXTERN PETSC_DLLEXPORT PetscErrorCode (*PetscTrMalloc)(size_t,int,const char[],const char[],const char[],void**);
849: EXTERN PETSC_DLLEXPORT PetscErrorCode (*PetscTrFree)(void*,int,const char[],const char[],const char[]);
850: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscSetMalloc(PetscErrorCode (*)(size_t,int,const char[],const char[],const char[],void**),PetscErrorCode (*)(void*,int,const char[],const char[],const char[]));
851: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscClearMalloc(void);

853: /*
854:    Routines for tracing memory corruption/bleeding with default PETSc 
855:    memory allocation
856: */
857: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscMallocDump(FILE *);
858: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscMallocDumpLog(FILE *);
859: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscMallocGetCurrentUsage(PetscLogDouble *);
860: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscMallocGetMaximumUsage(PetscLogDouble *);
861: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscMallocDebug(PetscTruth);
862: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscMallocValidate(int,const char[],const char[],const char[]);
863: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscMallocSetDumpLog(void);


866: /*
867:     Variable type where we stash PETSc object pointers in Fortran.
868:     Assumes that sizeof(long) == sizeof(void*)which is true on 
869:     all machines that we know.
870: */
871: #define PetscFortranAddr   long

873: /*E
874:     PetscDataType - Used for handling different basic data types.

876:    Level: beginner

878: .seealso: PetscBinaryRead(), PetscBinaryWrite(), PetscDataTypeToMPIDataType(),
879:           PetscDataTypeGetSize()

881: E*/
882: typedef enum {PETSC_INT = 0,PETSC_DOUBLE = 1,PETSC_COMPLEX = 2,
883:               PETSC_LONG = 3 ,PETSC_SHORT = 4,PETSC_FLOAT = 5,
884:               PETSC_CHAR = 6,PETSC_LOGICAL = 7,PETSC_ENUM = 8,PETSC_TRUTH=9} PetscDataType;

887: #if defined(PETSC_USE_COMPLEX)
888: #define PETSC_SCALAR PETSC_COMPLEX
889: #else
890: #if defined(PETSC_USE_SINGLE)
891: #define PETSC_SCALAR PETSC_FLOAT
892: #else
893: #define PETSC_SCALAR PETSC_DOUBLE
894: #endif
895: #endif
896: #if defined(PETSC_USE_SINGLE)
897: #define PETSC_REAL PETSC_FLOAT
898: #else
899: #define PETSC_REAL PETSC_DOUBLE
900: #endif
901: #define PETSC_FORTRANADDR PETSC_LONG

903: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscDataTypeToMPIDataType(PetscDataType,MPI_Datatype*);
904: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscDataTypeGetSize(PetscDataType,PetscInt*);

906: /*
907:     Basic memory and string operations. These are usually simple wrappers
908:    around the basic Unix system calls, but a few of them have additional
909:    functionality and/or error checking.
910: */
911: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscMemcpy(void*,const void *,size_t);
912: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscBitMemcpy(void*,PetscInt,const void*,PetscInt,PetscInt,PetscDataType);
913: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscMemmove(void*,void *,size_t);
914: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscMemzero(void*,size_t);
915: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscMemcmp(const void*,const void*,size_t,PetscTruth *);
916: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscStrlen(const char[],size_t*);
917: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscStrcmp(const char[],const char[],PetscTruth *);
918: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscStrgrt(const char[],const char[],PetscTruth *);
919: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscStrcasecmp(const char[],const char[],PetscTruth*);
920: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscStrncmp(const char[],const char[],size_t,PetscTruth*);
921: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscStrcpy(char[],const char[]);
922: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscStrcat(char[],const char[]);
923: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscStrncat(char[],const char[],size_t);
924: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscStrncpy(char[],const char[],size_t);
925: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscStrchr(const char[],char,char *[]);
926: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscStrtolower(char[]);
927: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscStrrchr(const char[],char,char *[]);
928: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscStrstr(const char[],const char[],char *[]);
929: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscStrrstr(const char[],const char[],char *[]);
930: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscStrallocpy(const char[],char *[]);
931: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscStrreplace(MPI_Comm,const char[],char[],size_t);
932: #define      PetscStrfree(a) ((a) ? PetscFree(a) : 0) 
933: /*S
934:     PetscToken - 'Token' used for managing tokenizing strings

936:   Level: intermediate

938: .seealso: PetscTokenCreate(), PetscTokenFind(), PetscTokenDestroy()
939: S*/
940: typedef struct {char token;char *array;char *current;} PetscToken;

942: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscTokenCreate(const char[],const char,PetscToken**);
943: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscTokenFind(PetscToken*,char *[]);
944: EXTERN PetscErrorCode PETSC_DLLEXPORT   PetscTokenDestroy(PetscToken*);

946: /*
947:    These are  MPI operations for MPI_Allreduce() etc
948: */
949: EXTERN PETSC_DLLEXPORT MPI_Op PetscMaxSum_Op;
950: #if defined(PETSC_USE_COMPLEX)
951: EXTERN PETSC_DLLEXPORT MPI_Op PetscSum_Op;
952: #else
953: #define PetscSum_Op MPI_SUM
954: #endif
955: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscMaxSum(MPI_Comm,const PetscInt[],PetscInt*,PetscInt*);

957: /*S
958:      PetscObject - any PETSc object, PetscViewer, Mat, Vec, KSP etc

960:    Level: beginner

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

964: .seealso:  PetscObjectDestroy(), PetscObjectView(), PetscObjectGetName(), PetscObjectSetName()
965: S*/
966: typedef struct _p_PetscObject* PetscObject;

968: /*S
969:      PetscFList - Linked list of functions, possibly stored in dynamic libraries, accessed
970:       by string name

972:    Level: advanced

974: .seealso:  PetscFListAdd(), PetscFListDestroy()
975: S*/
976: typedef struct _PetscFList *PetscFList;

978:  #include petscviewer.h
979:  #include petscoptions.h


983: /*
984:    Routines that get memory usage information from the OS
985: */
986: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscMemoryGetCurrentUsage(PetscLogDouble *);
987: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscMemoryGetMaximumUsage(PetscLogDouble *);
988: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscMemorySetGetMaximumUsage(void);
989: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscMemoryShowUsage(PetscViewer,const char[]);

991: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscLogInfoAllow(PetscTruth,const char []);
992: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscGetTime(PetscLogDouble*);
993: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscGetCPUTime(PetscLogDouble*);
994: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscSleep(int);

996: /*
997:     Initialization of PETSc
998: */
999: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscInitialize(int*,char***,const char[],const char[]);
1000: PetscPolymorphicSubroutine(PetscInitialize,(int *argc,char ***args),(argc,args,PETSC_NULL,PETSC_NULL))
1001: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscInitializeNoArguments(void);
1002: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscInitialized(PetscTruth *);
1003: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscFinalized(PetscTruth *);
1004: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscFinalize(void);
1005: EXTERN PetscErrorCode PetscInitializeFortran(void);
1006: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscGetArgs(int*,char ***);
1007: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscEnd(void);
1008: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscInitializePackage(char *);
1009: typedef void (**PetscVoidFunction)(void);

1011: /*
1012:    PetscTryMethod - Queries an object for a method, if it exists then calls it.
1013:               These are intended to be used only inside PETSc functions.
1014: */
1015: #define  PetscTryMethod(obj,A,B,C) \
1016:   0;{ PetscErrorCode (*f)B, __ierr; \
1017:     __PetscObjectQueryFunction((PetscObject)obj,#A,(PetscVoidFunction)&f);CHKERRQ(__ierr); \
1018:     if (f) {__(*f)C;CHKERRQ(__ierr);}\
1019:   }
1020: #define  PetscUseMethod(obj,A,B,C) \
1021:   0;{ PetscErrorCode (*f)B, __ierr; \
1022:     __PetscObjectQueryFunction((PetscObject)obj,A,(PetscVoidFunction)&f);CHKERRQ(__ierr); \
1023:     if (f) {__(*f)C;CHKERRQ(__ierr);}\
1024:     else {SETERRQ1(PETSC_ERR_SUP,"Cannot locate function %s in object",A);} \
1025:   }
1026: /*
1027:     Functions that can act on any PETSc object.
1028: */
1029: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectCreate(MPI_Comm,PetscObject*);
1030: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectDestroy(PetscObject);
1031: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectExists(PetscObject,PetscTruth*);
1032: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectGetComm(PetscObject,MPI_Comm *);
1033: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectGetCookie(PetscObject,int *);
1034: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectSetType(PetscObject,const char []);
1035: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectGetType(PetscObject,const char *[]);
1036: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectSetName(PetscObject,const char[]);
1037: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectGetName(PetscObject,const char*[]);
1038: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectReference(PetscObject);
1039: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectGetReference(PetscObject,PetscInt*);
1040: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectDereference(PetscObject);
1041: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectGetNewTag(PetscObject,PetscMPIInt *);
1042: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscCommGetNewTag(MPI_Comm,PetscMPIInt *);
1043: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectView(PetscObject,PetscViewer);
1044: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectCompose(PetscObject,const char[],PetscObject);
1045: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectQuery(PetscObject,const char[],PetscObject *);
1046: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectComposeFunction(PetscObject,const char[],const char[],void (*)(void));
1047: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectSetFromOptions(PetscObject);
1048: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectSetUp(PetscObject);

1052: /*MC
1053:    PetscObjectComposeFunctionDynamic - Associates a function with a given PETSc object. 
1054:                        
1055:    Collective on PetscObject

1057:    Input Parameters:
1058: +  obj - the PETSc object; this must be cast with a (PetscObject), for example, 
1059:          PetscObjectCompose((PetscObject)mat,...);
1060: .  name - name associated with the child function
1061: .  fname - name of the function
1062: -  ptr - function pointer (or PETSC_NULL if using dynamic libraries)

1064:    Level: advanced

1066:     Synopsis:
1067:     PetscErrorCode PetscObjectComposeFunctionDynamic(PetscObject obj,const char name[],const char fname[],void *ptr)

1069:    Notes:
1070:    To remove a registered routine, pass in a PETSC_NULL rname and fnc().

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

1076:    work in C++/complex with dynamic link libraries (PETSC_USE_DYNAMIC_LIBRARIES)
1077:    enabled.

1079:    Concepts: objects^composing functions
1080:    Concepts: composing functions
1081:    Concepts: functions^querying
1082:    Concepts: objects^querying
1083:    Concepts: querying objects

1085: .seealso: PetscObjectQueryFunction()
1086: M*/
1087: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
1088: #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,0)
1089: #else
1090: #define PetscObjectComposeFunctionDynamic(a,b,c,d) PetscObjectComposeFunction(a,b,c,(FCNVOID)(d))
1091: #endif

1093: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectQueryFunction(PetscObject,const char[],void (**)(void));
1094: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectSetOptionsPrefix(PetscObject,const char[]);
1095: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectAppendOptionsPrefix(PetscObject,const char[]);
1096: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectPrependOptionsPrefix(PetscObject,const char[]);
1097: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectGetOptionsPrefix(PetscObject,const char*[]);
1098: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectPublish(PetscObject);
1099: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectChangeTypeName(PetscObject,const char[]);
1100: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectRegisterDestroy(PetscObject);
1101: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectRegisterDestroyAll(void);
1102: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectName(PetscObject);
1103: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscTypeCompare(PetscObject,const char[],PetscTruth*);

1105: /*
1106:     Defines PETSc error handling.
1107: */
1108:  #include petscerror.h

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

1113:    Level: advanced

1115: .seealso:  PetscOListAdd(), PetscOListDestroy(), PetscOListFind()
1116: S*/
1117: typedef struct _PetscOList *PetscOList;

1119: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscOListDestroy(PetscOList *);
1120: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscOListFind(PetscOList,const char[],PetscObject*);
1121: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscOListReverseFind(PetscOList,PetscObject,char**);
1122: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscOListAdd(PetscOList *,const char[],PetscObject);
1123: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscOListDuplicate(PetscOList,PetscOList *);

1125: /*
1126:     Dynamic library lists. Lists of names of routines in dynamic 
1127:   link libraries that will be loaded as needed.
1128: */
1129: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscFListAdd(PetscFList*,const char[],const char[],void (*)(void));
1130: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscFListDestroy(PetscFList*);
1131: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscFListFind(MPI_Comm,PetscFList,const char[],void (**)(void));
1132: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscFListPrintTypes(MPI_Comm,FILE*,const char[],const char[],const char[],const char[],PetscFList);
1133: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
1134: #define    PetscFListAddDynamic(a,b,p,c) PetscFListAdd(a,b,p,0)
1135: #else
1136: #define    PetscFListAddDynamic(a,b,p,c) PetscFListAdd(a,b,p,(void (*)(void))c)
1137: #endif
1138: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscFListDuplicate(PetscFList,PetscFList *);
1139: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscFListView(PetscFList,PetscViewer);
1140: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscFListConcat(const char [],const char [],char []);
1141: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscFListGet(PetscFList,char ***,int*);

1143: /*S
1144:      PetscDLLibraryList - Linked list of dynamics libraries to search for functions

1146:    Level: advanced

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

1150: .seealso:  PetscDLLibraryOpen()
1151: S*/
1152: typedef struct _PetscDLLibraryList *PetscDLLibraryList;
1154: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscDLLibraryRetrieve(MPI_Comm,const char[],char *,int,PetscTruth *);
1155: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscDLLibraryOpen(MPI_Comm,const char[],void **);
1156: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscDLLibrarySym(MPI_Comm,PetscDLLibraryList *,const char[],const char[],void **);
1157: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscDLLibraryAppend(MPI_Comm,PetscDLLibraryList *,const char[]);
1158: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscDLLibraryPrepend(MPI_Comm,PetscDLLibraryList *,const char[]);
1159: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscDLLibraryClose(PetscDLLibraryList);
1160: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscDLLibraryPrintPath(void);
1161: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscDLLibraryGetInfo(void*,const char[],const char *[]);

1163: /*
1164:     Mechanism for translating PETSc object representations between languages
1165:     Not currently used.
1166: */
1167: typedef enum {PETSC_LANGUAGE_C,PETSC_LANGUAGE_CXX} PetscLanguage;
1168: #define PETSC_LANGUAGE_F77 PETSC_LANGUAGE_C
1169: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectComposeLanguage(PetscObject,PetscLanguage,void *);
1170: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectQueryLanguage(PetscObject,PetscLanguage,void **);

1172: /*
1173:      Useful utility routines
1174: */
1175: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscSplitOwnership(MPI_Comm,PetscInt*,PetscInt*);
1176: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscSplitOwnershipBlock(MPI_Comm,PetscInt,PetscInt*,PetscInt*);
1177: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscSequentialPhaseBegin(MPI_Comm,PetscMPIInt);
1178: PetscPolymorphicSubroutine(PetscSequentialPhaseBegin,(MPI_Comm comm),(comm,1))
1179: PetscPolymorphicSubroutine(PetscSequentialPhaseBegin,(void),(PETSC_COMM_WORLD,1))
1180: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscSequentialPhaseEnd(MPI_Comm,PetscMPIInt);
1181: PetscPolymorphicSubroutine(PetscSequentialPhaseEnd,(MPI_Comm comm),(comm,1))
1182: PetscPolymorphicSubroutine(PetscSequentialPhaseEnd,(void),(PETSC_COMM_WORLD,1))
1183: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscBarrier(PetscObject);
1184: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscMPIDump(FILE*);

1186: #define PetscNot(a) ((a) ? PETSC_FALSE : PETSC_TRUE)
1187: /*
1188:     Defines basic graphics available from PETSc.
1189: */
1190:  #include petscdraw.h

1192: /*
1193:     Defines the base data structures for all PETSc objects
1194: */
1195:  #include petschead.h

1197: /*
1198:      Defines PETSc profiling.
1199: */
1200:  #include petsclog.h

1202: /*
1203:           For locking, unlocking and destroying AMS memories associated with 
1204:     PETSc objects. Not currently used.
1205: */
1206: #define PetscPublishAll(v)           0
1207: #define PetscObjectTakeAccess(obj)   0
1208: #define PetscObjectGrantAccess(obj)  0
1209: #define PetscObjectDepublish(obj)    0



1213: /*
1214:       This code allows one to pass a MPI communicator between 
1215:     C and Fortran. MPI 2.0 defines a standard API for doing this.
1216:     The code here is provided to allow PETSc to work with MPI 1.1
1217:     standard MPI libraries.
1218: */
1219: EXTERN PetscErrorCode MPICCommToFortranComm(MPI_Comm,int *);
1220: EXTERN PetscErrorCode MPIFortranCommToCComm(int,MPI_Comm*);

1222: /*
1223:       Simple PETSc parallel IO for ASCII printing
1224: */
1225: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscFixFilename(const char[],char[]);
1226: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscFOpen(MPI_Comm,const char[],const char[],FILE**);
1227: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscFClose(MPI_Comm,FILE*);
1228: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscFPrintf(MPI_Comm,FILE*,const char[],...) PETSC_PRINTF_FORMAT_CHECK(3,4);
1229: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscPrintf(MPI_Comm,const char[],...)  PETSC_PRINTF_FORMAT_CHECK(2,3);

1231: /* These are used internally by PETSc ASCII IO routines*/
1232: #include <stdarg.h>
1233: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscVSNPrintf(char*,size_t,const char*,va_list);
1234: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscVFPrintf(FILE*,const char*,va_list);

1236: /*MC
1237:     PetscErrorPrintf - Prints error messages.

1239:     Not Collective

1241:    Synopsis:
1242:      PetscErrorCode (*PetscErrorPrintf)(const char format[],...);

1244:     Input Parameters:
1245: .   format - the usual printf() format string 

1247:    Options Database Keys:
1248: .    -error_output_stderr - cause error messages to be printed to stderr instead of the
1249:          (default) stdout


1252:    Level: developer

1254:     Fortran Note:
1255:     This routine is not supported in Fortran.

1257:     Concepts: error messages^printing
1258:     Concepts: printing^error messages

1260: .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscHelpPrintf()
1261: M*/
1262: EXTERN PETSC_DLLEXPORT PetscErrorCode (*PetscErrorPrintf)(const char[],...);

1264: /*MC
1265:     PetscHelpPrintf - Prints help messages.

1267:     Not Collective

1269:    Synopsis:
1270:      PetscErrorCode (*PetscHelpPrintf)(const char format[],...);

1272:     Input Parameters:
1273: .   format - the usual printf() format string 

1275:    Level: developer

1277:     Fortran Note:
1278:     This routine is not supported in Fortran.

1280:     Concepts: help messages^printing
1281:     Concepts: printing^help messages

1283: .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscErrorPrintf()
1284: M*/
1285: EXTERN PETSC_DLLEXPORT PetscErrorCode  (*PetscHelpPrintf)(MPI_Comm,const char[],...);

1287: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscPOpen(MPI_Comm,const char[],const char[],const char[],FILE **);
1288: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscPClose(MPI_Comm,FILE*);
1289: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscSynchronizedPrintf(MPI_Comm,const char[],...) PETSC_PRINTF_FORMAT_CHECK(2,3);
1290: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscSynchronizedFPrintf(MPI_Comm,FILE*,const char[],...) PETSC_PRINTF_FORMAT_CHECK(3,4);
1291: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscSynchronizedFlush(MPI_Comm);
1292: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscSynchronizedFGets(MPI_Comm,FILE*,size_t,char[]);
1293: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscStartMatlab(MPI_Comm,const char[],const char[],FILE**);
1294: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscStartJava(MPI_Comm,const char[],const char[],FILE**);
1295: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscGetPetscDir(const char*[]);

1297: EXTERN PetscErrorCode PETSC_DLLEXPORT  PetscPopUpSelect(MPI_Comm,char*,char*,int,char**,int*);
1298: /*S
1299:      PetscObjectContainer - Simple PETSc object that contains a pointer to any required data

1301:    Level: advanced

1303: .seealso:  PetscObject, PetscObjectContainerCreate()
1304: S*/
1305: typedef struct _p_PetscObjectContainer*  PetscObjectContainer;
1306: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectContainerGetPointer(PetscObjectContainer,void **);
1307: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectContainerSetPointer(PetscObjectContainer,void *);
1308: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectContainerDestroy(PetscObjectContainer);
1309: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectContainerCreate(MPI_Comm comm,PetscObjectContainer *);
1310: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscObjectContainerSetUserDestroy(PetscObjectContainer, PetscErrorCode (*)(void*));

1312: /*
1313:    For use in debuggers 
1314: */

1318: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscIntView(PetscInt,PetscInt[],PetscViewer);
1319: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscRealView(PetscInt,PetscReal[],PetscViewer);
1320: EXTERN PetscErrorCode PETSC_DLLEXPORT PetscScalarView(PetscInt,PetscScalar[],PetscViewer);

1322: /*
1323:     Allows accessing Matlab Engine
1324: */
1325:  #include petscmatlab.h

1327: /*
1328:     C code optimization is often enhanced by telling the compiler 
1329:   that certain pointer arguments to functions are not aliased to 
1330:   to other arguments. This is not yet ANSI C standard so we define 
1331:   the macro "restrict" to indicate that the variable is not aliased 
1332:   to any other argument.
1333: */
1334: #if defined(PETSC_HAVE_RESTRICT) && !defined(__cplusplus)
1335: #define restrict _Restrict
1336: #else
1337: #if defined(restrict)
1338: #undef restrict
1339: #endif
1340: #define restrict
1341: #endif

1343: /*
1344:       Determine if some of the kernel computation routines use
1345:    Fortran (rather than C) for the numerical calculations. On some machines
1346:    and compilers (like complex numbers) the Fortran version of the routines
1347:    is faster than the C/C++ versions. The flag PETSC_USE_FORTRAN_KERNELS  
1348:    would be set in the petscconf.h file
1349: */
1350: #if defined(PETSC_USE_FORTRAN_KERNELS)

1352: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTAIJ)
1353: #define PETSC_USE_FORTRAN_KERNEL_MULTAIJ
1354: #endif

1356: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTTRANSPOSEAIJ)
1357: #define PETSC_USE_FORTRAN_KERNEL_MULTTRANSPOSEAIJ
1358: #endif

1360: #if !defined(PETSC_USE_FORTRAN_KERNEL_NORM)
1361: #define PETSC_USE_FORTRAN_KERNEL_NORM
1362: #endif

1364: #if !defined(PETSC_USE_FORTRAN_KERNEL_MAXPY)
1365: #define PETSC_USE_FORTRAN_KERNEL_MAXPY
1366: #endif

1368: #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ)
1369: #define PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ
1370: #endif

1372: #if !defined(PETSC_USE_FORTRAN_KERNEL_RELAXAIJ)
1373: #define PETSC_USE_FORTRAN_KERNEL_RELAXAIJ
1374: #endif

1376: #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ)
1377: #define PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ
1378: #endif

1380: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ)
1381: #define PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ
1382: #endif

1384: #if !defined(PETSC_USE_FORTRAN_KERNEL_MDOT)
1385: #define PETSC_USE_FORTRAN_KERNEL_MDOT
1386: #endif

1388: #if !defined(PETSC_USE_FORTRAN_KERNEL_XTIMESY)
1389: #define PETSC_USE_FORTRAN_KERNEL_XTIMESY
1390: #endif

1392: #if !defined(PETSC_USE_FORTRAN_KERNEL_AYPX)
1393: #define PETSC_USE_FORTRAN_KERNEL_AYPX
1394: #endif

1396: #if !defined(PETSC_USE_FORTRAN_KERNEL_WAXPY)
1397: #define PETSC_USE_FORTRAN_KERNEL_WAXPY
1398: #endif

1400: #endif

1402: /*
1403:     Macros for indicating code that should be compiled with a C interface,
1404:    rather than a C++ interface. Any routines that are dynamically loaded
1405:    (such as the PCCreate_XXX() routines) must be wrapped so that the name
1406:    mangler does not change the functions symbol name. This just hides the 
1408: */
1409: #if defined(__cplusplus)
1412: #else
1415: #endif

1417: /* --------------------------------------------------------------------*/

1419: /*M
1420:     size - integer variable used to contain the number of processors in
1421:            the relevent MPI_Comm

1423:    Level: beginner

1425: .seealso: rank, comm
1426: M*/

1428: /*M
1429:     rank - integer variable used to contain the number of this processor relative
1430:            to all in the relevent MPI_Comm

1432:    Level: beginner

1434: .seealso: size, comm
1435: M*/

1437: /*M
1438:     comm - MPI_Comm used in the current routine or object

1440:    Level: beginner

1442: .seealso: size, rank
1443: M*/

1445: /*M
1446:     MPI_Comm - the basic object used by MPI to determine which processes are involved in a 
1447:         communication

1449:    Level: beginner

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

1453: .seealso: size, rank, comm, PETSC_COMM_WORLD, PETSC_COMM_SELF
1454: M*/

1456: /*M
1457:     PetscScalar - PETSc type that represents either a double precision real number or 
1458:        a double precision complex number if the code is configured with --with-scalar-type=complex

1460:    Level: beginner

1462: .seealso: PetscReal, PassiveReal, PassiveScalar
1463: M*/

1465: /*M
1466:     PetscReal - PETSc type that represents a double precision real number

1468:    Level: beginner

1470: .seealso: PetscScalar, PassiveReal, PassiveScalar
1471: M*/

1473: /*M
1474:     PassiveScalar - PETSc type that represents either a double precision real number or 
1475:        a double precision complex number if the code is  code is configured with --with-scalar-type=complex

1477:    Level: beginner

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

1482: .seealso: PetscReal, PassiveReal, PetscScalar
1483: M*/

1485: /*M
1486:     PassiveReal - PETSc type that represents a double precision real number

1488:    Level: beginner

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

1493: .seealso: PetscScalar, PetscReal, PassiveScalar
1494: M*/

1496: /*M
1497:     MPIU_SCALAR - MPI datatype corresponding to PetscScalar

1499:    Level: beginner

1501:     Note: In MPI calls that require an MPI datatype that matches a PetscScalar or array of PetscScalars
1502:           pass this value

1504: .seealso: PetscReal, PassiveReal, PassiveScalar, PetscScalar
1505: M*/

1507: /*
1508:      The IBM include files define hz, here we hide it so that it may be used
1509:    as a regular user variable.
1510: */
1511: #if defined(hz)
1512: #undef hz
1513: #endif

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


1518: #if defined(PETSC_HAVE_LIMITS_H)
1519: #include <limits.h>
1520: #endif
1521: #if defined(PETSC_HAVE_SYS_PARAM_H)
1522: #include <sys/param.h>
1523: #endif
1524: #if defined(PETSC_HAVE_SYS_TYPES_H)
1525: #include <sys/types.h>
1526: #endif
1527: #if defined(MAXPATHLEN)
1528: #  define PETSC_MAX_PATH_LEN     MAXPATHLEN
1529: #elif defined(MAX_PATH)
1530: #  define PETSC_MAX_PATH_LEN     MAX_PATH
1531: #elif defined(_MAX_PATH)
1532: #  define PETSC_MAX_PATH_LEN     _MAX_PATH
1533: #else
1534: #  define PETSC_MAX_PATH_LEN     4096
1535: #endif

1538: #endif