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: PETSC_ERROR_CODE_TYPEDEF enum PETSC_ERROR_CODE_NODISCARD {
40: PETSC_SUCCESS = 0,
41: PETSC_ERR_BOOLEAN_MACRO_FAILURE = 1, /* do not use */
43: PETSC_ERR_MIN_VALUE = 54, /* should always be one less than the smallest value */
45: PETSC_ERR_MEM = 55, /* unable to allocate requested memory */
46: PETSC_ERR_SUP = 56, /* no support for requested operation */
47: PETSC_ERR_SUP_SYS = 57, /* no support for requested operation on this computer system */
48: PETSC_ERR_ORDER = 58, /* operation done in wrong order */
49: PETSC_ERR_SIG = 59, /* signal received */
50: PETSC_ERR_FP = 72, /* floating point exception */
51: PETSC_ERR_COR = 74, /* corrupted PETSc object */
52: PETSC_ERR_LIB = 76, /* error in library called by PETSc */
53: PETSC_ERR_PLIB = 77, /* PETSc library generated inconsistent data */
54: PETSC_ERR_MEMC = 78, /* memory corruption */
55: PETSC_ERR_CONV_FAILED = 82, /* iterative method (KSP or SNES) failed */
56: PETSC_ERR_USER = 83, /* user has not provided needed function */
57: PETSC_ERR_SYS = 88, /* error in system call */
58: PETSC_ERR_POINTER = 70, /* pointer does not point to valid address */
59: PETSC_ERR_MPI_LIB_INCOMP = 87, /* MPI library at runtime is not compatible with MPI user compiled with */
61: PETSC_ERR_ARG_SIZ = 60, /* nonconforming object sizes used in operation */
62: PETSC_ERR_ARG_IDN = 61, /* two arguments not allowed to be the same */
63: PETSC_ERR_ARG_WRONG = 62, /* wrong argument (but object probably ok) */
64: PETSC_ERR_ARG_CORRUPT = 64, /* null or corrupted PETSc object as argument */
65: PETSC_ERR_ARG_OUTOFRANGE = 63, /* input argument, out of range */
66: PETSC_ERR_ARG_BADPTR = 68, /* invalid pointer argument */
67: PETSC_ERR_ARG_NOTSAMETYPE = 69, /* two args must be same object type */
68: PETSC_ERR_ARG_NOTSAMECOMM = 80, /* two args must be same communicators */
69: PETSC_ERR_ARG_WRONGSTATE = 73, /* object in argument is in wrong state, e.g. unassembled mat */
70: PETSC_ERR_ARG_TYPENOTSET = 89, /* the type of the object has not yet been set */
71: PETSC_ERR_ARG_INCOMP = 75, /* two arguments are incompatible */
72: PETSC_ERR_ARG_NULL = 85, /* argument is null that should not be */
73: PETSC_ERR_ARG_UNKNOWN_TYPE = 86, /* type name doesn't match any registered type */
75: PETSC_ERR_FILE_OPEN = 65, /* unable to open file */
76: PETSC_ERR_FILE_READ = 66, /* unable to read from file */
77: PETSC_ERR_FILE_WRITE = 67, /* unable to write to file */
78: PETSC_ERR_FILE_UNEXPECTED = 79, /* unexpected data in file */
80: PETSC_ERR_MAT_LU_ZRPVT = 71, /* detected a zero pivot during LU factorization */
81: PETSC_ERR_MAT_CH_ZRPVT = 81, /* detected a zero pivot during Cholesky factorization */
83: PETSC_ERR_INT_OVERFLOW = 84,
84: PETSC_ERR_FLOP_COUNT = 90,
85: PETSC_ERR_NOT_CONVERGED = 91, /* solver did not converge */
86: PETSC_ERR_MISSING_FACTOR = 92, /* MatGetFactor() failed */
87: PETSC_ERR_OPT_OVERWRITE = 93, /* attempted to over write options which should not be changed */
88: PETSC_ERR_WRONG_MPI_SIZE = 94, /* example/application run with number of MPI ranks it does not support */
89: PETSC_ERR_USER_INPUT = 95, /* missing or incorrect user input */
90: PETSC_ERR_GPU_RESOURCE = 96, /* unable to load a GPU resource, for example cuBLAS */
91: 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 */
92: PETSC_ERR_MPI = 98, /* general MPI error */
93: PETSC_ERR_RETURN = 99, /* PetscError() incorrectly returned an error code of 0 */
94: PETSC_ERR_MEM_LEAK = 100, /* memory alloc/free imbalance */
95: PETSC_ERR_PYTHON = 101, /* Exception in Python */
96: PETSC_ERR_MAX_VALUE = 102, /* this is always the one more than the largest error code */
98: /*
99: do not use, exist purely to make the enum bounds equal that of a regular int (so conversion
100: to int in main() is not undefined behavior)
101: */
102: PETSC_ERR_MIN_SIGNED_BOUND_DO_NOT_USE = INT_MIN,
103: PETSC_ERR_MAX_SIGNED_BOUND_DO_NOT_USE = INT_MAX
104: } PETSC_ERROR_CODE_ENUM_NAME;
106: #if !defined(PETSC_USE_STRICT_PETSCERRORCODE)
107: /*E
108: PetscErrorCode - Datatype used to return PETSc error codes.
110: Level: beginner
112: Notes:
113: Virtually all PETSc functions return an error code. It is the callers responsibility to check
114: the value of the returned error code after each PETSc call to determine if any errors
115: occurred. A set of convenience macros (e.g., `PetscCall()` or `PetscCallVoid()`) are provided
116: for this purpose. Failing to properly check for errors is not supported, as errors may leave
117: PETSc in an undetermined state.
119: One can retrieve the error string corresponding to a particular error code using
120: `PetscErrorMessage()`.
122: The user can also configure PETSc with the `--with-strict-petscerrorcode` option to enable
123: compiler warnings when the returned error codes are not captured and checked. Users are
124: *heavily* encouraged to opt-in to this option, as it will become enabled by default in a
125: future release.
127: Developer Notes:
128: These are the generic error codes. These error codes are used in many different places in the
129: PETSc source code. The C-string versions are at defined in `PetscErrorStrings[]` in
130: `src/sys/error/err.c`, while the Fortran versions are defined in
131: `src/sys/ftn-mod/petscerror.h`. Any changes here must also be made in both locations.
133: .seealso: `PetscErrorMessage()`, `PetscCall()`, `SETERRQ()`
134: E*/
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: /*MC
230: PetscShort - PETSc datatype for the C `short` type
232: Level: beginner
234: Note:
235: Provided so that values of C type `short` can be referenced through a PETSc-style typedef. Most user code should prefer `PetscInt` for integers.
237: .seealso: `PetscInt`, `PetscFloat`, `PetscEnum`
238: M*/
239: typedef short PetscShort;
241: /*MC
242: PetscFloat - PETSc datatype for the C `float` type
244: Level: beginner
246: Note:
247: Provided so that values of C type `float` can be referenced through a PETSc-style typedef. Most user code should prefer `PetscReal` for real-valued floating-point data, which is `float` only when PETSc is configured `--with-precision=single`.
249: .seealso: `PetscReal`, `PetscScalar`, `PetscShort`
250: M*/
251: typedef float PetscFloat;
253: #if defined(PETSC_HAVE_STDINT_H)
254: #include <stdint.h>
255: #endif
256: #if defined(PETSC_HAVE_INTTYPES_H)
259: #endif
260: #include <inttypes.h>
261: #if !defined(PRId64)
262: #define PRId64 "ld"
263: #endif
264: #endif
266: /*MC
267: 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`
269: Level: beginner
271: .seealso: `PetscBLASInt`, `PetscInt`, `PetscMPIInt`, `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt32`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PetscIntCast()`
272: M*/
273: #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 */
274: typedef int64_t PetscInt64;
276: #define PETSC_INT64_MIN INT64_MIN
277: #define PETSC_INT64_MAX INT64_MAX
279: #elif (PETSC_SIZEOF_LONG_LONG == 8)
280: typedef long long PetscInt64;
282: #define PETSC_INT64_MIN LLONG_MIN
283: #define PETSC_INT64_MAX LLONG_MAX
285: #elif defined(PETSC_HAVE___INT64)
286: typedef __int64 PetscInt64;
288: #define PETSC_INT64_MIN INT64_MIN
289: #define PETSC_INT64_MAX INT64_MAX
291: #else
292: #error "cannot determine PetscInt64 type"
293: #endif
295: #if PETSC_SIZEOF_SIZE_T == 4
296: #define PETSC_COUNT_MIN INT_MIN
297: #define PETSC_COUNT_MAX INT_MAX
298: #else
299: #define PETSC_COUNT_MIN PETSC_INT64_MIN
300: #define PETSC_COUNT_MAX PETSC_INT64_MAX
301: #endif
303: /*MC
304: 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`
306: Level: beginner
308: .seealso: `PetscBLASInt`, `PetscInt`, `PetscMPIInt`, `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt64`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PetscIntCast()`
309: M*/
310: typedef int32_t PetscInt32;
311: #define PETSC_INT32_MIN INT32_MIN
312: #define PETSC_INT32_MAX INT32_MAX
314: /*MC
315: PetscInt - PETSc type that represents an integer, used primarily to
316: 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.
318: Level: beginner
320: Notes:
321: 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`.
323: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt32`, `PetscInt64`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PetscIntCast()`, `PETSC_INT_MIN`, `PETSC_INT_MAX`
324: M*/
325: #if defined(PETSC_USE_64BIT_INDICES)
326: typedef PetscInt64 PetscInt;
328: #define PETSC_INT_MIN PETSC_INT64_MIN
329: #define PETSC_INT_MAX PETSC_INT64_MAX
330: #define PetscInt_FMT PetscInt64_FMT
331: #else
332: typedef int PetscInt;
334: enum {
335: PETSC_INT_MIN = INT_MIN,
336: PETSC_INT_MAX = INT_MAX
337: };
338: #define PetscInt_FMT "d"
339: #endif
341: #define PETSC_UINT16_MAX 65535
343: /* deprecated */
344: #define PETSC_MIN_INT PETSC_INT_MIN
345: #define PETSC_MAX_INT PETSC_INT_MAX
346: #define PETSC_MAX_UINT16 PETSC_UINT16_MAX
348: #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 */
349: #define MPIU_INT64 MPI_INT64_T
350: #define PetscInt64_FMT PRId64
351: #elif (PETSC_SIZEOF_LONG_LONG == 8)
352: #define MPIU_INT64 MPI_LONG_LONG_INT
353: #define PetscInt64_FMT "lld"
354: #elif defined(PETSC_HAVE___INT64)
355: #define MPIU_INT64 MPI_INT64_T
356: #define PetscInt64_FMT "ld"
357: #else
358: #error "cannot determine PetscInt64 type"
359: #endif
361: #define MPIU_INT32 MPI_INT32_T
362: #define PetscInt32_FMT PRId32
364: /*MC
365: PetscBLASInt - datatype used to represent 'int' parameters to BLAS/LAPACK functions.
367: Level: intermediate
369: Notes:
370: Usually this is the same as `PetscInt`, but if PETSc was built with `--with-64-bit-indices` but
371: standard C/Fortran integers are 32-bit then this may not be the same as `PetscInt`,
372: except on some BLAS/LAPACK implementations that support 64-bit integers see the notes below.
374: `PetscErrorCode` `PetscBLASIntCast`(a,&b) checks if the given `PetscInt` a will fit in a `PetscBLASInt`, if not it
375: generates a `PETSC_ERR_ARG_OUTOFRANGE` error
377: Installation Notes\:
378: ./configure automatically determines the size of the integers used by BLAS/LAPACK except when `--with-batch` is used
379: 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`
381: MATLAB ships with BLAS and LAPACK that use 64-bit integers, for example if you run ./configure with, the option
382: `--with-blaslapack-lib`=[/Applications/MATLAB_R2010b.app/bin/maci64/libmwblas.dylib,/Applications/MATLAB_R2010b.app/bin/maci64/libmwlapack.dylib]
384: 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
385: against the 64-bit version, otherwise it uses the 32-bit version
387: 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
389: External packages such as hypre, ML, SuperLU etc do not provide any support for passing 64-bit integers to BLAS/LAPACK so cannot
390: 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
391: these external libraries while using 64-bit integer BLAS/LAPACK.
393: .seealso: `PetscMPIInt`, `PetscInt`, `PetscBLASIntCast()`
394: M*/
395: #if defined(PETSC_HAVE_64BIT_BLAS_INDICES)
396: typedef PetscInt64 PetscBLASInt;
398: #define PETSC_BLAS_INT_MIN PETSC_INT64_MIN
399: #define PETSC_BLAS_INT_MAX PETSC_INT64_MAX
400: #define PetscBLASInt_FMT PetscInt64_FMT
401: #else
402: typedef int PetscBLASInt;
404: enum {
405: PETSC_BLAS_INT_MIN = INT_MIN,
406: PETSC_BLAS_INT_MAX = INT_MAX
407: };
409: #define PetscBLASInt_FMT "d"
410: #endif
412: /*MC
413: PetscCuBLASInt - datatype used to represent 'int' parameters to cuBLAS/cuSOLVER functions.
415: Level: intermediate
417: Notes:
418: As of this writing `PetscCuBLASInt` is always the system `int`.
420: `PetscErrorCode` `PetscCuBLASIntCast`(a,&b) checks if the given `PetscInt` a will fit in a `PetscCuBLASInt`, if not it
421: generates a `PETSC_ERR_ARG_OUTOFRANGE` error
423: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscCuBLASIntCast()`
424: M*/
425: typedef int PetscCuBLASInt;
427: enum {
428: PETSC_CUBLAS_INT_MIN = INT_MIN,
429: PETSC_CUBLAS_INT_MAX = INT_MAX
430: };
432: /*MC
433: PetscHipBLASInt - datatype used to represent 'int' parameters to hipBLAS/hipSOLVER functions.
435: Level: intermediate
437: Notes:
438: `PetscHipBLASInt` is always the system `int`.
440: `PetscErrorCode` `PetscHipBLASIntCast`(a,&b) checks if the given `PetscInt` a will fit in a `PetscHipBLASInt`, if not it
441: generates a `PETSC_ERR_ARG_OUTOFRANGE` error
443: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscHipBLASIntCast()`
444: M*/
445: typedef int PetscHipBLASInt;
447: enum {
448: PETSC_HIPBLAS_INT_MIN = INT_MIN,
449: PETSC_HIPBLAS_INT_MAX = INT_MAX
450: };
452: /*MC
453: PetscExodusIIInt - datatype used to represent 'int' parameters to ExodusII functions.
455: Level: intermediate
457: Notes:
458: This is the same as `int`
460: .seealso: `PetscMPIInt`, `PetscInt`, `PetscExodusIIFloat`, `PetscBLASIntCast()`
461: M*/
462: typedef int PetscExodusIIInt;
463: #define PetscExodusIIInt_FMT "d"
465: /*MC
466: PetscExodusIIFloat - datatype used to represent 'float' parameters to ExodusII functions.
468: Level: intermediate
470: Notes:
471: This is the same as `float`
473: .seealso: `PetscMPIInt`, `PetscInt`, `PetscExodusIIInt`, `PetscBLASIntCast()`
474: M*/
475: typedef float PetscExodusIIFloat;
477: /*E
478: PetscBool - Logical variable.
480: Level: beginner
482: Notes:
483: This is a C bool.
485: Use `MPI_C_BOOL` for communicating with MPI calls in C, C++, and Fortran.
487: Fortran Note:
488: This is a `logical(C_BOOL)` with an internal representation that is equivalent to that of a `bool` in C and C++.
489: 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).
491: Developer Note:
492: We should deprecate this definition since there is a native representation in all the languages.
494: .seealso: `PETSC_TRUE`, `PETSC_FALSE`, `PetscNot()`, `PetscBool3`, `PetscBool3ToBool()`, `PetscBoolToBool3()`
495: E*/
496: typedef bool PetscBool;
497: #define PETSC_FALSE false
498: #define PETSC_TRUE true
499: PETSC_EXTERN const char *const PetscBools[];
501: /*E
502: PetscBool3 - Ternary logical variable. Actually an enum in C and a 4 byte integer in Fortran.
504: Level: beginner
506: Note:
507: Should not be used with the `if (flg)` or `if (!flg)` syntax.
509: .seealso: `PETSC_TRUE`, `PETSC_FALSE`, `PetscNot()`, `PETSC_BOOL3_TRUE`, `PETSC_BOOL3_FALSE`, `PETSC_BOOL3_UNKNOWN`, `PetscBool3ToBool()`, `PetscBoolToBool3()`
510: E*/
511: typedef enum {
512: PETSC_BOOL3_FALSE = 0,
513: PETSC_BOOL3_TRUE = 1,
514: PETSC_BOOL3_UNKNOWN = -1 /* the value is unknown at the time of query, but might be determined later */
515: } PetscBool3;
516: PETSC_EXTERN const char *const PetscBool3s[];
518: /*MC
519: PetscBool3ToBool - Convert a `PetscBool3` to a `PetscBool`
521: Synopsis:
522: #include <petscsystypes.h>
523: PetscBool PetscBool3ToBool(PetscBool3 var)
525: No Fortran Support
527: Level: beginner
529: Note:
530: Evaluates to `PETSC_TRUE` if `var` is `PETSC_BOOL3_TRUE`, and `PETSC_FALSE` otherwise (including when `var` is `PETSC_BOOL3_UNKNOWN`).
532: .seealso: `PetscBool`, `PetscBool3`, `PetscBoolToBool3()`
533: M*/
534: #define PetscBool3ToBool(a) ((a) == PETSC_BOOL3_TRUE ? PETSC_TRUE : PETSC_FALSE)
536: /*MC
537: PetscBoolToBool3 - Convert a `PetscBool` to a `PetscBool3`
539: Synopsis:
540: #include <petscsystypes.h>
541: PetscBool3 PetscBoolToBool3(PetscBool var)
543: No Fortran Support
545: Level: beginner
547: Note:
548: Evaluates to `PETSC_BOOL3_TRUE` if `var` is `PETSC_TRUE`, and `PETSC_BOOL3_FALSE` otherwise.
550: .seealso: `PetscBool`, `PetscBool3`, `PetscBool3ToBool()`
551: M*/
552: #define PetscBoolToBool3(a) ((a) == PETSC_TRUE ? PETSC_BOOL3_TRUE : PETSC_BOOL3_FALSE)
554: /*MC
555: PetscReal - PETSc type that represents a real number version of `PetscScalar`
557: Level: beginner
559: Notes:
560: For MPI calls that require datatypes, use `MPIU_REAL` as the datatype for `PetscReal` and `MPIU_SUM`, `MPIU_MAX`, etc. for operations.
561: They will automatically work correctly regardless of the size of `PetscReal`.
563: See `PetscScalar` for details on how to ./configure the size of `PetscReal`.
565: .seealso: `PetscScalar`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`
566: M*/
567: #if defined(PETSC_USE_REAL_SINGLE)
568: typedef float PetscReal;
569: #elif defined(PETSC_USE_REAL_DOUBLE)
570: typedef double PetscReal;
571: #elif defined(PETSC_USE_REAL___FLOAT128)
572: #if defined(__cplusplus)
573: extern "C" {
574: #endif
575: #include <quadmath.h>
576: #if defined(__cplusplus)
577: }
578: #endif
579: typedef __float128 PetscReal;
580: #elif defined(PETSC_USE_REAL___FP16)
581: typedef __fp16 PetscReal;
582: #endif /* PETSC_USE_REAL_* */
584: #if !defined(PETSC_SKIP_COMPLEX)
585: #if defined(PETSC_CLANGUAGE_CXX)
586: #if !defined(PETSC_USE_REAL___FP16) && !defined(PETSC_USE_REAL___FLOAT128)
587: #if defined(__cplusplus) && defined(PETSC_HAVE_CXX_COMPLEX) /* enable complex for library code */
588: #define PETSC_HAVE_COMPLEX 1
589: #elif !defined(__cplusplus) && defined(PETSC_HAVE_C99_COMPLEX) && defined(PETSC_HAVE_CXX_COMPLEX) /* User code only - conditional on library code complex support */
590: #define PETSC_HAVE_COMPLEX 1
591: #endif
592: #elif defined(PETSC_USE_REAL___FLOAT128) && defined(PETSC_HAVE_C99_COMPLEX)
593: #define PETSC_HAVE_COMPLEX 1
594: #endif
595: #else /* !PETSC_CLANGUAGE_CXX */
596: #if !defined(PETSC_USE_REAL___FP16)
598: #define PETSC_HAVE_COMPLEX 1
599: #elif defined(__cplusplus) && defined(PETSC_HAVE_C99_COMPLEX) && defined(PETSC_HAVE_CXX_COMPLEX) /* User code only - conditional on library code complex support */
600: #define PETSC_HAVE_COMPLEX 1
601: #endif
602: #endif
603: #endif /* PETSC_CLANGUAGE_CXX */
604: #endif /* !PETSC_SKIP_COMPLEX */
606: #if defined(PETSC_HAVE_COMPLEX)
607: #if defined(__cplusplus) /* C++ complex support */
608: /* Locate a C++ complex template library */
609: #if defined(PETSC_DESIRE_KOKKOS_COMPLEX) /* Defined in petscvec_kokkos.hpp for *.kokkos.cxx files */
610: #define petsccomplexlib Kokkos
611: #include <Kokkos_Complex.hpp>
612: #elif (defined(__CUDACC__) && defined(PETSC_HAVE_CUDA)) || (defined(__HIPCC__) && defined(PETSC_HAVE_HIP))
613: #define petsccomplexlib thrust
614: #include <thrust/complex.h>
615: #elif defined(PETSC_USE_REAL___FLOAT128)
616: #include <complex.h>
617: #else
618: #define petsccomplexlib std
619: #include <complex>
620: #endif
622: /* Define PetscComplex based on the precision */
623: #if defined(PETSC_USE_REAL_SINGLE)
624: typedef petsccomplexlib::complex<float> PetscComplex;
625: #elif defined(PETSC_USE_REAL_DOUBLE)
626: typedef petsccomplexlib::complex<double> PetscComplex;
627: #elif defined(PETSC_USE_REAL___FLOAT128)
628: typedef __complex128 PetscComplex;
629: #endif
631: /* Include a PETSc C++ complex 'fix'. Check PetscComplex manual page for details */
632: #if defined(PETSC_HAVE_CXX_COMPLEX_FIX) && !defined(PETSC_SKIP_CXX_COMPLEX_FIX)
633: #include <petsccxxcomplexfix.h>
634: #endif
635: #else /* c99 complex support */
636: #include <complex.h>
637: #if defined(PETSC_USE_REAL_SINGLE) || defined(PETSC_USE_REAL___FP16)
639: typedef float _Complex PetscComplex;
640: #elif defined(PETSC_USE_REAL_DOUBLE)
641: typedef double _Complex PetscComplex;
642: #elif defined(PETSC_USE_REAL___FLOAT128)
644: /*MC
645: PetscComplex - PETSc type that represents a complex number with precision matching that of `PetscReal`.
647: Synopsis:
648: #include <petscsys.h>
649: PetscComplex number = 1. + 2.*PETSC_i;
651: Level: beginner
653: Notes:
654: For MPI calls that require datatypes, use `MPIU_COMPLEX` as the datatype for `PetscComplex` and `MPIU_SUM` etc for operations.
655: They will automatically work correctly regardless of the size of `PetscComplex`.
657: See `PetscScalar` for details on how to `./configure` the size of `PetscReal`
659: Complex numbers are automatically available if PETSc was able to find a working complex implementation
661: PETSc has a 'fix' for complex numbers to support expressions such as `std::complex<PetscReal>` + `PetscInt`, which are not supported by the standard
662: C++ library, but are convenient for PETSc users. If the C++ compiler is able to compile code in `petsccxxcomplexfix.h` (This is checked by
663: configure), we include `petsccxxcomplexfix.h` to provide this convenience.
665: 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`
666: at the beginning of the C++ file to skip the fix.
668: .seealso: `PetscReal`, `PetscScalar`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PETSC_i`
669: M*/
670: typedef __complex128 PetscComplex;
671: #endif /* PETSC_USE_REAL_* */
672: #endif /* !__cplusplus */
673: #endif /* PETSC_HAVE_COMPLEX */
675: /*MC
676: PetscScalar - PETSc type that represents either a double precision real number, a double precision
677: complex number, a single precision real number, a __float128 real or complex or a __fp16 real - if the code is configured
678: with `--with-scalar-type`=real,complex `--with-precision`=single,double,__float128,__fp16
680: Level: beginner
682: Note:
683: 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`.
685: .seealso: `PetscReal`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PetscRealPart()`, `PetscImaginaryPart()`
686: M*/
687: #if defined(PETSC_USE_COMPLEX) && defined(PETSC_HAVE_COMPLEX)
688: typedef PetscComplex PetscScalar;
689: #else /* PETSC_USE_COMPLEX */
690: typedef PetscReal PetscScalar;
691: #endif /* PETSC_USE_COMPLEX */
693: /*E
694: PetscCopyMode - Determines how an array or `PetscObject` passed to certain functions is copied or retained by the aggregate `PetscObject`
696: Values for array input:
697: + `PETSC_COPY_VALUES` - the array values are copied into new space, the user is free to reuse or delete the passed in array
698: . `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
699: delete the array. The array MUST have been obtained with `PetscMalloc()`. Hence this mode cannot be used in Fortran.
700: - `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
701: the array but the user must delete the array after the object is destroyed.
703: Values for PetscObject:
704: + `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.
705: . `PETSC_OWN_POINTER` - the input `PetscObject` is referenced by pointer (with reference count), thus should not be modified by the user.
706: increases its reference count).
707: - `PETSC_USE_POINTER` - invalid for `PetscObject` inputs.
709: Level: beginner
711: .seealso: `InsertMode`
712: E*/
713: typedef enum {
714: PETSC_COPY_VALUES,
715: PETSC_OWN_POINTER,
716: PETSC_USE_POINTER
717: } PetscCopyMode;
718: PETSC_EXTERN const char *const PetscCopyModes[];
720: /*MC
721: PETSC_FALSE - False value of `PetscBool`
723: Level: beginner
725: Note:
726: Zero integer
728: .seealso: `PetscBool`, `PetscBool3`, `PETSC_TRUE`
729: M*/
731: /*MC
732: PETSC_TRUE - True value of `PetscBool`
734: Level: beginner
736: Note:
737: Nonzero integer
739: .seealso: `PetscBool`, `PetscBool3`, `PETSC_FALSE`
740: M*/
742: /*MC
743: PETSC_INT_MIN - Minimum integer value representable by a `PetscInt`
745: Level: beginner
747: .seealso: `PETSC_INT_MAX`, `PetscInt`, `PetscIntCast()`
748: M*/
750: /*MC
751: PETSC_INT_MAX - Maximum integer value representable by a `PetscInt`
753: Level: beginner
755: .seealso: `PETSC_INT_MIN`, `PetscInt`, `PetscIntCast()`
756: M*/
758: /*MC
759: PETSC_MAX_PATH_LEN - Maximum length of a path (file name including directory)
761: Level: beginner
763: Note:
764: This value is set at configuration time based on the system's maximum path length (e.g., `MAXPATHLEN`, `MAX_PATH`, or `_MAX_PATH`).
765: It defaults to 4096 if no system value is available.
767: .seealso: `PetscGetFullPath()`, `PetscGetRealPath()`, `PetscGetHomeDirectory()`
768: M*/
770: /*MC
771: PetscLogDouble - Used for logging times
773: Level: developer
775: Note:
776: Contains double precision numbers that are not used in the numerical computations, but rather in logging, timing etc.
778: .seealso: `PetscBool`, `PetscDataType`
779: M*/
780: typedef double PetscLogDouble;
782: /*E
783: PetscDataType - Used for handling different basic data types.
785: Level: beginner
787: Notes:
788: Use of this should be avoided if one can directly use `MPI_Datatype` instead.
790: `PETSC_INT` is the datatype for a `PetscInt`, regardless of whether it is 4 or 8 bytes.
791: `PETSC_REAL`, `PETSC_COMPLEX` and `PETSC_SCALAR` are the datatypes for `PetscReal`, `PetscComplex` and `PetscScalar`, regardless of their sizes.
793: Developer Notes:
794: It would be nice if we could always just use MPI Datatypes, why can we not?
796: If you change any values in `PetscDatatype` make sure you update their usage in
797: share/petsc/matlab/PetscBagRead.m and share/petsc/matlab/@PetscOpenSocket/read/write.m
799: TODO:
800: Remove use of improper `PETSC_ENUM`
802: .seealso: `PetscBinaryRead()`, `PetscBinaryWrite()`, `PetscDataTypeToMPIDataType()`,
803: `PetscDataTypeGetSize()`
804: E*/
805: typedef enum {
806: PETSC_DATATYPE_UNKNOWN = 0,
807: PETSC_DOUBLE = 1,
808: PETSC_COMPLEX = 2,
809: PETSC_LONG = 3,
810: PETSC_SHORT = 4,
811: PETSC_FLOAT = 5,
812: PETSC_CHAR = 6,
813: PETSC_BIT_LOGICAL = 7,
814: PETSC_ENUM = 8,
815: PETSC_BOOL = 9,
816: PETSC___FLOAT128 = 10,
817: PETSC_OBJECT = 11,
818: PETSC_FUNCTION = 12,
819: PETSC_STRING = 13,
820: PETSC___FP16 = 14,
821: PETSC_STRUCT = 15,
822: PETSC_INT = 16,
823: PETSC_INT64 = 17,
824: PETSC_COUNT = 18,
825: PETSC_INT32 = 19,
826: } PetscDataType;
827: PETSC_EXTERN const char *const PetscDataTypes[];
829: #if defined(PETSC_USE_REAL_SINGLE)
830: #define PETSC_REAL PETSC_FLOAT
831: #elif defined(PETSC_USE_REAL_DOUBLE)
832: #define PETSC_REAL PETSC_DOUBLE
833: #elif defined(PETSC_USE_REAL___FLOAT128)
834: #define PETSC_REAL PETSC___FLOAT128
835: #elif defined(PETSC_USE_REAL___FP16)
836: #define PETSC_REAL PETSC___FP16
837: #else
838: #define PETSC_REAL PETSC_DOUBLE
839: #endif
841: #if defined(PETSC_USE_COMPLEX)
842: #define PETSC_SCALAR PETSC_COMPLEX
843: #else
844: #define PETSC_SCALAR PETSC_REAL
845: #endif
847: #define PETSC_FORTRANADDR PETSC_LONG
849: /*S
850: PetscToken - 'Token' used for managing tokenizing strings
852: Level: intermediate
854: .seealso: `PetscTokenCreate()`, `PetscTokenFind()`, `PetscTokenDestroy()`
855: S*/
856: typedef struct _n_PetscToken *PetscToken;
858: /*S
859: PetscObject - any PETSc object, for example: `PetscViewer`, `Mat`, `Vec`, `KSP`, `DM`
861: Level: beginner
863: Notes:
864: This is the base class from which all PETSc objects are derived.
866: In certain situations one can cast an object, for example a `Vec`, to a `PetscObject` with (`PetscObject`)vec
868: .seealso: `PetscObjectDestroy()`, `PetscObjectView()`, `PetscObjectGetName()`, `PetscObjectSetName()`, `PetscObjectReference()`, `PetscObjectDereference()`
869: S*/
870: typedef struct _p_PetscObject *PetscObject;
872: /*MC
873: PetscObjectId - unique integer Id for a `PetscObject`
875: Level: developer
877: Note:
878: 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
879: if the objects are the same. Never compare two object pointer values.
881: .seealso: `PetscObjectState`, `PetscObjectGetId()`
882: M*/
883: typedef PetscInt64 PetscObjectId;
885: /*MC
886: PetscObjectState - integer state for a `PetscObject`
888: Level: developer
890: Note:
891: Object state is always-increasing and (for objects that track state) can be used to determine if an object has
892: changed since the last time you interacted with it. It is 64-bit so that it will not overflow for a very long time.
894: .seealso: `PetscObjectId`, `PetscObjectStateGet()`, `PetscObjectStateIncrease()`, `PetscObjectStateSet()`
895: M*/
896: typedef PetscInt64 PetscObjectState;
898: /*S
899: PetscFunctionList - Linked list of functions, possibly stored in dynamic libraries, accessed
900: by string name
902: Level: advanced
904: .seealso: `PetscFunctionListAdd()`, `PetscFunctionListDestroy()`
905: S*/
906: typedef struct _n_PetscFunctionList *PetscFunctionList;
908: /*E
909: PetscFileMode - Access mode for a file.
911: Values:
912: + `FILE_MODE_UNDEFINED` - initial invalid value
913: . `FILE_MODE_READ` - open a file at its beginning for reading
914: . `FILE_MODE_WRITE` - open a file at its beginning for writing (will create if the file does not exist)
915: . `FILE_MODE_APPEND` - open a file at end for writing
916: . `FILE_MODE_UPDATE` - open a file for updating, meaning for reading and writing
917: - `FILE_MODE_APPEND_UPDATE` - open a file for updating, meaning for reading and writing, at the end
919: Level: beginner
921: .seealso: `PetscViewerFileSetMode()`
922: E*/
923: typedef enum {
924: FILE_MODE_UNDEFINED = -1,
925: FILE_MODE_READ = 0,
926: FILE_MODE_WRITE = 1,
927: FILE_MODE_APPEND = 2,
928: FILE_MODE_UPDATE = 3,
929: FILE_MODE_APPEND_UPDATE = 4
930: } PetscFileMode;
931: PETSC_EXTERN const char *const PetscFileModes[];
933: /*S
934: PetscDLHandle - dynamic library handler object returned from `PetscDLOpen()`
936: Level: developer
938: .seealso: `PetscDLOpen()`, `PetscDLClose()`, `PetscDLSym()`
939: S*/
940: typedef void *PetscDLHandle;
942: /*E
943: PetscDLMode - Controls when the symbols of a dynamic library opened with `PetscDLOpen()` are resolved and whether they are visible to subsequently loaded libraries
945: Values:
946: + `PETSC_DL_DECIDE` - let PETSc choose a sensible default, lazy resolution and global visibility: `RTLD_LAZY` | `RTLD_GLOBAL`
947: . `PETSC_DL_NOW` - resolve all symbols of the library immediately on load (corresponds to `RTLD_NOW`)
948: - `PETSC_DL_LOCAL` - keep them private to this library (corresponds to `RTLD_LOCAL`)
950: Level: developer
952: .seealso: `PetscDLOpen()`, `PetscDLClose()`, `PetscDLSym()`, `PetscDLHandle`
953: E*/
954: typedef enum {
955: PETSC_DL_DECIDE = 0,
956: PETSC_DL_NOW = 1,
957: PETSC_DL_LOCAL = 2
958: } PetscDLMode;
960: /*S
961: PetscObjectList - Linked list of PETSc objects, each accessible by string name
963: Level: developer
965: Note:
966: Used by `PetscObjectCompose()` and `PetscObjectQuery()`
968: .seealso: `PetscObjectListAdd()`, `PetscObjectListDestroy()`, `PetscObjectListFind()`, `PetscObjectCompose()`, `PetscObjectQuery()`, `PetscFunctionList`
969: S*/
970: typedef struct _n_PetscObjectList *PetscObjectList;
972: /*S
973: PetscDLLibrary - Linked list of dynamic libraries to search for functions
975: Level: developer
977: .seealso: `PetscDLLibraryOpen()`
978: S*/
979: typedef struct _n_PetscDLLibrary *PetscDLLibrary;
981: /*S
982: PetscContainer - Simple PETSc object that contains a pointer to any required data
984: Level: advanced
986: Note:
987: This is useful to attach arbitrary data to a `PetscObject` with `PetscObjectCompose()` and `PetscObjectQuery()`
989: .seealso: `PetscObject`, `PetscContainerCreate()`, `PetscObjectCompose()`, `PetscObjectQuery()`
990: S*/
991: typedef struct _p_PetscContainer *PetscContainer;
993: /*S
994: PetscRandom - Abstract PETSc object that manages generating random numbers
996: Level: intermediate
998: .seealso: `PetscRandomCreate()`, `PetscRandomGetValue()`, `PetscRandomType`
999: S*/
1000: typedef struct _p_PetscRandom *PetscRandom;
1002: /*
1003: In binary files variables are stored using the following lengths,
1004: regardless of how they are stored in memory on any one particular
1005: machine. Use these rather than sizeof() in computing sizes for
1006: PetscBinarySeek().
1007: */
1008: #define PETSC_BINARY_INT_SIZE (32 / 8)
1009: #define PETSC_BINARY_FLOAT_SIZE (32 / 8)
1010: #define PETSC_BINARY_CHAR_SIZE (8 / 8)
1011: #define PETSC_BINARY_SHORT_SIZE (16 / 8)
1012: #define PETSC_BINARY_DOUBLE_SIZE (64 / 8)
1013: #define PETSC_BINARY_SCALAR_SIZE sizeof(PetscScalar)
1015: /*E
1016: PetscBinarySeekType - argument to `PetscBinarySeek()`
1018: Values:
1019: + `PETSC_BINARY_SEEK_SET` - offset is an absolute location in the file
1020: . `PETSC_BINARY_SEEK_CUR` - offset is an offset from the current location of the file pointer
1021: - `PETSC_BINARY_SEEK_END` - offset is an offset from the end of the file
1023: Level: advanced
1025: .seealso: `PetscBinarySeek()`, `PetscBinarySynchronizedSeek()`
1026: E*/
1027: typedef enum {
1028: PETSC_BINARY_SEEK_SET = 0,
1029: PETSC_BINARY_SEEK_CUR = 1,
1030: PETSC_BINARY_SEEK_END = 2
1031: } PetscBinarySeekType;
1033: /*E
1034: PetscBuildTwoSidedType - algorithm for setting up two-sided communication for use with `PetscSF`
1036: Values:
1037: + `PETSC_BUILDTWOSIDED_ALLREDUCE` - classical algorithm using an `MPI_Allreduce()` with
1038: a buffer of length equal to the communicator size. Not memory-scalable due to
1039: the large reduction size. Requires only an MPI-1 implementation.
1040: . `PETSC_BUILDTWOSIDED_IBARRIER` - nonblocking algorithm based on `MPI_Issend()` and `MPI_Ibarrier()`.
1041: Proved communication-optimal in Hoefler, Siebert, and Lumsdaine (2010). Requires an MPI-3 implementation.
1042: - `PETSC_BUILDTWOSIDED_REDSCATTER` - similar to above, but use more optimized function
1043: that only communicates the part of the reduction that is necessary. Requires an MPI-2 implementation.
1045: Level: developer
1047: .seealso: `PetscCommBuildTwoSided()`, `PetscCommBuildTwoSidedSetType()`, `PetscCommBuildTwoSidedGetType()`
1048: E*/
1049: typedef enum {
1050: PETSC_BUILDTWOSIDED_NOTSET = -1,
1051: PETSC_BUILDTWOSIDED_ALLREDUCE = 0,
1052: PETSC_BUILDTWOSIDED_IBARRIER = 1,
1053: PETSC_BUILDTWOSIDED_REDSCATTER = 2
1054: /* Updates here must be accompanied by updates in finclude/petscsys.h and the string array in mpits.c */
1055: } PetscBuildTwoSidedType;
1056: PETSC_EXTERN const char *const PetscBuildTwoSidedTypes[];
1058: /*E
1059: InsertMode - How the entries are combined with the current values in the vectors or matrices
1061: Values:
1062: + `NOT_SET_VALUES` - do not actually use the values
1063: . `INSERT_VALUES` - replace the current values with the provided values, unless the index is marked as constrained by the `PetscSection`
1064: . `ADD_VALUES` - add the values to the current values, unless the index is marked as constrained by the `PetscSection`
1065: . `MAX_VALUES` - use the maximum of each current value and provided value
1066: . `MIN_VALUES` - use the minimum of each current value and provided value
1067: . `INSERT_ALL_VALUES` - insert, even if indices that are not marked as constrained by the `PetscSection`
1068: . `ADD_ALL_VALUES` - add, even if indices that are not marked as constrained by the `PetscSection`
1069: . `INSERT_BC_VALUES` - insert, but ignore indices that are not marked as constrained by the `PetscSection`
1070: - `ADD_BC_VALUES` - add, but ignore indices that are not marked as constrained by the `PetscSection`
1072: Level: beginner
1074: Note:
1075: The `PetscSection` that determines the effects of the `InsertMode` values can be obtained by the `Vec` object with `VecGetDM()`
1076: and `DMGetLocalSection()`.
1078: Not all options are supported for all operations or PETSc object types.
1080: .seealso: `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`,
1081: `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`,
1082: `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`
1083: E*/
1084: typedef enum {
1085: NOT_SET_VALUES,
1086: INSERT_VALUES,
1087: ADD_VALUES,
1088: MAX_VALUES,
1089: MIN_VALUES,
1090: INSERT_ALL_VALUES,
1091: ADD_ALL_VALUES,
1092: INSERT_BC_VALUES,
1093: ADD_BC_VALUES
1094: } InsertMode;
1096: /*MC
1097: INSERT_VALUES - Put a value into a vector or matrix, overwrites any previous value
1099: Level: beginner
1101: .seealso: `InsertMode`, `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`,
1102: `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`, `ADD_VALUES`,
1103: `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`, `MAX_VALUES`
1104: M*/
1106: /*MC
1107: ADD_VALUES - Adds a value into a vector or matrix, if there previously was no value, just puts the
1108: value into that location
1110: Level: beginner
1112: .seealso: `InsertMode`, `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`,
1113: `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`, `INSERT_VALUES`,
1114: `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`, `MAX_VALUES`
1115: M*/
1117: /*MC
1118: MAX_VALUES - Puts the maximum of the scattered/gathered value and the current value into each location
1120: Level: beginner
1122: .seealso: `InsertMode`, `VecScatterBegin()`, `VecScatterEnd()`, `ADD_VALUES`, `INSERT_VALUES`
1123: M*/
1125: /*MC
1126: MIN_VALUES - Puts the minimal of the scattered/gathered value and the current value into each location
1128: Level: beginner
1130: .seealso: `InsertMode`, `VecScatterBegin()`, `VecScatterEnd()`, `ADD_VALUES`, `INSERT_VALUES`
1131: M*/
1133: /*S
1134: PetscSubcomm - A decomposition of an MPI communicator into subcommunicators
1136: Sample Usage:
1137: .vb
1138: PetscSubcommCreate()
1139: PetscSubcommSetNumber()
1140: PetscSubcommSetType(PETSC_SUBCOMM_INTERLACED);
1141: ccomm = PetscSubcommChild()
1142: PetscSubcommDestroy()
1143: .ve
1145: Level: advanced
1147: Note:
1148: After a call to `PetscSubcommSetType()`, `PetscSubcommSetTypeGeneral()`, or `PetscSubcommSetFromOptions()` one may call
1149: .vb
1150: PetscSubcommChild() returns the associated subcommunicator on this process
1151: PetscSubcommContiguousParent() returns a parent communitor but with all child of the same subcommunicator having contiguous rank
1152: .ve
1154: Developer Note:
1155: This is used in objects such as `PCREDUNDANT` to manage the subcommunicators on which the redundant computations
1156: are performed.
1158: .seealso: `PetscSubcommCreate()`, `PetscSubcommSetNumber()`, `PetscSubcommSetType()`, `PetscSubcommView()`, `PetscSubcommSetFromOptions()`,
1159: `PetscSubcommType`
1160: S*/
1161: typedef struct _n_PetscSubcomm *PetscSubcomm;
1163: /*E
1164: PetscSubcommType - How a `PetscSubcomm` is constructed
1166: Values:
1167: + `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
1168: . `PETSC_SUBCOMM_CONTIGUOUS` - each new communicator contains a set of process with contiguous ranks in the original MPI communicator
1169: - `PETSC_SUBCOMM_INTERLACED` - each new communicator contains a set of processes equally far apart in rank from the others in that new communicator
1171: Level: advanced
1173: Example:
1174: Consider a communicator with six processes split into 3 subcommunicators.
1175: .vb
1176: PETSC_SUBCOMM_CONTIGUOUS - the first communicator contains rank 0 and 1, the second rank 2 and 3, and the third rank 4 and 5 in the original ordering of the original communicator
1177: PETSC_SUBCOMM_INTERLACED - the first communicator contains rank 0 and 3, the second rank 1 and 4, and the third process 2 and 5
1178: .ve
1180: .seealso: `PetscSubcommCreate()`, `PetscSubcommSetNumber()`, `PetscSubcommSetType()`, `PetscSubcommView()`, `PetscSubcommSetFromOptions()`
1181: E*/
1182: typedef enum {
1183: PETSC_SUBCOMM_GENERAL = 0,
1184: PETSC_SUBCOMM_CONTIGUOUS = 1,
1185: PETSC_SUBCOMM_INTERLACED = 2
1186: } PetscSubcommType;
1187: PETSC_EXTERN const char *const PetscSubcommTypes[];
1189: /*S
1190: PetscHeap - A simple class for managing heaps
1192: Level: intermediate
1194: .seealso: `PetscHeapCreate()`, `PetscHeapAdd()`, `PetscHeapPop()`, `PetscHeapPeek()`, `PetscHeapStash()`, `PetscHeapUnstash()`, `PetscHeapView()`, `PetscHeapDestroy()`
1195: S*/
1196: typedef struct _n_PetscHeap *PetscHeap;
1198: /*S
1199: 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
1201: Level: developer
1203: .seealso: `PetscShmCommGet()`, `PetscShmCommGlobalToLocal()`, `PetscShmCommLocalToGlobal()`, `PetscShmCommGetMpiShmComm()`
1204: S*/
1205: typedef struct _n_PetscShmComm *PetscShmComm;
1207: /*S
1208: 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
1210: Level: developer
1212: .seealso: `PetscOmpCtrlCreate()`, `PetscOmpCtrlDestroy()`, `PetscOmpCtrlGetOmpComms()`, `PetscOmpCtrlOmpRegionOnMasterBegin()`, `PetscOmpCtrlOmpRegionOnMasterEnd()`, `PetscOmpCtrlBarrier()`
1213: S*/
1214: typedef struct _n_PetscOmpCtrl *PetscOmpCtrl;
1216: /*S
1217: PetscSegBuffer - a segmented extendable buffer
1219: Level: developer
1221: .seealso: `PetscSegBufferCreate()`, `PetscSegBufferGet()`, `PetscSegBufferExtract()`, `PetscSegBufferDestroy()`
1222: S*/
1223: typedef struct _n_PetscSegBuffer *PetscSegBuffer;
1225: /*S
1226: 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
1228: Level: developer
1230: .seealso: `PetscOptions`, `PetscOptionsHelpPrintedCreate()`, `PetscOptionsHelpPrintedDestroy()`, `PetscOptionsHelpPrintedCheck()`
1231: S*/
1232: typedef struct _n_PetscOptionsHelpPrinted *PetscOptionsHelpPrinted;
1234: /*S
1235: PetscByte - datatype used to represent bytes
1237: Level: intermediate
1239: .seealso: `PetscBT`
1240: S*/
1241: typedef unsigned char PetscByte;
1243: /*S
1244: PetscBT - PETSc bitarrays, efficient storage of arrays of boolean values
1246: Level: advanced
1248: .seealso: `PetscByte`, `PetscBTCreate()`, `PetscBTDestroy()`, `PetscBTMemzero()`, `PetscBTSet()`, `PetscBTClear()`, `PetscBTLookup()`,
1249: `PetscBTLookupSet()`, `PetscBTLookupClear()`, `PetscBTLength()`, `PetscBTView()`
1250: S*/
1251: typedef PetscByte *PetscBT;
1253: /* The number of bits in a byte */
1254: #define PETSC_BITS_PER_BYTE CHAR_BIT