Actual source code: petscsystypes.h

      1: /* Portions of this code are under:
      2:    Copyright (c) 2022 Advanced Micro Devices, Inc. All rights reserved.
      3: */

      5: #pragma once

      7: #include <petscconf.h>
      8: #include <petscconf_poison.h>
      9: #include <petscfix.h>
     10: #include <petscmacros.h>
     11: #include <stddef.h>
     12: #include <stdbool.h>

     14: /* SUBMANSEC = Sys */

     16: #include <limits.h> // INT_MIN, INT_MAX, CHAR_BIT

     18: #if defined(__clang__) || (PETSC_CPP_VERSION >= 17)
     19:   // clang allows both [[nodiscard]] and __attribute__((warn_unused_result)) on type
     20:   // definitions. GCC, however, does not, so check that we are using C++17 [[nodiscard]]
     21:   // instead of __attribute__((warn_unused_result))
     22:   #define PETSC_ERROR_CODE_NODISCARD PETSC_NODISCARD
     23: #else
     24:   #define PETSC_ERROR_CODE_NODISCARD
     25: #endif

     27: #ifdef PETSC_CLANG_STATIC_ANALYZER
     28:   #undef PETSC_USE_STRICT_PETSCERRORCODE
     29: #endif

     31: #ifdef PETSC_USE_STRICT_PETSCERRORCODE
     32:   #define PETSC_ERROR_CODE_TYPEDEF   typedef
     33:   #define PETSC_ERROR_CODE_ENUM_NAME PetscErrorCode
     34: #else
     35:   #define PETSC_ERROR_CODE_TYPEDEF
     36:   #define PETSC_ERROR_CODE_ENUM_NAME
     37: #endif

     39: /*E
     40:   PetscErrorCode - Datatype used to return PETSc error codes.

     42:   Level: beginner

     44:   Notes:
     45:   Virtually all PETSc functions return an error code. It is the callers responsibility to check
     46:   the value of the returned error code after each PETSc call to determine if any errors
     47:   occurred. A set of convenience macros (e.g. `PetscCall()`, `PetscCallVoid()`) are provided
     48:   for this purpose. Failing to properly check for errors is not supported, as errors may leave
     49:   PETSc in an undetermined state.

     51:   One can retrieve the error string corresponding to a particular error code using
     52:   `PetscErrorMessage()`.

     54:   The user can also configure PETSc with the `--with-strict-petscerrorcode` option to enable
     55:   compiler warnings when the returned error codes are not captured and checked. Users are
     56:   *heavily* encouraged to opt-in to this option, as it will become enabled by default in a
     57:   future release.

     59:   Developer Notes:
     60:   These are the generic error codes. These error codes are used in many different places in the
     61:   PETSc source code. The C-string versions are at defined in `PetscErrorStrings[]` in
     62:   `src/sys/error/err.c`, while the Fortran versions are defined in
     63:   `src/sys/ftn-mod/petscerror.h`. Any changes here must also be made in both locations.

     65: .seealso: `PetscErrorMessage()`, `PetscCall()`, `SETERRQ()`
     66: E*/
     67: PETSC_ERROR_CODE_TYPEDEF enum PETSC_ERROR_CODE_NODISCARD {
     68:   PETSC_SUCCESS                   = 0,
     69:   PETSC_ERR_BOOLEAN_MACRO_FAILURE = 1, /* do not use */

     71:   PETSC_ERR_MIN_VALUE = 54, /* should always be one less than the smallest value */

     73:   PETSC_ERR_MEM            = 55, /* unable to allocate requested memory */
     74:   PETSC_ERR_SUP            = 56, /* no support for requested operation */
     75:   PETSC_ERR_SUP_SYS        = 57, /* no support for requested operation on this computer system */
     76:   PETSC_ERR_ORDER          = 58, /* operation done in wrong order */
     77:   PETSC_ERR_SIG            = 59, /* signal received */
     78:   PETSC_ERR_FP             = 72, /* floating point exception */
     79:   PETSC_ERR_COR            = 74, /* corrupted PETSc object */
     80:   PETSC_ERR_LIB            = 76, /* error in library called by PETSc */
     81:   PETSC_ERR_PLIB           = 77, /* PETSc library generated inconsistent data */
     82:   PETSC_ERR_MEMC           = 78, /* memory corruption */
     83:   PETSC_ERR_CONV_FAILED    = 82, /* iterative method (KSP or SNES) failed */
     84:   PETSC_ERR_USER           = 83, /* user has not provided needed function */
     85:   PETSC_ERR_SYS            = 88, /* error in system call */
     86:   PETSC_ERR_POINTER        = 70, /* pointer does not point to valid address */
     87:   PETSC_ERR_MPI_LIB_INCOMP = 87, /* MPI library at runtime is not compatible with MPI user compiled with */

     89:   PETSC_ERR_ARG_SIZ          = 60, /* nonconforming object sizes used in operation */
     90:   PETSC_ERR_ARG_IDN          = 61, /* two arguments not allowed to be the same */
     91:   PETSC_ERR_ARG_WRONG        = 62, /* wrong argument (but object probably ok) */
     92:   PETSC_ERR_ARG_CORRUPT      = 64, /* null or corrupted PETSc object as argument */
     93:   PETSC_ERR_ARG_OUTOFRANGE   = 63, /* input argument, out of range */
     94:   PETSC_ERR_ARG_BADPTR       = 68, /* invalid pointer argument */
     95:   PETSC_ERR_ARG_NOTSAMETYPE  = 69, /* two args must be same object type */
     96:   PETSC_ERR_ARG_NOTSAMECOMM  = 80, /* two args must be same communicators */
     97:   PETSC_ERR_ARG_WRONGSTATE   = 73, /* object in argument is in wrong state, e.g. unassembled mat */
     98:   PETSC_ERR_ARG_TYPENOTSET   = 89, /* the type of the object has not yet been set */
     99:   PETSC_ERR_ARG_INCOMP       = 75, /* two arguments are incompatible */
    100:   PETSC_ERR_ARG_NULL         = 85, /* argument is null that should not be */
    101:   PETSC_ERR_ARG_UNKNOWN_TYPE = 86, /* type name doesn't match any registered type */

    103:   PETSC_ERR_FILE_OPEN       = 65, /* unable to open file */
    104:   PETSC_ERR_FILE_READ       = 66, /* unable to read from file */
    105:   PETSC_ERR_FILE_WRITE      = 67, /* unable to write to file */
    106:   PETSC_ERR_FILE_UNEXPECTED = 79, /* unexpected data in file */

    108:   PETSC_ERR_MAT_LU_ZRPVT = 71, /* detected a zero pivot during LU factorization */
    109:   PETSC_ERR_MAT_CH_ZRPVT = 81, /* detected a zero pivot during Cholesky factorization */

    111:   PETSC_ERR_INT_OVERFLOW   = 84,
    112:   PETSC_ERR_FLOP_COUNT     = 90,
    113:   PETSC_ERR_NOT_CONVERGED  = 91,  /* solver did not converge */
    114:   PETSC_ERR_MISSING_FACTOR = 92,  /* MatGetFactor() failed */
    115:   PETSC_ERR_OPT_OVERWRITE  = 93,  /* attempted to over write options which should not be changed */
    116:   PETSC_ERR_WRONG_MPI_SIZE = 94,  /* example/application run with number of MPI ranks it does not support */
    117:   PETSC_ERR_USER_INPUT     = 95,  /* missing or incorrect user input */
    118:   PETSC_ERR_GPU_RESOURCE   = 96,  /* unable to load a GPU resource, for example cuBLAS */
    119:   PETSC_ERR_GPU            = 97,  /* An error from a GPU call, this may be due to lack of resources on the GPU or a true error in the call */
    120:   PETSC_ERR_MPI            = 98,  /* general MPI error */
    121:   PETSC_ERR_RETURN         = 99,  /* PetscError() incorrectly returned an error code of 0 */
    122:   PETSC_ERR_MEM_LEAK       = 100, /* memory alloc/free imbalance */
    123:   PETSC_ERR_PYTHON         = 101, /* Exception in Python */
    124:   PETSC_ERR_MAX_VALUE      = 102, /* this is always the one more than the largest error code */

    126:   /*
    127:     do not use, exist purely to make the enum bounds equal that of a regular int (so conversion
    128:     to int in main() is not undefined behavior)
    129:   */
    130:   PETSC_ERR_MIN_SIGNED_BOUND_DO_NOT_USE = INT_MIN,
    131:   PETSC_ERR_MAX_SIGNED_BOUND_DO_NOT_USE = INT_MAX
    132: } PETSC_ERROR_CODE_ENUM_NAME;

    134: #if !defined(PETSC_USE_STRICT_PETSCERRORCODE)
    135: typedef int PetscErrorCode;

    137:   /*
    138:   Needed so that C++ lambdas can deduce the return type as PetscErrorCode from
    139:   PetscFunctionReturn(PETSC_SUCCESS). Otherwise we get

    141:   error: return type '(unnamed enum at include/petscsystypes.h:50:1)' must match previous
    142:   return type 'int' when lambda expression has unspecified explicit return type
    143:   PetscFunctionReturn(PETSC_SUCCESS);
    144:   ^
    145: */
    146:   #define PETSC_SUCCESS ((PetscErrorCode)0)
    147: #endif

    149: #undef PETSC_ERROR_CODE_NODISCARD
    150: #undef PETSC_ERROR_CODE_TYPEDEF
    151: #undef PETSC_ERROR_CODE_ENUM_NAME

    153: /*MC
    154:     PetscClassId - A unique id used to identify each PETSc class.

    156:     Level: developer

    158:     Note:
    159:     Use `PetscClassIdRegister()` to obtain a new value for a new class being created. Usually
    160:     XXXInitializePackage() calls it for each class it defines.

    162:     Developer Note:
    163:     Internal integer stored in the `_p_PetscObject` data structure. These are all computed by an offset from the lowest one, `PETSC_SMALLEST_CLASSID`.

    165: .seealso: `PetscClassIdRegister()`, `PetscLogEventRegister()`, `PetscHeaderCreate()`
    166: M*/
    167: typedef int PetscClassId;

    169: /*MC
    170:     PetscMPIInt - datatype used to represent `int` parameters to MPI functions.

    172:     Level: intermediate

    174:     Notes:
    175:     This is always a 32-bit integer even if PETSc was built with `--with-64-bit-indices`.
    176:     Hence, it is not guaranteed that it is the same as `PetscInt`.

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

    181: .seealso: [](stylePetscCount), `PetscBLASInt`, `PetscInt`, `PetscMPIIntCast()`
    182: M*/
    183: typedef int PetscMPIInt;

    185: /* Limit MPI to 32-bits */
    186: enum {
    187:   PETSC_MPI_INT_MIN = INT_MIN,
    188:   PETSC_MPI_INT_MAX = INT_MAX
    189: };

    191: /*MC
    192:     PetscSizeT - datatype used to represent sizes in memory (like `size_t`)

    194:     Level: intermediate

    196:     Notes:
    197:     This is equivalent to `size_t`, but defined for consistency with Fortran, which lacks a native equivalent of `size_t`.

    199: .seealso: `PetscInt`, `PetscInt64`, `PetscCount`
    200: M*/
    201: typedef size_t PetscSizeT;

    203: /*MC
    204:     PetscCount - signed datatype used to represent counts

    206:     Level: intermediate

    208:     Notes:
    209:     This is equivalent to `ptrdiff_t`, but defined for consistency with Fortran, which lacks a native equivalent of `ptrdiff_t`.

    211:     Use `PetscCount_FMT` to format with `PetscPrintf()`, `printf()`, and related functions.

    213: .seealso: [](stylePetscCount), `PetscInt`, `PetscInt64`, `PetscSizeT`
    214: M*/
    215: typedef ptrdiff_t PetscCount;
    216: #define PetscCount_FMT "td"

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

    221:     Level: intermediate

    223: .seealso: `PetscOptionsGetEnum()`, `PetscOptionsEnum()`, `PetscBagRegisterEnum()`
    224: M*/
    225: typedef enum {
    226:   ENUM_DUMMY
    227: } PetscEnum;

    229: typedef short PetscShort;
    230: typedef float PetscFloat;

    232: #if defined(PETSC_HAVE_STDINT_H)
    233:   #include <stdint.h>
    234: #endif
    235: #if defined(PETSC_HAVE_INTTYPES_H)
    238:   #endif
    239:   #include <inttypes.h>
    240:   #if !defined(PRId64)
    241:     #define PRId64 "ld"
    242:   #endif
    243: #endif

    245: /*MC
    246:   PetscInt64 - PETSc type that represents a 64-bit integer. When PETSc is configured with the option `--with-64-bit-indices` then `PetscInt` is identical to `PetscInt64`

    248:   Level: beginner

    250: .seealso: `PetscBLASInt`, `PetscInt`, `PetscMPIInt`, `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt32`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PetscIntCast()`
    251: M*/
    252: #if defined(PETSC_HAVE_STDINT_H) && defined(PETSC_HAVE_INTTYPES_H) && (defined(PETSC_HAVE_MPIUNI) || defined(PETSC_HAVE_MPI_INT64_T)) /* MPI_INT64_T is not guaranteed to be a macro */
    253: typedef int64_t PetscInt64;

    255:   #define PETSC_INT64_MIN INT64_MIN
    256:   #define PETSC_INT64_MAX INT64_MAX

    258: #elif (PETSC_SIZEOF_LONG_LONG == 8)
    259: typedef long long PetscInt64;

    261:   #define PETSC_INT64_MIN LLONG_MIN
    262:   #define PETSC_INT64_MAX LLONG_MAX

    264: #elif defined(PETSC_HAVE___INT64)
    265: typedef __int64 PetscInt64;

    267:   #define PETSC_INT64_MIN INT64_MIN
    268:   #define PETSC_INT64_MAX INT64_MAX

    270: #else
    271:   #error "cannot determine PetscInt64 type"
    272: #endif

    274: #if PETSC_SIZEOF_SIZE_T == 4
    275:   #define PETSC_COUNT_MIN INT_MIN
    276:   #define PETSC_COUNT_MAX INT_MAX
    277: #else
    278:   #define PETSC_COUNT_MIN PETSC_INT64_MIN
    279:   #define PETSC_COUNT_MAX PETSC_INT64_MAX
    280: #endif

    282: /*MC
    283:   PetscInt32 - PETSc type that represents a 32-bit integer. When PETSc is not configured with the option `--with-64-bit-indices` then `PetscInt` is identical to `PetscInt32`

    285:   Level: beginner

    287: .seealso: `PetscBLASInt`, `PetscInt`, `PetscMPIInt`, `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt64`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PetscIntCast()`
    288: M*/
    289: typedef int32_t PetscInt32;
    290: #define PETSC_INT32_MIN INT32_MIN
    291: #define PETSC_INT32_MAX INT32_MAX

    293: /*MC
    294:   PetscInt - PETSc type that represents an integer, used primarily to
    295:              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.

    297:   Level: beginner

    299:   Notes:
    300:   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`.

    302: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt32`, `PetscInt64`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PetscIntCast()`, `PETSC_INT_MIN`, `PETSC_INT_MAX`
    303: M*/
    304: #if defined(PETSC_USE_64BIT_INDICES)
    305: typedef PetscInt64 PetscInt;

    307:   #define PETSC_INT_MIN PETSC_INT64_MIN
    308:   #define PETSC_INT_MAX PETSC_INT64_MAX
    309:   #define PetscInt_FMT  PetscInt64_FMT
    310: #else
    311: typedef int PetscInt;

    313: enum {
    314:   PETSC_INT_MIN = INT_MIN,
    315:   PETSC_INT_MAX = INT_MAX
    316: };
    317:   #define PetscInt_FMT "d"
    318: #endif

    320: #define PETSC_UINT16_MAX 65535

    322: /* deprecated */
    323: #define PETSC_MIN_INT    PETSC_INT_MIN
    324: #define PETSC_MAX_INT    PETSC_INT_MAX
    325: #define PETSC_MAX_UINT16 PETSC_UINT16_MAX

    327: #if defined(PETSC_HAVE_STDINT_H) && defined(PETSC_HAVE_INTTYPES_H) && (defined(PETSC_HAVE_MPIUNI) || defined(PETSC_HAVE_MPI_INT64_T)) /* MPI_INT64_T is not guaranteed to be a macro */
    328:   #define MPIU_INT64     MPI_INT64_T
    329:   #define PetscInt64_FMT PRId64
    330: #elif (PETSC_SIZEOF_LONG_LONG == 8)
    331:   #define MPIU_INT64     MPI_LONG_LONG_INT
    332:   #define PetscInt64_FMT "lld"
    333: #elif defined(PETSC_HAVE___INT64)
    334:   #define MPIU_INT64     MPI_INT64_T
    335:   #define PetscInt64_FMT "ld"
    336: #else
    337:   #error "cannot determine PetscInt64 type"
    338: #endif

    340: #define MPIU_INT32     MPI_INT32_T
    341: #define PetscInt32_FMT PRId32

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

    346:    Level: intermediate

    348:    Notes:
    349:    Usually this is the same as `PetscInt`, but if PETSc was built with `--with-64-bit-indices` but
    350:    standard C/Fortran integers are 32-bit then this may not be the same as `PetscInt`,
    351:    except on some BLAS/LAPACK implementations that support 64-bit integers see the notes below.

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

    356:    Installation Notes\:
    357:    ./configure automatically determines the size of the integers used by BLAS/LAPACK except when `--with-batch` is used
    358:    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-indices`

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

    363:    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
    364:    against the 64-bit version, otherwise it uses the 32-bit version

    366:    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

    368:    External packages such as hypre, ML, SuperLU etc do not provide any support for passing 64-bit integers to BLAS/LAPACK so cannot
    369:    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
    370:    these external libraries while using 64-bit integer BLAS/LAPACK.

    372: .seealso: `PetscMPIInt`, `PetscInt`, `PetscBLASIntCast()`
    373: M*/
    374: #if defined(PETSC_HAVE_64BIT_BLAS_INDICES)
    375: typedef PetscInt64 PetscBLASInt;

    377:   #define PETSC_BLAS_INT_MIN PETSC_INT64_MIN
    378:   #define PETSC_BLAS_INT_MAX PETSC_INT64_MAX
    379:   #define PetscBLASInt_FMT   PetscInt64_FMT
    380: #else
    381: typedef int PetscBLASInt;

    383: enum {
    384:   PETSC_BLAS_INT_MIN = INT_MIN,
    385:   PETSC_BLAS_INT_MAX = INT_MAX
    386: };

    388:   #define PetscBLASInt_FMT "d"
    389: #endif

    391: /*MC
    392:    PetscCuBLASInt - datatype used to represent 'int' parameters to cuBLAS/cuSOLVER functions.

    394:    Level: intermediate

    396:    Notes:
    397:    As of this writing `PetscCuBLASInt` is always the system `int`.

    399:   `PetscErrorCode` `PetscCuBLASIntCast`(a,&b) checks if the given `PetscInt` a will fit in a `PetscCuBLASInt`, if not it
    400:    generates a `PETSC_ERR_ARG_OUTOFRANGE` error

    402: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscCuBLASIntCast()`
    403: M*/
    404: typedef int PetscCuBLASInt;

    406: enum {
    407:   PETSC_CUBLAS_INT_MIN = INT_MIN,
    408:   PETSC_CUBLAS_INT_MAX = INT_MAX
    409: };

    411: /*MC
    412:    PetscHipBLASInt - datatype used to represent 'int' parameters to hipBLAS/hipSOLVER functions.

    414:    Level: intermediate

    416:    Notes:
    417:    `PetscHipBLASInt` is always the system `int`.

    419:    `PetscErrorCode` `PetscHipBLASIntCast`(a,&b) checks if the given `PetscInt` a will fit in a `PetscHipBLASInt`, if not it
    420:    generates a `PETSC_ERR_ARG_OUTOFRANGE` error

    422: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscHipBLASIntCast()`
    423: M*/
    424: typedef int PetscHipBLASInt;

    426: enum {
    427:   PETSC_HIPBLAS_INT_MIN = INT_MIN,
    428:   PETSC_HIPBLAS_INT_MAX = INT_MAX
    429: };

    431: /*MC
    432:    PetscExodusIIInt - datatype used to represent 'int' parameters to ExodusII functions.

    434:    Level: intermediate

    436:    Notes:
    437:    This is the same as `int`

    439: .seealso: `PetscMPIInt`, `PetscInt`, `PetscExodusIIFloat`, `PetscBLASIntCast()`
    440: M*/
    441: typedef int PetscExodusIIInt;
    442: #define PetscExodusIIInt_FMT "d"

    444: /*MC
    445:    PetscExodusIIFloat - datatype used to represent 'float' parameters to ExodusII functions.

    447:    Level: intermediate

    449:    Notes:
    450:    This is the same as `float`

    452: .seealso: `PetscMPIInt`, `PetscInt`, `PetscExodusIIInt`, `PetscBLASIntCast()`
    453: M*/
    454: typedef float PetscExodusIIFloat;

    456: /*E
    457:    PetscBool - Logical variable.

    459:    Level: beginner

    461:    Notes:
    462:    This is a C bool.

    464:    Use `MPI_C_BOOL` for communicating with MPI calls in C, C++, and Fortran.

    466:    Fortran Note:
    467:    This is a `logical(C_BOOL)` with an internal representation that is equivalent to that of a `bool` in C and C++.
    468:    It typically has a size of 1 byte, in contrast to a default `logical` which has the size of a default integer (typically 4 bytes).

    470:    Developer Note:
    471:    We should deprecate this definition since there is a native representation in all the languages.

    473: .seealso: `PETSC_TRUE`, `PETSC_FALSE`, `PetscNot()`, `PetscBool3`, `PetscBool3ToBool()`, `PetscBoolToBool3()`
    474: E*/
    475: typedef bool PetscBool;
    476: #define PETSC_FALSE false
    477: #define PETSC_TRUE  true
    478: PETSC_EXTERN const char *const PetscBools[];

    480: /*E
    481:    PetscBool3 - Ternary logical variable. Actually an enum in C and a 4 byte integer in Fortran.

    483:    Level: beginner

    485:    Note:
    486:    Should not be used with the `if (flg)` or `if (!flg)` syntax.

    488: .seealso: `PETSC_TRUE`, `PETSC_FALSE`, `PetscNot()`, `PETSC_BOOL3_TRUE`, `PETSC_BOOL3_FALSE`, `PETSC_BOOL3_UNKNOWN`, `PetscBool3ToBool()`, `PetscBoolToBool3()`
    489: E*/
    490: typedef enum {
    491:   PETSC_BOOL3_FALSE   = 0,
    492:   PETSC_BOOL3_TRUE    = 1,
    493:   PETSC_BOOL3_UNKNOWN = -1 /* the value is unknown at the time of query, but might be determined later */
    494: } PetscBool3;
    495: PETSC_EXTERN const char *const PetscBool3s[];

    497: /*MC
    498:    PetscBool3ToBool - Convert a `PetscBool3` to a `PetscBool`

    500:    Synopsis:
    501: #include <petscsystypes.h>
    502:    PetscBool PetscBool3ToBool(PetscBool3 var)

    504:    No Fortran Support

    506:    Level: beginner

    508:    Note:
    509:    Evaluates to `PETSC_TRUE` if `var` is `PETSC_BOOL3_TRUE`, and `PETSC_FALSE` otherwise (including when `var` is `PETSC_BOOL3_UNKNOWN`).

    511: .seealso: `PetscBool`, `PetscBool3`, `PetscBoolToBool3()`
    512: M*/
    513: #define PetscBool3ToBool(a) ((a) == PETSC_BOOL3_TRUE ? PETSC_TRUE : PETSC_FALSE)

    515: /*MC
    516:    PetscBoolToBool3 - Convert a `PetscBool` to a `PetscBool3`

    518:    Synopsis:
    519: #include <petscsystypes.h>
    520:    PetscBool3 PetscBoolToBool3(PetscBool var)

    522:    No Fortran Support

    524:    Level: beginner

    526:    Note:
    527:    Evaluates to `PETSC_BOOL3_TRUE` if `var` is `PETSC_TRUE`, and `PETSC_BOOL3_FALSE` otherwise.

    529: .seealso: `PetscBool`, `PetscBool3`, `PetscBool3ToBool()`
    530: M*/
    531: #define PetscBoolToBool3(a) ((a) == PETSC_TRUE ? PETSC_BOOL3_TRUE : PETSC_BOOL3_FALSE)

    533: /*MC
    534:    PetscReal - PETSc type that represents a real number version of `PetscScalar`

    536:    Level: beginner

    538:    Notes:
    539:    For MPI calls that require datatypes, use `MPIU_REAL` as the datatype for `PetscReal` and `MPIU_SUM`, `MPIU_MAX`, etc. for operations.
    540:    They will automatically work correctly regardless of the size of `PetscReal`.

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

    544: .seealso: `PetscScalar`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`
    545: M*/
    546: #if defined(PETSC_USE_REAL_SINGLE)
    547: typedef float PetscReal;
    548: #elif defined(PETSC_USE_REAL_DOUBLE)
    549: typedef double PetscReal;
    550: #elif defined(PETSC_USE_REAL___FLOAT128)
    551:   #if defined(__cplusplus)
    552: extern "C" {
    553:   #endif
    554:   #include <quadmath.h>
    555:   #if defined(__cplusplus)
    556: }
    557:   #endif
    558: typedef __float128 PetscReal;
    559: #elif defined(PETSC_USE_REAL___FP16)
    560: typedef __fp16 PetscReal;
    561: #endif /* PETSC_USE_REAL_* */

    563: #if !defined(PETSC_SKIP_COMPLEX)
    564:   #if defined(PETSC_CLANGUAGE_CXX)
    565:     #if !defined(PETSC_USE_REAL___FP16) && !defined(PETSC_USE_REAL___FLOAT128)
    566:       #if defined(__cplusplus) && defined(PETSC_HAVE_CXX_COMPLEX) /* enable complex for library code */
    567:         #define PETSC_HAVE_COMPLEX 1
    568:       #elif !defined(__cplusplus) && defined(PETSC_HAVE_C99_COMPLEX) && defined(PETSC_HAVE_CXX_COMPLEX) /* User code only - conditional on library code complex support */
    569:         #define PETSC_HAVE_COMPLEX 1
    570:       #endif
    571:     #elif defined(PETSC_USE_REAL___FLOAT128) && defined(PETSC_HAVE_C99_COMPLEX)
    572:       #define PETSC_HAVE_COMPLEX 1
    573:     #endif
    574:   #else /* !PETSC_CLANGUAGE_CXX */
    575:     #if !defined(PETSC_USE_REAL___FP16)
    577:         #define PETSC_HAVE_COMPLEX 1
    578:       #elif defined(__cplusplus) && defined(PETSC_HAVE_C99_COMPLEX) && defined(PETSC_HAVE_CXX_COMPLEX) /* User code only - conditional on library code complex support */
    579:         #define PETSC_HAVE_COMPLEX 1
    580:       #endif
    581:     #endif
    582:   #endif /* PETSC_CLANGUAGE_CXX */
    583: #endif   /* !PETSC_SKIP_COMPLEX */

    585: #if defined(PETSC_HAVE_COMPLEX)
    586:   #if defined(__cplusplus) /* C++ complex support */
    587:     /* Locate a C++ complex template library */
    588:     #if defined(PETSC_DESIRE_KOKKOS_COMPLEX) /* Defined in petscvec_kokkos.hpp for *.kokkos.cxx files */
    589:       #define petsccomplexlib Kokkos
    590:       #include <Kokkos_Complex.hpp>
    591:     #elif (defined(__CUDACC__) && defined(PETSC_HAVE_CUDA)) || (defined(__HIPCC__) && defined(PETSC_HAVE_HIP))
    592:       #define petsccomplexlib thrust
    593:       #include <thrust/complex.h>
    594:     #elif defined(PETSC_USE_REAL___FLOAT128)
    595:       #include <complex.h>
    596:     #else
    597:       #define petsccomplexlib std
    598:       #include <complex>
    599:     #endif

    601:     /* Define PetscComplex based on the precision */
    602:     #if defined(PETSC_USE_REAL_SINGLE)
    603: typedef petsccomplexlib::complex<float> PetscComplex;
    604:     #elif defined(PETSC_USE_REAL_DOUBLE)
    605: typedef petsccomplexlib::complex<double> PetscComplex;
    606:     #elif defined(PETSC_USE_REAL___FLOAT128)
    607: typedef __complex128 PetscComplex;
    608:     #endif

    610:     /* Include a PETSc C++ complex 'fix'. Check PetscComplex manual page for details */
    611:     #if defined(PETSC_HAVE_CXX_COMPLEX_FIX) && !defined(PETSC_SKIP_CXX_COMPLEX_FIX)
    612: #include <petsccxxcomplexfix.h>
    613:     #endif
    614:   #else /* c99 complex support */
    615:     #include <complex.h>
    616:     #if defined(PETSC_USE_REAL_SINGLE) || defined(PETSC_USE_REAL___FP16)

    618: typedef float _Complex PetscComplex;
    619:     #elif defined(PETSC_USE_REAL_DOUBLE)
    620: typedef double _Complex PetscComplex;
    621:     #elif defined(PETSC_USE_REAL___FLOAT128)

    623: /*MC
    624:    PetscComplex - PETSc type that represents a complex number with precision matching that of `PetscReal`.

    626:    Synopsis:
    627: #include <petscsys.h>
    628:    PetscComplex number = 1. + 2.*PETSC_i;

    630:    Level: beginner

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

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

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

    640:     PETSc has a 'fix' for complex numbers to support expressions such as `std::complex<PetscReal>` + `PetscInt`, which are not supported by the standard
    641:     C++ library, but are convenient for PETSc users. If the C++ compiler is able to compile code in `petsccxxcomplexfix.h` (This is checked by
    642:     configure), we include `petsccxxcomplexfix.h` to provide this convenience.

    644:     If the fix causes conflicts, or one really does not want this fix for a particular C++ file, one can define `PETSC_SKIP_CXX_COMPLEX_FIX`
    645:     at the beginning of the C++ file to skip the fix.

    647: .seealso: `PetscReal`, `PetscScalar`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PETSC_i`
    648: M*/
    649: typedef __complex128 PetscComplex;
    650:     #endif /* PETSC_USE_REAL_* */
    651:   #endif   /* !__cplusplus */
    652: #endif     /* PETSC_HAVE_COMPLEX */

    654: /*MC
    655:    PetscScalar - PETSc type that represents either a double precision real number, a double precision
    656:                  complex number, a single precision real number, a __float128 real or complex or a __fp16 real - if the code is configured
    657:                  with `--with-scalar-type`=real,complex `--with-precision`=single,double,__float128,__fp16

    659:    Level: beginner

    661:    Note:
    662:    For MPI calls that require datatypes, use `MPIU_SCALAR` as the datatype for `PetscScalar` and `MPIU_SUM`, etc for operations. They will automatically work correctly regardless of the size of `PetscScalar`.

    664: .seealso: `PetscReal`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PetscRealPart()`, `PetscImaginaryPart()`
    665: M*/
    666: #if defined(PETSC_USE_COMPLEX) && defined(PETSC_HAVE_COMPLEX)
    667: typedef PetscComplex PetscScalar;
    668: #else  /* PETSC_USE_COMPLEX */
    669: typedef PetscReal PetscScalar;
    670: #endif /* PETSC_USE_COMPLEX */

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

    675:    Values for array input:
    676: +   `PETSC_COPY_VALUES` - the array values are copied into new space, the user is free to reuse or delete the passed in array
    677: .   `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
    678:                           delete the array. The array MUST have been obtained with `PetscMalloc()`. Hence this mode cannot be used in Fortran.
    679: -   `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
    680:                           the array but the user must delete the array after the object is destroyed.

    682:    Values for PetscObject:
    683: +   `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.
    684: .   `PETSC_OWN_POINTER` - the input `PetscObject` is referenced by pointer (with reference count), thus should not be modified by the user.
    685:                           increases its reference count).
    686: -   `PETSC_USE_POINTER` - invalid for `PetscObject` inputs.

    688:    Level: beginner

    690: .seealso: `InsertMode`
    691: E*/
    692: typedef enum {
    693:   PETSC_COPY_VALUES,
    694:   PETSC_OWN_POINTER,
    695:   PETSC_USE_POINTER
    696: } PetscCopyMode;
    697: PETSC_EXTERN const char *const PetscCopyModes[];

    699: /*MC
    700:     PETSC_FALSE - False value of `PetscBool`

    702:     Level: beginner

    704:     Note:
    705:     Zero integer

    707: .seealso: `PetscBool`, `PetscBool3`, `PETSC_TRUE`
    708: M*/

    710: /*MC
    711:     PETSC_TRUE - True value of `PetscBool`

    713:     Level: beginner

    715:     Note:
    716:     Nonzero integer

    718: .seealso: `PetscBool`, `PetscBool3`, `PETSC_FALSE`
    719: M*/

    721: /*MC
    722:     PETSC_INT_MIN - Minimum integer value representable by a `PetscInt`

    724:     Level: beginner

    726: .seealso: `PETSC_INT_MAX`, `PetscInt`, `PetscIntCast()`
    727: M*/

    729: /*MC
    730:     PETSC_INT_MAX - Maximum integer value representable by a `PetscInt`

    732:     Level: beginner

    734: .seealso: `PETSC_INT_MIN`, `PetscInt`, `PetscIntCast()`
    735: M*/

    737: /*MC
    738:     PETSC_MAX_PATH_LEN - Maximum length of a path (file name including directory)

    740:     Level: beginner

    742:     Note:
    743:     This value is set at configuration time based on the system's maximum path length (e.g., `MAXPATHLEN`, `MAX_PATH`, or `_MAX_PATH`).
    744:     It defaults to 4096 if no system value is available.

    746: .seealso: `PetscGetFullPath()`, `PetscGetRealPath()`, `PetscGetHomeDirectory()`
    747: M*/

    749: /*MC
    750:     PetscLogDouble - Used for logging times

    752:   Level: developer

    754:   Note:
    755:   Contains double precision numbers that are not used in the numerical computations, but rather in logging, timing etc.

    757: .seealso: `PetscBool`, `PetscDataType`
    758: M*/
    759: typedef double PetscLogDouble;

    761: /*E
    762:     PetscDataType - Used for handling different basic data types.

    764:    Level: beginner

    766:    Notes:
    767:    Use of this should be avoided if one can directly use `MPI_Datatype` instead.

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

    772:    Developer Notes:
    773:    It would be nice if we could always just use MPI Datatypes, why can we not?

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

    778:    TODO:
    779:    Remove use of improper `PETSC_ENUM`

    781: .seealso: `PetscBinaryRead()`, `PetscBinaryWrite()`, `PetscDataTypeToMPIDataType()`,
    782:           `PetscDataTypeGetSize()`
    783: E*/
    784: typedef enum {
    785:   PETSC_DATATYPE_UNKNOWN = 0,
    786:   PETSC_DOUBLE           = 1,
    787:   PETSC_COMPLEX          = 2,
    788:   PETSC_LONG             = 3,
    789:   PETSC_SHORT            = 4,
    790:   PETSC_FLOAT            = 5,
    791:   PETSC_CHAR             = 6,
    792:   PETSC_BIT_LOGICAL      = 7,
    793:   PETSC_ENUM             = 8,
    794:   PETSC_BOOL             = 9,
    795:   PETSC___FLOAT128       = 10,
    796:   PETSC_OBJECT           = 11,
    797:   PETSC_FUNCTION         = 12,
    798:   PETSC_STRING           = 13,
    799:   PETSC___FP16           = 14,
    800:   PETSC_STRUCT           = 15,
    801:   PETSC_INT              = 16,
    802:   PETSC_INT64            = 17,
    803:   PETSC_COUNT            = 18,
    804:   PETSC_INT32            = 19,
    805: } PetscDataType;
    806: PETSC_EXTERN const char *const PetscDataTypes[];

    808: #if defined(PETSC_USE_REAL_SINGLE)
    809:   #define PETSC_REAL PETSC_FLOAT
    810: #elif defined(PETSC_USE_REAL_DOUBLE)
    811:   #define PETSC_REAL PETSC_DOUBLE
    812: #elif defined(PETSC_USE_REAL___FLOAT128)
    813:   #define PETSC_REAL PETSC___FLOAT128
    814: #elif defined(PETSC_USE_REAL___FP16)
    815:   #define PETSC_REAL PETSC___FP16
    816: #else
    817:   #define PETSC_REAL PETSC_DOUBLE
    818: #endif

    820: #if defined(PETSC_USE_COMPLEX)
    821:   #define PETSC_SCALAR PETSC_COMPLEX
    822: #else
    823:   #define PETSC_SCALAR PETSC_REAL
    824: #endif

    826: #define PETSC_FORTRANADDR PETSC_LONG

    828: /*S
    829:   PetscToken - 'Token' used for managing tokenizing strings

    831:   Level: intermediate

    833: .seealso: `PetscTokenCreate()`, `PetscTokenFind()`, `PetscTokenDestroy()`
    834: S*/
    835: typedef struct _n_PetscToken *PetscToken;

    837: /*S
    838:    PetscObject - any PETSc object, for example: `PetscViewer`, `Mat`, `Vec`, `KSP`, `DM`

    840:    Level: beginner

    842:    Notes:
    843:    This is the base class from which all PETSc objects are derived.

    845:    In certain situations one can cast an object, for example a `Vec`, to a `PetscObject` with (`PetscObject`)vec

    847: .seealso: `PetscObjectDestroy()`, `PetscObjectView()`, `PetscObjectGetName()`, `PetscObjectSetName()`, `PetscObjectReference()`, `PetscObjectDereference()`
    848: S*/
    849: typedef struct _p_PetscObject *PetscObject;

    851: /*MC
    852:     PetscObjectId - unique integer Id for a `PetscObject`

    854:     Level: developer

    856:     Note:
    857:     Unlike pointer values, object ids are never reused so one may save a `PetscObjectId` and compare it to one obtained later from a `PetscObject` to determine
    858:     if the objects are the same. Never compare two object pointer values.

    860: .seealso: `PetscObjectState`, `PetscObjectGetId()`
    861: M*/
    862: typedef PetscInt64 PetscObjectId;

    864: /*MC
    865:     PetscObjectState - integer state for a `PetscObject`

    867:     Level: developer

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

    873: .seealso: `PetscObjectId`, `PetscObjectStateGet()`, `PetscObjectStateIncrease()`, `PetscObjectStateSet()`
    874: M*/
    875: typedef PetscInt64 PetscObjectState;

    877: /*S
    878:      PetscFunctionList - Linked list of functions, possibly stored in dynamic libraries, accessed
    879:       by string name

    881:    Level: advanced

    883: .seealso: `PetscFunctionListAdd()`, `PetscFunctionListDestroy()`
    884: S*/
    885: typedef struct _n_PetscFunctionList *PetscFunctionList;

    887: /*E
    888:   PetscFileMode - Access mode for a file.

    890:   Values:
    891: +  `FILE_MODE_UNDEFINED`     - initial invalid value
    892: .  `FILE_MODE_READ`          - open a file at its beginning for reading
    893: .  `FILE_MODE_WRITE`         - open a file at its beginning for writing (will create if the file does not exist)
    894: .  `FILE_MODE_APPEND`        - open a file at end for writing
    895: .  `FILE_MODE_UPDATE`        - open a file for updating, meaning for reading and writing
    896: -  `FILE_MODE_APPEND_UPDATE` - open a file for updating, meaning for reading and writing, at the end

    898:   Level: beginner

    900: .seealso: `PetscViewerFileSetMode()`
    901: E*/
    902: typedef enum {
    903:   FILE_MODE_UNDEFINED     = -1,
    904:   FILE_MODE_READ          = 0,
    905:   FILE_MODE_WRITE         = 1,
    906:   FILE_MODE_APPEND        = 2,
    907:   FILE_MODE_UPDATE        = 3,
    908:   FILE_MODE_APPEND_UPDATE = 4
    909: } PetscFileMode;
    910: PETSC_EXTERN const char *const PetscFileModes[];

    912: typedef void *PetscDLHandle;
    913: typedef enum {
    914:   PETSC_DL_DECIDE = 0,
    915:   PETSC_DL_NOW    = 1,
    916:   PETSC_DL_LOCAL  = 2
    917: } PetscDLMode;

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

    922:    Level: developer

    924:    Note:
    925:    Used by `PetscObjectCompose()` and `PetscObjectQuery()`

    927: .seealso: `PetscObjectListAdd()`, `PetscObjectListDestroy()`, `PetscObjectListFind()`, `PetscObjectCompose()`, `PetscObjectQuery()`, `PetscFunctionList`
    928: S*/
    929: typedef struct _n_PetscObjectList *PetscObjectList;

    931: /*S
    932:    PetscDLLibrary - Linked list of dynamic libraries to search for functions

    934:    Level: developer

    936: .seealso: `PetscDLLibraryOpen()`
    937: S*/
    938: typedef struct _n_PetscDLLibrary *PetscDLLibrary;

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

    943:    Level: advanced

    945:    Note:
    946:    This is useful to attach arbitrary data to a `PetscObject` with `PetscObjectCompose()` and `PetscObjectQuery()`

    948: .seealso: `PetscObject`, `PetscContainerCreate()`, `PetscObjectCompose()`, `PetscObjectQuery()`
    949: S*/
    950: typedef struct _p_PetscContainer *PetscContainer;

    952: /*S
    953:    PetscRandom - Abstract PETSc object that manages generating random numbers

    955:    Level: intermediate

    957: .seealso: `PetscRandomCreate()`, `PetscRandomGetValue()`, `PetscRandomType`
    958: S*/
    959: typedef struct _p_PetscRandom *PetscRandom;

    961: /*
    962:    In binary files variables are stored using the following lengths,
    963:   regardless of how they are stored in memory on any one particular
    964:   machine. Use these rather than sizeof() in computing sizes for
    965:   PetscBinarySeek().
    966: */
    967: #define PETSC_BINARY_INT_SIZE    (32 / 8)
    968: #define PETSC_BINARY_FLOAT_SIZE  (32 / 8)
    969: #define PETSC_BINARY_CHAR_SIZE   (8 / 8)
    970: #define PETSC_BINARY_SHORT_SIZE  (16 / 8)
    971: #define PETSC_BINARY_DOUBLE_SIZE (64 / 8)
    972: #define PETSC_BINARY_SCALAR_SIZE sizeof(PetscScalar)

    974: /*E
    975:   PetscBinarySeekType - argument to `PetscBinarySeek()`

    977:   Values:
    978: +  `PETSC_BINARY_SEEK_SET` - offset is an absolute location in the file
    979: .  `PETSC_BINARY_SEEK_CUR` - offset is an offset from the current location of the file pointer
    980: -  `PETSC_BINARY_SEEK_END` - offset is an offset from the end of the file

    982:   Level: advanced

    984: .seealso: `PetscBinarySeek()`, `PetscBinarySynchronizedSeek()`
    985: E*/
    986: typedef enum {
    987:   PETSC_BINARY_SEEK_SET = 0,
    988:   PETSC_BINARY_SEEK_CUR = 1,
    989:   PETSC_BINARY_SEEK_END = 2
    990: } PetscBinarySeekType;

    992: /*E
    993:    PetscBuildTwoSidedType - algorithm for setting up two-sided communication for use with `PetscSF`

    995:    Values:
    996: +  `PETSC_BUILDTWOSIDED_ALLREDUCE`  - classical algorithm using an `MPI_Allreduce()` with
    997:                                       a buffer of length equal to the communicator size. Not memory-scalable due to
    998:                                       the large reduction size. Requires only an MPI-1 implementation.
    999: .  `PETSC_BUILDTWOSIDED_IBARRIER`   - nonblocking algorithm based on `MPI_Issend()` and `MPI_Ibarrier()`.
    1000:                                       Proved communication-optimal in Hoefler, Siebert, and Lumsdaine (2010). Requires an MPI-3 implementation.
    1001: -  `PETSC_BUILDTWOSIDED_REDSCATTER` - similar to above, but use more optimized function
    1002:                                       that only communicates the part of the reduction that is necessary.  Requires an MPI-2 implementation.

    1004:    Level: developer

    1006: .seealso: `PetscCommBuildTwoSided()`, `PetscCommBuildTwoSidedSetType()`, `PetscCommBuildTwoSidedGetType()`
    1007: E*/
    1008: typedef enum {
    1009:   PETSC_BUILDTWOSIDED_NOTSET     = -1,
    1010:   PETSC_BUILDTWOSIDED_ALLREDUCE  = 0,
    1011:   PETSC_BUILDTWOSIDED_IBARRIER   = 1,
    1012:   PETSC_BUILDTWOSIDED_REDSCATTER = 2
    1013:   /* Updates here must be accompanied by updates in finclude/petscsys.h and the string array in mpits.c */
    1014: } PetscBuildTwoSidedType;
    1015: PETSC_EXTERN const char *const PetscBuildTwoSidedTypes[];

    1017: /*E
    1018:   InsertMode - How the entries are combined with the current values in the vectors or matrices

    1020:   Values:
    1021: +  `NOT_SET_VALUES`    - do not actually use the values
    1022: .  `INSERT_VALUES`     - replace the current values with the provided values, unless the index is marked as constrained by the `PetscSection`
    1023: .  `ADD_VALUES`        - add the values to the current values, unless the index is marked as constrained by the `PetscSection`
    1024: .  `MAX_VALUES`        - use the maximum of each current value and provided value
    1025: .  `MIN_VALUES`        - use the minimum of each current value and provided value
    1026: .  `INSERT_ALL_VALUES` - insert, even if indices that are not marked as constrained by the `PetscSection`
    1027: .  `ADD_ALL_VALUES`    - add, even if indices that are not marked as constrained by the `PetscSection`
    1028: .  `INSERT_BC_VALUES`  - insert, but ignore indices that are not marked as constrained by the `PetscSection`
    1029: -  `ADD_BC_VALUES`     - add, but ignore indices that are not marked as constrained by the `PetscSection`

    1031:   Level: beginner

    1033:   Note:
    1034:   The `PetscSection` that determines the effects of the `InsertMode` values can be obtained by the `Vec` object with `VecGetDM()`
    1035:   and `DMGetLocalSection()`.

    1037:   Not all options are supported for all operations or PETSc object types.

    1039: .seealso: `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`,
    1040:           `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`,
    1041:           `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`
    1042: E*/
    1043: typedef enum {
    1044:   NOT_SET_VALUES,
    1045:   INSERT_VALUES,
    1046:   ADD_VALUES,
    1047:   MAX_VALUES,
    1048:   MIN_VALUES,
    1049:   INSERT_ALL_VALUES,
    1050:   ADD_ALL_VALUES,
    1051:   INSERT_BC_VALUES,
    1052:   ADD_BC_VALUES
    1053: } InsertMode;

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

    1058:     Level: beginner

    1060: .seealso: `InsertMode`, `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`,
    1061:           `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`, `ADD_VALUES`,
    1062:           `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`, `MAX_VALUES`
    1063: M*/

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

    1069:     Level: beginner

    1071: .seealso: `InsertMode`, `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`,
    1072:           `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`, `INSERT_VALUES`,
    1073:           `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`, `MAX_VALUES`
    1074: M*/

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

    1079:     Level: beginner

    1081: .seealso: `InsertMode`, `VecScatterBegin()`, `VecScatterEnd()`, `ADD_VALUES`, `INSERT_VALUES`
    1082: M*/

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

    1087:     Level: beginner

    1089: .seealso: `InsertMode`, `VecScatterBegin()`, `VecScatterEnd()`, `ADD_VALUES`, `INSERT_VALUES`
    1090: M*/

    1092: /*S
    1093:    PetscSubcomm - A decomposition of an MPI communicator into subcommunicators

    1095:    Values:
    1096: +   `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
    1097: .   `PETSC_SUBCOMM_CONTIGUOUS` - each new communicator contains a set of process with contiguous ranks in the original MPI communicator
    1098: -   `PETSC_SUBCOMM_INTERLACED` - each new communictor contains a set of processes equally far apart in rank from the others in that new communicator

    1100:    Sample Usage:
    1101: .vb
    1102:        PetscSubcommCreate()
    1103:        PetscSubcommSetNumber()
    1104:        PetscSubcommSetType(PETSC_SUBCOMM_INTERLACED);
    1105:        ccomm = PetscSubcommChild()
    1106:        PetscSubcommDestroy()
    1107: .ve

    1109:    Example:
    1110:    Consider a communicator with six processes split into 3 subcommunicators.
    1111: .vb
    1112:    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
    1113:    PETSC_SUBCOMM_INTERLACED - the first communicator contains rank 0,3, the second 1,4 and the third 2,5
    1114: .ve

    1116:    Level: advanced

    1118:    Note:
    1119:    After a call to `PetscSubcommSetType()`, `PetscSubcommSetTypeGeneral()`, or `PetscSubcommSetFromOptions()` one may call
    1120: .vb
    1121:      PetscSubcommChild() returns the associated subcommunicator on this process
    1122:      PetscSubcommContiguousParent() returns a parent communitor but with all child of the same subcommunicator having contiguous rank
    1123: .ve

    1125:    Developer Note:
    1126:    This is used in objects such as `PCREDUNDANT` to manage the subcommunicators on which the redundant computations
    1127:    are performed.

    1129: .seealso: `PetscSubcommCreate()`, `PetscSubcommSetNumber()`, `PetscSubcommSetType()`, `PetscSubcommView()`, `PetscSubcommSetFromOptions()`
    1130: S*/
    1131: typedef struct _n_PetscSubcomm *PetscSubcomm;

    1133: typedef enum {
    1134:   PETSC_SUBCOMM_GENERAL    = 0,
    1135:   PETSC_SUBCOMM_CONTIGUOUS = 1,
    1136:   PETSC_SUBCOMM_INTERLACED = 2
    1137: } PetscSubcommType;
    1138: PETSC_EXTERN const char *const PetscSubcommTypes[];

    1140: /*S
    1141:    PetscHeap - A simple class for managing heaps

    1143:    Level: intermediate

    1145: .seealso: `PetscHeapCreate()`, `PetscHeapAdd()`, `PetscHeapPop()`, `PetscHeapPeek()`, `PetscHeapStash()`, `PetscHeapUnstash()`, `PetscHeapView()`, `PetscHeapDestroy()`
    1146: S*/
    1147: typedef struct _n_PetscHeap *PetscHeap;

    1149: /*S
    1150:   PetscShmComm - Opaque handle to a partition of an `MPI_Comm` into shared-memory subcommunicators, used by PETSc to share memory between ranks that live on the same compute node

    1152:   Level: developer

    1154: .seealso: `PetscShmCommGet()`, `PetscShmCommGlobalToLocal()`, `PetscShmCommLocalToGlobal()`, `PetscShmCommGetMpiShmComm()`
    1155: S*/
    1156: typedef struct _n_PetscShmComm *PetscShmComm;

    1158: /*S
    1159:   PetscOmpCtrl - Opaque control object that PETSc uses to coordinate work between the MPI ranks of a node and OpenMP worker threads when running in the "OpenMP-on-the-rank-subset" mode

    1161:   Level: developer

    1163: .seealso: `PetscOmpCtrlCreate()`, `PetscOmpCtrlDestroy()`, `PetscOmpCtrlGetOmpComms()`, `PetscOmpCtrlOmpRegionOnMasterBegin()`, `PetscOmpCtrlOmpRegionOnMasterEnd()`, `PetscOmpCtrlBarrier()`
    1164: S*/
    1165: typedef struct _n_PetscOmpCtrl *PetscOmpCtrl;

    1167: /*S
    1168:    PetscSegBuffer - a segmented extendable buffer

    1170:    Level: developer

    1172: .seealso: `PetscSegBufferCreate()`, `PetscSegBufferGet()`, `PetscSegBufferExtract()`, `PetscSegBufferDestroy()`
    1173: S*/
    1174: typedef struct _n_PetscSegBuffer *PetscSegBuffer;

    1176: /*S
    1177:   PetscOptionsHelpPrinted - Opaque registry that tracks which options-database help strings have already been printed during one run, so that `-help` does not emit the same help text multiple times

    1179:   Level: developer

    1181: .seealso: `PetscOptions`, `PetscOptionsHelpPrintedCreate()`, `PetscOptionsHelpPrintedDestroy()`, `PetscOptionsHelpPrintedCheck()`
    1182: S*/
    1183: typedef struct _n_PetscOptionsHelpPrinted *PetscOptionsHelpPrinted;

    1185: /*S
    1186:      PetscByte - datatype used to represent bytes

    1188:      Level: intermediate

    1190: .seealso: `PetscBT`
    1191: S*/
    1192: typedef unsigned char PetscByte;

    1194: /*S
    1195:      PetscBT - PETSc bitarrays, efficient storage of arrays of boolean values

    1197:      Level: advanced

    1199: .seealso: `PetscByte`, `PetscBTCreate()`, `PetscBTDestroy()`, `PetscBTMemzero()`, `PetscBTSet()`, `PetscBTClear()`, `PetscBTLookup()`,
    1200:           `PetscBTLookupSet()`, `PetscBTLookupClear()`, `PetscBTLength()`, `PetscBTView()`
    1201: S*/
    1202: typedef PetscByte *PetscBT;

    1204: /* The number of bits in a byte */
    1205: #define PETSC_BITS_PER_BYTE CHAR_BIT