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