Date: 2013-07-02T14:52:32+00:00

Actual source code: petscsys.h
petsc-3.4.2 2013-07-02

      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. For --prefix installs the ${PETSC_ARCH}/
     12:    does not exist and petscconf.h is in the same directory as the other PETSc include files.
     13: */
     14: #include <petscconf.h>
     15: #include <petscfix.h>

     17: #if defined(PETSC_DESIRE_FEATURE_TEST_MACROS)
     18: /*
     19:    Feature test macros must be included before headers defined by IEEE Std 1003.1-2001
     20:    We only turn these in PETSc source files that require them by setting PETSC_DESIRE_FEATURE_TEST_MACROS
     21: */
     22: #if defined(PETSC__POSIX_C_SOURCE_200112L) && !defined(_POSIX_C_SOURCE)
     23: #define _POSIX_C_SOURCE 200112L
     24: #endif
     25: #if defined(PETSC__BSD_SOURCE) && !defined(_BSD_SOURCE)
     26: #define _BSD_SOURCE
     27: #endif
     28: #if defined(PETSC__GNU_SOURCE) && !defined(_GNU_SOURCE)
     29: #define _GNU_SOURCE
     30: #endif
     31: #endif

     33: /* ========================================================================== */
     34: /*
     35:    This facilitates using the C version of PETSc from C++ and the C++ version from C.
     36: */
     37: #if defined(__cplusplus)
     38: #  define PETSC_FUNCTION_NAME PETSC_FUNCTION_NAME_CXX
     39: #else
     40: #  define PETSC_FUNCTION_NAME PETSC_FUNCTION_NAME_C
     41: #endif

     43: #if defined(_WIN32) && defined(PETSC_USE_SHARED_LIBRARIES) /* For Win32 shared libraries */
     44: #  define  __declspec(dllexport)
     45: #  define PETSC_DLLIMPORT __declspec(dllimport)
     46: #  define PETSC_VISIBILITY_INTERNAL
     47: #elif defined(PETSC_USE_VISIBILITY)
     48: #  define  __attribute__((visibility ("default")))
     49: #  define PETSC_DLLIMPORT __attribute__((visibility ("default")))
     50: #  define PETSC_VISIBILITY_INTERNAL __attribute__((visibility ("hidden")))
     51: #else
     52: #  define
     53: #  define PETSC_DLLIMPORT
     54: #  define PETSC_VISIBILITY_INTERNAL
     55: #endif

     57: #if defined(petsc_EXPORTS)      /* CMake defines this when building the shared library */
     58: #  define PETSC_VISIBILITY_PUBLIC
     59: #else  /* Win32 users need this to import symbols from petsc.dll */
     60: #  define PETSC_VISIBILITY_PUBLIC PETSC_DLLIMPORT
     61: #endif

     63: #if defined(__cplusplus)
     64: #define PETSC_EXTERN extern "C" PETSC_VISIBILITY_PUBLIC
     65: #define PETSC_EXTERN_TYPEDEF extern "C"
     66: #define PETSC_INTERN extern "C" PETSC_VISIBILITY_INTERNAL
     67: #else
     68: #define PETSC_EXTERN extern PETSC_VISIBILITY_PUBLIC
     69: #define PETSC_EXTERN_TYPEDEF
     70: #define PETSC_INTERN extern PETSC_VISIBILITY_INTERNAL
     71: #endif

     73: #include <petscversion.h>
     74: #define PETSC_AUTHOR_INFO  "       The PETSc Team\n    petsc-maint@mcs.anl.gov\n http://www.mcs.anl.gov/petsc/\n"

     76: /* ========================================================================== */

     78: /*
     79:     Defines the interface to MPI allowing the use of all MPI functions.

     81:     PETSc does not use the C++ binding of MPI at ALL. The following flag
     82:     makes sure the C++ bindings are not included. The C++ bindings REQUIRE
     83:     putting mpi.h before ANY C++ include files, we cannot control this
     84:     with all PETSc users. Users who want to use the MPI C++ bindings can include
     85:     mpicxx.h directly in their code
     86: */
     87: #if !defined(MPICH_SKIP_MPICXX)
     88: #  define MPICH_SKIP_MPICXX 1
     89: #endif
     90: #if !defined(OMPI_SKIP_MPICXX)
     91: #  define OMPI_SKIP_MPICXX 1
     92: #endif
     93: #include <mpi.h>

     95: /*
     96:     Need to put stdio.h AFTER mpi.h for MPICH2 with C++ compiler
     97:     see the top of mpicxx.h in the MPICH2 distribution.
     98: */
     99: #include <stdio.h>

    101: /* MSMPI on 32bit windows requires this yukky hack - that breaks MPI standard compliance */
    102: #if !defined(MPIAPI)
    103: #define MPIAPI
    104: #endif

    106: /* Support for Clang (>=3.2) matching type tag arguments with void* buffer types */
    107: #if defined(__has_attribute)
    108: #  if __has_attribute(argument_with_type_tag) && __has_attribute(pointer_with_type_tag) && __has_attribute(type_tag_for_datatype)
    109: #    define PetscAttrMPIPointerWithType(bufno,typeno) __attribute__((pointer_with_type_tag(MPI,bufno,typeno)))
    110: #    define PetscAttrMPITypeTag(type)                 __attribute__((type_tag_for_datatype(MPI,type)))
    111: #    define PetscAttrMPITypeTagLayoutCompatible(type) __attribute__((type_tag_for_datatype(MPI,type,layout_compatible)))
    112: #  endif
    113: #endif
    114: #if !defined(PetscAttrMPIPointerWithType)
    115: #  define PetscAttrMPIPointerWithType(bufno,typeno)
    116: #  define PetscAttrMPITypeTag(type)
    117: #  define PetscAttrMPITypeTagLayoutCompatible(type)
    118: #endif

    120: /*MC
    121:     PetscErrorCode - datatype used for return error code from all PETSc functions

    123:     Level: beginner

    125: .seealso: CHKERRQ, SETERRQ
    126: M*/
    127: typedef int PetscErrorCode;

    129: /*MC

    131:     PetscClassId - A unique id used to identify each PETSc class.
    132:          (internal integer in the data structure used for error
    133:          checking). These are all computed by an offset from the lowest
    134:          one, PETSC_SMALLEST_CLASSID.

    136:     Level: advanced

    138: .seealso: PetscClassIdRegister(), PetscLogEventRegister(), PetscHeaderCreate()
    139: M*/
    140: typedef int PetscClassId;

    143: /*MC
    144:     PetscMPIInt - datatype used to represent 'int' parameters to MPI functions.

    146:     Level: intermediate

    148:     Notes: usually this is the same as PetscInt, but if PETSc was built with --with-64-bit-indices but
    149:            standard C/Fortran integers are 32 bit then this is NOT the same as PetscInt it remains 32 bit

    151:     PetscMPIIntCast(a,&b) checks if the given PetscInt a will fit in a PetscMPIInt, if not it
    152:       generates a PETSC_ERR_ARG_OUTOFRANGE error.

    154: .seealso: PetscBLASInt, PetscInt

    156: M*/
    157: typedef int PetscMPIInt;

    159: /*MC
    160:     PetscEnum - datatype used to pass enum types within PETSc functions.

    162:     Level: intermediate

    164: .seealso: PetscOptionsGetEnum(), PetscOptionsEnum(), PetscBagRegisterEnum()
    165: M*/
    166: typedef enum { ENUM_DUMMY } PetscEnum;
    167: PETSC_EXTERN MPI_Datatype MPIU_ENUM PetscAttrMPITypeTag(PetscEnum);

    169: /*MC
    170:     PetscInt - PETSc type that represents integer - used primarily to
    171:       represent size of arrays and indexing into arrays. Its size can be configured with the option
    172:       --with-64-bit-indices - to be either 32bit or 64bit [default 32 bit ints]

    174:    Level: intermediate

    176: .seealso: PetscScalar, PetscBLASInt, PetscMPIInt
    177: M*/
    178: #if (PETSC_SIZEOF_LONG_LONG == 8)
    179: typedef long long Petsc64bitInt;
    180: #elif defined(PETSC_HAVE___INT64)
    181: typedef __int64 Petsc64bitInt;
    182: #else
    183: typedef unknown64bit Petsc64bitInt
    184: #endif
    185: #if defined(PETSC_USE_64BIT_INDICES)
    186: typedef Petsc64bitInt PetscInt;
    187: #define MPIU_INT MPI_LONG_LONG_INT
    188: #else
    189: typedef int PetscInt;
    190: #define MPIU_INT MPI_INT
    191: #endif

    194: /*MC
    195:     PetscBLASInt - datatype used to represent 'int' parameters to BLAS/LAPACK functions.

    197:     Level: intermediate

    199:     Notes: usually this is the same as PetscInt, but if PETSc was built with --with-64-bit-indices but
    200:            standard C/Fortran integers are 32 bit then this is NOT the same as PetscInt it remains 32 bit
    201:            (except on very rare BLAS/LAPACK implementations that support 64 bit integers see the note below).

    203:     PetscErrorCode PetscBLASIntCast(a,&b) checks if the given PetscInt a will fit in a PetscBLASInt, if not it
    204:       generates a PETSC_ERR_ARG_OUTOFRANGE error

    206:     Installation Notes: The 64bit versions of MATLAB ship with BLAS and LAPACK that use 64 bit integers for sizes etc,
    207:      if you run ./configure with the option
    208:      --with-blas-lapack-lib=[/Applications/MATLAB_R2010b.app/bin/maci64/libmwblas.dylib,/Applications/MATLAB_R2010b.app/bin/maci64/libmwlapack.dylib]
    209:      but you need to also use --known-64-bit-blas-indices.

    211:         MKL also ships with 64 bit integer versions of the BLAS and LAPACK, if you select those you must also ./configure with --known-64-bit-blas-indices

    213:      Developer Notes: Eventually ./configure should automatically determine the size of the integers used by BLAS/LAPACK.

    215:      External packages such as hypre, ML, SuperLU etc do not provide any support for passing 64 bit integers to BLAS/LAPACK so cannot
    216:      be used with PETSc if you have set PetscBLASInt to long int.

    218: .seealso: PetscMPIInt, PetscInt

    220: M*/
    221: #if defined(PETSC_HAVE_64BIT_BLAS_INDICES)
    222: typedef Petsc64bitInt PetscBLASInt;
    223: #else
    224: typedef int PetscBLASInt;
    225: #endif

    227: /*EC

    229:     PetscPrecision - indicates what precision the object is using. This is currently not used.

    231:     Level: advanced

    233: .seealso: PetscObjectSetPrecision()
    234: E*/
    235: typedef enum { PETSC_PRECISION_SINGLE=4,PETSC_PRECISION_DOUBLE=8 } PetscPrecision;
    236: PETSC_EXTERN const char *PetscPrecisions[];

    238: /*
    239:     For the rare cases when one needs to send a size_t object with MPI
    240: */
    241: #if (PETSC_SIZEOF_SIZE_T) == (PETSC_SIZEOF_INT)
    242: #define MPIU_SIZE_T MPI_UNSIGNED
    243: #elif  (PETSC_SIZEOF_SIZE_T) == (PETSC_SIZEOF_LONG)
    244: #define MPIU_SIZE_T MPI_UNSIGNED_LONG
    245: #elif  (PETSC_SIZEOF_SIZE_T) == (PETSC_SIZEOF_LONG_LONG)
    246: #define MPIU_SIZE_T MPI_UNSIGNED_LONG_LONG
    247: #else
    248: #error "Unknown size for size_t! Send us a bugreport at petsc-maint@mcs.anl.gov"
    249: #endif

    252: /*
    253:       You can use PETSC_STDOUT as a replacement of stdout. You can also change
    254:     the value of PETSC_STDOUT to redirect all standard output elsewhere
    255: */
    256: PETSC_EXTERN FILE* PETSC_STDOUT;

    258: /*
    259:       You can use PETSC_STDERR as a replacement of stderr. You can also change
    260:     the value of PETSC_STDERR to redirect all standard error elsewhere
    261: */
    262: PETSC_EXTERN FILE* PETSC_STDERR;

    264: /*MC
    265:     PetscUnlikely - hints the compiler that the given condition is usually FALSE

    267:     Synopsis:
    268:     #include "petscsys.h"
    269:     PetscBool  PetscUnlikely(PetscBool  cond)

    271:     Not Collective

    273:     Input Parameters:
    274: .   cond - condition or expression

    276:     Note: This returns the same truth value, it is only a hint to compilers that the resulting
    277:     branch is unlikely.

    279:     Level: advanced

    281: .seealso: PetscLikely(), CHKERRQ
    282: M*/

    284: /*MC
    285:     PetscLikely - hints the compiler that the given condition is usually TRUE

    287:     Synopsis:
    288:     #include "petscsys.h"
    289:     PetscBool  PetscUnlikely(PetscBool  cond)

    291:     Not Collective

    293:     Input Parameters:
    294: .   cond - condition or expression

    296:     Note: This returns the same truth value, it is only a hint to compilers that the resulting
    297:     branch is likely.

    299:     Level: advanced

    301: .seealso: PetscUnlikely()
    302: M*/
    303: #if defined(PETSC_HAVE_BUILTIN_EXPECT)
    304: #  define PetscUnlikely(cond)   __builtin_expect(!!(cond),0)
    305: #  define PetscLikely(cond)     __builtin_expect(!!(cond),1)
    306: #else
    307: #  define PetscUnlikely(cond)   (cond)
    308: #  define PetscLikely(cond)     (cond)
    309: #endif

    311: /*
    312:     Defines some elementary mathematics functions and constants.
    313: */
    314: #include <petscmath.h>

    316: /*
    317:     Declare extern C stuff after including external header files
    318: */

    321: /*
    322:        Basic PETSc constants
    323: */

    325: /*E
    326:     PetscBool  - Logical variable. Actually an int in C and a logical in Fortran.

    328:    Level: beginner

    330:    Developer Note: Why have PetscBool , why not use bool in C? The problem is that K and R C, C99 and C++ all have different mechanisms for
    331:       boolean values. It is not easy to have a simple macro that that will work properly in all circumstances with all three mechanisms.

    333: E*/
    334: typedef enum { PETSC_FALSE,PETSC_TRUE } PetscBool;
    335: PETSC_EXTERN const char *const PetscBools[];
    336: PETSC_EXTERN MPI_Datatype MPIU_BOOL PetscAttrMPITypeTag(PetscBool);

    338: /*E
    339:     PetscCopyMode  - Determines how an array passed to certain functions is copied or retained

    341:    Level: beginner

    343: $   PETSC_COPY_VALUES - the array values are copied into new space, the user is free to reuse or delete the passed in array
    344: $   PETSC_OWN_POINTER - the array values are NOT copied, the object takes ownership of the array and will free it later, the user cannot change or
    345: $                       delete the array. The array MUST have been obtained with PetscMalloc(). Hence this mode cannot be used in Fortran.
    346: $   PETSC_USE_POINTER - the array values are NOT copied, the object uses the array but does NOT take ownership of the array. The user cannot use
    347:                         the array but the user must delete the array after the object is destroyed.

    349: E*/
    350: typedef enum { PETSC_COPY_VALUES, PETSC_OWN_POINTER, PETSC_USE_POINTER} PetscCopyMode;
    351: PETSC_EXTERN const char *const PetscCopyModes[];

    353: /*MC
    354:     PETSC_FALSE - False value of PetscBool

    356:     Level: beginner

    358:     Note: Zero integer

    360: .seealso: PetscBool , PETSC_TRUE
    361: M*/

    363: /*MC
    364:     PETSC_TRUE - True value of PetscBool

    366:     Level: beginner

    368:     Note: Nonzero integer

    370: .seealso: PetscBool , PETSC_FALSE
    371: M*/

    373: /*MC
    374:     PETSC_NULL - standard way of passing in a null or array or pointer. This is deprecated in C/C++ simply use NULL

    376:    Level: beginner

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

    381:           This macro does not exist in Fortran; you must use PETSC_NULL_INTEGER,
    382:           PETSC_NULL_DOUBLE_PRECISION, PETSC_NULL_FUNCTION, PETSC_NULL_OBJECT etc

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

    386: M*/
    387: #define PETSC_NULL           NULL

    389: /*MC
    390:     PETSC_IGNORE - same as NULL, means PETSc will ignore this argument

    392:    Level: beginner

    394:    Note: accepted by many PETSc functions to not set a parameter and instead use
    395:           some default

    397:    Fortran Notes: This macro does not exist in Fortran; you must use PETSC_NULL_INTEGER,
    398:           PETSC_NULL_DOUBLE_PRECISION etc

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

    402: M*/
    403: #define PETSC_IGNORE         NULL

    405: /*MC
    406:     PETSC_DECIDE - standard way of passing in integer or floating point parameter
    407:        where you wish PETSc to use the default.

    409:    Level: beginner

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

    413: M*/
    414: #define PETSC_DECIDE  -1

    416: /*MC
    417:     PETSC_DETERMINE - standard way of passing in integer or floating point parameter
    418:        where you wish PETSc to compute the required value.

    420:    Level: beginner

    423:    Developer Note: I would like to use const PetscInt PETSC_DETERMINE = PETSC_DECIDE; but for
    424:      some reason this is not allowed by the standard even though PETSC_DECIDE is a constant value.

    426: .seealso: PETSC_DECIDE, PETSC_DEFAULT, PETSC_IGNORE, VecSetSizes()

    428: M*/
    429: #define PETSC_DETERMINE PETSC_DECIDE

    431: /*MC
    432:     PETSC_DEFAULT - standard way of passing in integer or floating point parameter
    433:        where you wish PETSc to use the default.

    435:    Level: beginner

    437:    Fortran Notes: You need to use PETSC_DEFAULT_INTEGER or PETSC_DEFAULT_DOUBLE_PRECISION.

    439: .seealso: PETSC_DECIDE, PETSC_IGNORE, PETSC_DETERMINE

    441: M*/
    442: #define PETSC_DEFAULT  -2

    444: /*MC
    445:     PETSC_COMM_WORLD - the equivalent of the MPI_COMM_WORLD communicator which represents
    446:            all the processs that PETSc knows about.

    448:    Level: beginner

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

    455: .seealso: PETSC_COMM_SELF

    457: M*/
    458: PETSC_EXTERN MPI_Comm PETSC_COMM_WORLD;

    460: /*MC
    461:     PETSC_COMM_SELF - This is always MPI_COMM_SELF

    463:    Level: beginner

    465: .seealso: PETSC_COMM_WORLD

    467: M*/
    468: #define PETSC_COMM_SELF MPI_COMM_SELF

    470: PETSC_EXTERN PetscBool PetscBeganMPI;
    471: PETSC_EXTERN PetscBool PetscInitializeCalled;
    472: PETSC_EXTERN PetscBool PetscFinalizeCalled;
    473: PETSC_EXTERN PetscBool PetscCUSPSynchronize;

    475: PETSC_EXTERN PetscErrorCode PetscSetHelpVersionFunctions(PetscErrorCode (*)(MPI_Comm),PetscErrorCode (*)(MPI_Comm));
    476: PETSC_EXTERN PetscErrorCode PetscCommDuplicate(MPI_Comm,MPI_Comm*,int*);
    477: PETSC_EXTERN PetscErrorCode PetscCommDestroy(MPI_Comm*);

    479: /*MC
    480:    PetscMalloc - Allocates memory

    482:    Synopsis:
    483:     #include "petscsys.h"
    484:    PetscErrorCode PetscMalloc(size_t m,void **result)

    486:    Not Collective

    488:    Input Parameter:
    489: .  m - number of bytes to allocate

    491:    Output Parameter:
    492: .  result - memory allocated

    494:    Level: beginner

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

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

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

    503:   Concepts: memory allocation

    505: M*/
    506: #define PetscMalloc(a,b)  ((a != 0) ? (*PetscTrMalloc)((a),__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__,(void**)(b)) : (*(b) = 0,0) )

    508: /*MC
    509:    PetscAddrAlign - Rounds up an address to PETSC_MEMALIGN alignment

    511:    Synopsis:
    512:     #include "petscsys.h"
    513:    void *PetscAddrAlign(void *addr)

    515:    Not Collective

    517:    Input Parameters:
    518: .  addr - address to align (any pointer type)

    520:    Level: developer

    522: .seealso: PetscMallocAlign()

    524:   Concepts: memory allocation
    525: M*/
    526: #define PetscAddrAlign(a) (void*)((((PETSC_UINTPTR_T)(a))+(PETSC_MEMALIGN-1)) & ~(PETSC_MEMALIGN-1))

    528: /*MC
    529:    PetscMalloc2 - Allocates 2 chunks of  memory both aligned to PETSC_MEMALIGN

    531:    Synopsis:
    532:     #include "petscsys.h"
    533:    PetscErrorCode PetscMalloc2(size_t m1,type, t1,void **r1,size_t m2,type t2,void **r2)

    535:    Not Collective

    537:    Input Parameter:
    538: +  m1 - number of elements to allocate in 1st chunk  (may be zero)
    539: .  t1 - type of first memory elements
    540: .  m2 - number of elements to allocate in 2nd chunk  (may be zero)
    541: -  t2 - type of second memory elements

    543:    Output Parameter:
    544: +  r1 - memory allocated in first chunk
    545: -  r2 - memory allocated in second chunk

    547:    Level: developer

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

    551:   Concepts: memory allocation

    553: M*/
    554: #if defined(PETSC_USE_DEBUG)
    555: #define PetscMalloc2(m1,t1,r1,m2,t2,r2) (PetscMalloc((m1)*sizeof(t1),r1) || PetscMalloc((m2)*sizeof(t2),r2))
    556: #else
    557: #define PetscMalloc2(m1,t1,r1,m2,t2,r2) ((*(r2) = 0,PetscMalloc((m1)*sizeof(t1)+(m2)*sizeof(t2)+(PETSC_MEMALIGN-1),r1)) || (*(r2) = (t2*)PetscAddrAlign(*(r1)+m1),0))
    558: #endif

    560: /*MC
    561:    PetscMalloc3 - Allocates 3 chunks of  memory  all aligned to PETSC_MEMALIGN

    563:    Synopsis:
    564:     #include "petscsys.h"
    565:    PetscErrorCode PetscMalloc3(size_t m1,type, t1,void **r1,size_t m2,type t2,void **r2,size_t m3,type t3,void **r3)

    567:    Not Collective

    569:    Input Parameter:
    570: +  m1 - number of elements to allocate in 1st chunk  (may be zero)
    571: .  t1 - type of first memory elements
    572: .  m2 - number of elements to allocate in 2nd chunk  (may be zero)
    573: .  t2 - type of second memory elements
    574: .  m3 - number of elements to allocate in 3rd chunk  (may be zero)
    575: -  t3 - type of third memory elements

    577:    Output Parameter:
    578: +  r1 - memory allocated in first chunk
    579: .  r2 - memory allocated in second chunk
    580: -  r3 - memory allocated in third chunk

    582:    Level: developer

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

    586:   Concepts: memory allocation

    588: M*/
    589: #if defined(PETSC_USE_DEBUG)
    590: #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))
    591: #else
    592: #define PetscMalloc3(m1,t1,r1,m2,t2,r2,m3,t3,r3) ((*(r2) = 0,*(r3) = 0,PetscMalloc((m1)*sizeof(t1)+(m2)*sizeof(t2)+(m3)*sizeof(t3)+2*(PETSC_MEMALIGN-1),r1)) \
    593:                                                   || (*(r2) = (t2*)PetscAddrAlign(*(r1)+m1),*(r3) = (t3*)PetscAddrAlign(*(r2)+m2),0))
    594: #endif

    596: /*MC
    597:    PetscMalloc4 - Allocates 4 chunks of  memory  all aligned to PETSC_MEMALIGN

    599:    Synopsis:
    600:     #include "petscsys.h"
    601:    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)

    603:    Not Collective

    605:    Input Parameter:
    606: +  m1 - number of elements to allocate in 1st chunk  (may be zero)
    607: .  t1 - type of first memory elements
    608: .  m2 - number of elements to allocate in 2nd chunk  (may be zero)
    609: .  t2 - type of second memory elements
    610: .  m3 - number of elements to allocate in 3rd chunk  (may be zero)
    611: .  t3 - type of third memory elements
    612: .  m4 - number of elements to allocate in 4th chunk  (may be zero)
    613: -  t4 - type of fourth memory elements

    615:    Output Parameter:
    616: +  r1 - memory allocated in first chunk
    617: .  r2 - memory allocated in second chunk
    618: .  r3 - memory allocated in third chunk
    619: -  r4 - memory allocated in fourth chunk

    621:    Level: developer

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

    625:   Concepts: memory allocation

    627: M*/
    628: #if defined(PETSC_USE_DEBUG)
    629: #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))
    630: #else
    631: #define PetscMalloc4(m1,t1,r1,m2,t2,r2,m3,t3,r3,m4,t4,r4)               \
    632:   ((*(r2) = 0, *(r3) = 0, *(r4) = 0,PetscMalloc((m1)*sizeof(t1)+(m2)*sizeof(t2)+(m3)*sizeof(t3)+(m4)*sizeof(t4)+3*(PETSC_MEMALIGN-1),r1)) \
    633:    || (*(r2) = (t2*)PetscAddrAlign(*(r1)+m1),*(r3) = (t3*)PetscAddrAlign(*(r2)+m2),*(r4) = (t4*)PetscAddrAlign(*(r3)+m3),0))
    634: #endif

    636: /*MC
    637:    PetscMalloc5 - Allocates 5 chunks of  memory all aligned to PETSC_MEMALIGN

    639:    Synopsis:
    640:     #include "petscsys.h"
    641:    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)

    643:    Not Collective

    645:    Input Parameter:
    646: +  m1 - number of elements to allocate in 1st chunk  (may be zero)
    647: .  t1 - type of first memory elements
    648: .  m2 - number of elements to allocate in 2nd chunk  (may be zero)
    649: .  t2 - type of second memory elements
    650: .  m3 - number of elements to allocate in 3rd chunk  (may be zero)
    651: .  t3 - type of third memory elements
    652: .  m4 - number of elements to allocate in 4th chunk  (may be zero)
    653: .  t4 - type of fourth memory elements
    654: .  m5 - number of elements to allocate in 5th chunk  (may be zero)
    655: -  t5 - type of fifth memory elements

    657:    Output Parameter:
    658: +  r1 - memory allocated in first chunk
    659: .  r2 - memory allocated in second chunk
    660: .  r3 - memory allocated in third chunk
    661: .  r4 - memory allocated in fourth chunk
    662: -  r5 - memory allocated in fifth chunk

    664:    Level: developer

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

    668:   Concepts: memory allocation

    670: M*/
    671: #if defined(PETSC_USE_DEBUG)
    672: #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))
    673: #else
    674: #define PetscMalloc5(m1,t1,r1,m2,t2,r2,m3,t3,r3,m4,t4,r4,m5,t5,r5)      \
    675:   ((*(r2) = 0, *(r3) = 0, *(r4) = 0,*(r5) = 0,PetscMalloc((m1)*sizeof(t1)+(m2)*sizeof(t2)+(m3)*sizeof(t3)+(m4)*sizeof(t4)+(m5)*sizeof(t5)+4*(PETSC_MEMALIGN-1),r1)) \
    676:    || (*(r2) = (t2*)PetscAddrAlign(*(r1)+m1),*(r3) = (t3*)PetscAddrAlign(*(r2)+m2),*(r4) = (t4*)PetscAddrAlign(*(r3)+m3),*(r5) = (t5*)PetscAddrAlign(*(r4)+m4),0))
    677: #endif

    680: /*MC
    681:    PetscMalloc6 - Allocates 6 chunks of  memory all aligned to PETSC_MEMALIGN

    683:    Synopsis:
    684:     #include "petscsys.h"
    685:    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)

    687:    Not Collective

    689:    Input Parameter:
    690: +  m1 - number of elements to allocate in 1st chunk  (may be zero)
    691: .  t1 - type of first memory elements
    692: .  m2 - number of elements to allocate in 2nd chunk  (may be zero)
    693: .  t2 - type of second memory elements
    694: .  m3 - number of elements to allocate in 3rd chunk  (may be zero)
    695: .  t3 - type of third memory elements
    696: .  m4 - number of elements to allocate in 4th chunk  (may be zero)
    697: .  t4 - type of fourth memory elements
    698: .  m5 - number of elements to allocate in 5th chunk  (may be zero)
    699: .  t5 - type of fifth memory elements
    700: .  m6 - number of elements to allocate in 6th chunk  (may be zero)
    701: -  t6 - type of sixth memory elements

    703:    Output Parameter:
    704: +  r1 - memory allocated in first chunk
    705: .  r2 - memory allocated in second chunk
    706: .  r3 - memory allocated in third chunk
    707: .  r4 - memory allocated in fourth chunk
    708: .  r5 - memory allocated in fifth chunk
    709: -  r6 - memory allocated in sixth chunk

    711:    Level: developer

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

    715:   Concepts: memory allocation

    717: M*/
    718: #if defined(PETSC_USE_DEBUG)
    719: #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))
    720: #else
    721: #define PetscMalloc6(m1,t1,r1,m2,t2,r2,m3,t3,r3,m4,t4,r4,m5,t5,r5,m6,t6,r6) \
    722:   ((*(r2) = 0, *(r3) = 0, *(r4) = 0,*(r5) = 0,*(r6) = 0,PetscMalloc((m1)*sizeof(t1)+(m2)*sizeof(t2)+(m3)*sizeof(t3)+(m4)*sizeof(t4)+(m5)*sizeof(t5)+(m6)*sizeof(t6)+5*(PETSC_MEMALIGN-1),r1)) \
    723:    || (*(r2) = (t2*)PetscAddrAlign(*(r1)+m1),*(r3) = (t3*)PetscAddrAlign(*(r2)+m2),*(r4) = (t4*)PetscAddrAlign(*(r3)+m3),*(r5) = (t5*)PetscAddrAlign(*(r4)+m4),*(r6) = (t6*)PetscAddrAlign(*(r5)+m5),0))
    724: #endif

    726: /*MC
    727:    PetscMalloc7 - Allocates 7 chunks of  memory all aligned to PETSC_MEMALIGN

    729:    Synopsis:
    730:     #include "petscsys.h"
    731:    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)

    733:    Not Collective

    735:    Input Parameter:
    736: +  m1 - number of elements to allocate in 1st chunk  (may be zero)
    737: .  t1 - type of first memory elements
    738: .  m2 - number of elements to allocate in 2nd chunk  (may be zero)
    739: .  t2 - type of second memory elements
    740: .  m3 - number of elements to allocate in 3rd chunk  (may be zero)
    741: .  t3 - type of third memory elements
    742: .  m4 - number of elements to allocate in 4th chunk  (may be zero)
    743: .  t4 - type of fourth memory elements
    744: .  m5 - number of elements to allocate in 5th chunk  (may be zero)
    745: .  t5 - type of fifth memory elements
    746: .  m6 - number of elements to allocate in 6th chunk  (may be zero)
    747: .  t6 - type of sixth memory elements
    748: .  m7 - number of elements to allocate in 7th chunk  (may be zero)
    749: -  t7 - type of sixth memory elements

    751:    Output Parameter:
    752: +  r1 - memory allocated in first chunk
    753: .  r2 - memory allocated in second chunk
    754: .  r3 - memory allocated in third chunk
    755: .  r4 - memory allocated in fourth chunk
    756: .  r5 - memory allocated in fifth chunk
    757: .  r6 - memory allocated in sixth chunk
    758: -  r7 - memory allocated in seventh chunk

    760:    Level: developer

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

    764:   Concepts: memory allocation

    766: M*/
    767: #if defined(PETSC_USE_DEBUG)
    768: #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))
    769: #else
    770: #define PetscMalloc7(m1,t1,r1,m2,t2,r2,m3,t3,r3,m4,t4,r4,m5,t5,r5,m6,t6,r6,m7,t7,r7) \
    771:   ((*(r2) = 0, *(r3) = 0, *(r4) = 0,*(r5) = 0,*(r6) = 0,*(r7) = 0,PetscMalloc((m1)*sizeof(t1)+(m2)*sizeof(t2)+(m3)*sizeof(t3)+(m4)*sizeof(t4)+(m5)*sizeof(t5)+(m6)*sizeof(t6)+(m7)*sizeof(t7)+6*(PETSC_MEMALIGN-1),r1)) \
    772:    || (*(r2) = (t2*)PetscAddrAlign(*(r1)+m1),*(r3) = (t3*)PetscAddrAlign(*(r2)+m2),*(r4) = (t4*)PetscAddrAlign(*(r3)+m3),*(r5) = (t5*)PetscAddrAlign(*(r4)+m4),*(r6) = (t6*)PetscAddrAlign(*(r5)+m5),*(r7) = (t7*)PetscAddrAlign(*(r6)+m6),0))
    773: #endif

    775: /*MC
    776:    PetscNew - Allocates memory of a particular type, zeros the memory! Aligned to PETSC_MEMALIGN

    778:    Synopsis:
    779:     #include "petscsys.h"
    780:    PetscErrorCode PetscNew(struct type,((type *))result)

    782:    Not Collective

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

    787:    Output Parameter:
    788: .  result - memory allocated

    790:    Level: beginner

    792: .seealso: PetscFree(), PetscMalloc(), PetscNewLog()

    794:   Concepts: memory allocation

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

    799: /*MC
    800:    PetscNewLog - Allocates memory of a particular type, zeros the memory! Aligned to PETSC_MEMALIGN. Associates the memory allocated
    801:          with the given object using PetscLogObjectMemory().

    803:    Synopsis:
    804:     #include "petscsys.h"
    805:    PetscErrorCode PetscNewLog(PetscObject obj,struct type,((type *))result)

    807:    Not Collective

    809:    Input Parameter:
    810: +  obj - object memory is logged to
    811: -  type - structure name of space to be allocated. Memory of size sizeof(type) is allocated

    813:    Output Parameter:
    814: .  result - memory allocated

    816:    Level: developer

    818: .seealso: PetscFree(), PetscMalloc(), PetscNew(), PetscLogObjectMemory()

    820:   Concepts: memory allocation

    822: M*/
    823: #define PetscNewLog(o,A,b) (PetscNew(A,b) || ((o) ? PetscLogObjectMemory(o,sizeof(A)) : 0))

    825: /*MC
    826:    PetscFree - Frees memory

    828:    Synopsis:
    829:     #include "petscsys.h"
    830:    PetscErrorCode PetscFree(void *memory)

    832:    Not Collective

    834:    Input Parameter:
    835: .   memory - memory to free (the pointer is ALWAYS set to 0 upon sucess)

    837:    Level: beginner

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

    841: .seealso: PetscNew(), PetscMalloc(), PetscFreeVoid()

    843:   Concepts: memory allocation

    845: M*/
    846: #define PetscFree(a)   ((a) && ((*PetscTrFree)((void*)(a),__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__) || ((a) = 0,0)))

    848: /*MC
    849:    PetscFreeVoid - Frees memory

    851:    Synopsis:
    852:     #include "petscsys.h"
    853:    void PetscFreeVoid(void *memory)

    855:    Not Collective

    857:    Input Parameter:
    858: .   memory - memory to free

    860:    Level: beginner

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

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

    866:   Concepts: memory allocation

    868: M*/
    869: #define PetscFreeVoid(a) ((*PetscTrFree)((a),__LINE__,PETSC_FUNCTION_NAME,__FILE__,__SDIR__),(a) = 0)

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

    875:    Synopsis:
    876:     #include "petscsys.h"
    877:    PetscErrorCode PetscFree2(void *memory1,void *memory2)

    879:    Not Collective

    881:    Input Parameter:
    882: +   memory1 - memory to free
    883: -   memory2 - 2nd memory to free

    885:    Level: developer

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

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

    891:   Concepts: memory allocation

    893: M*/
    894: #if defined(PETSC_USE_DEBUG)
    895: #define PetscFree2(m1,m2)   (PetscFree(m2) || PetscFree(m1))
    896: #else
    897: #define PetscFree2(m1,m2)   ((m2)=0, PetscFree(m1))
    898: #endif

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

    903:    Synopsis:
    904:     #include "petscsys.h"
    905:    PetscErrorCode PetscFree3(void *memory1,void *memory2,void *memory3)

    907:    Not Collective

    909:    Input Parameter:
    910: +   memory1 - memory to free
    911: .   memory2 - 2nd memory to free
    912: -   memory3 - 3rd memory to free

    914:    Level: developer

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

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

    920:   Concepts: memory allocation

    922: M*/
    923: #if defined(PETSC_USE_DEBUG)
    924: #define PetscFree3(m1,m2,m3)   (PetscFree(m3) || PetscFree(m2) || PetscFree(m1))
    925: #else
    926: #define PetscFree3(m1,m2,m3)   ((m3)=0,(m2)=0,PetscFree(m1))
    927: #endif

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

    932:    Synopsis:
    933:     #include "petscsys.h"
    934:    PetscErrorCode PetscFree4(void *m1,void *m2,void *m3,void *m4)

    936:    Not Collective

    938:    Input Parameter:
    939: +   m1 - memory to free
    940: .   m2 - 2nd memory to free
    941: .   m3 - 3rd memory to free
    942: -   m4 - 4th memory to free

    944:    Level: developer

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

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

    950:   Concepts: memory allocation

    952: M*/
    953: #if defined(PETSC_USE_DEBUG)
    954: #define PetscFree4(m1,m2,m3,m4)   (PetscFree(m4) || PetscFree(m3) || PetscFree(m2) || PetscFree(m1))
    955: #else
    956: #define PetscFree4(m1,m2,m3,m4)   ((m4)=0,(m3)=0,(m2)=0,PetscFree(m1))
    957: #endif

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

    962:    Synopsis:
    963:     #include "petscsys.h"
    964:    PetscErrorCode PetscFree5(void *m1,void *m2,void *m3,void *m4,void *m5)

    966:    Not Collective

    968:    Input Parameter:
    969: +   m1 - memory to free
    970: .   m2 - 2nd memory to free
    971: .   m3 - 3rd memory to free
    972: .   m4 - 4th memory to free
    973: -   m5 - 5th memory to free

    975:    Level: developer

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

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

    981:   Concepts: memory allocation

    983: M*/
    984: #if defined(PETSC_USE_DEBUG)
    985: #define PetscFree5(m1,m2,m3,m4,m5)   (PetscFree(m5) || PetscFree(m4) || PetscFree(m3) || PetscFree(m2) || PetscFree(m1))
    986: #else
    987: #define PetscFree5(m1,m2,m3,m4,m5)   ((m5)=0,(m4)=0,(m3)=0,(m2)=0,PetscFree(m1))
    988: #endif

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

    994:    Synopsis:
    995:     #include "petscsys.h"
    996:    PetscErrorCode PetscFree6(void *m1,void *m2,void *m3,void *m4,void *m5,void *m6)

    998:    Not Collective

    1000:    Input Parameter:
    1001: +   m1 - memory to free
    1002: .   m2 - 2nd memory to free
    1003: .   m3 - 3rd memory to free
    1004: .   m4 - 4th memory to free
    1005: .   m5 - 5th memory to free
    1006: -   m6 - 6th memory to free

    1009:    Level: developer

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

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

    1015:   Concepts: memory allocation

    1017: M*/
    1018: #if defined(PETSC_USE_DEBUG)
    1019: #define PetscFree6(m1,m2,m3,m4,m5,m6)   (PetscFree(m6) || PetscFree(m5) || PetscFree(m4) || PetscFree(m3) || PetscFree(m2) || PetscFree(m1))
    1020: #else
    1021: #define PetscFree6(m1,m2,m3,m4,m5,m6)   ((m6)=0,(m5)=0,(m4)=0,(m3)=0,(m2)=0,PetscFree(m1))
    1022: #endif

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

    1027:    Synopsis:
    1028:     #include "petscsys.h"
    1029:    PetscErrorCode PetscFree7(void *m1,void *m2,void *m3,void *m4,void *m5,void *m6,void *m7)

    1031:    Not Collective

    1033:    Input Parameter:
    1034: +   m1 - memory to free
    1035: .   m2 - 2nd memory to free
    1036: .   m3 - 3rd memory to free
    1037: .   m4 - 4th memory to free
    1038: .   m5 - 5th memory to free
    1039: .   m6 - 6th memory to free
    1040: -   m7 - 7th memory to free

    1043:    Level: developer

    1045:    Notes: Memory must have been obtained with PetscMalloc7()

    1047: .seealso: PetscNew(), PetscMalloc(), PetscMalloc2(), PetscFree(), PetscMalloc3(), PetscMalloc4(), PetscMalloc5(), PetscMalloc6(),
    1048:           PetscMalloc7()

    1050:   Concepts: memory allocation

    1052: M*/
    1053: #if defined(PETSC_USE_DEBUG)
    1054: #define PetscFree7(m1,m2,m3,m4,m5,m6,m7)   (PetscFree(m7) || PetscFree(m6) || PetscFree(m5) || PetscFree(m4) || PetscFree(m3) || PetscFree(m2) || PetscFree(m1))
    1055: #else
    1056: #define PetscFree7(m1,m2,m3,m4,m5,m6,m7)   ((m7)=0,(m6)=0,(m5)=0,(m4)=0,(m3)=0,(m2)=0,PetscFree(m1))
    1057: #endif

    1059: PETSC_EXTERN PetscErrorCode (*PetscTrMalloc)(size_t,int,const char[],const char[],const char[],void**);
    1060: PETSC_EXTERN PetscErrorCode (*PetscTrFree)(void*,int,const char[],const char[],const char[]);
    1061: PETSC_EXTERN PetscErrorCode PetscMallocSet(PetscErrorCode (*)(size_t,int,const char[],const char[],const char[],void**),PetscErrorCode (*)(void*,int,const char[],const char[],const char[]));
    1062: PETSC_EXTERN PetscErrorCode PetscMallocClear(void);

    1064: /*
    1065:     PetscLogDouble variables are used to contain double precision numbers
    1066:   that are not used in the numerical computations, but rather in logging,
    1067:   timing etc.
    1068: */
    1069: typedef double PetscLogDouble;
    1070: #define MPIU_PETSCLOGDOUBLE MPI_DOUBLE

    1072: /*
    1073:    Routines for tracing memory corruption/bleeding with default PETSc  memory allocation
    1074: */
    1075: PETSC_EXTERN PetscErrorCode PetscMallocDump(FILE *);
    1076: PETSC_EXTERN PetscErrorCode PetscMallocDumpLog(FILE *);
    1077: PETSC_EXTERN PetscErrorCode PetscMallocGetCurrentUsage(PetscLogDouble *);
    1078: PETSC_EXTERN PetscErrorCode PetscMallocGetMaximumUsage(PetscLogDouble *);
    1079: PETSC_EXTERN PetscErrorCode PetscMallocDebug(PetscBool);
    1080: PETSC_EXTERN PetscErrorCode PetscMallocGetDebug(PetscBool*);
    1081: PETSC_EXTERN PetscErrorCode PetscMallocValidate(int,const char[],const char[],const char[]);
    1082: PETSC_EXTERN PetscErrorCode PetscMallocSetDumpLog(void);
    1083: PETSC_EXTERN PetscErrorCode PetscMallocSetDumpLogThreshold(PetscLogDouble);
    1084: PETSC_EXTERN PetscErrorCode PetscMallocGetDumpLog(PetscBool*);

    1086: /*E
    1087:     PetscDataType - Used for handling different basic data types.

    1089:    Level: beginner

    1091:    Developer comment: It would be nice if we could always just use MPI Datatypes, why can we not?

    1093: .seealso: PetscBinaryRead(), PetscBinaryWrite(), PetscDataTypeToMPIDataType(),
    1094:           PetscDataTypeGetSize()

    1096: E*/
    1097: typedef enum {PETSC_INT = 0,PETSC_DOUBLE = 1,PETSC_COMPLEX = 2, PETSC_LONG = 3 ,PETSC_SHORT = 4,PETSC_FLOAT = 5,
    1098:               PETSC_CHAR = 6,PETSC_BIT_LOGICAL = 7,PETSC_ENUM = 8,PETSC_BOOL=9, PETSC___FLOAT128 = 10,PETSC_OBJECT = 11, PETSC_FUNCTION = 12} PetscDataType;
    1099: PETSC_EXTERN const char *const PetscDataTypes[];

    1101: #if defined(PETSC_USE_COMPLEX)
    1102: #define  PETSC_SCALAR  PETSC_COMPLEX
    1103: #else
    1104: #if defined(PETSC_USE_REAL_SINGLE)
    1105: #define  PETSC_SCALAR  PETSC_FLOAT
    1106: #elif defined(PETSC_USE_REAL___FLOAT128)
    1107: #define  PETSC_SCALAR  PETSC___FLOAT128
    1108: #else
    1109: #define  PETSC_SCALAR  PETSC_DOUBLE
    1110: #endif
    1111: #endif
    1112: #if defined(PETSC_USE_REAL_SINGLE)
    1113: #define  PETSC_REAL  PETSC_FLOAT
    1114: #elif defined(PETSC_USE_REAL___FLOAT128)
    1115: #define  PETSC_REAL  PETSC___FLOAT128
    1116: #else
    1117: #define  PETSC_REAL  PETSC_DOUBLE
    1118: #endif
    1119: #define  PETSC_FORTRANADDR  PETSC_LONG

    1121: PETSC_EXTERN PetscErrorCode PetscDataTypeToMPIDataType(PetscDataType,MPI_Datatype*);
    1122: PETSC_EXTERN PetscErrorCode PetscMPIDataTypeToPetscDataType(MPI_Datatype,PetscDataType*);
    1123: PETSC_EXTERN PetscErrorCode PetscDataTypeGetSize(PetscDataType,size_t*);

    1125: /*
    1126:     Basic memory and string operations. These are usually simple wrappers
    1127:    around the basic Unix system calls, but a few of them have additional
    1128:    functionality and/or error checking.
    1129: */
    1130: PETSC_EXTERN PetscErrorCode PetscBitMemcpy(void*,PetscInt,const void*,PetscInt,PetscInt,PetscDataType);
    1131: PETSC_EXTERN PetscErrorCode PetscMemmove(void*,void *,size_t);
    1132: PETSC_EXTERN PetscErrorCode PetscMemcmp(const void*,const void*,size_t,PetscBool  *);
    1133: PETSC_EXTERN PetscErrorCode PetscStrlen(const char[],size_t*);
    1134: PETSC_EXTERN PetscErrorCode PetscStrToArray(const char[],char,int*,char ***);
    1135: PETSC_EXTERN PetscErrorCode PetscStrToArrayDestroy(int,char **);
    1136: PETSC_EXTERN PetscErrorCode PetscStrcmp(const char[],const char[],PetscBool  *);
    1137: PETSC_EXTERN PetscErrorCode PetscStrgrt(const char[],const char[],PetscBool  *);
    1138: PETSC_EXTERN PetscErrorCode PetscStrcasecmp(const char[],const char[],PetscBool *);
    1139: PETSC_EXTERN PetscErrorCode PetscStrncmp(const char[],const char[],size_t,PetscBool *);
    1140: PETSC_EXTERN PetscErrorCode PetscStrcpy(char[],const char[]);
    1141: PETSC_EXTERN PetscErrorCode PetscStrcat(char[],const char[]);
    1142: PETSC_EXTERN PetscErrorCode PetscStrncat(char[],const char[],size_t);
    1143: PETSC_EXTERN PetscErrorCode PetscStrncpy(char[],const char[],size_t);
    1144: PETSC_EXTERN PetscErrorCode PetscStrchr(const char[],char,char *[]);
    1145: PETSC_EXTERN PetscErrorCode PetscStrtolower(char[]);
    1146: PETSC_EXTERN PetscErrorCode PetscStrtoupper(char[]);
    1147: PETSC_EXTERN PetscErrorCode PetscStrrchr(const char[],char,char *[]);
    1148: PETSC_EXTERN PetscErrorCode PetscStrstr(const char[],const char[],char *[]);
    1149: PETSC_EXTERN PetscErrorCode PetscStrrstr(const char[],const char[],char *[]);
    1150: PETSC_EXTERN PetscErrorCode PetscStrendswith(const char[],const char[],PetscBool*);
    1151: PETSC_EXTERN PetscErrorCode PetscStrbeginswith(const char[],const char[],PetscBool*);
    1152: PETSC_EXTERN PetscErrorCode PetscStrendswithwhich(const char[],const char *const*,PetscInt*);
    1153: PETSC_EXTERN PetscErrorCode PetscStrallocpy(const char[],char *[]);
    1154: PETSC_EXTERN PetscErrorCode PetscStrArrayallocpy(const char *const*,char***);
    1155: PETSC_EXTERN PetscErrorCode PetscStrArrayDestroy(char***);
    1156: PETSC_EXTERN PetscErrorCode PetscStrreplace(MPI_Comm,const char[],char[],size_t);

    1158: PETSC_EXTERN void PetscStrcmpNoError(const char[],const char[],PetscBool  *);

    1160: /*S
    1161:     PetscToken - 'Token' used for managing tokenizing strings

    1163:   Level: intermediate

    1165: .seealso: PetscTokenCreate(), PetscTokenFind(), PetscTokenDestroy()
    1166: S*/
    1167: typedef struct _p_PetscToken* PetscToken;

    1169: PETSC_EXTERN PetscErrorCode PetscTokenCreate(const char[],const char,PetscToken*);
    1170: PETSC_EXTERN PetscErrorCode PetscTokenFind(PetscToken,char *[]);
    1171: PETSC_EXTERN PetscErrorCode PetscTokenDestroy(PetscToken*);

    1173: PETSC_EXTERN PetscErrorCode PetscEListFind(PetscInt,const char *const*,const char*,PetscInt*,PetscBool*);
    1174: PETSC_EXTERN PetscErrorCode PetscEnumFind(const char *const*,const char*,PetscEnum*,PetscBool*);

    1176: /*
    1177:    These are  MPI operations for MPI_Allreduce() etc
    1178: */
    1179: PETSC_EXTERN MPI_Op PetscMaxSum_Op;
    1180: #if (defined(PETSC_HAVE_COMPLEX) && !defined(PETSC_HAVE_MPI_C_DOUBLE_COMPLEX)) || defined(PETSC_USE_REAL___FLOAT128)
    1181: PETSC_EXTERN MPI_Op MPIU_SUM;
    1182: #else
    1183: #define MPIU_SUM MPI_SUM
    1184: #endif
    1185: #if defined(PETSC_USE_REAL___FLOAT128)
    1186: PETSC_EXTERN MPI_Op MPIU_MAX;
    1187: PETSC_EXTERN MPI_Op MPIU_MIN;
    1188: #else
    1189: #define MPIU_MAX MPI_MAX
    1190: #define MPIU_MIN MPI_MIN
    1191: #endif
    1192: PETSC_EXTERN PetscErrorCode PetscMaxSum(MPI_Comm,const PetscInt[],PetscInt*,PetscInt*);

    1194: PETSC_EXTERN PetscErrorCode MPIULong_Send(void*,PetscInt,MPI_Datatype,PetscMPIInt,PetscMPIInt,MPI_Comm);
    1195: PETSC_EXTERN PetscErrorCode MPIULong_Recv(void*,PetscInt,MPI_Datatype,PetscMPIInt,PetscMPIInt,MPI_Comm);

    1197: /*S
    1198:      PetscObject - any PETSc object, PetscViewer, Mat, Vec, KSP etc

    1200:    Level: beginner

    1202:    Note: This is the base class from which all PETSc objects are derived from.

    1204: .seealso:  PetscObjectDestroy(), PetscObjectView(), PetscObjectGetName(), PetscObjectSetName(), PetscObjectReference(), PetscObjectDereferenc()
    1205: S*/
    1206: typedef struct _p_PetscObject* PetscObject;

    1208: /*S
    1209:      PetscFunctionList - Linked list of functions, possibly stored in dynamic libraries, accessed
    1210:       by string name

    1212:    Level: advanced

    1214: .seealso:  PetscFunctionListAdd(), PetscFunctionListDestroy(), PetscOpFlist
    1215: S*/
    1216: typedef struct _n_PetscFunctionList *PetscFunctionList;

    1218: /*E
    1219:   PetscFileMode - Access mode for a file.

    1221:   Level: beginner

    1223:   FILE_MODE_READ - open a file at its beginning for reading

    1225:   FILE_MODE_WRITE - open a file at its beginning for writing (will create if the file does not exist)

    1227:   FILE_MODE_APPEND - open a file at end for writing

    1229:   FILE_MODE_UPDATE - open a file for updating, meaning for reading and writing

    1231:   FILE_MODE_APPEND_UPDATE - open a file for updating, meaning for reading and writing, at the end

    1233: .seealso: PetscViewerFileSetMode()
    1234: E*/
    1235: typedef enum {FILE_MODE_READ, FILE_MODE_WRITE, FILE_MODE_APPEND, FILE_MODE_UPDATE, FILE_MODE_APPEND_UPDATE} PetscFileMode;
    1236: extern const char *const PetscFileModes[];

    1238: /*
    1239:     Defines PETSc error handling.
    1240: */
    1241: #include <petscerror.h>

    1243: #define PETSC_SMALLEST_CLASSID  1211211
    1244: PETSC_EXTERN PetscClassId PETSC_LARGEST_CLASSID;
    1245: PETSC_EXTERN PetscClassId PETSC_OBJECT_CLASSID;
    1246: PETSC_EXTERN PetscErrorCode PetscClassIdRegister(const char[],PetscClassId *);

    1248: /*
    1249:    Routines that get memory usage information from the OS
    1250: */
    1251: PETSC_EXTERN PetscErrorCode PetscMemoryGetCurrentUsage(PetscLogDouble *);
    1252: PETSC_EXTERN PetscErrorCode PetscMemoryGetMaximumUsage(PetscLogDouble *);
    1253: PETSC_EXTERN PetscErrorCode PetscMemorySetGetMaximumUsage(void);

    1255: PETSC_EXTERN PetscErrorCode PetscInfoAllow(PetscBool ,const char []);
    1256: PETSC_EXTERN PetscErrorCode PetscSleep(PetscReal);

    1258: /*
    1259:    Initialization of PETSc
    1260: */
    1261: PETSC_EXTERN PetscErrorCode PetscInitialize(int*,char***,const char[],const char[]);
    1262: PETSC_EXTERN PetscErrorCode PetscInitializeNoPointers(int,char**,const char[],const char[]);
    1263: PETSC_EXTERN PetscErrorCode PetscInitializeNoArguments(void);
    1264: PETSC_EXTERN PetscErrorCode PetscInitialized(PetscBool *);
    1265: PETSC_EXTERN PetscErrorCode PetscFinalized(PetscBool *);
    1266: PETSC_EXTERN PetscErrorCode PetscFinalize(void);
    1267: PETSC_EXTERN PetscErrorCode PetscInitializeFortran(void);
    1268: PETSC_EXTERN PetscErrorCode PetscGetArgs(int*,char ***);
    1269: PETSC_EXTERN PetscErrorCode PetscGetArguments(char ***);
    1270: PETSC_EXTERN PetscErrorCode PetscFreeArguments(char **);

    1272: PETSC_EXTERN PetscErrorCode PetscEnd(void);
    1273: PETSC_EXTERN PetscErrorCode PetscSysInitializePackage(void);

    1275: PETSC_EXTERN MPI_Comm PETSC_COMM_LOCAL_WORLD;
    1276: PETSC_EXTERN PetscErrorCode PetscHMPIMerge(PetscMPIInt,PetscErrorCode (*)(void*),void*);
    1277: PETSC_EXTERN PetscErrorCode PetscHMPISpawn(PetscMPIInt);
    1278: PETSC_EXTERN PetscErrorCode PetscHMPIFinalize(void);
    1279: PETSC_EXTERN PetscErrorCode PetscHMPIRun(MPI_Comm,PetscErrorCode (*)(MPI_Comm,void *),void*);
    1280: PETSC_EXTERN PetscErrorCode PetscHMPIRunCtx(MPI_Comm,PetscErrorCode (*)(MPI_Comm,void*,void *),void*);
    1281: PETSC_EXTERN PetscErrorCode PetscHMPIFree(MPI_Comm,void*);
    1282: PETSC_EXTERN PetscErrorCode PetscHMPIMalloc(MPI_Comm,size_t,void**);

    1284: PETSC_EXTERN PetscErrorCode PetscPythonInitialize(const char[],const char[]);
    1285: PETSC_EXTERN PetscErrorCode PetscPythonFinalize(void);
    1286: PETSC_EXTERN PetscErrorCode PetscPythonPrintError(void);
    1287: PETSC_EXTERN PetscErrorCode PetscPythonMonitorSet(PetscObject,const char[]);

    1289: /*
    1290:      These are so that in extern C code we can caste function pointers to non-extern C
    1291:    function pointers. Since the regular C++ code expects its function pointers to be C++
    1292: */
    1293: PETSC_EXTERN_TYPEDEF typedef void (**PetscVoidStarFunction)(void);
    1294: PETSC_EXTERN_TYPEDEF typedef void (*PetscVoidFunction)(void);
    1295: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode (*PetscErrorCodeFunction)(void);

    1297: /*
    1298:     Functions that can act on any PETSc object.
    1299: */
    1300: PETSC_EXTERN PetscErrorCode PetscObjectDestroy(PetscObject*);
    1301: PETSC_EXTERN PetscErrorCode PetscObjectGetComm(PetscObject,MPI_Comm *);
    1302: PETSC_EXTERN PetscErrorCode PetscObjectGetClassId(PetscObject,PetscClassId *);
    1303: PETSC_EXTERN PetscErrorCode PetscObjectGetClassName(PetscObject,const char *[]);
    1304: PETSC_EXTERN PetscErrorCode PetscObjectSetType(PetscObject,const char []);
    1305: PETSC_EXTERN PetscErrorCode PetscObjectSetPrecision(PetscObject,PetscPrecision);
    1306: PETSC_EXTERN PetscErrorCode PetscObjectGetType(PetscObject,const char *[]);
    1307: PETSC_EXTERN PetscErrorCode PetscObjectSetName(PetscObject,const char[]);
    1308: PETSC_EXTERN PetscErrorCode PetscObjectGetName(PetscObject,const char*[]);
    1309: PETSC_EXTERN PetscErrorCode PetscObjectSetTabLevel(PetscObject,PetscInt);
    1310: PETSC_EXTERN PetscErrorCode PetscObjectGetTabLevel(PetscObject,PetscInt*);
    1311: PETSC_EXTERN PetscErrorCode PetscObjectIncrementTabLevel(PetscObject,PetscObject,PetscInt);
    1312: PETSC_EXTERN PetscErrorCode PetscObjectReference(PetscObject);
    1313: PETSC_EXTERN PetscErrorCode PetscObjectGetReference(PetscObject,PetscInt*);
    1314: PETSC_EXTERN PetscErrorCode PetscObjectDereference(PetscObject);
    1315: PETSC_EXTERN PetscErrorCode PetscObjectGetNewTag(PetscObject,PetscMPIInt *);
    1316: PETSC_EXTERN PetscErrorCode PetscObjectCompose(PetscObject,const char[],PetscObject);
    1317: PETSC_EXTERN PetscErrorCode PetscObjectRemoveReference(PetscObject,const char[]);
    1318: PETSC_EXTERN PetscErrorCode PetscObjectQuery(PetscObject,const char[],PetscObject *);
    1319: PETSC_EXTERN PetscErrorCode PetscObjectComposeFunction_Private(PetscObject,const char[],void (*)(void));
    1320: #define PetscObjectComposeFunction(a,b,d) PetscObjectComposeFunction_Private(a,b,(PetscVoidFunction)(d))
    1321: PETSC_EXTERN PetscErrorCode PetscObjectSetFromOptions(PetscObject);
    1322: PETSC_EXTERN PetscErrorCode PetscObjectSetUp(PetscObject);
    1323: PETSC_EXTERN PetscErrorCode PetscCommGetNewTag(MPI_Comm,PetscMPIInt *);
    1324: PETSC_EXTERN PetscErrorCode PetscObjectAddOptionsHandler(PetscObject,PetscErrorCode (*)(PetscObject,void*),PetscErrorCode (*)(PetscObject,void*),void*);
    1325: PETSC_EXTERN PetscErrorCode PetscObjectProcessOptionsHandlers(PetscObject);
    1326: PETSC_EXTERN PetscErrorCode PetscObjectDestroyOptionsHandlers(PetscObject);
    1327: PETSC_EXTERN PetscErrorCode PetscObjectsGetGlobalNumbering(MPI_Comm,PetscInt,PetscObject*,PetscInt*,PetscInt*);

    1329: #include <petscviewertypes.h>
    1330: #include <petscoptions.h>

    1332: PETSC_EXTERN PetscErrorCode PetscMemoryShowUsage(PetscViewer,const char[]);
    1333: PETSC_EXTERN PetscErrorCode PetscObjectPrintClassNamePrefixType(PetscObject,PetscViewer,const char[]);
    1334: PETSC_EXTERN PetscErrorCode PetscObjectView(PetscObject,PetscViewer);
    1335: #define PetscObjectQueryFunction(obj,name,fptr) PetscObjectQueryFunction_Private((obj),(name),(PetscVoidFunction*)(fptr))
    1336: PETSC_EXTERN PetscErrorCode PetscObjectQueryFunction_Private(PetscObject,const char[],void (**)(void));
    1337: PETSC_EXTERN PetscErrorCode PetscObjectSetOptionsPrefix(PetscObject,const char[]);
    1338: PETSC_EXTERN PetscErrorCode PetscObjectAppendOptionsPrefix(PetscObject,const char[]);
    1339: PETSC_EXTERN PetscErrorCode PetscObjectPrependOptionsPrefix(PetscObject,const char[]);
    1340: PETSC_EXTERN PetscErrorCode PetscObjectGetOptionsPrefix(PetscObject,const char*[]);
    1341: PETSC_EXTERN PetscErrorCode PetscObjectChangeTypeName(PetscObject,const char[]);
    1342: PETSC_EXTERN PetscErrorCode PetscObjectRegisterDestroy(PetscObject);
    1343: PETSC_EXTERN PetscErrorCode PetscObjectRegisterDestroyAll(void);
    1344: PETSC_EXTERN PetscErrorCode PetscObjectName(PetscObject);
    1345: PETSC_EXTERN PetscErrorCode PetscObjectTypeCompare(PetscObject,const char[],PetscBool *);
    1346: PETSC_EXTERN PetscErrorCode PetscObjectTypeCompareAny(PetscObject,PetscBool*,const char[],...);
    1347: PETSC_EXTERN PetscErrorCode PetscRegisterFinalize(PetscErrorCode (*)(void));
    1348: PETSC_EXTERN PetscErrorCode PetscRegisterFinalizeAll(void);

    1350: #if defined(PETSC_HAVE_AMS)
    1351: PETSC_EXTERN PetscErrorCode PetscObjectAMSViewOff(PetscObject);
    1352: PETSC_EXTERN PetscErrorCode PetscObjectAMSSetBlock(PetscObject,PetscBool);
    1353: PETSC_EXTERN PetscErrorCode PetscObjectAMSBlock(PetscObject);
    1354: PETSC_EXTERN PetscErrorCode PetscObjectAMSGrantAccess(PetscObject);
    1355: PETSC_EXTERN PetscErrorCode PetscObjectAMSTakeAccess(PetscObject);
    1356: PETSC_EXTERN void           PetscStackAMSGrantAccess(void);
    1357: PETSC_EXTERN void           PetscStackAMSTakeAccess(void);
    1358: PETSC_EXTERN PetscErrorCode PetscStackViewAMS(void);
    1359: PETSC_EXTERN PetscErrorCode PetscStackAMSViewOff(void);

    1361: #else
    1362: #define PetscObjectAMSViewOff(obj)             0
    1363: #define PetscObjectAMSSetBlock(obj,flg)        0
    1364: #define PetscObjectAMSBlock(obj)               0
    1365: #define PetscObjectAMSGrantAccess(obj)         0
    1366: #define PetscObjectAMSTakeAccess(obj)          0
    1367: #define PetscStackViewAMS()                    0
    1368: #define PetscStackAMSViewOff()                 0
    1369: #define PetscStackAMSTakeAccess()
    1370: #define PetscStackAMSGrantAccess()

    1372: #endif

    1374: typedef void* PetscDLHandle;
    1375: typedef enum {PETSC_DL_DECIDE=0,PETSC_DL_NOW=1,PETSC_DL_LOCAL=2} PetscDLMode;
    1376: PETSC_EXTERN PetscErrorCode PetscDLOpen(const char[],PetscDLMode,PetscDLHandle *);
    1377: PETSC_EXTERN PetscErrorCode PetscDLClose(PetscDLHandle *);
    1378: PETSC_EXTERN PetscErrorCode PetscDLSym(PetscDLHandle,const char[],void **);

    1381: #if defined(PETSC_USE_DEBUG)
    1382: PETSC_EXTERN PetscErrorCode PetscMallocGetStack(void*,PetscStack**);
    1383: #endif
    1384: PETSC_EXTERN PetscErrorCode PetscObjectsDump(FILE*,PetscBool);

    1386: /*S
    1387:      PetscObjectList - Linked list of PETSc objects, each accessable by string name

    1389:    Level: developer

    1391:    Notes: Used by PetscObjectCompose() and PetscObjectQuery()

    1393: .seealso:  PetscObjectListAdd(), PetscObjectListDestroy(), PetscObjectListFind(), PetscObjectCompose(), PetscObjectQuery(), PetscFunctionList
    1394: S*/
    1395: typedef struct _n_PetscObjectList *PetscObjectList;

    1397: PETSC_EXTERN PetscErrorCode PetscObjectListDestroy(PetscObjectList*);
    1398: PETSC_EXTERN PetscErrorCode PetscObjectListFind(PetscObjectList,const char[],PetscObject*);
    1399: PETSC_EXTERN PetscErrorCode PetscObjectListReverseFind(PetscObjectList,PetscObject,char**,PetscBool*);
    1400: PETSC_EXTERN PetscErrorCode PetscObjectListAdd(PetscObjectList *,const char[],PetscObject);
    1401: PETSC_EXTERN PetscErrorCode PetscObjectListRemoveReference(PetscObjectList *,const char[]);
    1402: PETSC_EXTERN PetscErrorCode PetscObjectListDuplicate(PetscObjectList,PetscObjectList *);

    1404: /*
    1405:     Dynamic library lists. Lists of names of routines in objects or in dynamic
    1406:   link libraries that will be loaded as needed.
    1407: */

    1409: #define PetscFunctionListAdd(list,name,fptr) PetscFunctionListAdd_Private((list),(name),(PetscVoidFunction)(fptr))
    1410: PETSC_EXTERN PetscErrorCode PetscFunctionListAdd_Private(PetscFunctionList*,const char[],void (*)(void));
    1411: PETSC_EXTERN PetscErrorCode PetscFunctionListDestroy(PetscFunctionList*);
    1412: #define PetscFunctionListFind(list,name,fptr) PetscFunctionListFind_Private((list),(name),(PetscVoidFunction*)(fptr))
    1413: PETSC_EXTERN PetscErrorCode PetscFunctionListFind_Private(PetscFunctionList,const char[],void (**)(void));
    1414: PETSC_EXTERN PetscErrorCode PetscFunctionListPrintTypes(MPI_Comm,FILE*,const char[],const char[],const char[],const char[],PetscFunctionList,const char[]);
    1415: PETSC_EXTERN PetscErrorCode PetscFunctionListDuplicate(PetscFunctionList,PetscFunctionList *);
    1416: PETSC_EXTERN PetscErrorCode PetscFunctionListView(PetscFunctionList,PetscViewer);
    1417: PETSC_EXTERN PetscErrorCode PetscFunctionListGet(PetscFunctionList,const char ***,int*);

    1419: /*S
    1420:      PetscDLLibrary - Linked list of dynamics libraries to search for functions

    1422:    Level: advanced

    1424:    --with-shared-libraries --with-dynamic-loading must be used with ./configure to use dynamic libraries

    1426: .seealso:  PetscDLLibraryOpen()
    1427: S*/
    1428: typedef struct _n_PetscDLLibrary *PetscDLLibrary;
    1429: PETSC_EXTERN PetscDLLibrary  PetscDLLibrariesLoaded;
    1430: PETSC_EXTERN PetscErrorCode PetscDLLibraryAppend(MPI_Comm,PetscDLLibrary *,const char[]);
    1431: PETSC_EXTERN PetscErrorCode PetscDLLibraryPrepend(MPI_Comm,PetscDLLibrary *,const char[]);
    1432: PETSC_EXTERN PetscErrorCode PetscDLLibrarySym(MPI_Comm,PetscDLLibrary *,const char[],const char[],void **);
    1433: PETSC_EXTERN PetscErrorCode PetscDLLibraryPrintPath(PetscDLLibrary);
    1434: PETSC_EXTERN PetscErrorCode PetscDLLibraryRetrieve(MPI_Comm,const char[],char *,size_t,PetscBool  *);
    1435: PETSC_EXTERN PetscErrorCode PetscDLLibraryOpen(MPI_Comm,const char[],PetscDLLibrary *);
    1436: PETSC_EXTERN PetscErrorCode PetscDLLibraryClose(PetscDLLibrary);

    1438: /*
    1439:      Useful utility routines
    1440: */
    1441: PETSC_EXTERN PetscErrorCode PetscSplitOwnership(MPI_Comm,PetscInt*,PetscInt*);
    1442: PETSC_EXTERN PetscErrorCode PetscSplitOwnershipBlock(MPI_Comm,PetscInt,PetscInt*,PetscInt*);
    1443: PETSC_EXTERN PetscErrorCode PetscSequentialPhaseBegin(MPI_Comm,PetscMPIInt);
    1444: PETSC_EXTERN PetscErrorCode PetscSequentialPhaseEnd(MPI_Comm,PetscMPIInt);
    1445: PETSC_EXTERN PetscErrorCode PetscBarrier(PetscObject);
    1446: PETSC_EXTERN PetscErrorCode PetscMPIDump(FILE*);

    1448: /*
    1449:     PetscNot - negates a logical type value and returns result as a PetscBool

    1451:     Notes: This is useful in cases like
    1452: $     int        *a;
    1453: $     PetscBool  flag = PetscNot(a)
    1454:      where !a does not return a PetscBool  because we cannot provide a cast from int to PetscBool  in C.
    1455: */
    1456: #define PetscNot(a) ((a) ? PETSC_FALSE : PETSC_TRUE)

    1458: #if defined(PETSC_HAVE_VALGRIND)
    1459: #  include <valgrind/valgrind.h>
    1460: #  define PETSC_RUNNING_ON_VALGRIND RUNNING_ON_VALGRIND
    1461: #else
    1462: #  define PETSC_RUNNING_ON_VALGRIND PETSC_FALSE
    1463: #endif

    1466: /*MC
    1467:     PetscHelpPrintf - Prints help messages.

    1469:    Synopsis:
    1470:     #include "petscsys.h"
    1471:      PetscErrorCode (*PetscHelpPrintf)(const char format[],...);

    1473:     Not Collective

    1475:     Input Parameters:
    1476: .   format - the usual printf() format string

    1478:    Level: developer

    1480:     Fortran Note:
    1481:     This routine is not supported in Fortran.

    1483:     Concepts: help messages^printing
    1484:     Concepts: printing^help messages

    1486: .seealso: PetscFPrintf(), PetscSynchronizedPrintf(), PetscErrorPrintf()
    1487: M*/
    1488: PETSC_EXTERN PetscErrorCode (*PetscHelpPrintf)(MPI_Comm,const char[],...);

    1490: /*
    1491:      Defines PETSc profiling.
    1492: */
    1493: #include <petsclog.h>

    1497: /*
    1498:       Simple PETSc parallel IO for ASCII printing
    1499: */
    1500: PETSC_EXTERN PetscErrorCode PetscFixFilename(const char[],char[]);
    1501: PETSC_EXTERN PetscErrorCode PetscFOpen(MPI_Comm,const char[],const char[],FILE**);
    1502: PETSC_EXTERN PetscErrorCode PetscFClose(MPI_Comm,FILE*);
    1503: PETSC_EXTERN PetscErrorCode PetscFPrintf(MPI_Comm,FILE*,const char[],...);
    1504: PETSC_EXTERN PetscErrorCode PetscPrintf(MPI_Comm,const char[],...);
    1505: PETSC_EXTERN PetscErrorCode PetscSNPrintf(char*,size_t,const char [],...);
    1506: PETSC_EXTERN PetscErrorCode PetscSNPrintfCount(char*,size_t,const char [],size_t*,...);

    1508: /* These are used internally by PETSc ASCII IO routines*/
    1509: #include <stdarg.h>
    1510: PETSC_EXTERN PetscErrorCode PetscVSNPrintf(char*,size_t,const char[],size_t*,va_list);
    1511: PETSC_EXTERN PetscErrorCode (*PetscVFPrintf)(FILE*,const char[],va_list);
    1512: PETSC_EXTERN PetscErrorCode PetscVFPrintfDefault(FILE*,const char[],va_list);

    1514: #if defined(PETSC_HAVE_MATLAB_ENGINE)
    1515: PETSC_EXTERN PetscErrorCode PetscVFPrintf_Matlab(FILE*,const char[],va_list);
    1516: #endif

    1518: PETSC_EXTERN PetscErrorCode PetscErrorPrintfDefault(const char [],...);
    1519: PETSC_EXTERN PetscErrorCode PetscErrorPrintfNone(const char [],...);
    1520: PETSC_EXTERN PetscErrorCode PetscHelpPrintfDefault(MPI_Comm,const char [],...);

    1522: #if defined(PETSC_HAVE_POPEN)
    1523: PETSC_EXTERN PetscErrorCode PetscPOpen(MPI_Comm,const char[],const char[],const char[],FILE **);
    1524: PETSC_EXTERN PetscErrorCode PetscPClose(MPI_Comm,FILE*,PetscInt*);
    1525: #endif

    1527: PETSC_EXTERN PetscErrorCode PetscSynchronizedPrintf(MPI_Comm,const char[],...);
    1528: PETSC_EXTERN PetscErrorCode PetscSynchronizedFPrintf(MPI_Comm,FILE*,const char[],...);
    1529: PETSC_EXTERN PetscErrorCode PetscSynchronizedFlush(MPI_Comm);
    1530: PETSC_EXTERN PetscErrorCode PetscSynchronizedFGets(MPI_Comm,FILE*,size_t,char[]);
    1531: PETSC_EXTERN PetscErrorCode PetscStartMatlab(MPI_Comm,const char[],const char[],FILE**);
    1532: PETSC_EXTERN PetscErrorCode PetscStartJava(MPI_Comm,const char[],const char[],FILE**);
    1533: PETSC_EXTERN PetscErrorCode PetscGetPetscDir(const char*[]);

    1535: PETSC_EXTERN PetscErrorCode PetscPopUpSelect(MPI_Comm,const char*,const char*,int,const char**,int*);

    1537: /*S
    1538:      PetscContainer - Simple PETSc object that contains a pointer to any required data

    1540:    Level: advanced

    1542: .seealso:  PetscObject, PetscContainerCreate()
    1543: S*/
    1544: PETSC_EXTERN PetscClassId PETSC_CONTAINER_CLASSID;
    1545: typedef struct _p_PetscContainer*  PetscContainer;
    1546: PETSC_EXTERN PetscErrorCode PetscContainerGetPointer(PetscContainer,void **);
    1547: PETSC_EXTERN PetscErrorCode PetscContainerSetPointer(PetscContainer,void *);
    1548: PETSC_EXTERN PetscErrorCode PetscContainerDestroy(PetscContainer*);
    1549: PETSC_EXTERN PetscErrorCode PetscContainerCreate(MPI_Comm,PetscContainer *);
    1550: PETSC_EXTERN PetscErrorCode PetscContainerSetUserDestroy(PetscContainer, PetscErrorCode (*)(void*));

    1552: /*
    1553:    For use in debuggers
    1554: */
    1555: PETSC_EXTERN PetscMPIInt PetscGlobalRank;
    1556: PETSC_EXTERN PetscMPIInt PetscGlobalSize;
    1557: PETSC_EXTERN PetscErrorCode PetscIntView(PetscInt,const PetscInt[],PetscViewer);
    1558: PETSC_EXTERN PetscErrorCode PetscRealView(PetscInt,const PetscReal[],PetscViewer);
    1559: PETSC_EXTERN PetscErrorCode PetscScalarView(PetscInt,const PetscScalar[],PetscViewer);

    1561: #include <stddef.h>
    1562: #if defined(PETSC_HAVE_MEMORY_H)
    1563: #include <memory.h>
    1564: #endif
    1565: #if defined(PETSC_HAVE_STDLIB_H)
    1566: #include <stdlib.h>
    1567: #endif

    1569: #if defined(PETSC_HAVE_XMMINTRIN_H) && !defined(__CUDACC__)
    1570: #include <xmmintrin.h>
    1571: #endif
    1572: #if defined(PETSC_HAVE_STDINT_H)
    1573: #include <stdint.h>
    1574: #endif

    1578: /*@C
    1579:    PetscMemcpy - Copies n bytes, beginning at location b, to the space
    1580:    beginning at location a. The two memory regions CANNOT overlap, use
    1581:    PetscMemmove() in that case.

    1583:    Not Collective

    1585:    Input Parameters:
    1586: +  b - pointer to initial memory space
    1587: -  n - length (in bytes) of space to copy

    1589:    Output Parameter:
    1590: .  a - pointer to copy space

    1592:    Level: intermediate

    1594:    Compile Option:
    1595:     PETSC_PREFER_DCOPY_FOR_MEMCPY will cause the BLAS dcopy() routine to be used
    1596:                                   for memory copies on double precision values.
    1597:     PETSC_PREFER_COPY_FOR_MEMCPY will cause C code to be used
    1598:                                   for memory copies on double precision values.
    1599:     PETSC_PREFER_FORTRAN_FORMEMCPY will cause Fortran code to be used
    1600:                                   for memory copies on double precision values.

    1602:    Note:
    1603:    This routine is analogous to memcpy().

    1605:    Developer Note: this is inlined for fastest performance

    1607:   Concepts: memory^copying
    1608:   Concepts: copying^memory

    1610: .seealso: PetscMemmove()

    1612: @*/
    1613: PETSC_STATIC_INLINE PetscErrorCode PetscMemcpy(void *a,const void *b,size_t n)
    1614: {
    1615: #if defined(PETSC_USE_DEBUG)
    1616:   unsigned long al = (unsigned long) a,bl = (unsigned long) b;
    1617:   unsigned long nl = (unsigned long) n;
    1619:   if (n > 0 && !b) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_NULL,"Trying to copy from a null pointer");
    1620:   if (n > 0 && !a) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_NULL,"Trying to copy to a null pointer");
    1621: #else
    1623: #endif
    1624:   if (a != b) {
    1625: #if defined(PETSC_USE_DEBUG)
    1626:     if ((al > bl && (al - bl) < nl) || (bl - al) < nl)  SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_INCOMP,"Memory regions overlap: either use PetscMemmov()\n\
    1627:               or make sure your copy regions and lengths are correct. \n\
    1628:               Length (bytes) %ld first address %ld second address %ld",nl,al,bl);
    1629: #endif
    1630: #if (defined(PETSC_PREFER_DCOPY_FOR_MEMCPY) || defined(PETSC_PREFER_COPY_FOR_MEMCPY) || defined(PETSC_PREFER_FORTRAN_FORMEMCPY))
    1631:    if (!(((long) a) % sizeof(PetscScalar)) && !(n % sizeof(PetscScalar))) {
    1632:       size_t len = n/sizeof(PetscScalar);
    1633: #if defined(PETSC_PREFER_DCOPY_FOR_MEMCPY)
    1634:       PetscBLASInt   one = 1,blen;
    1636:       PetscBLASIntCast(len,&blen);
    1637:       PetscStackCallBLAS("BLAScopy",BLAScopy_(&blen,(PetscScalar *)b,&one,(PetscScalar *)a,&one));
    1638: #elif defined(PETSC_PREFER_FORTRAN_FORMEMCPY)
    1639:       fortrancopy_(&len,(PetscScalar*)b,(PetscScalar*)a);
    1640: #else
    1641:       size_t      i;
    1642:       PetscScalar *x = (PetscScalar*)b, *y = (PetscScalar*)a;
    1643:       for (i=0; i<len; i++) y[i] = x[i];
    1644: #endif
    1645:     } else {
    1646:       memcpy((char*)(a),(char*)(b),n);
    1647:     }
    1648: #else
    1649:     memcpy((char*)(a),(char*)(b),n);
    1650: #endif
    1651:   }
    1652:   return(0);
    1653: }

    1655: /*@C
    1656:    PetscMemzero - Zeros the specified memory.

    1658:    Not Collective

    1660:    Input Parameters:
    1661: +  a - pointer to beginning memory location
    1662: -  n - length (in bytes) of memory to initialize

    1664:    Level: intermediate

    1666:    Compile Option:
    1667:    PETSC_PREFER_BZERO - on certain machines (the IBM RS6000) the bzero() routine happens
    1668:   to be faster than the memset() routine. This flag causes the bzero() routine to be used.

    1670:    Developer Note: this is inlined for fastest performance

    1672:    Concepts: memory^zeroing
    1673:    Concepts: zeroing^memory

    1675: .seealso: PetscMemcpy()
    1676: @*/
    1677: PETSC_STATIC_INLINE PetscErrorCode  PetscMemzero(void *a,size_t n)
    1678: {
    1679:   if (n > 0) {
    1680: #if defined(PETSC_USE_DEBUG)
    1681:     if (!a) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_NULL,"Trying to zero at a null pointer");
    1682: #endif
    1683: #if defined(PETSC_PREFER_ZERO_FOR_MEMZERO)
    1684:     if (!(((long) a) % sizeof(PetscScalar)) && !(n % sizeof(PetscScalar))) {
    1685:       size_t      i,len = n/sizeof(PetscScalar);
    1686:       PetscScalar *x = (PetscScalar*)a;
    1687:       for (i=0; i<len; i++) x[i] = 0.0;
    1688:     } else {
    1689: #elif defined(PETSC_PREFER_FORTRAN_FOR_MEMZERO)
    1690:     if (!(((long) a) % sizeof(PetscScalar)) && !(n % sizeof(PetscScalar))) {
    1691:       PetscInt len = n/sizeof(PetscScalar);
    1692:       fortranzero_(&len,(PetscScalar*)a);
    1693:     } else {
    1694: #endif
    1695: #if defined(PETSC_PREFER_BZERO)
    1696:       bzero((char *)a,n);
    1697: #else
    1698:       memset((char*)a,0,n);
    1699: #endif
    1700: #if defined(PETSC_PREFER_ZERO_FOR_MEMZERO) || defined(PETSC_PREFER_FORTRAN_FOR_MEMZERO)
    1701:     }
    1702: #endif
    1703:   }
    1704:   return 0;
    1705: }

    1707: /*MC
    1708:    PetscPrefetchBlock - Prefetches a block of memory

    1710:    Synopsis:
    1711:     #include "petscsys.h"
    1712:     void PetscPrefetchBlock(const anytype *a,size_t n,int rw,int t)

    1714:    Not Collective

    1716:    Input Parameters:
    1717: +  a - pointer to first element to fetch (any type but usually PetscInt or PetscScalar)
    1718: .  n - number of elements to fetch
    1719: .  rw - 1 if the memory will be written to, otherwise 0 (ignored by many processors)
    1720: -  t - temporal locality (PETSC_PREFETCH_HINT_{NTA,T0,T1,T2}), see note

    1722:    Level: developer

    1724:    Notes:
    1725:    The last two arguments (rw and t) must be compile-time constants.

    1727:    Adopting Intel's x86/x86-64 conventions, there are four levels of temporal locality.  Not all architectures offer
    1728:    equivalent locality hints, but the following macros are always defined to their closest analogue.
    1729: +  PETSC_PREFETCH_HINT_NTA - Non-temporal.  Prefetches directly to L1, evicts to memory (skips higher level cache unless it was already there when prefetched).
    1730: .  PETSC_PREFETCH_HINT_T0 - Fetch to all levels of cache and evict to the closest level.  Use this when the memory will be reused regularly despite necessary eviction from L1.
    1731: .  PETSC_PREFETCH_HINT_T1 - Fetch to level 2 and higher (not L1).
    1732: -  PETSC_PREFETCH_HINT_T2 - Fetch to high-level cache only.  (On many systems, T0 and T1 are equivalent.)

    1734:    This function does nothing on architectures that do not support prefetch and never errors (even if passed an invalid
    1735:    address).

    1737:    Concepts: memory
    1738: M*/
    1739: #define PetscPrefetchBlock(a,n,rw,t) do {                               \
    1740:     const char *_p = (const char*)(a),*_end = (const char*)((a)+(n));   \
    1741:     for ( ; _p < _end; _p += PETSC_LEVEL1_DCACHE_LINESIZE) PETSC_Prefetch(_p,(rw),(t)); \
    1742:   } while (0)

    1744: /*
    1745:       Determine if some of the kernel computation routines use
    1746:    Fortran (rather than C) for the numerical calculations. On some machines
    1747:    and compilers (like complex numbers) the Fortran version of the routines
    1748:    is faster than the C/C++ versions. The flag --with-fortran-kernels
    1749:    should be used with ./configure to turn these on.
    1750: */
    1751: #if defined(PETSC_USE_FORTRAN_KERNELS)

    1753: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTCRL)
    1754: #define PETSC_USE_FORTRAN_KERNEL_MULTCRL
    1755: #endif

    1757: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTAIJPERM)
    1758: #define PETSC_USE_FORTRAN_KERNEL_MULTAIJPERM
    1759: #endif

    1761: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTAIJ)
    1762: #define PETSC_USE_FORTRAN_KERNEL_MULTAIJ
    1763: #endif

    1765: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTTRANSPOSEAIJ)
    1766: #define PETSC_USE_FORTRAN_KERNEL_MULTTRANSPOSEAIJ
    1767: #endif

    1769: #if !defined(PETSC_USE_FORTRAN_KERNEL_NORM)
    1770: #define PETSC_USE_FORTRAN_KERNEL_NORM
    1771: #endif

    1773: #if !defined(PETSC_USE_FORTRAN_KERNEL_MAXPY)
    1774: #define PETSC_USE_FORTRAN_KERNEL_MAXPY
    1775: #endif

    1777: #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ)
    1778: #define PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ
    1779: #endif

    1781: #if !defined(PETSC_USE_FORTRAN_KERNEL_RELAXAIJ)
    1782: #define PETSC_USE_FORTRAN_KERNEL_RELAXAIJ
    1783: #endif

    1785: #if !defined(PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ)
    1786: #define PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ
    1787: #endif

    1789: #if !defined(PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ)
    1790: #define PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ
    1791: #endif

    1793: #if !defined(PETSC_USE_FORTRAN_KERNEL_MDOT)
    1794: #define PETSC_USE_FORTRAN_KERNEL_MDOT
    1795: #endif

    1797: #if !defined(PETSC_USE_FORTRAN_KERNEL_XTIMESY)
    1798: #define PETSC_USE_FORTRAN_KERNEL_XTIMESY
    1799: #endif

    1801: #if !defined(PETSC_USE_FORTRAN_KERNEL_AYPX)
    1802: #define PETSC_USE_FORTRAN_KERNEL_AYPX
    1803: #endif

    1805: #if !defined(PETSC_USE_FORTRAN_KERNEL_WAXPY)
    1806: #define PETSC_USE_FORTRAN_KERNEL_WAXPY
    1807: #endif

    1809: #endif

    1811: /*
    1812:     Macros for indicating code that should be compiled with a C interface,
    1813:    rather than a C++ interface. Any routines that are dynamically loaded
    1814:    (such as the PCCreate_XXX() routines) must be wrapped so that the name
    1815:    mangler does not change the functions symbol name. This just hides the
    1816:    ugly extern "C" {} wrappers.
    1817: */
    1818: #if defined(__cplusplus)
    1819: #define EXTERN_C_BEGIN extern "C" {
    1820: #define EXTERN_C_END }
    1821: #else
    1822: #define EXTERN_C_BEGIN
    1823: #define EXTERN_C_END
    1824: #endif

    1826: /* --------------------------------------------------------------------*/

    1828: /*MC
    1829:     MPI_Comm - the basic object used by MPI to determine which processes are involved in a
    1830:         communication

    1832:    Level: beginner

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

    1836: .seealso: PETSC_COMM_WORLD, PETSC_COMM_SELF
    1837: M*/

    1839: /*MC
    1840:     PetscScalar - PETSc type that represents either a double precision real number, a double precision
    1841:        complex number, a single precision real number, a long double or an int - if the code is configured
    1842:        with --with-scalar-type=real,complex --with-precision=single,double,longdouble,int,matsingle

    1845:    Level: beginner

    1847: .seealso: PetscReal, PassiveReal, PassiveScalar, MPIU_SCALAR, PetscInt
    1848: M*/

    1850: /*MC
    1851:     PetscComplex - PETSc type that represents a complex number with precision matching that of PetscReal.

    1853:    Synopsis:
    1854:    #define PETSC_DESIRE_COMPLEX
    1855:    #include <petscsys.h>
    1856:    PetscComplex number = 1. + 2.*PETSC_i;

    1858:    Level: beginner

    1860:    Note:
    1861:    Complex numbers are automatically available if PETSc was configured --with-scalar-type=complex (in which case
    1862:    PetscComplex will match PetscScalar), otherwise the macro PETSC_DESIRE_COMPLEX must be defined before including any
    1863:    PETSc headers. If the compiler supports complex numbers, PetscComplex and associated variables and functions will be
    1864:    defined and PETSC_HAVE_COMPLEX will be set.

    1866: .seealso: PetscReal, PetscComplex, MPIU_COMPLEX, PetscInt, PETSC_i
    1867: M*/

    1869: /*MC
    1870:     PetscReal - PETSc type that represents a real number version of PetscScalar

    1872:    Level: beginner

    1874: .seealso: PetscScalar, PassiveReal, PassiveScalar
    1875: M*/

    1877: /*MC
    1878:     PassiveScalar - PETSc type that represents a PetscScalar
    1879:    Level: beginner

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

    1884: .seealso: PetscReal, PassiveReal, PetscScalar
    1885: M*/

    1887: /*MC
    1888:     PassiveReal - PETSc type that represents a PetscReal

    1890:    Level: beginner

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

    1895: .seealso: PetscScalar, PetscReal, PassiveScalar
    1896: M*/

    1898: /*MC
    1899:     MPIU_SCALAR - MPI datatype corresponding to PetscScalar

    1901:    Level: beginner

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

    1906: .seealso: PetscReal, PassiveReal, PassiveScalar, PetscScalar, MPIU_INT
    1907: M*/

    1909: #if defined(PETSC_HAVE_MPIIO)
    1910: #if !defined(PETSC_WORDS_BIGENDIAN)
    1911: PETSC_EXTERN PetscErrorCode MPIU_File_write_all(MPI_File,void*,PetscMPIInt,MPI_Datatype,MPI_Status*);
    1912: PETSC_EXTERN PetscErrorCode MPIU_File_read_all(MPI_File,void*,PetscMPIInt,MPI_Datatype,MPI_Status*);
    1913: #else
    1914: #define MPIU_File_write_all(a,b,c,d,e) MPI_File_write_all(a,b,c,d,e)
    1915: #define MPIU_File_read_all(a,b,c,d,e) MPI_File_read_all(a,b,c,d,e)
    1916: #endif
    1917: #endif

    1919: /* the following petsc_static_inline require petscerror.h */

    1921: /* Limit MPI to 32-bits */
    1922: #define PETSC_MPI_INT_MAX  2147483647
    1923: #define PETSC_MPI_INT_MIN -2147483647
    1924: /* Limit BLAS to 32-bits */
    1925: #define PETSC_BLAS_INT_MAX  2147483647
    1926: #define PETSC_BLAS_INT_MIN -2147483647

    1930: PETSC_STATIC_INLINE PetscErrorCode PetscBLASIntCast(PetscInt a,PetscBLASInt *b)
    1931: {
    1933: #if defined(PETSC_USE_64BIT_INDICES) && !defined(PETSC_HAVE_64BIT_BLAS_INDICES)
    1934:   if ((a) > PETSC_BLAS_INT_MAX) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Array too long for BLAS/LAPACK");
    1935: #endif
    1936:   *b =  (PetscBLASInt)(a);
    1937:   return(0);
    1938: }

    1942: PETSC_STATIC_INLINE PetscErrorCode PetscMPIIntCast(PetscInt a,PetscMPIInt *b)
    1943: {
    1945: #if defined(PETSC_USE_64BIT_INDICES)
    1946:   if ((a) > PETSC_MPI_INT_MAX) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Array too long for MPI");
    1947: #endif
    1948:   *b =  (PetscMPIInt)(a);
    1949:   return(0);
    1950: }

    1953: /*
    1954:      The IBM include files define hz, here we hide it so that it may be used as a regular user variable.
    1955: */
    1956: #if defined(hz)
    1957: #undef hz
    1958: #endif

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

    1963: #if defined(PETSC_HAVE_LIMITS_H)
    1964: #include <limits.h>
    1965: #endif
    1966: #if defined(PETSC_HAVE_SYS_PARAM_H)
    1967: #include <sys/param.h>
    1968: #endif
    1969: #if defined(PETSC_HAVE_SYS_TYPES_H)
    1970: #include <sys/types.h>
    1971: #endif
    1972: #if defined(MAXPATHLEN)
    1973: #  define PETSC_MAX_PATH_LEN     MAXPATHLEN
    1974: #elif defined(MAX_PATH)
    1975: #  define PETSC_MAX_PATH_LEN     MAX_PATH
    1976: #elif defined(_MAX_PATH)
    1977: #  define PETSC_MAX_PATH_LEN     _MAX_PATH
    1978: #else
    1979: #  define PETSC_MAX_PATH_LEN     4096
    1980: #endif

    1982: /* Special support for C++ */
    1983: #if defined(PETSC_CLANGUAGE_CXX) && defined(__cplusplus)
    1984: #include <petscsys.hh>
    1985: #endif

    1987: /*MC

    1989:     UsingFortran - Fortran can be used with PETSc in four distinct approaches

    1991: $    1) classic Fortran 77 style
    1992: $#include "finclude/petscXXX.h" to work with material from the XXX component of PETSc
    1993: $       XXX variablename
    1994: $      You cannot use this approach if you wish to use the Fortran 90 specific PETSc routines
    1995: $      which end in F90; such as VecGetArrayF90()
    1996: $
    1997: $    2) classic Fortran 90 style
    1998: $#include "finclude/petscXXX.h"
    1999: $#include "finclude/petscXXX.h90" to work with material from the XXX component of PETSc
    2000: $       XXX variablename
    2001: $
    2002: $    3) Using Fortran modules
    2003: $#include "finclude/petscXXXdef.h"
    2004: $         use petscXXXX
    2005: $       XXX variablename
    2006: $
    2007: $    4) Use Fortran modules and Fortran data types for PETSc types
    2008: $#include "finclude/petscXXXdef.h"
    2009: $         use petscXXXX
    2010: $       type(XXX) variablename
    2011: $      To use this approach you must ./configure PETSc with the additional
    2012: $      option --with-fortran-datatypes You cannot use the type(XXX) declaration approach without using Fortran modules

    2014:     Finally if you absolutely do not want to use any #include you can use either

    2016: $    3a) skip the #include BUT you cannot use any PETSc data type names like Vec, Mat, PetscInt, PetscErrorCode etc
    2017: $        and you must declare the variables as integer, for example
    2018: $        integer variablename
    2019: $
    2020: $    4a) skip the #include, you use the object types like type(Vec) type(Mat) but cannot use the data type
    2021: $        names like PetscErrorCode, PetscInt etc. again for those you must use integer

    2023:    We recommend either 2 or 3. Approaches 2 and 3 provide type checking for most PETSc function calls; 4 has type checking
    2024: for only a few PETSc functions.

    2026:    Fortran type checking with interfaces is strick, this means you cannot pass a scalar value when an array value
    2027: is expected (even though it is legal Fortran). For example when setting a single value in a matrix with MatSetValues()
    2028: you cannot have something like
    2029: $      PetscInt row,col
    2030: $      PetscScalar val
    2031: $        ...
    2032: $      call MatSetValues(mat,1,row,1,col,val,INSERT_VALUES,ierr)
    2033: You must instead have
    2034: $      PetscInt row(1),col(1)
    2035: $      PetscScalar val(1)
    2036: $        ...
    2037: $      call MatSetValues(mat,1,row,1,col,val,INSERT_VALUES,ierr)

    2040:     See the example src/vec/vec/examples/tutorials/ex20f90.F90 for an example that can use all four approaches

    2042:     Developer Notes: The finclude/petscXXXdef.h contain all the #defines (would be typedefs in C code) these
    2043:      automatically include their predecessors; for example finclude/petscvecdef.h includes finclude/petscisdef.h

    2045:      The finclude/petscXXXX.h contain all the parameter statements for that package. These automatically include
    2046:      their finclude/petscXXXdef.h file but DO NOT automatically include their predecessors;  for example
    2047:      finclude/petscvec.h does NOT automatically include finclude/petscis.h

    2049:      The finclude/ftn-custom/petscXXXdef.h90 are not intended to be used directly in code, they define the
    2050:      Fortran data type type(XXX) (for example type(Vec)) when PETSc is ./configure with the --with-fortran-datatypes option.

    2052:      The finclude/ftn-custom/petscXXX.h90 (not included directly by code) contain interface definitions for
    2053:      the PETSc Fortran stubs that have different bindings then their C version (for example VecGetArrayF90).

    2055:      The finclude/ftn-auto/petscXXX.h90 (not included directly by code) contain interface definitions generated
    2056:      automatically by "make allfortranstubs".

    2058:      The finclude/petscXXX.h90 includes the custom finclude/ftn-custom/petscXXX.h90 and if ./configure
    2059:      was run with --with-fortran-interfaces it also includes the finclude/ftn-auto/petscXXX.h90 These DO NOT automatically
    2060:      include their predecessors

    2062:     Level: beginner

    2064: M*/

    2066: PETSC_EXTERN PetscErrorCode PetscGetArchType(char[],size_t);
    2067: PETSC_EXTERN PetscErrorCode PetscGetHostName(char[],size_t);
    2068: PETSC_EXTERN PetscErrorCode PetscGetUserName(char[],size_t);
    2069: PETSC_EXTERN PetscErrorCode PetscGetProgramName(char[],size_t);
    2070: PETSC_EXTERN PetscErrorCode PetscSetProgramName(const char[]);
    2071: PETSC_EXTERN PetscErrorCode PetscGetDate(char[],size_t);
    2072: PETSC_EXTERN PetscErrorCode PetscGetVersion(char[], size_t);

    2074: PETSC_EXTERN PetscErrorCode PetscSortInt(PetscInt,PetscInt[]);
    2075: PETSC_EXTERN PetscErrorCode PetscSortRemoveDupsInt(PetscInt*,PetscInt[]);
    2076: PETSC_EXTERN PetscErrorCode PetscFindInt(PetscInt, PetscInt, const PetscInt[], PetscInt*);
    2077: PETSC_EXTERN PetscErrorCode PetscSortIntWithPermutation(PetscInt,const PetscInt[],PetscInt[]);
    2078: PETSC_EXTERN PetscErrorCode PetscSortStrWithPermutation(PetscInt,const char*[],PetscInt[]);
    2079: PETSC_EXTERN PetscErrorCode PetscSortIntWithArray(PetscInt,PetscInt[],PetscInt[]);
    2080: PETSC_EXTERN PetscErrorCode PetscSortIntWithArrayPair(PetscInt,PetscInt*,PetscInt*,PetscInt*);
    2081: PETSC_EXTERN PetscErrorCode PetscSortMPIInt(PetscInt,PetscMPIInt[]);
    2082: PETSC_EXTERN PetscErrorCode PetscSortRemoveDupsMPIInt(PetscInt*,PetscMPIInt[]);
    2083: PETSC_EXTERN PetscErrorCode PetscSortMPIIntWithArray(PetscMPIInt,PetscMPIInt[],PetscMPIInt[]);
    2084: PETSC_EXTERN PetscErrorCode PetscSortIntWithScalarArray(PetscInt,PetscInt[],PetscScalar[]);
    2085: PETSC_EXTERN PetscErrorCode PetscSortReal(PetscInt,PetscReal[]);
    2086: PETSC_EXTERN PetscErrorCode PetscSortRealWithPermutation(PetscInt,const PetscReal[],PetscInt[]);
    2087: PETSC_EXTERN PetscErrorCode PetscSortSplit(PetscInt,PetscInt,PetscScalar[],PetscInt[]);
    2088: PETSC_EXTERN PetscErrorCode PetscSortSplitReal(PetscInt,PetscInt,PetscReal[],PetscInt[]);
    2089: PETSC_EXTERN PetscErrorCode PetscProcessTree(PetscInt,const PetscBool [],const PetscInt[],PetscInt*,PetscInt**,PetscInt**,PetscInt**,PetscInt**);
    2090: PETSC_EXTERN PetscErrorCode PetscMergeIntArrayPair(PetscInt,const PetscInt*,const PetscInt*,PetscInt,const PetscInt*,const PetscInt*,PetscInt*,PetscInt**,PetscInt**);

    2092: PETSC_EXTERN PetscErrorCode PetscSetDisplay(void);
    2093: PETSC_EXTERN PetscErrorCode PetscGetDisplay(char[],size_t);

    2095: /*J
    2096:     PetscRandomType - String with the name of a PETSc randomizer

    2098:    Level: beginner

    2100:    Notes: to use the SPRNG you must have ./configure PETSc
    2101:    with the option --download-sprng

    2103: .seealso: PetscRandomSetType(), PetscRandom, PetscRandomCreate()
    2104: J*/
    2105: typedef const char* PetscRandomType;
    2106: #define PETSCRAND       "rand"
    2107: #define PETSCRAND48     "rand48"
    2108: #define PETSCSPRNG      "sprng"

    2110: /* Logging support */
    2111: PETSC_EXTERN PetscClassId PETSC_RANDOM_CLASSID;

    2113: PETSC_EXTERN PetscErrorCode PetscRandomInitializePackage(void);

    2115: /*S
    2116:      PetscRandom - Abstract PETSc object that manages generating random numbers

    2118:    Level: intermediate

    2120:   Concepts: random numbers

    2122: .seealso:  PetscRandomCreate(), PetscRandomGetValue(), PetscRandomType
    2123: S*/
    2124: typedef struct _p_PetscRandom*   PetscRandom;

    2126: /* Dynamic creation and loading functions */
    2127: PETSC_EXTERN PetscFunctionList PetscRandomList;
    2128: PETSC_EXTERN PetscBool         PetscRandomRegisterAllCalled;

    2130: PETSC_EXTERN PetscErrorCode PetscRandomRegisterAll(void);
    2131: PETSC_EXTERN PetscErrorCode PetscRandomRegister(const char[],PetscErrorCode (*)(PetscRandom));
    2132: PETSC_EXTERN PetscErrorCode PetscRandomSetType(PetscRandom, PetscRandomType);
    2133: PETSC_EXTERN PetscErrorCode PetscRandomSetFromOptions(PetscRandom);
    2134: PETSC_EXTERN PetscErrorCode PetscRandomGetType(PetscRandom, PetscRandomType*);
    2135:  PETSC_EXTERN PetscErrorCode PetscRandomViewFromOptions(PetscRandom,const char[],const char[]);
    2136: PETSC_EXTERN PetscErrorCode PetscRandomView(PetscRandom,PetscViewer);

    2138: PETSC_EXTERN PetscErrorCode PetscRandomCreate(MPI_Comm,PetscRandom*);
    2139: PETSC_EXTERN PetscErrorCode PetscRandomGetValue(PetscRandom,PetscScalar*);
    2140: PETSC_EXTERN PetscErrorCode PetscRandomGetValueReal(PetscRandom,PetscReal*);
    2141: PETSC_EXTERN PetscErrorCode PetscRandomGetInterval(PetscRandom,PetscScalar*,PetscScalar*);
    2142: PETSC_EXTERN PetscErrorCode PetscRandomSetInterval(PetscRandom,PetscScalar,PetscScalar);
    2143: PETSC_EXTERN PetscErrorCode PetscRandomSetSeed(PetscRandom,unsigned long);
    2144: PETSC_EXTERN PetscErrorCode PetscRandomGetSeed(PetscRandom,unsigned long *);
    2145: PETSC_EXTERN PetscErrorCode PetscRandomSeed(PetscRandom);
    2146: PETSC_EXTERN PetscErrorCode PetscRandomDestroy(PetscRandom*);

    2148: PETSC_EXTERN PetscErrorCode PetscGetFullPath(const char[],char[],size_t);
    2149: PETSC_EXTERN PetscErrorCode PetscGetRelativePath(const char[],char[],size_t);
    2150: PETSC_EXTERN PetscErrorCode PetscGetWorkingDirectory(char[],size_t);
    2151: PETSC_EXTERN PetscErrorCode PetscGetRealPath(const char[],char[]);
    2152: PETSC_EXTERN PetscErrorCode PetscGetHomeDirectory(char[],size_t);
    2153: PETSC_EXTERN PetscErrorCode PetscTestFile(const char[],char,PetscBool *);
    2154: PETSC_EXTERN PetscErrorCode PetscTestDirectory(const char[],char,PetscBool *);

    2156: PETSC_EXTERN PetscErrorCode PetscBinaryRead(int,void*,PetscInt,PetscDataType);
    2157: PETSC_EXTERN PetscErrorCode PetscBinarySynchronizedRead(MPI_Comm,int,void*,PetscInt,PetscDataType);
    2158: PETSC_EXTERN PetscErrorCode PetscBinarySynchronizedWrite(MPI_Comm,int,void*,PetscInt,PetscDataType,PetscBool );
    2159: PETSC_EXTERN PetscErrorCode PetscBinaryWrite(int,void*,PetscInt,PetscDataType,PetscBool );
    2160: PETSC_EXTERN PetscErrorCode PetscBinaryOpen(const char[],PetscFileMode,int *);
    2161: PETSC_EXTERN PetscErrorCode PetscBinaryClose(int);
    2162: PETSC_EXTERN PetscErrorCode PetscSharedTmp(MPI_Comm,PetscBool  *);
    2163: PETSC_EXTERN PetscErrorCode PetscSharedWorkingDirectory(MPI_Comm,PetscBool  *);
    2164: PETSC_EXTERN PetscErrorCode PetscGetTmp(MPI_Comm,char[],size_t);
    2165: PETSC_EXTERN PetscErrorCode PetscFileRetrieve(MPI_Comm,const char[],char[],size_t,PetscBool *);
    2166: PETSC_EXTERN PetscErrorCode PetscLs(MPI_Comm,const char[],char[],size_t,PetscBool *);
    2167: PETSC_EXTERN PetscErrorCode PetscOpenSocket(char*,int,int*);
    2168: PETSC_EXTERN PetscErrorCode PetscWebServe(MPI_Comm,int);

    2170: /*
    2171:    In binary files variables are stored using the following lengths,
    2172:   regardless of how they are stored in memory on any one particular
    2173:   machine. Use these rather then sizeof() in computing sizes for
    2174:   PetscBinarySeek().
    2175: */
    2176: #define PETSC_BINARY_INT_SIZE   (32/8)
    2177: #define PETSC_BINARY_FLOAT_SIZE  (32/8)
    2178: #define PETSC_BINARY_CHAR_SIZE  (8/8)
    2179: #define PETSC_BINARY_SHORT_SIZE  (16/8)
    2180: #define PETSC_BINARY_DOUBLE_SIZE  (64/8)
    2181: #define PETSC_BINARY_SCALAR_SIZE  sizeof(PetscScalar)

    2183: /*E
    2184:   PetscBinarySeekType - argument to PetscBinarySeek()

    2186:   Level: advanced

    2188: .seealso: PetscBinarySeek(), PetscBinarySynchronizedSeek()
    2189: E*/
    2190: typedef enum {PETSC_BINARY_SEEK_SET = 0,PETSC_BINARY_SEEK_CUR = 1,PETSC_BINARY_SEEK_END = 2} PetscBinarySeekType;
    2191: PETSC_EXTERN PetscErrorCode PetscBinarySeek(int,off_t,PetscBinarySeekType,off_t*);
    2192: PETSC_EXTERN PetscErrorCode PetscBinarySynchronizedSeek(MPI_Comm,int,off_t,PetscBinarySeekType,off_t*);
    2193: PETSC_EXTERN PetscErrorCode PetscByteSwap(void *,PetscDataType,PetscInt);

    2195: PETSC_EXTERN PetscErrorCode PetscSetDebugTerminal(const char[]);
    2196: PETSC_EXTERN PetscErrorCode PetscSetDebugger(const char[],PetscBool );
    2197: PETSC_EXTERN PetscErrorCode PetscSetDefaultDebugger(void);
    2198: PETSC_EXTERN PetscErrorCode PetscSetDebuggerFromString(const char*);
    2199: PETSC_EXTERN PetscErrorCode PetscAttachDebugger(void);
    2200: PETSC_EXTERN PetscErrorCode PetscStopForDebugger(void);

    2202: PETSC_EXTERN PetscErrorCode PetscGatherNumberOfMessages(MPI_Comm,const PetscMPIInt[],const PetscMPIInt[],PetscMPIInt*);
    2203: PETSC_EXTERN PetscErrorCode PetscGatherMessageLengths(MPI_Comm,PetscMPIInt,PetscMPIInt,const PetscMPIInt[],PetscMPIInt**,PetscMPIInt**);
    2204: PETSC_EXTERN PetscErrorCode PetscGatherMessageLengths2(MPI_Comm,PetscMPIInt,PetscMPIInt,const PetscMPIInt[],const PetscMPIInt[],PetscMPIInt**,PetscMPIInt**,PetscMPIInt**);
    2205: PETSC_EXTERN PetscErrorCode PetscPostIrecvInt(MPI_Comm,PetscMPIInt,PetscMPIInt,const PetscMPIInt[],const PetscMPIInt[],PetscInt***,MPI_Request**);
    2206: PETSC_EXTERN PetscErrorCode PetscPostIrecvScalar(MPI_Comm,PetscMPIInt,PetscMPIInt,const PetscMPIInt[],const PetscMPIInt[],PetscScalar***,MPI_Request**);
    2207: PETSC_EXTERN PetscErrorCode PetscCommBuildTwoSided(MPI_Comm,PetscMPIInt,MPI_Datatype,PetscInt,const PetscMPIInt*,const void*,PetscInt*,PetscMPIInt**,void*) PetscAttrMPIPointerWithType(6,3);

    2209: /*E
    2210:     PetscBuildTwoSidedType - algorithm for setting up two-sided communication

    2212: $  PETSC_BUILDTWOSIDED_ALLREDUCE - classical algorithm using an MPI_Allreduce with
    2213: $      a buffer of length equal to the communicator size. Not memory-scalable due to
    2214: $      the large reduction size. Requires only MPI-1.
    2215: $  PETSC_BUILDTWOSIDED_IBARRIER - nonblocking algorithm based on MPI_Issend and MPI_Ibarrier.
    2216: $      Proved communication-optimal in Hoefler, Siebert, and Lumsdaine (2010). Requires MPI-3.

    2218:    Level: developer

    2220: .seealso: PetscCommBuildTwoSided(), PetscCommBuildTwoSidedSetType(), PetscCommBuildTwoSidedGetType()
    2221: E*/
    2222: typedef enum {
    2223:   PETSC_BUILDTWOSIDED_NOTSET = -1,
    2224:   PETSC_BUILDTWOSIDED_ALLREDUCE = 0,
    2225:   PETSC_BUILDTWOSIDED_IBARRIER = 1
    2226:   /* Updates here must be accompanied by updates in finclude/petscsys.h and the string array in mpits.c */
    2227: } PetscBuildTwoSidedType;
    2228: PETSC_EXTERN const char *const PetscBuildTwoSidedTypes[];
    2229: PETSC_EXTERN PetscErrorCode PetscCommBuildTwoSidedSetType(MPI_Comm,PetscBuildTwoSidedType);
    2230: PETSC_EXTERN PetscErrorCode PetscCommBuildTwoSidedGetType(MPI_Comm,PetscBuildTwoSidedType*);

    2232: PETSC_EXTERN PetscErrorCode PetscSSEIsEnabled(MPI_Comm,PetscBool  *,PetscBool  *);

    2234: /*E
    2235:   InsertMode - Whether entries are inserted or added into vectors or matrices

    2237:   Level: beginner

    2239: .seealso: VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
    2240:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(),
    2241:           MatSetValuesBlockedLocal(), MatSetValuesLocal(), VecScatterBegin(), VecScatterEnd()
    2242: E*/
    2243:  typedef enum {NOT_SET_VALUES, INSERT_VALUES, ADD_VALUES, MAX_VALUES, INSERT_ALL_VALUES, ADD_ALL_VALUES, INSERT_BC_VALUES, ADD_BC_VALUES} InsertMode;

    2245: /*MC
    2246:     INSERT_VALUES - Put a value into a vector or matrix, overwrites any previous value

    2248:     Level: beginner

    2250: .seealso: InsertMode, VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
    2251:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(), ADD_VALUES,
    2252:           MatSetValuesBlockedLocal(), MatSetValuesLocal(), VecScatterBegin(), VecScatterEnd(), MAX_VALUES

    2254: M*/

    2256: /*MC
    2257:     ADD_VALUES - Adds a value into a vector or matrix, if there previously was no value, just puts the
    2258:                 value into that location

    2260:     Level: beginner

    2262: .seealso: InsertMode, VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
    2263:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(), INSERT_VALUES,
    2264:           MatSetValuesBlockedLocal(), MatSetValuesLocal(), VecScatterBegin(), VecScatterEnd(), MAX_VALUES

    2266: M*/

    2268: /*MC
    2269:     MAX_VALUES - Puts the maximum of the scattered/gathered value and the current value into each location

    2271:     Level: beginner

    2273: .seealso: InsertMode, VecScatterBegin(), VecScatterEnd(), ADD_VALUES, INSERT_VALUES

    2275: M*/

    2277: PETSC_EXTERN MPI_Comm PetscObjectComm(PetscObject);

    2279: /*S
    2280:    PetscSubcomm - Context of MPI subcommunicators, used by PCREDUNDANT

    2282:    Level: advanced

    2284:    Concepts: communicator, create
    2285: S*/
    2286: typedef struct _n_PetscSubcomm* PetscSubcomm;

    2288: struct _n_PetscSubcomm {
    2289:   MPI_Comm   parent;      /* parent communicator */
    2290:   MPI_Comm   dupparent;   /* duplicate parent communicator, under which the processors of this subcomm have contiguous rank */
    2291:   MPI_Comm   comm;        /* this communicator */
    2292:   PetscInt   n;           /* num of subcommunicators under the parent communicator */
    2293:   PetscInt   color;       /* color of processors belong to this communicator */
    2294: };

    2296: typedef enum {PETSC_SUBCOMM_GENERAL=0,PETSC_SUBCOMM_CONTIGUOUS=1,PETSC_SUBCOMM_INTERLACED=2} PetscSubcommType;
    2297: PETSC_EXTERN const char *const PetscSubcommTypes[];

    2299: PETSC_EXTERN PetscErrorCode PetscSubcommCreate(MPI_Comm,PetscSubcomm*);
    2300: PETSC_EXTERN PetscErrorCode PetscSubcommDestroy(PetscSubcomm*);
    2301: PETSC_EXTERN PetscErrorCode PetscSubcommSetNumber(PetscSubcomm,PetscInt);
    2302: PETSC_EXTERN PetscErrorCode PetscSubcommSetType(PetscSubcomm,PetscSubcommType);
    2303: PETSC_EXTERN PetscErrorCode PetscSubcommSetTypeGeneral(PetscSubcomm,PetscMPIInt,PetscMPIInt,PetscMPIInt);

    2305: /*S
    2306:    PetscSegBuffer - a segmented extendable buffer

    2308:    Level: developer

    2310: .seealso: PetscSegBufferCreate(), PetscSegBufferGet(), PetscSegBufferExtract(), PetscSegBufferDestroy()
    2311: S*/
    2312: typedef struct _n_PetscSegBuffer *PetscSegBuffer;
    2313: PETSC_EXTERN PetscErrorCode PetscSegBufferCreate(size_t,size_t,PetscSegBuffer*);
    2314: PETSC_EXTERN PetscErrorCode PetscSegBufferDestroy(PetscSegBuffer*);
    2315: PETSC_EXTERN PetscErrorCode PetscSegBufferGet(PetscSegBuffer,size_t,void*);
    2316: PETSC_EXTERN PetscErrorCode PetscSegBufferExtractAlloc(PetscSegBuffer,void*);
    2317: PETSC_EXTERN PetscErrorCode PetscSegBufferExtractTo(PetscSegBuffer,void*);
    2318: PETSC_EXTERN PetscErrorCode PetscSegBufferExtractInPlace(PetscSegBuffer,void*);
    2319: PETSC_EXTERN PetscErrorCode PetscSegBufferGetSize(PetscSegBuffer,size_t*);
    2320: PETSC_EXTERN PetscErrorCode PetscSegBufferUnuse(PetscSegBuffer,size_t);

    2323:  * prevents the compiler from completely erasing the stub. This is called in inner loops so it has to be as fast as
    2324:  * possible. */
    2325: PETSC_STATIC_INLINE PetscErrorCode PetscSegBufferGetInts(PetscSegBuffer seg,PetscInt count,PetscInt *PETSC_RESTRICT *slot) {return PetscSegBufferGet(seg,count,(void**)slot);}

    2327: /* Reset __FUNCT__ in case the user does not define it themselves */

    2331: #endif