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 <petscfix.h>
9: #include <petscmacros.h>
10: #include <stddef.h>
11: #include <stdbool.h>
13: /* SUBMANSEC = Sys */
15: #include <limits.h> // INT_MIN, INT_MAX, CHAR_BIT
17: /*
18: Defines the interface to MPI allowing the use of all MPI functions.
20: This is included in petscsystypes.h instead of petscsys.h because the use of
21: the MPI API is so pervasive in the source code. By including it here other
22: include files can avoid including petscsys.h and creating cyclic loops of include files.
24: PETSc does not use the C++ binding of MPI at ALL. The following flag
25: makes sure the C++ bindings are not included. The C++ bindings REQUIRE
26: putting mpi.h before ANY C++ include files, we cannot control this
27: with all PETSc users. Users who want to use the MPI C++ bindings can include
28: mpicxx.h directly in their code
29: */
30: #if !defined(MPICH_SKIP_MPICXX)
31: #define MPICH_SKIP_MPICXX 1
32: #endif
33: #if !defined(OMPI_SKIP_MPICXX)
34: #define OMPI_SKIP_MPICXX 1
35: #endif
36: #if PetscDefined(HAVE_MPIUNI)
37: #include <petsc/mpiuni/mpi.h>
38: #else
39: #include <mpi.h>
40: #endif
42: /*MC
43: PETSC_COMM_WORLD - the equivalent of the `MPI_COMM_WORLD` communicator which represents all the processes that PETSc knows about.
45: Level: beginner
47: Notes:
48: By default `PETSC_COMM_WORLD` and `MPI_COMM_WORLD` are identical unless you wish to
49: run PETSc on ONLY a subset of `MPI_COMM_WORLD`. In that case create your new (smaller)
50: communicator, call it, say comm, and set `PETSC_COMM_WORLD` = comm BEFORE calling
51: `PetscInitialize()`, but after `MPI_Init()` has been called.
53: The value of `PETSC_COMM_WORLD` should never be used or accessed before `PetscInitialize()`
54: is called because it may not have a valid value yet.
56: .seealso: `PETSC_COMM_SELF`
57: M*/
58: PETSC_EXTERN MPI_Comm PETSC_COMM_WORLD;
60: /*MC
61: PETSC_COMM_SELF - This is always `MPI_COMM_SELF`
63: Level: beginner
65: Note:
66: Do not USE/access or set this variable before `PetscInitialize()` has been called.
68: .seealso: `PETSC_COMM_WORLD`
69: M*/
70: #define PETSC_COMM_SELF MPI_COMM_SELF
72: #if defined(__clang__) || (PETSC_CPP_VERSION >= 17)
73: // clang allows both [[nodiscard]] and __attribute__((warn_unused_result)) on type
74: // definitions. GCC, however, does not, so check that we are using C++17 [[nodiscard]]
75: // instead of __attribute__((warn_unused_result))
76: #define PETSC_ERROR_CODE_NODISCARD PETSC_NODISCARD
77: #else
78: #define PETSC_ERROR_CODE_NODISCARD
79: #endif
81: #if PetscDefined(CLANG_STATIC_ANALYZER)
82: #undef PETSC_USE_STRICT_PETSCERRORCODE
83: #endif
85: #if PetscDefined(USE_STRICT_PETSCERRORCODE)
86: #define PETSC_ERROR_CODE_TYPEDEF typedef
87: #define PETSC_ERROR_CODE_ENUM_NAME PetscErrorCode
88: #else
89: #define PETSC_ERROR_CODE_TYPEDEF
90: #define PETSC_ERROR_CODE_ENUM_NAME
91: #endif
93: PETSC_ERROR_CODE_TYPEDEF enum PETSC_ERROR_CODE_NODISCARD {
94: PETSC_SUCCESS = 0,
95: PETSC_ERR_BOOLEAN_MACRO_FAILURE = 1, /* do not use */
97: PETSC_ERR_MIN_VALUE = 54, /* should always be one less than the smallest value */
99: PETSC_ERR_MEM = 55, /* unable to allocate requested memory */
100: PETSC_ERR_SUP = 56, /* no support for requested operation */
101: PETSC_ERR_SUP_SYS = 57, /* no support for requested operation on this computer system */
102: PETSC_ERR_ORDER = 58, /* operation done in wrong order */
103: PETSC_ERR_SIG = 59, /* signal received */
104: PETSC_ERR_FP = 72, /* floating point exception */
105: PETSC_ERR_COR = 74, /* corrupted PETSc object */
106: PETSC_ERR_LIB = 76, /* error in library called by PETSc */
107: PETSC_ERR_PLIB = 77, /* PETSc library generated inconsistent data */
108: PETSC_ERR_MEMC = 78, /* memory corruption */
109: PETSC_ERR_CONV_FAILED = 82, /* iterative method (KSP or SNES) failed */
110: PETSC_ERR_USER = 83, /* user has not provided needed function */
111: PETSC_ERR_SYS = 88, /* error in system call */
112: PETSC_ERR_POINTER = 70, /* pointer does not point to valid address */
113: PETSC_ERR_MPI_LIB_INCOMP = 87, /* MPI library at runtime is not compatible with MPI user compiled with */
115: PETSC_ERR_ARG_SIZ = 60, /* nonconforming object sizes used in operation */
116: PETSC_ERR_ARG_IDN = 61, /* two arguments not allowed to be the same */
117: PETSC_ERR_ARG_WRONG = 62, /* wrong argument (but object probably ok) */
118: PETSC_ERR_ARG_CORRUPT = 64, /* null or corrupted PETSc object as argument */
119: PETSC_ERR_ARG_OUTOFRANGE = 63, /* input argument, out of range */
120: PETSC_ERR_ARG_BADPTR = 68, /* invalid pointer argument */
121: PETSC_ERR_ARG_NOTSAMETYPE = 69, /* two args must be same object type */
122: PETSC_ERR_ARG_NOTSAMECOMM = 80, /* two args must be same communicators */
123: PETSC_ERR_ARG_WRONGSTATE = 73, /* object in argument is in wrong state, e.g. unassembled mat */
124: PETSC_ERR_ARG_TYPENOTSET = 89, /* the type of the object has not yet been set */
125: PETSC_ERR_ARG_INCOMP = 75, /* two arguments are incompatible */
126: PETSC_ERR_ARG_NULL = 85, /* argument is null that should not be */
127: PETSC_ERR_ARG_UNKNOWN_TYPE = 86, /* type name doesn't match any registered type */
129: PETSC_ERR_FILE_OPEN = 65, /* unable to open file */
130: PETSC_ERR_FILE_READ = 66, /* unable to read from file */
131: PETSC_ERR_FILE_WRITE = 67, /* unable to write to file */
132: PETSC_ERR_FILE_UNEXPECTED = 79, /* unexpected data in file */
134: PETSC_ERR_MAT_LU_ZRPVT = 71, /* detected a zero pivot during LU factorization */
135: PETSC_ERR_MAT_CH_ZRPVT = 81, /* detected a zero pivot during Cholesky factorization */
137: PETSC_ERR_INT_OVERFLOW = 84,
138: PETSC_ERR_FLOP_COUNT = 90,
139: PETSC_ERR_NOT_CONVERGED = 91, /* solver did not converge */
140: PETSC_ERR_MISSING_FACTOR = 92, /* MatGetFactor() failed */
141: PETSC_ERR_OPT_OVERWRITE = 93, /* attempted to over write options which should not be changed */
142: PETSC_ERR_WRONG_MPI_SIZE = 94, /* example/application run with number of MPI ranks it does not support */
143: PETSC_ERR_USER_INPUT = 95, /* missing or incorrect user input */
144: PETSC_ERR_GPU_RESOURCE = 96, /* unable to load a GPU resource, for example cuBLAS */
145: 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 */
146: PETSC_ERR_MPI = 98, /* general MPI error */
147: PETSC_ERR_RETURN = 99, /* PetscError() incorrectly returned an error code of 0 */
148: PETSC_ERR_MEM_LEAK = 100, /* memory alloc/free imbalance */
149: PETSC_ERR_PYTHON = 101, /* Exception in Python */
150: PETSC_ERR_MAX_VALUE = 102, /* this is always the one more than the largest error code */
152: /*
153: do not use, exist purely to make the enum bounds equal that of a regular int (so conversion
154: to int in main() is not undefined behavior)
155: */
156: PETSC_ERR_MIN_SIGNED_BOUND_DO_NOT_USE = INT_MIN,
157: PETSC_ERR_MAX_SIGNED_BOUND_DO_NOT_USE = INT_MAX
158: } PETSC_ERROR_CODE_ENUM_NAME;
160: #if !PetscDefined(USE_STRICT_PETSCERRORCODE)
161: /*E
162: PetscErrorCode - Datatype used to return PETSc error codes.
164: Level: beginner
166: Notes:
167: Virtually all PETSc functions return an error code. It is the callers responsibility to check
168: the value of the returned error code after each PETSc call to determine if any errors
169: occurred. A set of convenience macros (e.g., `PetscCall()` or `PetscCallVoid()`) are provided
170: for this purpose. Failing to properly check for errors is not supported, as errors may leave
171: PETSc in an undetermined state.
173: One can retrieve the error string corresponding to a particular error code using
174: `PetscErrorMessage()`.
176: The user can also configure PETSc with the `--with-strict-petscerrorcode` option to enable
177: compiler warnings when the returned error codes are not captured and checked. Users are
178: *heavily* encouraged to opt-in to this option, as it will become enabled by default in a
179: future release.
181: Developer Notes:
182: These are the generic error codes. These error codes are used in many different places in the
183: PETSc source code. The C-string versions are at defined in `PetscErrorStrings[]` in
184: `src/sys/error/err.c`, while the Fortran versions are defined in
185: `src/sys/ftn-mod/petscerror.h`. Any changes here must also be made in both locations.
187: .seealso: `PetscErrorMessage()`, `PetscCall()`, `SETERRQ()`
188: E*/
189: typedef int PetscErrorCode;
191: /*
192: Needed so that C++ lambdas can deduce the return type as PetscErrorCode from
193: PetscFunctionReturn(PETSC_SUCCESS). Otherwise we get
195: error: return type '(unnamed enum at include/petscsystypes.h:50:1)' must match previous
196: return type 'int' when lambda expression has unspecified explicit return type
197: PetscFunctionReturn(PETSC_SUCCESS);
198: ^
199: */
200: #define PETSC_SUCCESS ((PetscErrorCode)0)
201: #endif
203: #undef PETSC_ERROR_CODE_NODISCARD
204: #undef PETSC_ERROR_CODE_TYPEDEF
205: #undef PETSC_ERROR_CODE_ENUM_NAME
207: /*MC
208: PetscClassId - A unique id used to identify each PETSc class.
210: Level: developer
212: Note:
213: Use `PetscClassIdRegister()` to obtain a new value for a new class being created. Usually
214: XXXInitializePackage() calls it for each class it defines.
216: Developer Note:
217: Internal integer stored in the `_p_PetscObject` data structure. These are all computed by an offset from the lowest one, `PETSC_SMALLEST_CLASSID`.
219: .seealso: `PetscClassIdRegister()`, `PetscLogEventRegister()`, `PetscHeaderCreate()`
220: M*/
221: typedef int PetscClassId;
223: /*MC
224: PetscMPIInt - datatype used to represent `int` parameters to MPI functions.
226: Level: intermediate
228: Notes:
229: This is always a 32-bit integer even if PETSc was built with `--with-64-bit-indices`.
230: Hence, it is not guaranteed that it is the same as `PetscInt`.
232: `PetscMPIIntCast`(a,&b) checks if the given `PetscInt` a will fit in a `PetscMPIInt`, if not it
233: generates a `PETSC_ERR_ARG_OUTOFRANGE` error.
235: .seealso: [](stylePetscCount), `PetscBLASInt`, `PetscInt`, `PetscMPIIntCast()`
236: M*/
237: typedef int PetscMPIInt;
239: /* Limit MPI to 32-bits */
240: enum {
241: PETSC_MPI_INT_MIN = INT_MIN,
242: PETSC_MPI_INT_MAX = INT_MAX
243: };
245: /*MC
246: PetscSizeT - datatype used to represent sizes in memory (like `size_t`)
248: Level: intermediate
250: Notes:
251: This is equivalent to `size_t`, but defined for consistency with Fortran, which lacks a native equivalent of `size_t`.
253: .seealso: `PetscInt`, `PetscInt64`, `PetscCount`
254: M*/
255: typedef size_t PetscSizeT;
257: /*MC
258: PetscCount - signed datatype used to represent counts
260: Level: intermediate
262: Notes:
263: This is equivalent to `ptrdiff_t`, but defined for consistency with Fortran, which lacks a native equivalent of `ptrdiff_t`.
265: Use `PetscCount_FMT` to format with `PetscPrintf()`, `printf()`, and related functions.
267: .seealso: [](stylePetscCount), `PetscInt`, `PetscInt64`, `PetscSizeT`
268: M*/
269: typedef ptrdiff_t PetscCount;
270: #define PetscCount_FMT "td"
272: /*MC
273: MPIU_COUNT - Portable `MPI_Datatype` corresponding to `PetscCount` independent of the precision of `PetscCount`
275: Level: beginner
277: Note:
278: In MPI calls that require an `MPI_Datatype` that matches a `PetscCount` or array of `PetscCount` values, pass this value.
280: Developer Note:
281: It seems `MPI_AINT` is unsigned so this may be the wrong choice here since `PetscCount` is signed
283: .seealso: `MPI_Datatype`, `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt`, `MPIU_INT`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`,
284: `MPI_Count`
285: M*/
286: #define MPIU_COUNT MPI_AINT
288: /*MC
289: PetscEnum - datatype used to pass enum types within PETSc functions.
291: Level: intermediate
293: .seealso: `PetscOptionsGetEnum()`, `PetscOptionsEnum()`, `PetscBagRegisterEnum()`
294: M*/
295: typedef enum {
296: ENUM_DUMMY
297: } PetscEnum;
299: /*MC
300: PetscShort - PETSc datatype for the C `short` type
302: Level: beginner
304: Note:
305: Provided so that values of C type `short` can be referenced through a PETSc-style typedef. Most user code should prefer `PetscInt` for integers.
307: .seealso: `PetscInt`, `PetscFloat`, `PetscEnum`
308: M*/
309: typedef short PetscShort;
311: /*MC
312: PetscFloat - PETSc datatype for the C `float` type
314: Level: beginner
316: Note:
317: 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`.
319: .seealso: `PetscReal`, `PetscScalar`, `PetscShort`
320: M*/
321: typedef float PetscFloat;
323: #if PetscDefined(HAVE_STDINT_H)
324: #include <stdint.h>
325: #endif
326: #if PetscDefined(HAVE_INTTYPES_H)
329: #endif
330: #include <inttypes.h>
331: #if !defined(PRId64)
332: #define PRId64 "ld"
333: #endif
334: #endif
336: /*MC
337: 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`
339: Level: beginner
341: .seealso: `PetscBLASInt`, `PetscInt`, `PetscMPIInt`, `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt32`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PetscIntCast()`
342: M*/
343: #if PetscDefined(HAVE_STDINT_H) && PetscDefined(HAVE_INTTYPES_H) && (PetscDefined(HAVE_MPIUNI) || PetscDefined(HAVE_MPI_INT64_T)) /* MPI_INT64_T is not guaranteed to be a macro */
344: typedef int64_t PetscInt64;
346: #define PETSC_INT64_MIN INT64_MIN
347: #define PETSC_INT64_MAX INT64_MAX
349: #elif (PETSC_SIZEOF_LONG_LONG == 8)
350: typedef long long PetscInt64;
352: #define PETSC_INT64_MIN LLONG_MIN
353: #define PETSC_INT64_MAX LLONG_MAX
355: #elif PetscDefined(HAVE___INT64)
356: typedef __int64 PetscInt64;
358: #define PETSC_INT64_MIN INT64_MIN
359: #define PETSC_INT64_MAX INT64_MAX
361: #else
362: #error "cannot determine PetscInt64 type"
363: #endif
365: #if PETSC_SIZEOF_SIZE_T == 4
366: #define PETSC_COUNT_MIN INT_MIN
367: #define PETSC_COUNT_MAX INT_MAX
368: #else
369: #define PETSC_COUNT_MIN PETSC_INT64_MIN
370: #define PETSC_COUNT_MAX PETSC_INT64_MAX
371: #endif
373: /*MC
374: 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`
376: Level: beginner
378: .seealso: `PetscBLASInt`, `PetscInt`, `PetscMPIInt`, `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt64`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PetscIntCast()`
379: M*/
380: typedef int32_t PetscInt32;
381: #define PETSC_INT32_MIN INT32_MIN
382: #define PETSC_INT32_MAX INT32_MAX
384: /*MC
385: PetscInt - PETSc type that represents an integer, used primarily to
386: 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.
388: Level: beginner
390: Notes:
391: 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`.
393: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt32`, `PetscInt64`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PetscIntCast()`, `PETSC_INT_MIN`, `PETSC_INT_MAX`
394: M*/
395: #if PetscDefined(USE_64BIT_INDICES)
396: typedef PetscInt64 PetscInt;
398: #define PETSC_INT_MIN PETSC_INT64_MIN
399: #define PETSC_INT_MAX PETSC_INT64_MAX
400: #define PetscInt_FMT PetscInt64_FMT
401: #else
402: typedef int PetscInt;
404: enum {
405: PETSC_INT_MIN = INT_MIN,
406: PETSC_INT_MAX = INT_MAX
407: };
408: #define PetscInt_FMT "d"
409: #endif
411: /*MC
412: MPIU_INT - Portable `MPI_Datatype` corresponding to `PetscInt` independent of the precision of `PetscInt`
414: Level: beginner
416: Note:
417: In MPI calls that require an `MPI_Datatype` that matches a `PetscInt` or array of `PetscInt` values, pass this value.
419: .seealso: `MPI_Datatype`, `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt`, `MPIU_COUNT`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`
420: M*/
421: #if PetscDefined(USE_64BIT_INDICES)
422: #define MPIU_INT MPIU_INT64
423: #else
424: #define MPIU_INT MPI_INT
425: #endif
427: #define PETSC_UINT16_MAX 65535
429: /* deprecated */
430: #define PETSC_MIN_INT PETSC_INT_MIN
431: #define PETSC_MAX_INT PETSC_INT_MAX
432: #define PETSC_MAX_UINT16 PETSC_UINT16_MAX
434: #if PetscDefined(HAVE_STDINT_H) && PetscDefined(HAVE_INTTYPES_H) && (PetscDefined(HAVE_MPIUNI) || PetscDefined(HAVE_MPI_INT64_T)) /* MPI_INT64_T is not guaranteed to be a macro */
435: #define MPIU_INT64 MPI_INT64_T
436: #define PetscInt64_FMT PRId64
437: #elif (PETSC_SIZEOF_LONG_LONG == 8)
438: #define MPIU_INT64 MPI_LONG_LONG_INT
439: #define PetscInt64_FMT "lld"
440: #elif PetscDefined(HAVE___INT64)
441: #define MPIU_INT64 MPI_INT64_T
442: #define PetscInt64_FMT "ld"
443: #else
444: #error "cannot determine PetscInt64 type"
445: #endif
447: #define MPIU_INT32 MPI_INT32_T
448: #define PetscInt32_FMT PRId32
450: /*MC
451: PetscBLASInt - datatype used to represent 'int' parameters to BLAS/LAPACK functions.
453: Level: intermediate
455: Notes:
456: Usually this is the same as `PetscInt`, but if PETSc was built with `--with-64-bit-indices` but
457: standard C/Fortran integers are 32-bit then this may not be the same as `PetscInt`,
458: except on some BLAS/LAPACK implementations that support 64-bit integers see the notes below.
460: `PetscErrorCode` `PetscBLASIntCast`(a,&b) checks if the given `PetscInt` a will fit in a `PetscBLASInt`, if not it
461: generates a `PETSC_ERR_ARG_OUTOFRANGE` error
463: Installation Notes\:
464: ./configure automatically determines the size of the integers used by BLAS/LAPACK except when `--with-batch` is used
465: 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`
467: MATLAB ships with BLAS and LAPACK that use 64-bit integers, for example if you run ./configure with, the option
468: `--with-blaslapack-lib`=[/Applications/MATLAB_R2010b.app/bin/maci64/libmwblas.dylib,/Applications/MATLAB_R2010b.app/bin/maci64/libmwlapack.dylib]
470: 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
471: against the 64-bit version, otherwise it uses the 32-bit version
473: 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
475: External packages such as hypre, ML, SuperLU etc do not provide any support for passing 64-bit integers to BLAS/LAPACK so cannot
476: 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
477: these external libraries while using 64-bit integer BLAS/LAPACK.
479: .seealso: `PetscMPIInt`, `PetscInt`, `PetscBLASIntCast()`
480: M*/
481: #if PetscDefined(HAVE_64BIT_BLAS_INDICES)
482: typedef PetscInt64 PetscBLASInt;
484: #define PETSC_BLAS_INT_MIN PETSC_INT64_MIN
485: #define PETSC_BLAS_INT_MAX PETSC_INT64_MAX
486: #define PetscBLASInt_FMT PetscInt64_FMT
487: #else
488: typedef int PetscBLASInt;
490: enum {
491: PETSC_BLAS_INT_MIN = INT_MIN,
492: PETSC_BLAS_INT_MAX = INT_MAX
493: };
495: #define PetscBLASInt_FMT "d"
496: #endif
498: /*MC
499: PetscCuBLASInt - datatype used to represent 'int' parameters to cuBLAS/cuSOLVER functions.
501: Level: intermediate
503: Notes:
504: As of this writing `PetscCuBLASInt` is always the system `int`.
506: `PetscErrorCode` `PetscCuBLASIntCast`(a,&b) checks if the given `PetscInt` a will fit in a `PetscCuBLASInt`, if not it
507: generates a `PETSC_ERR_ARG_OUTOFRANGE` error
509: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscCuBLASIntCast()`
510: M*/
511: typedef int PetscCuBLASInt;
513: enum {
514: PETSC_CUBLAS_INT_MIN = INT_MIN,
515: PETSC_CUBLAS_INT_MAX = INT_MAX
516: };
518: /*MC
519: PetscHipBLASInt - datatype used to represent 'int' parameters to hipBLAS/hipSOLVER functions.
521: Level: intermediate
523: Notes:
524: `PetscHipBLASInt` is always the system `int`.
526: `PetscErrorCode` `PetscHipBLASIntCast`(a,&b) checks if the given `PetscInt` a will fit in a `PetscHipBLASInt`, if not it
527: generates a `PETSC_ERR_ARG_OUTOFRANGE` error
529: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscHipBLASIntCast()`
530: M*/
531: typedef int PetscHipBLASInt;
533: enum {
534: PETSC_HIPBLAS_INT_MIN = INT_MIN,
535: PETSC_HIPBLAS_INT_MAX = INT_MAX
536: };
538: /*MC
539: PetscExodusIIInt - datatype used to represent 'int' parameters to ExodusII functions.
541: Level: intermediate
543: Notes:
544: This is the same as `int`
546: .seealso: `PetscMPIInt`, `PetscInt`, `PetscExodusIIFloat`, `PetscBLASIntCast()`
547: M*/
548: typedef int PetscExodusIIInt;
549: #define PetscExodusIIInt_FMT "d"
551: /*MC
552: PetscExodusIIFloat - datatype used to represent 'float' parameters to ExodusII functions.
554: Level: intermediate
556: Notes:
557: This is the same as `float`
559: .seealso: `PetscMPIInt`, `PetscInt`, `PetscExodusIIInt`, `PetscBLASIntCast()`
560: M*/
561: typedef float PetscExodusIIFloat;
563: /*E
564: PetscBool - Logical variable.
566: Level: beginner
568: Notes:
569: This is a C bool.
571: Use `MPI_C_BOOL` for communicating with MPI calls in C, C++, and Fortran.
573: Fortran Note:
574: This is a `logical(C_BOOL)` with an internal representation that is equivalent to that of a `bool` in C and C++.
575: 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).
577: Developer Note:
578: We should deprecate this definition since there is a native representation in all the languages.
580: .seealso: `PETSC_TRUE`, `PETSC_FALSE`, `PetscNot()`, `PetscBool3`, `PetscBool3ToBool()`, `PetscBoolToBool3()`
581: E*/
582: typedef bool PetscBool;
583: #define PETSC_FALSE false
584: #define PETSC_TRUE true
585: #define MPIU_BOOL MPI_C_BOOL PETSC_DEPRECATED_MACRO(3, 24, 0, "MPI_C_BOOL", )
586: PETSC_EXTERN const char *const PetscBools[];
588: /*E
589: PetscBool3 - Ternary logical variable. Actually an enum in C and a 4 byte integer in Fortran.
591: Level: beginner
593: Note:
594: Should not be used with the `if (flg)` or `if (!flg)` syntax.
596: .seealso: `PETSC_TRUE`, `PETSC_FALSE`, `PetscNot()`, `PETSC_BOOL3_TRUE`, `PETSC_BOOL3_FALSE`, `PETSC_BOOL3_UNKNOWN`, `PetscBool3ToBool()`, `PetscBoolToBool3()`
597: E*/
598: typedef enum {
599: PETSC_BOOL3_FALSE = 0,
600: PETSC_BOOL3_TRUE = 1,
601: PETSC_BOOL3_UNKNOWN = -1 /* the value is unknown at the time of query, but might be determined later */
602: } PetscBool3;
603: PETSC_EXTERN const char *const PetscBool3s[];
605: /*MC
606: PetscBool3ToBool - Convert a `PetscBool3` to a `PetscBool`
608: Synopsis:
609: #include <petscsystypes.h>
610: PetscBool PetscBool3ToBool(PetscBool3 var)
612: No Fortran Support
614: Level: beginner
616: Note:
617: Evaluates to `PETSC_TRUE` if `var` is `PETSC_BOOL3_TRUE`, and `PETSC_FALSE` otherwise (including when `var` is `PETSC_BOOL3_UNKNOWN`).
619: .seealso: `PetscBool`, `PetscBool3`, `PetscBoolToBool3()`
620: M*/
621: #define PetscBool3ToBool(a) ((a) == PETSC_BOOL3_TRUE ? PETSC_TRUE : PETSC_FALSE)
623: /*MC
624: PetscBoolToBool3 - Convert a `PetscBool` to a `PetscBool3`
626: Synopsis:
627: #include <petscsystypes.h>
628: PetscBool3 PetscBoolToBool3(PetscBool var)
630: No Fortran Support
632: Level: beginner
634: Note:
635: Evaluates to `PETSC_BOOL3_TRUE` if `var` is `PETSC_TRUE`, and `PETSC_BOOL3_FALSE` otherwise.
637: .seealso: `PetscBool`, `PetscBool3`, `PetscBool3ToBool()`
638: M*/
639: #define PetscBoolToBool3(a) ((a) == PETSC_TRUE ? PETSC_BOOL3_TRUE : PETSC_BOOL3_FALSE)
641: /*MC
642: PetscReal - PETSc type that represents a real number version of `PetscScalar`
644: Level: beginner
646: Notes:
647: For MPI calls that require datatypes, use `MPIU_REAL` as the datatype for `PetscReal` and `MPIU_SUM`, `MPIU_MAX`, etc. for operations.
648: They will automatically work correctly regardless of the size of `PetscReal`.
650: See `PetscScalar` for details on how to ./configure the size of `PetscReal`.
652: .seealso: `PetscScalar`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`
653: M*/
654: #if PetscDefined(USE_REAL_SINGLE)
655: typedef float PetscReal;
656: #elif PetscDefined(USE_REAL_DOUBLE)
657: typedef double PetscReal;
658: #elif PetscDefined(USE_REAL___FLOAT128)
659: #if defined(__cplusplus)
660: extern "C" {
661: #endif
662: #include <quadmath.h>
663: #if defined(__cplusplus)
664: }
665: #endif
666: typedef __float128 PetscReal;
667: #elif PetscDefined(USE_REAL___FP16)
668: typedef __fp16 PetscReal;
669: #endif /* PETSC_USE_REAL_* */
671: #if !PetscDefined(SKIP_COMPLEX)
672: #if PetscDefined(CLANGUAGE_CXX)
673: #if !PetscDefined(USE_REAL___FP16) && !PetscDefined(USE_REAL___FLOAT128)
674: #if defined(__cplusplus) && PetscDefined(HAVE_CXX_COMPLEX) /* enable complex for library code */
675: #define PETSC_HAVE_COMPLEX 1
676: #elif !defined(__cplusplus) && PetscDefined(HAVE_C99_COMPLEX) && PetscDefined(HAVE_CXX_COMPLEX) /* User code only - conditional on library code complex support */
677: #define PETSC_HAVE_COMPLEX 1
678: #endif
679: #elif PetscDefined(USE_REAL___FLOAT128) && PetscDefined(HAVE_C99_COMPLEX)
680: #define PETSC_HAVE_COMPLEX 1
681: #endif
682: #else /* !PETSC_CLANGUAGE_CXX */
683: #if !PetscDefined(USE_REAL___FP16)
685: #define PETSC_HAVE_COMPLEX 1
686: #elif defined(__cplusplus) && PetscDefined(HAVE_C99_COMPLEX) && PetscDefined(HAVE_CXX_COMPLEX) /* User code only - conditional on library code complex support */
687: #define PETSC_HAVE_COMPLEX 1
688: #endif
689: #endif
690: #endif /* PETSC_CLANGUAGE_CXX */
691: #endif /* !PETSC_SKIP_COMPLEX */
693: #if PetscDefined(HAVE_COMPLEX)
694: #if defined(__cplusplus) /* C++ complex support */
695: /* Locate a C++ complex template library */
696: #if PetscDefined(DESIRE_KOKKOS_COMPLEX) /* Defined in petscvec_kokkos.hpp for *.kokkos.cxx files */
697: #define petsccomplexlib Kokkos
698: #include <Kokkos_Complex.hpp>
699: #elif (defined(__CUDACC__) && (PetscDefined(HAVE_CUDA) || PetscDefined(HAVE_HIPCUDA))) || (defined(__HIPCC__) && PetscDefined(HAVE_HIP))
700: #define petsccomplexlib thrust
701: #include <thrust/complex.h>
702: #elif PetscDefined(USE_REAL___FLOAT128)
703: #include <complex.h>
704: #else
705: #define petsccomplexlib std
706: #include <complex>
707: #endif
709: /* Define PetscComplex based on the precision */
710: #if PetscDefined(USE_REAL_SINGLE)
711: typedef petsccomplexlib::complex<float> PetscComplex;
712: #elif PetscDefined(USE_REAL_DOUBLE)
713: typedef petsccomplexlib::complex<double> PetscComplex;
714: #elif PetscDefined(USE_REAL___FLOAT128)
715: typedef __complex128 PetscComplex;
716: #endif
718: /* Include a PETSc C++ complex 'fix'. Check PetscComplex manual page for details */
719: #if PetscDefined(HAVE_CXX_COMPLEX_FIX) && !PetscDefined(SKIP_CXX_COMPLEX_FIX)
720: #include <petsccxxcomplexfix.h>
721: #endif
722: #else /* c99 complex support */
723: #include <complex.h>
724: #if PetscDefined(USE_REAL_SINGLE) || PetscDefined(USE_REAL___FP16)
726: typedef float _Complex PetscComplex;
727: #elif PetscDefined(USE_REAL_DOUBLE)
728: typedef double _Complex PetscComplex;
729: #elif PetscDefined(USE_REAL___FLOAT128)
731: /*MC
732: PetscComplex - PETSc type that represents a complex number with precision matching that of `PetscReal`.
734: Synopsis:
735: #include <petscsys.h>
736: PetscComplex number = 1. + 2.*PETSC_i;
738: Level: beginner
740: Notes:
741: For MPI calls that require datatypes, use `MPIU_COMPLEX` as the datatype for `PetscComplex` and `MPIU_SUM` etc for operations.
742: They will automatically work correctly regardless of the size of `PetscComplex`.
744: See `PetscScalar` for details on how to `./configure` the size of `PetscReal`
746: Complex numbers are automatically available if PETSc was able to find a working complex implementation
748: PETSc has a 'fix' for complex numbers to support expressions such as `std::complex<PetscReal>` + `PetscInt`, which are not supported by the standard
749: C++ library, but are convenient for PETSc users. If the C++ compiler is able to compile code in `petsccxxcomplexfix.h` (This is checked by
750: configure), we include `petsccxxcomplexfix.h` to provide this convenience.
752: 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`
753: at the beginning of the C++ file to skip the fix.
755: .seealso: `PetscReal`, `PetscScalar`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PETSC_i`
756: M*/
757: typedef __complex128 PetscComplex;
758: #endif /* PETSC_USE_REAL_* */
759: #endif /* !__cplusplus */
760: #endif /* PETSC_HAVE_COMPLEX */
762: /*MC
763: PetscScalar - PETSc type that represents either a double precision real number, a double precision
764: complex number, a single precision real number, a __float128 real or complex or a __fp16 real - if the code is configured
765: with `--with-scalar-type`=real,complex `--with-precision`=single,double,__float128,__fp16
767: Level: beginner
769: Note:
770: 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`.
772: .seealso: `PetscReal`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PetscRealPart()`, `PetscImaginaryPart()`
773: M*/
774: #if PetscDefined(USE_COMPLEX) && PetscDefined(HAVE_COMPLEX)
775: typedef PetscComplex PetscScalar;
776: #else /* PETSC_USE_COMPLEX */
777: typedef PetscReal PetscScalar;
778: #endif /* PETSC_USE_COMPLEX */
780: /*E
781: PetscCopyMode - Determines how an array or `PetscObject` passed to certain functions is copied or retained by the aggregate `PetscObject`
783: Values for array input:
784: + `PETSC_COPY_VALUES` - the array values are copied into new space, the user is free to reuse or delete the passed in array
785: . `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
786: delete the array. The array MUST have been obtained with `PetscMalloc()`. Hence this mode cannot be used in Fortran.
787: - `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
788: the array but the user must delete the array after the object is destroyed.
790: Values for PetscObject:
791: + `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.
792: . `PETSC_OWN_POINTER` - the input `PetscObject` is referenced by pointer (with reference count), thus should not be modified by the user.
793: increases its reference count).
794: - `PETSC_USE_POINTER` - invalid for `PetscObject` inputs.
796: Level: beginner
798: .seealso: `InsertMode`
799: E*/
800: typedef enum {
801: PETSC_COPY_VALUES,
802: PETSC_OWN_POINTER,
803: PETSC_USE_POINTER
804: } PetscCopyMode;
805: PETSC_EXTERN const char *const PetscCopyModes[];
807: /*MC
808: PETSC_FALSE - False value of `PetscBool`
810: Level: beginner
812: Note:
813: Zero integer
815: .seealso: `PetscBool`, `PetscBool3`, `PETSC_TRUE`
816: M*/
818: /*MC
819: PETSC_TRUE - True value of `PetscBool`
821: Level: beginner
823: Note:
824: Nonzero integer
826: .seealso: `PetscBool`, `PetscBool3`, `PETSC_FALSE`
827: M*/
829: /*MC
830: PETSC_INT_MIN - Minimum integer value representable by a `PetscInt`
832: Level: beginner
834: .seealso: `PETSC_INT_MAX`, `PetscInt`, `PetscIntCast()`
835: M*/
837: /*MC
838: PETSC_INT_MAX - Maximum integer value representable by a `PetscInt`
840: Level: beginner
842: .seealso: `PETSC_INT_MIN`, `PetscInt`, `PetscIntCast()`
843: M*/
845: /*MC
846: PETSC_MAX_PATH_LEN - Maximum length of a path (file name including directory)
848: Level: beginner
850: Note:
851: This value is set at configuration time based on the system's maximum path length (e.g., `MAXPATHLEN`, `MAX_PATH`, or `_MAX_PATH`).
852: It defaults to 4096 if no system value is available.
854: .seealso: `PetscGetFullPath()`, `PetscGetRealPath()`, `PetscGetHomeDirectory()`
855: M*/
857: /*MC
858: PetscLogDouble - Used for logging times
860: Level: developer
862: Note:
863: Contains double precision numbers that are not used in the numerical computations, but rather in logging, timing etc.
865: .seealso: `PetscBool`, `PetscDataType`
866: M*/
867: typedef double PetscLogDouble;
868: #define MPIU_PETSCLOGDOUBLE MPI_DOUBLE
869: #define MPIU_2PETSCLOGDOUBLE MPI_2DOUBLE_PRECISION
871: /*E
872: PetscDataType - Used for handling different basic data types.
874: Level: beginner
876: Notes:
877: Use of this should be avoided if one can directly use `MPI_Datatype` instead.
879: `PETSC_INT` is the datatype for a `PetscInt`, regardless of whether it is 4 or 8 bytes.
880: `PETSC_REAL`, `PETSC_COMPLEX` and `PETSC_SCALAR` are the datatypes for `PetscReal`, `PetscComplex` and `PetscScalar`, regardless of their sizes.
882: Developer Notes:
883: It would be nice if we could always just use MPI Datatypes, why can we not?
885: If you change any values in `PetscDatatype` make sure you update their usage in
886: share/petsc/matlab/PetscBagRead.m and share/petsc/matlab/@PetscOpenSocket/read/write.m
888: TODO:
889: Remove use of improper `PETSC_ENUM`
891: .seealso: `PetscBinaryRead()`, `PetscBinaryWrite()`, `PetscDataTypeToMPIDataType()`,
892: `PetscDataTypeGetSize()`
893: E*/
894: typedef enum {
895: PETSC_DATATYPE_UNKNOWN = 0,
896: PETSC_DOUBLE = 1,
897: PETSC_COMPLEX = 2,
898: PETSC_LONG = 3,
899: PETSC_SHORT = 4,
900: PETSC_FLOAT = 5,
901: PETSC_CHAR = 6,
902: PETSC_BIT_LOGICAL = 7,
903: PETSC_ENUM = 8,
904: PETSC_BOOL = 9,
905: PETSC___FLOAT128 = 10,
906: PETSC_OBJECT = 11,
907: PETSC_FUNCTION = 12,
908: PETSC_STRING = 13,
909: PETSC___FP16 = 14,
910: PETSC_STRUCT = 15,
911: PETSC_INT = 16,
912: PETSC_INT64 = 17,
913: PETSC_COUNT = 18,
914: PETSC_INT32 = 19,
915: } PetscDataType;
916: PETSC_EXTERN const char *const PetscDataTypes[];
918: #if PetscDefined(USE_REAL_SINGLE)
919: #define PETSC_REAL PETSC_FLOAT
920: #elif PetscDefined(USE_REAL_DOUBLE)
921: #define PETSC_REAL PETSC_DOUBLE
922: #elif PetscDefined(USE_REAL___FLOAT128)
923: #define PETSC_REAL PETSC___FLOAT128
924: #elif PetscDefined(USE_REAL___FP16)
925: #define PETSC_REAL PETSC___FP16
926: #else
927: #define PETSC_REAL PETSC_DOUBLE
928: #endif
930: #if PetscDefined(USE_COMPLEX)
931: #define PETSC_SCALAR PETSC_COMPLEX
932: #else
933: #define PETSC_SCALAR PETSC_REAL
934: #endif
936: #define PETSC_FORTRANADDR PETSC_LONG
938: /*S
939: PetscToken - 'Token' used for managing tokenizing strings
941: Level: intermediate
943: .seealso: `PetscTokenCreate()`, `PetscTokenFind()`, `PetscTokenDestroy()`
944: S*/
945: typedef struct _n_PetscToken *PetscToken;
947: /*S
948: PetscObject - any PETSc object, for example: `PetscViewer`, `Mat`, `Vec`, `KSP`, `DM`
950: Level: beginner
952: Notes:
953: This is the base class from which all PETSc objects are derived.
955: In certain situations one can cast an object, for example a `Vec`, to a `PetscObject` with (`PetscObject`)vec
957: .seealso: `PetscObjectDestroy()`, `PetscObjectView()`, `PetscObjectGetName()`, `PetscObjectSetName()`, `PetscObjectReference()`, `PetscObjectDereference()`
958: S*/
959: typedef struct _p_PetscObject *PetscObject;
961: /*MC
962: PetscObjectId - unique integer Id for a `PetscObject`
964: Level: developer
966: Note:
967: 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
968: if the objects are the same. Never compare two object pointer values.
970: .seealso: `PetscObjectState`, `PetscObjectGetId()`
971: M*/
972: typedef PetscInt64 PetscObjectId;
974: /*MC
975: PetscObjectState - integer state for a `PetscObject`
977: Level: developer
979: Note:
980: Object state is always-increasing and (for objects that track state) can be used to determine if an object has
981: changed since the last time you interacted with it. It is 64-bit so that it will not overflow for a very long time.
983: .seealso: `PetscObjectId`, `PetscObjectStateGet()`, `PetscObjectStateIncrease()`, `PetscObjectStateSet()`
984: M*/
985: typedef PetscInt64 PetscObjectState;
987: /*S
988: PetscFunctionList - Linked list of functions, possibly stored in dynamic libraries, accessed
989: by string name
991: Level: advanced
993: .seealso: `PetscFunctionListAdd()`, `PetscFunctionListDestroy()`
994: S*/
995: typedef struct _n_PetscFunctionList *PetscFunctionList;
997: /*E
998: PetscFileMode - Access mode for a file.
1000: Values:
1001: + `FILE_MODE_UNDEFINED` - initial invalid value
1002: . `FILE_MODE_READ` - open a file at its beginning for reading, string value `"read"`
1003: . `FILE_MODE_WRITE` - open a file at its beginning for writing (will create if the file does not exist), string value `"write"`
1004: . `FILE_MODE_APPEND` - open a file at end for writing, string value `"append"`
1005: . `FILE_MODE_UPDATE` - open a file for updating, meaning for reading and writing, string value `"update"`
1006: - `FILE_MODE_APPEND_UPDATE` - open a file for updating, meaning for reading and writing, at the end, string value `"append_update"`
1008: Level: beginner
1010: .seealso: `PetscViewerFileSetMode()`
1011: E*/
1012: typedef enum {
1013: FILE_MODE_UNDEFINED = -1,
1014: FILE_MODE_READ = 0,
1015: FILE_MODE_WRITE = 1,
1016: FILE_MODE_APPEND = 2,
1017: FILE_MODE_UPDATE = 3,
1018: FILE_MODE_APPEND_UPDATE = 4
1019: } PetscFileMode;
1020: PETSC_EXTERN const char *const PetscFileModes[];
1022: /*S
1023: PetscDLHandle - dynamic library handler object returned from `PetscDLOpen()`
1025: Level: developer
1027: .seealso: `PetscDLOpen()`, `PetscDLClose()`, `PetscDLSym()`
1028: S*/
1029: typedef void *PetscDLHandle;
1031: /*E
1032: PetscDLMode - Controls when the symbols of a dynamic library opened with `PetscDLOpen()` are resolved and whether they are visible to subsequently loaded libraries
1034: Values:
1035: + `PETSC_DL_DECIDE` - let PETSc choose a sensible default, lazy resolution and global visibility: `RTLD_LAZY` | `RTLD_GLOBAL`
1036: . `PETSC_DL_NOW` - resolve all symbols of the library immediately on load (corresponds to `RTLD_NOW`)
1037: - `PETSC_DL_LOCAL` - keep them private to this library (corresponds to `RTLD_LOCAL`)
1039: Level: developer
1041: .seealso: `PetscDLOpen()`, `PetscDLClose()`, `PetscDLSym()`, `PetscDLHandle`
1042: E*/
1043: typedef enum {
1044: PETSC_DL_DECIDE = 0,
1045: PETSC_DL_NOW = 1,
1046: PETSC_DL_LOCAL = 2
1047: } PetscDLMode;
1049: /*S
1050: PetscObjectList - Linked list of PETSc objects, each accessible by string name
1052: Level: developer
1054: Note:
1055: Used by `PetscObjectCompose()` and `PetscObjectQuery()`
1057: .seealso: `PetscObjectListAdd()`, `PetscObjectListDestroy()`, `PetscObjectListFind()`, `PetscObjectCompose()`, `PetscObjectQuery()`, `PetscFunctionList`
1058: S*/
1059: typedef struct _n_PetscObjectList *PetscObjectList;
1061: /*S
1062: PetscDLLibrary - Linked list of dynamic libraries to search for functions
1064: Level: developer
1066: .seealso: `PetscDLLibraryOpen()`
1067: S*/
1068: typedef struct _n_PetscDLLibrary *PetscDLLibrary;
1070: /*S
1071: PetscContainer - Simple PETSc object that contains a pointer to any required data
1073: Level: advanced
1075: Note:
1076: This is useful to attach arbitrary data to a `PetscObject` with `PetscObjectCompose()` and `PetscObjectQuery()`
1078: .seealso: `PetscObject`, `PetscContainerCreate()`, `PetscObjectCompose()`, `PetscObjectQuery()`
1079: S*/
1080: typedef struct _p_PetscContainer *PetscContainer;
1082: /*S
1083: PetscRandom - Abstract PETSc object that manages generating random numbers
1085: Level: intermediate
1087: .seealso: `PetscRandomCreate()`, `PetscRandomGetValue()`, `PetscRandomType`
1088: S*/
1089: typedef struct _p_PetscRandom *PetscRandom;
1091: /*J
1092: PetscRandomType - String with the name of a PETSc randomizer
1094: Level: beginner
1096: Note:
1097: To use `PETSCSPRNG` or `PETSCRANDOM123` you must have ./configure PETSc
1098: with the option `--download-sprng` or `--download-random123`. We recommend the default provided with PETSc.
1100: .seealso: `PetscRandomSetType()`, `PetscRandom`, `PetscRandomCreate()`
1101: J*/
1102: typedef const char *PetscRandomType;
1103: #define PETSCRAND "rand"
1104: #define PETSCRAND48 "rand48"
1105: #define PETSCSPRNG "sprng"
1106: #define PETSCRANDER48 "rander48"
1107: #define PETSCRANDOM123 "random123"
1108: #define PETSCCURAND "curand"
1110: /*
1111: In binary files variables are stored using the following lengths,
1112: regardless of how they are stored in memory on any one particular
1113: machine. Use these rather than sizeof() in computing sizes for
1114: PetscBinarySeek().
1115: */
1116: #define PETSC_BINARY_INT_SIZE (32 / 8)
1117: #define PETSC_BINARY_FLOAT_SIZE (32 / 8)
1118: #define PETSC_BINARY_CHAR_SIZE (8 / 8)
1119: #define PETSC_BINARY_SHORT_SIZE (16 / 8)
1120: #define PETSC_BINARY_DOUBLE_SIZE (64 / 8)
1121: #define PETSC_BINARY_SCALAR_SIZE sizeof(PetscScalar)
1123: /*E
1124: PetscBinarySeekType - argument to `PetscBinarySeek()`
1126: Values:
1127: + `PETSC_BINARY_SEEK_SET` - offset is an absolute location in the file
1128: . `PETSC_BINARY_SEEK_CUR` - offset is an offset from the current location of the file pointer
1129: - `PETSC_BINARY_SEEK_END` - offset is an offset from the end of the file
1131: Level: advanced
1133: .seealso: `PetscBinarySeek()`, `PetscBinarySynchronizedSeek()`
1134: E*/
1135: typedef enum {
1136: PETSC_BINARY_SEEK_SET = 0,
1137: PETSC_BINARY_SEEK_CUR = 1,
1138: PETSC_BINARY_SEEK_END = 2
1139: } PetscBinarySeekType;
1141: /*E
1142: PetscBuildTwoSidedType - algorithm for setting up two-sided communication for use with `PetscSF`
1144: Values:
1145: + `PETSC_BUILDTWOSIDED_ALLREDUCE` - classical algorithm using an `MPI_Allreduce()` with
1146: a buffer of length equal to the communicator size. Not memory-scalable due to
1147: the large reduction size. Requires only an MPI-1 implementation.
1148: . `PETSC_BUILDTWOSIDED_IBARRIER` - nonblocking algorithm based on `MPI_Issend()` and `MPI_Ibarrier()`.
1149: Proved communication-optimal in Hoefler, Siebert, and Lumsdaine (2010). Requires an MPI-3 implementation.
1150: - `PETSC_BUILDTWOSIDED_REDSCATTER` - similar to above, but use more optimized function
1151: that only communicates the part of the reduction that is necessary. Requires an MPI-2 implementation.
1153: Level: developer
1155: .seealso: `PetscCommBuildTwoSided()`, `PetscCommBuildTwoSidedSetType()`, `PetscCommBuildTwoSidedGetType()`
1156: E*/
1157: typedef enum {
1158: PETSC_BUILDTWOSIDED_NOTSET = -1,
1159: PETSC_BUILDTWOSIDED_ALLREDUCE = 0,
1160: PETSC_BUILDTWOSIDED_IBARRIER = 1,
1161: PETSC_BUILDTWOSIDED_REDSCATTER = 2
1162: /* Updates here must be accompanied by updates in finclude/petscsys.h and the string array in mpits.c */
1163: } PetscBuildTwoSidedType;
1164: PETSC_EXTERN const char *const PetscBuildTwoSidedTypes[];
1166: /*E
1167: InsertMode - How the entries are combined with the current values in the vectors or matrices
1169: Values:
1170: + `NOT_SET_VALUES` - do not actually use the values
1171: . `INSERT_VALUES` - replace the current values with the provided values, unless the index is marked as constrained by the `PetscSection`
1172: . `ADD_VALUES` - add the values to the current values, unless the index is marked as constrained by the `PetscSection`
1173: . `MAX_VALUES` - use the maximum of each current value and provided value
1174: . `MIN_VALUES` - use the minimum of each current value and provided value
1175: . `INSERT_ALL_VALUES` - insert, even if indices that are not marked as constrained by the `PetscSection`
1176: . `ADD_ALL_VALUES` - add, even if indices that are not marked as constrained by the `PetscSection`
1177: . `INSERT_BC_VALUES` - insert, but ignore indices that are not marked as constrained by the `PetscSection`
1178: - `ADD_BC_VALUES` - add, but ignore indices that are not marked as constrained by the `PetscSection`
1180: Level: beginner
1182: Note:
1183: The `PetscSection` that determines the effects of the `InsertMode` values can be obtained by the `Vec` object with `VecGetDM()`
1184: and `DMGetLocalSection()`.
1186: Not all options are supported for all operations or PETSc object types.
1188: .seealso: `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`,
1189: `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`,
1190: `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`
1191: E*/
1192: typedef enum {
1193: NOT_SET_VALUES,
1194: INSERT_VALUES,
1195: ADD_VALUES,
1196: MAX_VALUES,
1197: MIN_VALUES,
1198: INSERT_ALL_VALUES,
1199: ADD_ALL_VALUES,
1200: INSERT_BC_VALUES,
1201: ADD_BC_VALUES
1202: } InsertMode;
1204: /*MC
1205: INSERT_VALUES - Put a value into a vector or matrix, overwrites any previous value
1207: Level: beginner
1209: .seealso: `InsertMode`, `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`,
1210: `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`, `ADD_VALUES`,
1211: `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`, `MAX_VALUES`
1212: M*/
1214: /*MC
1215: ADD_VALUES - Adds a value into a vector or matrix, if there previously was no value, just puts the
1216: value into that location
1218: Level: beginner
1220: .seealso: `InsertMode`, `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`,
1221: `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`, `INSERT_VALUES`,
1222: `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`, `MAX_VALUES`
1223: M*/
1225: /*MC
1226: MAX_VALUES - Puts the maximum of the scattered/gathered value and the current value into each location
1228: Level: beginner
1230: .seealso: `InsertMode`, `VecScatterBegin()`, `VecScatterEnd()`, `ADD_VALUES`, `INSERT_VALUES`
1231: M*/
1233: /*MC
1234: MIN_VALUES - Puts the minimal of the scattered/gathered value and the current value into each location
1236: Level: beginner
1238: .seealso: `InsertMode`, `VecScatterBegin()`, `VecScatterEnd()`, `ADD_VALUES`, `INSERT_VALUES`
1239: M*/
1241: /*S
1242: PetscSubcomm - A decomposition of an MPI communicator into subcommunicators
1244: Sample Usage:
1245: .vb
1246: PetscSubcommCreate()
1247: PetscSubcommSetNumber()
1248: PetscSubcommSetType(PETSC_SUBCOMM_INTERLACED);
1249: ccomm = PetscSubcommChild()
1250: PetscSubcommDestroy()
1251: .ve
1253: Level: advanced
1255: Note:
1256: After a call to `PetscSubcommSetType()`, `PetscSubcommSetTypeGeneral()`, or `PetscSubcommSetFromOptions()` one may call
1257: .vb
1258: PetscSubcommChild() returns the associated subcommunicator on this process
1259: PetscSubcommContiguousParent() returns a parent communitor but with all child of the same subcommunicator having contiguous rank
1260: .ve
1262: Developer Note:
1263: This is used in objects such as `PCREDUNDANT` to manage the subcommunicators on which the redundant computations
1264: are performed.
1266: .seealso: `PetscSubcommCreate()`, `PetscSubcommSetNumber()`, `PetscSubcommSetType()`, `PetscSubcommView()`, `PetscSubcommSetFromOptions()`,
1267: `PetscSubcommType`
1268: S*/
1269: typedef struct _n_PetscSubcomm *PetscSubcomm;
1271: /*E
1272: PetscSubcommType - How a `PetscSubcomm` is constructed
1274: Values:
1275: + `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
1276: . `PETSC_SUBCOMM_CONTIGUOUS` - each new communicator contains a set of process with contiguous ranks in the original MPI communicator
1277: - `PETSC_SUBCOMM_INTERLACED` - each new communicator contains a set of processes equally far apart in rank from the others in that new communicator
1279: Level: advanced
1281: Example:
1282: Consider a communicator with six processes split into 3 subcommunicators.
1283: .vb
1284: 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
1285: PETSC_SUBCOMM_INTERLACED - the first communicator contains rank 0 and 3, the second rank 1 and 4, and the third process 2 and 5
1286: .ve
1288: .seealso: `PetscSubcommCreate()`, `PetscSubcommSetNumber()`, `PetscSubcommSetType()`, `PetscSubcommView()`, `PetscSubcommSetFromOptions()`
1289: E*/
1290: typedef enum {
1291: PETSC_SUBCOMM_GENERAL = 0,
1292: PETSC_SUBCOMM_CONTIGUOUS = 1,
1293: PETSC_SUBCOMM_INTERLACED = 2
1294: } PetscSubcommType;
1295: PETSC_EXTERN const char *const PetscSubcommTypes[];
1297: /*S
1298: PetscHeap - A simple class for managing heaps
1300: Level: intermediate
1302: .seealso: `PetscHeapCreate()`, `PetscHeapAdd()`, `PetscHeapPop()`, `PetscHeapPeek()`, `PetscHeapStash()`, `PetscHeapUnstash()`, `PetscHeapView()`, `PetscHeapDestroy()`
1303: S*/
1304: typedef struct _n_PetscHeap *PetscHeap;
1306: /*S
1307: 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
1309: Level: developer
1311: .seealso: `PetscShmCommGet()`, `PetscShmCommGlobalToLocal()`, `PetscShmCommLocalToGlobal()`, `PetscShmCommGetMpiShmComm()`
1312: S*/
1313: typedef struct _n_PetscShmComm *PetscShmComm;
1315: /*S
1316: 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
1318: Level: developer
1320: .seealso: `PetscOmpCtrlCreate()`, `PetscOmpCtrlDestroy()`, `PetscOmpCtrlGetOmpComms()`, `PetscOmpCtrlOmpRegionOnMasterBegin()`, `PetscOmpCtrlOmpRegionOnMasterEnd()`, `PetscOmpCtrlBarrier()`
1321: S*/
1322: typedef struct _n_PetscOmpCtrl *PetscOmpCtrl;
1324: /*S
1325: PetscSegBuffer - a segmented extendable buffer
1327: Level: developer
1329: .seealso: `PetscSegBufferCreate()`, `PetscSegBufferGet()`, `PetscSegBufferExtract()`, `PetscSegBufferDestroy()`
1330: S*/
1331: typedef struct _n_PetscSegBuffer *PetscSegBuffer;
1333: /*S
1334: 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
1336: Level: developer
1338: .seealso: `PetscOptions`, `PetscOptionsHelpPrintedCreate()`, `PetscOptionsHelpPrintedDestroy()`, `PetscOptionsHelpPrintedCheck()`
1339: S*/
1340: typedef struct _n_PetscOptionsHelpPrinted *PetscOptionsHelpPrinted;
1342: /*S
1343: PetscByte - datatype used to represent bytes
1345: Level: intermediate
1347: .seealso: `PetscBT`
1348: S*/
1349: typedef unsigned char PetscByte;
1351: /*S
1352: PetscBT - PETSc bitarrays, efficient storage of arrays of boolean values
1354: Level: advanced
1356: .seealso: `PetscByte`, `PetscBTCreate()`, `PetscBTDestroy()`, `PetscBTMemzero()`, `PetscBTSet()`, `PetscBTClear()`, `PetscBTLookup()`,
1357: `PetscBTLookupSet()`, `PetscBTLookupClear()`, `PetscBTLength()`, `PetscBTView()`
1358: S*/
1359: typedef PetscByte *PetscBT;
1361: /* The number of bits in a byte */
1362: #define PETSC_BITS_PER_BYTE CHAR_BIT
1364: /*MC
1365: PETSC_IGNORE - same as `NULL`, means PETSc will ignore this argument
1367: Level: beginner
1369: Note:
1370: Accepted by many PETSc functions to not set a parameter and instead use a default value
1372: Fortran Note:
1373: Use `PETSC_NULL_INTEGER`, `PETSC_NULL_SCALAR` etc
1375: .seealso: `PETSC_DECIDE`, `PETSC_DEFAULT`, `PETSC_DETERMINE`
1376: M*/
1377: #define PETSC_IGNORE PETSC_NULLPTR
1378: #define PETSC_NULL PETSC_DEPRECATED_MACRO(3, 19, 0, "PETSC_NULLPTR", ) PETSC_NULLPTR
1380: /*MC
1381: PETSC_UNLIMITED - standard way of passing an integer or floating point parameter to indicate PETSc there is no bound on the value allowed
1383: Level: beginner
1385: Example Usage:
1386: .vb
1387: KSPSetTolerances(ksp, PETSC_CURRENT, PETSC_CURRENT, PETSC_UNLIMITED, PETSC_UNLIMITED);
1388: .ve
1389: indicates that the solver is allowed to take any number of iterations and will not stop early no matter how the residual gets.
1391: Fortran Note:
1392: Use `PETSC_UNLIMITED_INTEGER` or `PETSC_UNLIMITED_REAL`.
1394: .seealso: `PETSC_DEFAULT`, `PETSC_IGNORE`, `PETSC_DETERMINE`, `PETSC_DECIDE`
1395: M*/
1397: /*MC
1398: PETSC_DECIDE - standard way of passing an integer or floating point parameter to indicate PETSc should determine an appropriate value
1400: Level: beginner
1402: Example Usage:
1403: .vb
1404: VecSetSizes(ksp, PETSC_DECIDE, 10);
1405: .ve
1406: indicates that the global size of the vector is 10 and the local size will be automatically determined so that the sum of the
1407: local sizes is the global size, see `PetscSplitOwnership()`.
1409: Fortran Note:
1410: Use `PETSC_DECIDE_INTEGER` or `PETSC_DECIDE_REAL`.
1412: .seealso: `PETSC_DEFAULT`, `PETSC_IGNORE`, `PETSC_DETERMINE`, `PETSC_UNLIMITED`
1413: M*/
1415: /*MC
1416: PETSC_DETERMINE - standard way of passing an integer or floating point parameter to indicate PETSc should determine an appropriate value
1418: Level: beginner
1420: Example Usage:
1421: .vb
1422: VecSetSizes(ksp, 10, PETSC_DETERMINE);
1423: .ve
1424: indicates that the local size of the vector is 10 and the global size will be automatically summing up all the local sizes.
1426: Note:
1427: Same as `PETSC_DECIDE`
1429: Fortran Note:
1430: Use `PETSC_DETERMINE_INTEGER` or `PETSC_DETERMINE_REAL`.
1432: Developer Note:
1433: I would like to use const `PetscInt` `PETSC_DETERMINE` = `PETSC_DECIDE`; but for
1434: some reason this is not allowed by the standard even though `PETSC_DECIDE` is a constant value.
1436: .seealso: `PETSC_DECIDE`, `PETSC_DEFAULT`, `PETSC_IGNORE`, `VecSetSizes()`, `PETSC_UNLIMITED`
1437: M*/
1439: /*MC
1440: PETSC_CURRENT - standard way of indicating to an object not to change the current value of the parameter in the object
1442: Level: beginner
1444: Note:
1445: Use `PETSC_DECIDE` to use the value that was set by PETSc when the object's type was set
1447: Fortran Note:
1448: Use `PETSC_CURRENT_INTEGER` or `PETSC_CURRENT_REAL`.
1450: .seealso: `PETSC_DECIDE`, `PETSC_IGNORE`, `PETSC_DETERMINE`, `PETSC_DEFAULT`, `PETSC_UNLIMITED`
1451: M*/
1453: /*MC
1454: PETSC_DEFAULT - deprecated, see `PETSC_CURRENT` and `PETSC_DETERMINE`
1456: Level: beginner
1458: Note:
1459: The name is confusing since it tells the object to continue to use the value it is using, not the default value when the object's type was set.
1461: Developer Note:
1462: Unfortunately this was used for two different purposes in the past, to actually trigger the use of a default value or to continue the
1463: use of currently set value (in, for example, `KSPSetTolerances()`.
1465: .seealso: `PETSC_DECIDE`, `PETSC_IGNORE`, `PETSC_DETERMINE`, `PETSC_CURRENT`, `PETSC_UNLIMITED`
1466: M*/
1468: /* These MUST be preprocessor defines! see https://gitlab.com/petsc/petsc/-/issues/1370 */
1469: #define PETSC_DECIDE (-1)
1470: #define PETSC_DETERMINE PETSC_DECIDE
1471: #define PETSC_CURRENT (-2)
1472: #define PETSC_UNLIMITED (-3)
1473: /* PETSC_DEFAULT is deprecated in favor of PETSC_CURRENT for use in KSPSetTolerances() and similar functions */
1474: #define PETSC_DEFAULT PETSC_CURRENT
1476: /*MC
1477: PeOP - indicates an argument to a PETSc function is optional and one can pass `NULL` instead. This is used by the Fortran API generator
1479: Level: developer
1481: Example:
1482: .vb
1483: PetscErrorCode XXXX(Vec v, PeOp PetscObject obj, PeOp PetscInt *idx, PeOp PetscInt *array[])
1484: .ve
1486: Notes:
1487: This is not part of the PETSc public API and should only be used in PETSc source code.
1489: Put this in the function declaration in front of each variable that is optional
1491: Developer Note:
1492: Shortened form of PETSc optional
1494: .seealso: `PeNS`, `PeNSS`, `PetscCtxRt`, `PetscInitialize()`
1495: M*/
1496: #define PeOp
1498: /*MC
1499: PeNS - indicates a function that does not use the PETSc standard arguments which make it easy to generate automatic language stubs for other languages
1501: Level: developer
1503: Notes:
1504: This is not part of the PETSc public API and should only be used in PETSc source code.
1506: Put this at the end of the function declaration closing parenthesis
1508: Developer Note:
1509: Shortened form of PETSc non-standard
1511: .seealso: `PeOp`, `PeNSS`, `PetscCtxRt`, `PetscInitialize()`
1512: M*/
1513: #define PeNS
1515: /*MC
1516: PeNSS - indicates a function that needs a special treatment in the C-side stub when generating the binding for other languages
1518: Level: developer
1520: Notes:
1521: This is not part of the PETSc public API and should only be used in PETSc source code.
1523: Put this at the end of the function declaration closing parenthesis
1525: It is similar to PeNS; in Fortran it will generate the Fortran interface definition automatically but not the C stub, which should be added manually under the appropriate `ftn-custom` directory
1527: Developer Note:
1528: Shortened form of PETSc non-standard stub
1530: .seealso: `PeOp`, `PeNS`, `PetscCtxRt`, `PetscInitialize()`
1531: M*/
1532: #define PeNSS
1534: /*MC
1535: PetscCtx - indicates an argument that can be a pointer to any C struct (or Fortran derived type).
1537: Level: developer
1539: Notes:
1540: This should not be used for arrays of unknown type.
1542: Fortran Notes:
1543: A Fortran code that calls a function with a `PetscCtx` argument would declare the variable `ctx` with
1544: .vb
1545: type(AppType) :: ctx
1546: .ve
1547: where `AppType` is a Fortran derived type. Or the argument can be a `PetscObject`.
1549: Developer Note:
1550: `PetscCtx` is used instead of `void *` in PETSc code to enhance the clarity of the PETSc source code since `void *` serves so many different roles.
1551: The getAPI() code processor also uses the variable type to generate correct bindings for other languages.
1553: .seealso: [](sec_fortran_context), `PetscCtxRt`, `PetscCtxDestroyFn()`, `PeOp`, `PeNS`, `PetscInitialize()`, `DMGetApplicationContext()`,
1554: `DMSetApplicationContextDestroy()`
1555: M*/
1556: typedef void *PetscCtx;
1558: /*MC
1559: PetscCtxRt - indicates an argument that returns a pointer to a C struct (or Fortran derived type) which is generally an application context
1561: Level: developer
1563: Notes:
1564: A PETSc object (in C or Fortran) can be used as a PETSc context
1566: This should not be used for functions that return pointers to arrays of unknown type. Thus it is used for, for example,
1567: `KSPGetApplicationContext()` but not used for `DMNetworkGetComponent()`
1569: A PETSc object (in C or Fortran) can be used as a PETSc context
1571: It is also used for functions that destroy an application context. For example, the destroy function passed to `DMSetApplicationContextDestroy()`
1572: which has a prototype of `PetscCtxDestroyFn()`
1574: This typedef is not part of the PETSc public API and should only be used in PETSc source code.
1576: For pointers to arrays of unknown type and for functions that return PETSc internal objects that are opaque to users, such
1577: as `KSPMonitorDynamicToleranceCreate()` a `void **` should be used.
1579: Fortran Notes:
1580: A Fortran code that calls a function with a `PetscCtxRt` argument must declare the variable `ctx` with
1581: .vb
1582: type(AppType), pointer :: ctx
1583: .ve
1584: where `AppType` is a Fortran derived type.
1586: If one passes a PETSc function with a `PetscCtxRt` argument as an argument in Fortran one must use the function named suffixed with `Cptr`,
1587: for example `KSPConvergedDefaultDestroyCptr`, see src/ksp/ksp/tutorials/ex1f.F90.
1589: Developer Notes:
1590: C++ compilers generate a warning or error if one passes a pointer to a pointer to a specific type (instead of `void`), for example,
1591: .vb
1592: extern calledfunction(void **);
1593: SomeCtx *ctx;
1594: calledfunction(&ctx); << warning that it is passing a pointer to a pointer to a SomeCtx instead of a void **
1595: .ve
1596: By using the common practice of prototyping the function as
1597: .vb
1598: extern calledfunction(void *);
1599: .ve
1600: the warning message is averted.
1602: `PetscCtxRt` is used instead of `void *` in PETSc code to enhance the clarity of the PETSc source code since `void *` serves so many different roles.
1603: The getAPI() code processor also uses the variable type to generate correct bindings for other languages.
1605: The Fortran C stub and Fortran interface definition generated for functions with a `PetscCtxRt` argument are the C function name suffixed with
1606: `Cptr`, for example `KSPConvergedDefaultDestroyCptr`. The Fortran user API is a macro with the original C function name, for example,
1607: `KSPConvergedDefaultDestroy` that calls the `KSPConvergedDefaultDestroyCptr` version and then calls `c_f_pointer()` to handle the equivalent of a `void**` cast
1608: to the users Fortran derived type argument.
1610: .seealso: [](sec_fortran_context), `PetscCtx`, `PetscCtxDestroyFn()`, `PeOp`, `PeNS`, `PetscInitialize()`, `DMGetApplicationContext()`,
1611: `DMSetApplicationContextDestroy()`
1612: M*/
1613: typedef void *PetscCtxRt;
1615: /*S
1616: PetscCtxDestroyFn - A prototype of a `PetscErrorCode (*)(PetscCtxRt)` function that is used to free application contexts
1618: Level: intermediate
1620: Notes:
1621: Used in the prototype of functions such as `DMSetApplicationContextDestroy()`
1623: The function argument is a `PetscCtxRt` which is psychologically equivalent to a `void **` meaning that this function is called with a pointer to
1624: the application context (which is itself a pointer) thus the destroy implementation must first reference the context via, for example,
1625: `*(AppCtx **)arg`. Note that syntactically `PetscCtxRt` is defined as a `void *`, this is because C++ does
1626: not accept passing a pointer to a pointer to a `void**` but it does accept passing a pointer to a pointer to `void *`.
1628: PETSc destroy functions take the address of the context (rather than just the context) so that that the destroy function can "zero the pointer" when
1629: appropriate, preventing accidental later use of a dangling pointer.
1631: .seealso: `PetscObject`, `PetscCtxDestroyDefault()`, `PetscObjectDestroy()`, `DMSetApplicationContextDestroy()`
1632: S*/
1633: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode PetscCtxDestroyFn(PetscCtxRt ctx);
1635: /*S
1636: PCMPIServerAddresses - Small bookkeeping record used by the `PCMPI` server to track shared-memory address mappings that have been distributed across the participating MPI ranks
1638: Level: developer
1640: Note:
1641: Allocated and managed by the `PCMPI` server when running with shared-memory transfers enabled (`PCMPIServerUseShmget`). Destroyed with `PCMPIServerAddressesDestroy()`. Not intended to be inspected or constructed by user code.
1643: .seealso: `PCMPI`, `PCMPIServerBegin()`, `PCMPIServerEnd()`, `PCMPIServerAddressesDestroy()`, `PCMPIServerUseShmget`
1644: S*/
1645: typedef struct {
1646: PetscInt n;
1647: void *addr[3];
1648: } PCMPIServerAddresses;