Actual source code: petscsystypes.h

      1: #if !defined(PETSCSYSTYPES_H)
      2: #define PETSCSYSTYPES_H

      4: #include <petscconf.h>
      5: #include <petscfix.h>

      7: /*MC
      8:     PetscErrorCode - datatype used for return error code from almost all PETSc functions

     10:     Level: beginner

     12: .seealso: CHKERRQ, SETERRQ
     13: M*/
     14: typedef int PetscErrorCode;

     16: /*MC

     18:     PetscClassId - A unique id used to identify each PETSc class.

     20:     Notes:
     21:     Use PetscClassIdRegister() to obtain a new value for a new class being created. Usually
     22:          XXXInitializePackage() calls it for each class it defines.

     24:     Developer Notes:
     25:     Internal integer stored in the _p_PetscObject data structure.
     26:          These are all computed by an offset from the lowest one, PETSC_SMALLEST_CLASSID.

     28:     Level: developer

     30: .seealso: PetscClassIdRegister(), PetscLogEventRegister(), PetscHeaderCreate()
     31: M*/
     32: typedef int PetscClassId;

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

     37:     Level: intermediate

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

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

     46: .seealso: PetscBLASInt, PetscInt, PetscMPIIntCast()

     48: M*/
     49: typedef int PetscMPIInt;

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

     54:     Level: intermediate

     56: .seealso: PetscOptionsGetEnum(), PetscOptionsEnum(), PetscBagRegisterEnum()
     57: M*/
     58: typedef enum { ENUM_DUMMY } PetscEnum;

     60: typedef short PetscShort;
     61: typedef char  PetscChar;
     62: typedef float PetscFloat;

     64: /*MC
     65:   PetscInt - PETSc type that represents an integer, used primarily to
     66:       represent size of arrays and indexing into arrays. Its size can be configured with the option --with-64-bit-indices to be either 32-bit (default) or 64-bit.

     68:   Notes:
     69:   For MPI calls that require datatypes, use MPIU_INT as the datatype for PetscInt. It will automatically work correctly regardless of the size of PetscInt.

     71:   Level: beginner

     73: .seealso: PetscBLASInt, PetscMPIInt, PetscReal, PetscScalar, PetscComplex, PetscInt, MPIU_REAL, MPIU_SCALAR, MPIU_COMPLEX, MPIU_INT
     74: M*/

     76: #if defined(PETSC_HAVE_STDINT_H)
     77: #  include <stdint.h>
     78: #endif
     79: #if defined (PETSC_HAVE_INTTYPES_H)
     80: #  if !defined(__STDC_FORMAT_MACROS)
     81: #    define __STDC_FORMAT_MACROS /* required for using PRId64 from c++ */
     82: #  endif
     83: #  include <inttypes.h>
     84: #  if !defined(PRId64)
     85: #    define PRId64 "ld"
     86: #  endif
     87: #endif

     89: #if defined(PETSC_HAVE_STDINT_H) && defined(PETSC_HAVE_INTTYPES_H) && defined(PETSC_HAVE_MPI_INT64_T) /* MPI_INT64_T is not guaranteed to be a macro */
     90:    typedef int64_t PetscInt64;
     91: #elif (PETSC_SIZEOF_LONG_LONG == 8)
     92:    typedef long long PetscInt64;
     93: #elif defined(PETSC_HAVE___INT64)
     94:    typedef __int64 PetscInt64;
     95: #else
     96: #  error "cannot determine PetscInt64 type"
     97: #endif

     99: #if defined(PETSC_USE_64BIT_INDICES)
    100:    typedef PetscInt64 PetscInt;
    101: #else
    102:    typedef int PetscInt;
    103: #endif

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

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

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

    116:    Installation Notes:
    117:     ./configure automatically determines the size of the integers used by BLAS/LAPACK except when --with-batch is used
    118:     in that situation one must know (by some other means) if the integers used by BLAS/LAPACK are 64 bit and if so pass the flag --known-64-bit-blas-indice

    120:     MATLAB ships with BLAS and LAPACK that use 64 bit integers, for example if you run ./configure with, the option
    121:      --with-blaslapack-lib=[/Applications/MATLAB_R2010b.app/bin/maci64/libmwblas.dylib,/Applications/MATLAB_R2010b.app/bin/maci64/libmwlapack.dylib]

    123:     MKL ships with both 32 and 64 bit integer versions of the BLAS and LAPACK. If you pass the flag -with-64-bit-blas-indices PETSc will link
    124:     against the 64 bit version, otherwise it use the 32 bit version

    126:     OpenBLAS can be built to use 64 bit integers. The ./configure options --download-openblas -with-64-bit-blas-indices will build a 64 bit integer version

    128:     External packages such as hypre, ML, SuperLU etc do not provide any support for passing 64 bit integers to BLAS/LAPACK so cannot
    129:     be used with PETSc when PETSc links against 64 bit integer BLAS/LAPACK. ./configure will generate an error if you attempt to link PETSc against any of
    130:     these external libraries while using 64 bit integer BLAS/LAPACK.

    132:    Level: intermediate

    134: .seealso: PetscMPIInt, PetscInt, PetscBLASIntCast()

    136: M*/
    137: #if defined(PETSC_HAVE_64BIT_BLAS_INDICES)
    138:    typedef PetscInt64 PetscBLASInt;
    139: #else
    140:    typedef int PetscBLASInt;
    141: #endif

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

    146:    Level: beginner

    148:    Developer Note:
    149:    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
    150:       boolean values. It is not easy to have a simple macro that that will work properly in all circumstances with all three mechanisms.

    152: .seealso: PETSC_TRUE, PETSC_FALSE, PetscNot()
    153: E*/
    154: typedef enum { PETSC_FALSE,PETSC_TRUE } PetscBool;

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

    160:    Notes:
    161:    For MPI calls that require datatypes, use MPIU_REAL as the datatype for PetscScalar and MPIU_SUM, MPIU_MAX, etc. for operations.
    162:           They will automatically work correctly regardless of the size of PetscReal.

    164:           See PetscScalar for details on how to ./configure the size of PetscReal.

    166:    Level: beginner

    168: .seealso: PetscScalar, PetscComplex, PetscInt, MPIU_REAL, MPIU_SCALAR, MPIU_COMPLEX, MPIU_INT
    169: M*/

    171: #if defined(PETSC_USE_REAL_SINGLE)
    172:    typedef float PetscReal;
    173: #elif defined(PETSC_USE_REAL_DOUBLE)
    174:    typedef double PetscReal;
    175: #elif defined(PETSC_USE_REAL___FLOAT128)
    176: #  if defined(__cplusplus)
    177:      extern "C" {
    178: #  endif
    179: #  include <quadmath.h>
    180: #  if defined(__cplusplus)
    181:      }
    182: #  endif
    183:    typedef __float128 PetscReal;
    184: #elif defined(PETSC_USE_REAL___FP16)
    185:    typedef __fp16 PetscReal;
    186: #endif /* PETSC_USE_REAL_* */

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

    191:    Synopsis:
    192: #include <petscsys.h>
    193:    PetscComplex number = 1. + 2.*PETSC_i;

    195:    Notes:
    196:    For MPI calls that require datatypes, use MPIU_COMPLEX as the datatype for PetscComplex and MPIU_SUM etc for operations.
    197:           They will automatically work correctly regardless of the size of PetscComplex.

    199:           See PetscScalar for details on how to ./configure the size of PetscReal

    201:           Complex numbers are automatically available if PETSc was able to find a working complex implementation

    203:    Level: beginner

    205: .seealso: PetscReal, PetscScalar, PetscComplex, PetscInt, MPIU_REAL, MPIU_SCALAR, MPIU_COMPLEX, MPIU_INT, PETSC_i
    206: M*/
    207: #if !defined(PETSC_SKIP_COMPLEX)
    208: #  if defined(PETSC_CLANGUAGE_CXX)
    209: #    if !defined(PETSC_USE_REAL___FP16) && !defined(PETSC_USE_REAL___FLOAT128)
    210: #      if defined(__cplusplus) && defined(PETSC_HAVE_CXX_COMPLEX)  /* enable complex for library code */
    211: #        define PETSC_HAVE_COMPLEX 1
    212: #      elif !defined(__cplusplus) && defined(PETSC_HAVE_C99_COMPLEX) && defined(PETSC_HAVE_CXX_COMPLEX)  /* User code only - conditional on libary code complex support */
    213: #        define PETSC_HAVE_COMPLEX 1
    214: #      endif
    215: #    endif
    216: #  else /* !PETSC_CLANGUAGE_CXX */
    217: #    if !defined(PETSC_USE_REAL___FP16)
    218: #      if !defined(__cplusplus) && defined(PETSC_HAVE_C99_COMPLEX) /* enable complex for library code */
    219: #        define PETSC_HAVE_COMPLEX 1
    220: #      elif defined(__cplusplus) && defined(PETSC_HAVE_C99_COMPLEX) && defined(PETSC_HAVE_CXX_COMPLEX)  /* User code only - conditional on libary code complex support */
    221: #        define PETSC_HAVE_COMPLEX 1
    222: #      endif
    223: #    endif
    224: #  endif /* PETSC_CLANGUAGE_CXX */
    225: #endif /* !PETSC_SKIP_COMPLEX */

    227: #if defined(PETSC_HAVE_COMPLEX)
    228: #  if defined(__cplusplus)  /* C++ complex support */
    229: #    if defined(PETSC_HAVE_CUDA)
    230: #      define petsccomplexlib thrust
    231: #      include <thrust/complex.h>
    232: #    else
    233: #      define petsccomplexlib std
    234: #      include <complex>
    235: #    endif
    236: #    if defined(PETSC_USE_REAL_SINGLE)
    237:        typedef petsccomplexlib::complex<float> PetscComplex;
    238: #    elif defined(PETSC_USE_REAL_DOUBLE)
    239:        typedef petsccomplexlib::complex<double> PetscComplex;
    240: #    elif defined(PETSC_USE_REAL___FLOAT128)
    241:        typedef petsccomplexlib::complex<__float128> PetscComplex; /* Notstandard and not expected to work, use __complex128 */
    242: #    endif  /* PETSC_USE_REAL_ */
    243: #    if !defined(PETSC_SKIP_CXX_COMPLEX_FIX)
    244: #      include <petsccxxcomplexfix.h>
    245: #    endif /* ! PETSC_SKIP_CXX_COMPLEX_FIX */
    246: #  else /* c99 complex support */
    247: #    include <complex.h>
    248: #    if defined(PETSC_USE_REAL_SINGLE) || defined(PETSC_USE_REAL___FP16)
    249:        typedef float _Complex PetscComplex;
    250: #    elif defined(PETSC_USE_REAL_DOUBLE)
    251:        typedef double _Complex PetscComplex;
    252: #    elif defined(PETSC_USE_REAL___FLOAT128)
    253:        typedef __complex128 PetscComplex;
    254: #    endif /* PETSC_USE_REAL_* */
    255: #  endif /* !__cplusplus */
    256: #endif /* PETSC_HAVE_COMPLEX */

    258: /*MC
    259:    PetscScalar - PETSc type that represents either a double precision real number, a double precision
    260:        complex number, a single precision real number, a __float128 real or complex or a __fp16 real - if the code is configured
    261:        with --with-scalar-type=real,complex --with-precision=single,double,__float128,__fp16

    263:    Notes:
    264:    For MPI calls that require datatypes, use MPIU_SCALAR as the datatype for PetscScalar and MPIU_SUM, MPIU_MAX etc for operations. They will automatically work correctly regardless of the size of PetscScalar.

    266:    Level: beginner

    268: .seealso: PetscReal, PetscComplex, PetscInt, MPIU_REAL, MPIU_SCALAR, MPIU_COMPLEX, MPIU_INT, PetscRealPart(), PetscImaginaryPart()
    269: M*/

    271: #if defined(PETSC_USE_COMPLEX) && defined(PETSC_HAVE_COMPLEX)
    272:    typedef PetscComplex PetscScalar;
    273: #else /* PETSC_USE_COMPLEX */
    274:    typedef PetscReal PetscScalar;
    275: #endif /* PETSC_USE_COMPLEX */

    277: /*E
    278:     PetscCopyMode  - Determines how an array or PetscObject passed to certain functions is copied or retained by the aggregate PetscObject

    280:    Level: beginner

    282:    For the array input:
    283: $   PETSC_COPY_VALUES - the array values are copied into new space, the user is free to reuse or delete the passed in array
    284: $   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
    285: $                       delete the array. The array MUST have been obtained with PetscMalloc(). Hence this mode cannot be used in Fortran.
    286: $   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
    287: $                       the array but the user must delete the array after the object is destroyed.

    289:    For the PetscObject input:
    290: $   PETSC_COPY_VALUES - the input PetscObject is cloned into the aggregate PetscObject; the user is free to reuse/modify the input PetscObject without side effects.
    291: $   PETSC_OWN_POINTER - the input PetscObject is referenced by pointer (with reference count), thus should not be modified by the user. (Modification may cause errors or unintended side-effects in this or a future version of PETSc.)
    292:    For either case above, the input PetscObject should be destroyed by the user when no longer needed (the aggregate object increases its reference count).
    293: $   PETSC_USE_POINTER - invalid for PetscObject inputs.

    295: E*/
    296: typedef enum {PETSC_COPY_VALUES, PETSC_OWN_POINTER, PETSC_USE_POINTER} PetscCopyMode;

    298: /*MC
    299:     PETSC_FALSE - False value of PetscBool

    301:     Level: beginner

    303:     Note:
    304:     Zero integer

    306: .seealso: PetscBool, PETSC_TRUE
    307: M*/

    309: /*MC
    310:     PETSC_TRUE - True value of PetscBool

    312:     Level: beginner

    314:     Note:
    315:     Nonzero integer

    317: .seealso: PetscBool, PETSC_FALSE
    318: M*/

    320: /*MC
    321:     PetscLogDouble - Used for logging times

    323:   Notes:
    324:   Contains double precision numbers that are not used in the numerical computations, but rather in logging, timing etc.

    326:   Level: developer

    328: M*/
    329: typedef double PetscLogDouble;

    331: /*E
    332:     PetscDataType - Used for handling different basic data types.

    334:    Level: beginner

    336:    Notes:
    337:    Use of this should be avoided if one can directly use MPI_Datatype instead.

    339:    PETSC_INT is the datatype for a PetscInt, regardless of whether it is 4 or 8 bytes.
    340:    PETSC_REAL, PETSC_COMPLEX and PETSC_SCALAR are the datatypes for PetscReal, PetscComplex and PetscScalar, regardless of their sizes.

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

    345:    If you change any values in PetscDatatype make sure you update their usage in
    346:    share/petsc/matlab/PetscBagRead.m and share/petsc/matlab/@PetscOpenSocket/read/write.m

    348:    TODO: Add PETSC_INT32 and remove use of improper PETSC_ENUM

    350: .seealso: PetscBinaryRead(), PetscBinaryWrite(), PetscDataTypeToMPIDataType(),
    351:           PetscDataTypeGetSize()

    353: E*/
    354: typedef enum {PETSC_DATATYPE_UNKNOWN = 0,
    355:               PETSC_DOUBLE = 1, PETSC_COMPLEX = 2, PETSC_LONG = 3, PETSC_SHORT = 4, PETSC_FLOAT = 5,
    356:               PETSC_CHAR = 6, PETSC_BIT_LOGICAL = 7, PETSC_ENUM = 8, PETSC_BOOL = 9, PETSC___FLOAT128 = 10,
    357:               PETSC_OBJECT = 11, PETSC_FUNCTION = 12, PETSC_STRING = 13, PETSC___FP16 = 14, PETSC_STRUCT = 15,
    358:               PETSC_INT = 16, PETSC_INT64 = 17} PetscDataType;

    360: #if defined(PETSC_USE_REAL_SINGLE)
    361: #  define PETSC_REAL PETSC_FLOAT
    362: #elif defined(PETSC_USE_REAL_DOUBLE)
    363: #  define PETSC_REAL PETSC_DOUBLE
    364: #elif defined(PETSC_USE_REAL___FLOAT128)
    365: #  define PETSC_REAL PETSC___FLOAT128
    366: #elif defined(PETSC_USE_REAL___FP16)
    367: #  define PETSC_REAL PETSC___FP16
    368: #else
    369: #  define PETSC_REAL PETSC_DOUBLE
    370: #endif

    372: #if defined(PETSC_USE_COMPLEX)
    373: #  define PETSC_SCALAR PETSC_COMPLEX
    374: #else
    375: #  define PETSC_SCALAR PETSC_REAL
    376: #endif

    378: #define PETSC_FORTRANADDR PETSC_LONG

    380: /*S
    381:     PetscToken - 'Token' used for managing tokenizing strings

    383:   Level: intermediate

    385: .seealso: PetscTokenCreate(), PetscTokenFind(), PetscTokenDestroy()
    386: S*/
    387: typedef struct _p_PetscToken* PetscToken;

    389: /*S
    390:      PetscObject - any PETSc object, PetscViewer, Mat, Vec, KSP etc

    392:    Level: beginner

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

    397: .seealso:  PetscObjectDestroy(), PetscObjectView(), PetscObjectGetName(), PetscObjectSetName(), PetscObjectReference(), PetscObjectDereference()
    398: S*/
    399: typedef struct _p_PetscObject* PetscObject;

    401: /*MC
    402:     PetscObjectId - unique integer Id for a PetscObject

    404:     Level: developer

    406:     Notes:
    407:     Unlike pointer values, object ids are never reused.

    409: .seealso: PetscObjectState, PetscObjectGetId()
    410: M*/
    411: typedef PetscInt64 PetscObjectId;

    413: /*MC
    414:     PetscObjectState - integer state for a PetscObject

    416:     Level: developer

    418:     Notes:
    419:     Object state is always-increasing and (for objects that track state) can be used to determine if an object has
    420:     changed since the last time you interacted with it.  It is 64-bit so that it will not overflow for a very long time.

    422: .seealso: PetscObjectId, PetscObjectStateGet(), PetscObjectStateIncrease(), PetscObjectStateSet()
    423: M*/
    424: typedef PetscInt64 PetscObjectState;

    426: /*S
    427:      PetscFunctionList - Linked list of functions, possibly stored in dynamic libraries, accessed
    428:       by string name

    430:    Level: advanced

    432: .seealso:  PetscFunctionListAdd(), PetscFunctionListDestroy()
    433: S*/
    434: typedef struct _n_PetscFunctionList *PetscFunctionList;

    436: /*E
    437:   PetscFileMode - Access mode for a file.

    439:   Level: beginner

    441: $  FILE_MODE_UNDEFINED - initial invalid value
    442: $  FILE_MODE_READ - open a file at its beginning for reading
    443: $  FILE_MODE_WRITE - open a file at its beginning for writing (will create if the file does not exist)
    444: $  FILE_MODE_APPEND - open a file at end for writing
    445: $  FILE_MODE_UPDATE - open a file for updating, meaning for reading and writing
    446: $  FILE_MODE_APPEND_UPDATE - open a file for updating, meaning for reading and writing, at the end

    448: .seealso: PetscViewerFileSetMode()
    449: E*/
    450: typedef enum {FILE_MODE_UNDEFINED=-1, FILE_MODE_READ=0, FILE_MODE_WRITE, FILE_MODE_APPEND, FILE_MODE_UPDATE, FILE_MODE_APPEND_UPDATE} PetscFileMode;

    452: typedef void* PetscDLHandle;
    453: typedef enum {PETSC_DL_DECIDE=0,PETSC_DL_NOW=1,PETSC_DL_LOCAL=2} PetscDLMode;

    455: /*S
    456:      PetscObjectList - Linked list of PETSc objects, each accessible by string name

    458:    Level: developer

    460:    Notes:
    461:    Used by PetscObjectCompose() and PetscObjectQuery()

    463: .seealso:  PetscObjectListAdd(), PetscObjectListDestroy(), PetscObjectListFind(), PetscObjectCompose(), PetscObjectQuery(), PetscFunctionList
    464: S*/
    465: typedef struct _n_PetscObjectList *PetscObjectList;

    467: /*S
    468:      PetscDLLibrary - Linked list of dynamics libraries to search for functions

    470:    Level: advanced

    472: .seealso:  PetscDLLibraryOpen()
    473: S*/
    474: typedef struct _n_PetscDLLibrary *PetscDLLibrary;

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

    479:    Level: advanced

    481: .seealso:  PetscObject, PetscContainerCreate()
    482: S*/
    483: typedef struct _p_PetscContainer*  PetscContainer;

    485: /*S
    486:      PetscRandom - Abstract PETSc object that manages generating random numbers

    488:    Level: intermediate

    490: .seealso:  PetscRandomCreate(), PetscRandomGetValue(), PetscRandomType
    491: S*/
    492: typedef struct _p_PetscRandom*   PetscRandom;

    494: /*
    495:    In binary files variables are stored using the following lengths,
    496:   regardless of how they are stored in memory on any one particular
    497:   machine. Use these rather then sizeof() in computing sizes for
    498:   PetscBinarySeek().
    499: */
    500: #define PETSC_BINARY_INT_SIZE    (32/8)
    501: #define PETSC_BINARY_FLOAT_SIZE  (32/8)
    502: #define PETSC_BINARY_CHAR_SIZE   (8/8)
    503: #define PETSC_BINARY_SHORT_SIZE  (16/8)
    504: #define PETSC_BINARY_DOUBLE_SIZE (64/8)
    505: #define PETSC_BINARY_SCALAR_SIZE sizeof(PetscScalar)

    507: /*E
    508:   PetscBinarySeekType - argument to PetscBinarySeek()

    510:   Level: advanced

    512: .seealso: PetscBinarySeek(), PetscBinarySynchronizedSeek()
    513: E*/
    514: typedef enum {PETSC_BINARY_SEEK_SET = 0,PETSC_BINARY_SEEK_CUR = 1,PETSC_BINARY_SEEK_END = 2} PetscBinarySeekType;

    516: /*E
    517:     PetscBuildTwoSidedType - algorithm for setting up two-sided communication

    519: $  PETSC_BUILDTWOSIDED_ALLREDUCE - classical algorithm using an MPI_Allreduce with
    520: $      a buffer of length equal to the communicator size. Not memory-scalable due to
    521: $      the large reduction size. Requires only MPI-1.
    522: $  PETSC_BUILDTWOSIDED_IBARRIER - nonblocking algorithm based on MPI_Issend and MPI_Ibarrier.
    523: $      Proved communication-optimal in Hoefler, Siebert, and Lumsdaine (2010). Requires MPI-3.
    524: $  PETSC_BUILDTWOSIDED_REDSCATTER - similar to above, but use more optimized function
    525: $      that only communicates the part of the reduction that is necessary.  Requires MPI-2.

    527:    Level: developer

    529: .seealso: PetscCommBuildTwoSided(), PetscCommBuildTwoSidedSetType(), PetscCommBuildTwoSidedGetType()
    530: E*/
    531: typedef enum {
    532:   PETSC_BUILDTWOSIDED_NOTSET = -1,
    533:   PETSC_BUILDTWOSIDED_ALLREDUCE = 0,
    534:   PETSC_BUILDTWOSIDED_IBARRIER = 1,
    535:   PETSC_BUILDTWOSIDED_REDSCATTER = 2
    536:   /* Updates here must be accompanied by updates in finclude/petscsys.h and the string array in mpits.c */
    537: } PetscBuildTwoSidedType;

    539: /* NOTE: If you change this, you must also change the values in src/vec/f90-mod/petscvec.h */
    540: /*E
    541:   InsertMode - Whether entries are inserted or added into vectors or matrices

    543:   Level: beginner

    545: .seealso: VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
    546:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(),
    547:           MatSetValuesBlockedLocal(), MatSetValuesLocal(), VecScatterBegin(), VecScatterEnd()
    548: E*/
    549:  typedef enum {NOT_SET_VALUES, INSERT_VALUES, ADD_VALUES, MAX_VALUES, MIN_VALUES, INSERT_ALL_VALUES, ADD_ALL_VALUES, INSERT_BC_VALUES, ADD_BC_VALUES} InsertMode;

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

    554:     Level: beginner

    556: .seealso: InsertMode, VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
    557:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(), ADD_VALUES,
    558:           MatSetValuesBlockedLocal(), MatSetValuesLocal(), VecScatterBegin(), VecScatterEnd(), MAX_VALUES

    560: M*/

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

    566:     Level: beginner

    568: .seealso: InsertMode, VecSetValues(), MatSetValues(), VecSetValue(), VecSetValuesBlocked(),
    569:           VecSetValuesLocal(), VecSetValuesBlockedLocal(), MatSetValuesBlocked(), INSERT_VALUES,
    570:           MatSetValuesBlockedLocal(), MatSetValuesLocal(), VecScatterBegin(), VecScatterEnd(), MAX_VALUES

    572: M*/

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

    577:     Level: beginner

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

    581: M*/

    583: /*MC
    584:     MIN_VALUES - Puts the minimal of the scattered/gathered value and the current value into each location

    586:     Level: beginner

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

    590: M*/

    593: /*S
    594:    PetscSubcomm - A decomposition of an MPI communicator into subcommunicators

    596:    Notes:
    597:    After a call to PetscSubcommSetType(), PetscSubcommSetTypeGeneral(), or PetscSubcommSetFromOptions() one may call
    598: $     PetscSubcommChild() returns the associated subcommunicator on this process
    599: $     PetscSubcommContiguousParent() returns a parent communitor but with all child of the same subcommunicator having contiguous rank

    601:    Sample Usage:
    602:        PetscSubcommCreate()
    603:        PetscSubcommSetNumber()
    604:        PetscSubcommSetType(PETSC_SUBCOMM_INTERLACED);
    605:        ccomm = PetscSubcommChild()
    606:        PetscSubcommDestroy()

    608:    Level: advanced

    610:    Notes:
    611: $   PETSC_SUBCOMM_GENERAL - similar to MPI_Comm_split() each process sets the new communicator (color) they will belong to and the order within that communicator
    612: $   PETSC_SUBCOMM_CONTIGUOUS - each new communicator contains a set of process with contiguous ranks in the original MPI communicator
    613: $   PETSC_SUBCOMM_INTERLACED - each new communictor contains a set of processes equally far apart in rank from the others in that new communicator

    615:    Example: Consider a communicator with six processes split into 3 subcommunicators.
    616: $     PETSC_SUBCOMM_CONTIGUOUS - the first communicator contains rank 0,1  the second rank 2,3 and the third rank 4,5 in the original ordering of the original communicator
    617: $     PETSC_SUBCOMM_INTERLACED - the first communicator contains rank 0,3, the second 1,4 and the third 2,5

    619:    Developer Notes:
    620:    This is used in objects such as PCREDUNDANT to manage the subcommunicators on which the redundant computations
    621:       are performed.

    624: .seealso: PetscSubcommCreate(), PetscSubcommSetNumber(), PetscSubcommSetType(), PetscSubcommView(), PetscSubcommSetFromOptions()

    626: S*/
    627: typedef struct _n_PetscSubcomm* PetscSubcomm;
    628: typedef enum {PETSC_SUBCOMM_GENERAL=0,PETSC_SUBCOMM_CONTIGUOUS=1,PETSC_SUBCOMM_INTERLACED=2} PetscSubcommType;

    630: /*S
    631:      PetscHeap - A simple class for managing heaps

    633:    Level: intermediate

    635: .seealso:  PetscHeapCreate(), PetscHeapAdd(), PetscHeapPop(), PetscHeapPeek(), PetscHeapStash(), PetscHeapUnstash(), PetscHeapView(), PetscHeapDestroy()
    636: S*/
    637: typedef struct _PetscHeap *PetscHeap;

    639: typedef struct _n_PetscShmComm* PetscShmComm;
    640: typedef struct _n_PetscOmpCtrl* PetscOmpCtrl;

    642: /*S
    643:    PetscSegBuffer - a segmented extendable buffer

    645:    Level: developer

    647: .seealso: PetscSegBufferCreate(), PetscSegBufferGet(), PetscSegBufferExtract(), PetscSegBufferDestroy()
    648: S*/
    649: typedef struct _n_PetscSegBuffer *PetscSegBuffer;

    651: typedef struct _n_PetscOptionsHelpPrinted *PetscOptionsHelpPrinted;

    653: /*E
    654:   PetscMemType - Memory type of a pointer

    656:   Level: beginner

    658:   Developer Note:
    659:    Encoding of the bitmask in binary: xxxxyyyz
    660:    z = 0:                Host memory
    661:    z = 1:                Device memory
    662:    yyy = 000:            CUDA-related memory
    663:    yyy = 001:            HIP-related memory
    664:    xxxxyyy1 = 0000,0001: CUDA memory
    665:    xxxxyyy1 = 0001,0001: CUDA NVSHMEM memory
    666:    xxxxyyy1 = 0000,0011: HIP memory

    668:   Other types of memory, e.g., CUDA managed memory, can be added when needed.

    670: .seealso: VecGetArrayAndMemType(), PetscSFBcastWithMemTypeBegin(), PetscSFReduceWithMemTypeBegin()
    671: E*/
    672: typedef enum {PETSC_MEMTYPE_HOST=0, PETSC_MEMTYPE_DEVICE=0x01, PETSC_MEMTYPE_CUDA=0x01, PETSC_MEMTYPE_NVSHMEM=0x11,PETSC_MEMTYPE_HIP=0x03} PetscMemType;

    674: #define PetscMemTypeHost(m)    (((m) & 0x1) == PETSC_MEMTYPE_HOST)
    675: #define PetscMemTypeDevice(m)  (((m) & 0x1) == PETSC_MEMTYPE_DEVICE)
    676: #define PetscMemTypeCUDA(m)    (((m) & 0xF) == PETSC_MEMTYPE_CUDA)
    677: #define PetscMemTypeHIP(m)     (((m) & 0xF) == PETSC_MEMTYPE_HIP)
    678: #define PetscMemTypeNVSHMEM(m) ((m) == PETSC_MEMTYPE_NVSHMEM)

    680: #endif