Actual source code: petscsystypes.h
1: #ifndef PETSCSYSTYPES_H
2: #define PETSCSYSTYPES_H
4: #include <petscconf.h>
5: #include <petscconf_poison.h>
6: #include <petscfix.h>
7: #include <stddef.h>
9: /* SUBMANSEC = Sys */
11: /*MC
12: PetscErrorCode - datatype used for return error code from almost all PETSc functions
14: Level: beginner
16: .seealso: `PetscCall()`, `SETERRQ()`
17: M*/
18: typedef int PetscErrorCode;
20: /*MC
22: PetscClassId - A unique id used to identify each PETSc class.
24: Notes:
25: Use `PetscClassIdRegister()` to obtain a new value for a new class being created. Usually
26: XXXInitializePackage() calls it for each class it defines.
28: Developer Notes:
29: Internal integer stored in the `_p_PetscObject` data structure.
30: These are all computed by an offset from the lowest one, `PETSC_SMALLEST_CLASSID`.
32: Level: developer
34: .seealso: `PetscClassIdRegister()`, `PetscLogEventRegister()`, `PetscHeaderCreate()`
35: M*/
36: typedef int PetscClassId;
38: /*MC
39: PetscMPIInt - datatype used to represent 'int' parameters to MPI functions.
41: Level: intermediate
43: Notes:
44: This is always a 32 bit integer, sometimes it is the same as `PetscInt`, but if PETSc was built with --with-64-bit-indices but
45: standard C/Fortran integers are 32 bit then this is NOT the same as `PetscInt`; it remains 32 bit.
47: `PetscMPIIntCast`(a,&b) checks if the given `PetscInt` a will fit in a `PetscMPIInt`, if not it
48: generates a `PETSC_ERR_ARG_OUTOFRANGE` error.
50: .seealso: `PetscBLASInt`, `PetscInt`, `PetscMPIIntCast()`
52: M*/
53: typedef int PetscMPIInt;
55: /*MC
56: PetscSizeT - datatype used to represent sizes in memory (like size_t)
58: Level: intermediate
60: Notes:
61: This is equivalent to size_t, but defined for consistency with Fortran, which lacks a native equivalent of size_t.
63: .seealso: `PetscInt`, `PetscInt64`, `PetscCount`
65: M*/
66: typedef size_t PetscSizeT;
68: /*MC
69: PetscCount - signed datatype used to represent counts
71: Level: intermediate
73: Notes:
74: This is equivalent to ptrdiff_t, but defined for consistency with Fortran, which lacks a native equivalent of ptrdiff_t.
76: Use `PetscCount_FMT` to format with `PetscPrintf()`, `printf()`, and related functions.
78: .seealso: `PetscInt`, `PetscInt64`, `PetscSizeT`
80: M*/
81: typedef ptrdiff_t PetscCount;
82: #define PetscCount_FMT "td"
84: /*MC
85: PetscEnum - datatype used to pass enum types within PETSc functions.
87: Level: intermediate
89: .seealso: `PetscOptionsGetEnum()`, `PetscOptionsEnum()`, `PetscBagRegisterEnum()`
90: M*/
91: typedef enum {
92: ENUM_DUMMY
93: } PetscEnum;
95: typedef short PetscShort;
96: typedef char PetscChar;
97: typedef float PetscFloat;
99: /*MC
100: PetscInt - PETSc type that represents an integer, used primarily to
101: 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.
103: Notes:
104: 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.
106: Level: beginner
108: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`
109: M*/
111: #if defined(PETSC_HAVE_STDINT_H)
112: #include <stdint.h>
113: #endif
114: #if defined(PETSC_HAVE_INTTYPES_H)
117: #endif
118: #include <inttypes.h>
119: #if !defined(PRId64)
120: #define PRId64 "ld"
121: #endif
122: #endif
124: #if defined(PETSC_HAVE_STDINT_H) && defined(PETSC_HAVE_INTTYPES_H) && defined(PETSC_HAVE_MPI_INT64_T) /* MPI_INT64_T is not guaranteed to be a macro */
125: typedef int64_t PetscInt64;
126: #elif (PETSC_SIZEOF_LONG_LONG == 8)
127: typedef long long PetscInt64;
128: #elif defined(PETSC_HAVE___INT64)
129: typedef __int64 PetscInt64;
130: #else
131: #error "cannot determine PetscInt64 type"
132: #endif
134: #if defined(PETSC_USE_64BIT_INDICES)
135: typedef PetscInt64 PetscInt;
136: #else
137: typedef int PetscInt;
138: #endif
140: #if defined(PETSC_HAVE_STDINT_H) && defined(PETSC_HAVE_INTTYPES_H) && defined(PETSC_HAVE_MPI_INT64_T) /* MPI_INT64_T is not guaranteed to be a macro */
141: #define MPIU_INT64 MPI_INT64_T
142: #define PetscInt64_FMT PRId64
143: #elif (PETSC_SIZEOF_LONG_LONG == 8)
144: #define MPIU_INT64 MPI_LONG_LONG_INT
145: #define PetscInt64_FMT "lld"
146: #elif defined(PETSC_HAVE___INT64)
147: #define MPIU_INT64 MPI_INT64_T
148: #define PetscInt64_FMT "ld"
149: #else
150: #error "cannot determine PetscInt64 type"
151: #endif
153: /*MC
154: PetscBLASInt - datatype used to represent 'int' parameters to BLAS/LAPACK functions.
156: Notes:
157: Usually this is the same as `PetscIn`t, but if PETSc was built with --with-64-bit-indices but
158: standard C/Fortran integers are 32 bit then this may not be the same as `PetscInt`,
159: except on some BLAS/LAPACK implementations that support 64 bit integers see the notes below.
161: `PetscErrorCode` `PetscBLASIntCast`(a,&b) checks if the given `PetscInt` a will fit in a `PetscBLASInt`, if not it
162: generates a `PETSC_ERR_ARG_OUTOFRANGE` error
164: Installation Notes:
165: ./configure automatically determines the size of the integers used by BLAS/LAPACK except when --with-batch is used
166: in that situation one must know (by some other means) if the integers used by BLAS/LAPACK are 64 bit and if so pass the flag --known-64-bit-blas-indice
168: MATLAB ships with BLAS and LAPACK that use 64 bit integers, for example if you run ./configure with, the option
169: --with-blaslapack-lib=[/Applications/MATLAB_R2010b.app/bin/maci64/libmwblas.dylib,/Applications/MATLAB_R2010b.app/bin/maci64/libmwlapack.dylib]
171: 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
172: against the 64 bit version, otherwise it use the 32 bit version
174: 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
176: External packages such as hypre, ML, SuperLU etc do not provide any support for passing 64 bit integers to BLAS/LAPACK so cannot
177: 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
178: these external libraries while using 64 bit integer BLAS/LAPACK.
180: Level: intermediate
182: .seealso: `PetscMPIInt`, `PetscInt`, `PetscBLASIntCast()`
184: M*/
185: #if defined(PETSC_HAVE_64BIT_BLAS_INDICES)
186: #define PetscBLASInt_FMT PetscInt64_FMT
187: typedef PetscInt64 PetscBLASInt;
188: #else
189: #define PetscBLASInt_FMT "d"
190: typedef int PetscBLASInt;
191: #endif
193: /*MC
194: PetscCuBLASInt - datatype used to represent 'int' parameters to cuBLAS/cuSOLVER functions.
196: Notes:
197: As of this writing PetscCuBLASInt is always the system `int`.
199: `PetscErrorCode` `PetscCuBLASIntCast`(a,&b) checks if the given `PetscInt` a will fit in a `PetscCuBLASInt`, if not it
200: generates a `PETSC_ERR_ARG_OUTOFRANGE` error
202: Level: intermediate
204: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscCuBLASIntCast()`
206: M*/
207: typedef int PetscCuBLASInt;
209: /*E
210: PetscBool - Logical variable. Actually an enum in C and a logical in Fortran.
212: Level: beginner
214: Developer Note:
215: Why have `PetscBool`, why not use bool in C? The problem is that K and R C, C99 and C++ all have different mechanisms for
216: boolean values. It is not easy to have a simple macro that that will work properly in all circumstances with all three mechanisms.
218: .seealso: `PETSC_TRUE`, `PETSC_FALSE`, `PetscNot()`, `PetscBool3`
219: E*/
220: typedef enum {
221: PETSC_FALSE,
222: PETSC_TRUE
223: } PetscBool;
225: /*E
226: PetscBool3 - Ternary logical variable. Actually an enum in C and a 4 byte integer in Fortran.
228: Level: beginner
230: Note:
231: Should not be used with the if (flg) or if (!flg) syntax.
233: .seealso: `PETSC_TRUE`, `PETSC_FALSE`, `PetscNot()`, `PETSC_BOOL3_TRUE`, `PETSC_BOOL3_FALSE`, `PETSC_BOOL3_UKNOWN`
234: E*/
235: typedef enum {
236: PETSC_BOOL3_FALSE,
237: PETSC_BOOL3_TRUE,
238: PETSC_BOOL3_UNKNOWN = -1
239: } PetscBool3;
241: #define PetscBool3ToBool(a) ((a) == PETSC_BOOL3_TRUE ? PETSC_TRUE : PETSC_FALSE)
242: #define PetscBoolToBool3(a) ((a) == PETSC_TRUE ? PETSC_BOOL3_TRUE : PETSC_BOOL3_FALSE)
244: /*MC
245: PetscReal - PETSc type that represents a real number version of `PetscScalar`
247: Notes:
248: For MPI calls that require datatypes, use `MPIU_REAL` as the datatype for `PetscReal` and `MPIU_SUM`, `MPIU_MAX`, etc. for operations.
249: They will automatically work correctly regardless of the size of `PetscReal`.
251: See `PetscScalar` for details on how to ./configure the size of `PetscReal`.
253: Level: beginner
255: .seealso: `PetscScalar`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`
256: M*/
258: #if defined(PETSC_USE_REAL_SINGLE)
259: typedef float PetscReal;
260: #elif defined(PETSC_USE_REAL_DOUBLE)
261: typedef double PetscReal;
262: #elif defined(PETSC_USE_REAL___FLOAT128)
263: #if defined(__cplusplus)
264: extern "C" {
265: #endif
266: #include <quadmath.h>
267: #if defined(__cplusplus)
268: }
269: #endif
270: typedef __float128 PetscReal;
271: #elif defined(PETSC_USE_REAL___FP16)
272: typedef __fp16 PetscReal;
273: #endif /* PETSC_USE_REAL_* */
275: /*MC
276: PetscComplex - PETSc type that represents a complex number with precision matching that of `PetscReal`.
278: Synopsis:
279: #include <petscsys.h>
280: PetscComplex number = 1. + 2.*PETSC_i;
282: Notes:
283: For MPI calls that require datatypes, use `MPIU_COMPLEX` as the datatype for `PetscComplex` and `MPIU_SUM` etc for operations.
284: They will automatically work correctly regardless of the size of `PetscComplex`.
286: See PetscScalar for details on how to ./configure the size of `PetscReal`
288: Complex numbers are automatically available if PETSc was able to find a working complex implementation
290: Petsc has a 'fix' for complex numbers to support expressions such as std::complex<PetscReal> + `PetscInt`, which are not supported by the standard
291: C++ library, but are convenient for petsc users. If the C++ compiler is able to compile code in petsccxxcomplexfix.h (This is checked by
292: configure), we include petsccxxcomplexfix.h to provide this convenience.
294: 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`
295: at the beginning of the C++ file to skip the fix.
297: Level: beginner
299: .seealso: `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PETSC_i`
300: M*/
301: #if !defined(PETSC_SKIP_COMPLEX)
302: #if defined(PETSC_CLANGUAGE_CXX)
303: #if !defined(PETSC_USE_REAL___FP16) && !defined(PETSC_USE_REAL___FLOAT128)
304: #if defined(__cplusplus) && defined(PETSC_HAVE_CXX_COMPLEX) /* enable complex for library code */
305: #define PETSC_HAVE_COMPLEX 1
306: #elif !defined(__cplusplus) && defined(PETSC_HAVE_C99_COMPLEX) && defined(PETSC_HAVE_CXX_COMPLEX) /* User code only - conditional on libary code complex support */
307: #define PETSC_HAVE_COMPLEX 1
308: #endif
309: #elif defined(PETSC_USE_REAL___FLOAT128) && defined(PETSC_HAVE_C99_COMPLEX)
310: #define PETSC_HAVE_COMPLEX 1
311: #endif
312: #else /* !PETSC_CLANGUAGE_CXX */
313: #if !defined(PETSC_USE_REAL___FP16)
315: #define PETSC_HAVE_COMPLEX 1
316: #elif defined(__cplusplus) && defined(PETSC_HAVE_C99_COMPLEX) && defined(PETSC_HAVE_CXX_COMPLEX) /* User code only - conditional on libary code complex support */
317: #define PETSC_HAVE_COMPLEX 1
318: #endif
319: #endif
320: #endif /* PETSC_CLANGUAGE_CXX */
321: #endif /* !PETSC_SKIP_COMPLEX */
323: #if defined(PETSC_HAVE_COMPLEX)
324: #if defined(__cplusplus) /* C++ complex support */
325: /* Locate a C++ complex template library */
326: #if defined(PETSC_DESIRE_KOKKOS_COMPLEX) /* Defined in petscvec_kokkos.hpp for *.kokkos.cxx files */
327: #define petsccomplexlib Kokkos
328: #include <Kokkos_Complex.hpp>
329: #elif defined(__CUDACC__) || defined(__HIPCC__)
330: #define petsccomplexlib thrust
331: #include <thrust/complex.h>
332: #elif defined(PETSC_USE_REAL___FLOAT128)
333: #include <complex.h>
334: #else
335: #define petsccomplexlib std
336: #include <complex>
337: #endif
339: /* Define PetscComplex based on the precision */
340: #if defined(PETSC_USE_REAL_SINGLE)
341: typedef petsccomplexlib::complex<float> PetscComplex;
342: #elif defined(PETSC_USE_REAL_DOUBLE)
343: typedef petsccomplexlib::complex<double> PetscComplex;
344: #elif defined(PETSC_USE_REAL___FLOAT128)
345: typedef __complex128 PetscComplex;
346: #endif
348: /* Include a PETSc C++ complex 'fix'. Check PetscComplex manual page for details */
349: #if defined(PETSC_HAVE_CXX_COMPLEX_FIX) && !defined(PETSC_SKIP_CXX_COMPLEX_FIX)
350: #include <petsccxxcomplexfix.h>
351: #endif
352: #else /* c99 complex support */
353: #include <complex.h>
354: #if defined(PETSC_USE_REAL_SINGLE) || defined(PETSC_USE_REAL___FP16)
355: typedef float _Complex PetscComplex;
356: #elif defined(PETSC_USE_REAL_DOUBLE)
357: typedef double _Complex PetscComplex;
358: #elif defined(PETSC_USE_REAL___FLOAT128)
359: typedef __complex128 PetscComplex;
360: #endif /* PETSC_USE_REAL_* */
361: #endif /* !__cplusplus */
362: #endif /* PETSC_HAVE_COMPLEX */
364: /*MC
365: PetscScalar - PETSc type that represents either a double precision real number, a double precision
366: complex number, a single precision real number, a __float128 real or complex or a __fp16 real - if the code is configured
367: with --with-scalar-type=real,complex --with-precision=single,double,__float128,__fp16
369: Notes:
370: 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`.
372: Level: beginner
374: .seealso: `PetscReal`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PetscRealPart()`, `PetscImaginaryPart()`
375: M*/
377: #if defined(PETSC_USE_COMPLEX) && defined(PETSC_HAVE_COMPLEX)
378: typedef PetscComplex PetscScalar;
379: #else /* PETSC_USE_COMPLEX */
380: typedef PetscReal PetscScalar;
381: #endif /* PETSC_USE_COMPLEX */
383: /*E
384: PetscCopyMode - Determines how an array or `PetscObject` passed to certain functions is copied or retained by the aggregate `PetscObject`
386: Level: beginner
388: For the array input:
389: $ `PETSC_COPY_VALUES` - the array values are copied into new space, the user is free to reuse or delete the passed in array
390: $ `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
391: $ delete the array. The array MUST have been obtained with PetscMalloc(). Hence this mode cannot be used in Fortran.
392: $ `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
393: $ the array but the user must delete the array after the object is destroyed.
395: For the PetscObject input:
396: $ `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.
397: $ `PETSC_OWN_POINTER` - the input `PetscObject` is referenced by pointer (with reference count), thus should not be modified by the user. (Modification may cause errors or unintended side-effects in this or a future version of PETSc.)
398: For either case above, the input `PetscObject` should be destroyed by the user when no longer needed (the aggregate object increases its reference count).
399: $ `PETSC_USE_POINTER` - invalid for `PetscObject` inputs.
401: E*/
402: typedef enum {
403: PETSC_COPY_VALUES,
404: PETSC_OWN_POINTER,
405: PETSC_USE_POINTER
406: } PetscCopyMode;
408: /*MC
409: PETSC_FALSE - False value of `PetscBool`
411: Level: beginner
413: Note:
414: Zero integer
416: .seealso: `PetscBool`, `PetscBool3`, `PETSC_TRUE`
417: M*/
419: /*MC
420: PETSC_TRUE - True value of `PetscBool`
422: Level: beginner
424: Note:
425: Nonzero integer
427: .seealso: `PetscBool`, `PetscBool3`, `PETSC_FALSE`
428: M*/
430: /*MC
431: PetscLogDouble - Used for logging times
433: Notes:
434: Contains double precision numbers that are not used in the numerical computations, but rather in logging, timing etc.
436: Level: developer
438: M*/
439: typedef double PetscLogDouble;
441: /*E
442: PetscDataType - Used for handling different basic data types.
444: Level: beginner
446: Notes:
447: Use of this should be avoided if one can directly use `MPI_Datatype` instead.
449: `PETSC_INT` is the datatype for a `PetscInt`, regardless of whether it is 4 or 8 bytes.
450: `PETSC_REAL`, `PETSC_COMPLEX` and `PETSC_SCALAR` are the datatypes for `PetscReal`, `PetscComplex` and `PetscScalar`, regardless of their sizes.
452: Developer Notes:
453: It would be nice if we could always just use MPI Datatypes, why can we not?
455: If you change any values in `PetscDatatype` make sure you update their usage in
456: share/petsc/matlab/PetscBagRead.m and share/petsc/matlab/@PetscOpenSocket/read/write.m
458: TODO: Add PETSC_INT32 and remove use of improper PETSC_ENUM
460: .seealso: `PetscBinaryRead()`, `PetscBinaryWrite()`, `PetscDataTypeToMPIDataType()`,
461: `PetscDataTypeGetSize()`
463: E*/
464: typedef enum {
465: PETSC_DATATYPE_UNKNOWN = 0,
466: PETSC_DOUBLE = 1,
467: PETSC_COMPLEX = 2,
468: PETSC_LONG = 3,
469: PETSC_SHORT = 4,
470: PETSC_FLOAT = 5,
471: PETSC_CHAR = 6,
472: PETSC_BIT_LOGICAL = 7,
473: PETSC_ENUM = 8,
474: PETSC_BOOL = 9,
475: PETSC___FLOAT128 = 10,
476: PETSC_OBJECT = 11,
477: PETSC_FUNCTION = 12,
478: PETSC_STRING = 13,
479: PETSC___FP16 = 14,
480: PETSC_STRUCT = 15,
481: PETSC_INT = 16,
482: PETSC_INT64 = 17
483: } PetscDataType;
485: #if defined(PETSC_USE_REAL_SINGLE)
486: #define PETSC_REAL PETSC_FLOAT
487: #elif defined(PETSC_USE_REAL_DOUBLE)
488: #define PETSC_REAL PETSC_DOUBLE
489: #elif defined(PETSC_USE_REAL___FLOAT128)
490: #define PETSC_REAL PETSC___FLOAT128
491: #elif defined(PETSC_USE_REAL___FP16)
492: #define PETSC_REAL PETSC___FP16
493: #else
494: #define PETSC_REAL PETSC_DOUBLE
495: #endif
497: #if defined(PETSC_USE_COMPLEX)
498: #define PETSC_SCALAR PETSC_COMPLEX
499: #else
500: #define PETSC_SCALAR PETSC_REAL
501: #endif
503: #define PETSC_FORTRANADDR PETSC_LONG
505: /*S
506: PetscToken - 'Token' used for managing tokenizing strings
508: Level: intermediate
510: .seealso: `PetscTokenCreate()`, `PetscTokenFind()`, `PetscTokenDestroy()`
511: S*/
512: typedef struct _p_PetscToken *PetscToken;
514: /*S
515: PetscObject - any PETSc object, `PetscViewer`, `Mat`, `Vec`, `KSP` etc
517: Level: beginner
519: Notes:
520: This is the base class from which all PETSc objects are derived from.
522: In certain situations one can cast an object, for example a `Vec`, to a `PetscObject` with (`PetscObject`)vec
524: .seealso: `PetscObjectDestroy()`, `PetscObjectView()`, `PetscObjectGetName()`, `PetscObjectSetName()`, `PetscObjectReference()`, `PetscObjectDereference()`
525: S*/
526: typedef struct _p_PetscObject *PetscObject;
528: /*MC
529: PetscObjectId - unique integer Id for a `PetscObject`
531: Level: developer
533: Note:
534: 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
535: if the objects are the same. Never compare two object pointer values.
537: .seealso: `PetscObjectState`, `PetscObjectGetId()`
538: M*/
539: typedef PetscInt64 PetscObjectId;
541: /*MC
542: PetscObjectState - integer state for a `PetscObject`
544: Level: developer
546: Notes:
547: Object state is always-increasing and (for objects that track state) can be used to determine if an object has
548: changed since the last time you interacted with it. It is 64-bit so that it will not overflow for a very long time.
550: .seealso: `PetscObjectId`, `PetscObjectStateGet()`, `PetscObjectStateIncrease()`, `PetscObjectStateSet()`
551: M*/
552: typedef PetscInt64 PetscObjectState;
554: /*S
555: PetscFunctionList - Linked list of functions, possibly stored in dynamic libraries, accessed
556: by string name
558: Level: advanced
560: .seealso: `PetscFunctionListAdd()`, `PetscFunctionListDestroy()`
561: S*/
562: typedef struct _n_PetscFunctionList *PetscFunctionList;
564: /*E
565: PetscFileMode - Access mode for a file.
567: Level: beginner
569: $ `FILE_MODE_UNDEFINED` - initial invalid value
570: $ `FILE_MODE_READ` - open a file at its beginning for reading
571: $ `FILE_MODE_WRITE` - open a file at its beginning for writing (will create if the file does not exist)
572: $ `FILE_MODE_APPEND` - open a file at end for writing
573: $ `FILE_MODE_UPDATE` - open a file for updating, meaning for reading and writing
574: $ `FILE_MODE_APPEND_UPDATE` - open a file for updating, meaning for reading and writing, at the end
576: .seealso: `PetscViewerFileSetMode()`
577: E*/
578: typedef enum {
579: FILE_MODE_UNDEFINED = -1,
580: FILE_MODE_READ = 0,
581: FILE_MODE_WRITE,
582: FILE_MODE_APPEND,
583: FILE_MODE_UPDATE,
584: FILE_MODE_APPEND_UPDATE
585: } PetscFileMode;
587: typedef void *PetscDLHandle;
588: typedef enum {
589: PETSC_DL_DECIDE = 0,
590: PETSC_DL_NOW = 1,
591: PETSC_DL_LOCAL = 2
592: } PetscDLMode;
594: /*S
595: PetscObjectList - Linked list of PETSc objects, each accessible by string name
597: Level: developer
599: Note:
600: Used by `PetscObjectCompose()` and `PetscObjectQuery()`
602: .seealso: `PetscObjectListAdd()`, `PetscObjectListDestroy()`, `PetscObjectListFind()`, `PetscObjectCompose()`, `PetscObjectQuery()`, `PetscFunctionList`
603: S*/
604: typedef struct _n_PetscObjectList *PetscObjectList;
606: /*S
607: PetscDLLibrary - Linked list of dynamics libraries to search for functions
609: Level: advanced
611: .seealso: `PetscDLLibraryOpen()`
612: S*/
613: typedef struct _n_PetscDLLibrary *PetscDLLibrary;
615: /*S
616: PetscContainer - Simple PETSc object that contains a pointer to any required data
618: Level: advanced
620: Note:
621: This is useful to attach arbitrary data to a `PetscObject` with `PetscObjectCompose()` and `PetscObjectQuery()`
623: .seealso: `PetscObject`, `PetscContainerCreate()`, `PetscObjectCompose()`, `PetscObjectQuery()`
624: S*/
625: typedef struct _p_PetscContainer *PetscContainer;
627: /*S
628: PetscRandom - Abstract PETSc object that manages generating random numbers
630: Level: intermediate
632: .seealso: `PetscRandomCreate()`, `PetscRandomGetValue()`, `PetscRandomType`
633: S*/
634: typedef struct _p_PetscRandom *PetscRandom;
636: /*
637: In binary files variables are stored using the following lengths,
638: regardless of how they are stored in memory on any one particular
639: machine. Use these rather then sizeof() in computing sizes for
640: PetscBinarySeek().
641: */
642: #define PETSC_BINARY_INT_SIZE (32 / 8)
643: #define PETSC_BINARY_FLOAT_SIZE (32 / 8)
644: #define PETSC_BINARY_CHAR_SIZE (8 / 8)
645: #define PETSC_BINARY_SHORT_SIZE (16 / 8)
646: #define PETSC_BINARY_DOUBLE_SIZE (64 / 8)
647: #define PETSC_BINARY_SCALAR_SIZE sizeof(PetscScalar)
649: /*E
650: PetscBinarySeekType - argument to `PetscBinarySeek()`
652: Level: advanced
654: .seealso: `PetscBinarySeek()`, `PetscBinarySynchronizedSeek()`
655: E*/
656: typedef enum {
657: PETSC_BINARY_SEEK_SET = 0,
658: PETSC_BINARY_SEEK_CUR = 1,
659: PETSC_BINARY_SEEK_END = 2
660: } PetscBinarySeekType;
662: /*E
663: PetscBuildTwoSidedType - algorithm for setting up two-sided communication
665: $ `PETSC_BUILDTWOSIDED_ALLREDUCE` - classical algorithm using an MPI_Allreduce with
666: $ a buffer of length equal to the communicator size. Not memory-scalable due to
667: $ the large reduction size. Requires only MPI-1.
668: $ `PETSC_BUILDTWOSIDED_IBARRIER` - nonblocking algorithm based on MPI_Issend and MPI_Ibarrier.
669: $ Proved communication-optimal in Hoefler, Siebert, and Lumsdaine (2010). Requires MPI-3.
670: $ `PETSC_BUILDTWOSIDED_REDSCATTER` - similar to above, but use more optimized function
671: $ that only communicates the part of the reduction that is necessary. Requires MPI-2.
673: Level: developer
675: .seealso: `PetscCommBuildTwoSided()`, `PetscCommBuildTwoSidedSetType()`, `PetscCommBuildTwoSidedGetType()`
676: E*/
677: typedef enum {
678: PETSC_BUILDTWOSIDED_NOTSET = -1,
679: PETSC_BUILDTWOSIDED_ALLREDUCE = 0,
680: PETSC_BUILDTWOSIDED_IBARRIER = 1,
681: PETSC_BUILDTWOSIDED_REDSCATTER = 2
682: /* Updates here must be accompanied by updates in finclude/petscsys.h and the string array in mpits.c */
683: } PetscBuildTwoSidedType;
685: /* NOTE: If you change this, you must also change the values in src/vec/f90-mod/petscvec.h */
686: /*E
687: InsertMode - Whether entries are inserted or added into vectors or matrices
689: Level: beginner
691: .seealso: `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`,
692: `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`,
693: `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`
694: E*/
695: typedef enum {
696: NOT_SET_VALUES,
697: INSERT_VALUES,
698: ADD_VALUES,
699: MAX_VALUES,
700: MIN_VALUES,
701: INSERT_ALL_VALUES,
702: ADD_ALL_VALUES,
703: INSERT_BC_VALUES,
704: ADD_BC_VALUES
705: } InsertMode;
707: /*MC
708: INSERT_VALUES - Put a value into a vector or matrix, overwrites any previous value
710: Level: beginner
712: .seealso: `InsertMode`, `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`,
713: `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`, `ADD_VALUES`,
714: `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`, `MAX_VALUES`
716: M*/
718: /*MC
719: ADD_VALUES - Adds a value into a vector or matrix, if there previously was no value, just puts the
720: value into that location
722: Level: beginner
724: .seealso: `InsertMode`, `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`,
725: `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`, `INSERT_VALUES`,
726: `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`, `MAX_VALUES`
728: M*/
730: /*MC
731: MAX_VALUES - Puts the maximum of the scattered/gathered value and the current value into each location
733: Level: beginner
735: .seealso: `InsertMode`, `VecScatterBegin()`, `VecScatterEnd()`, `ADD_VALUES`, `INSERT_VALUES`
737: M*/
739: /*MC
740: MIN_VALUES - Puts the minimal of the scattered/gathered value and the current value into each location
742: Level: beginner
744: .seealso: `InsertMode`, `VecScatterBegin()`, `VecScatterEnd()`, `ADD_VALUES`, `INSERT_VALUES`
746: M*/
748: /*S
749: PetscSubcomm - A decomposition of an MPI communicator into subcommunicators
751: Notes:
752: After a call to `PetscSubcommSetType()`, `PetscSubcommSetTypeGeneral()`, or `PetscSubcommSetFromOptions()` one may call
753: $ `PetscSubcommChild()` returns the associated subcommunicator on this process
754: $ `PetscSubcommContiguousParent()` returns a parent communitor but with all child of the same subcommunicator having contiguous rank
756: Sample Usage:
757: .vb
758: `PetscSubcommCreate()`
759: `PetscSubcommSetNumber()`
760: `PetscSubcommSetType`(`PETSC_SUBCOMM_INTERLACED`);
761: ccomm = `PetscSubcommChild()`
762: `PetscSubcommDestroy()`
763: .ve
765: Level: advanced
767: Notes:
768: $ `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
769: $ `PETSC_SUBCOMM_CONTIGUOUS` - each new communicator contains a set of process with contiguous ranks in the original MPI communicator
770: $ `PETSC_SUBCOMM_INTERLACED` - each new communictor contains a set of processes equally far apart in rank from the others in that new communicator
772: Example: Consider a communicator with six processes split into 3 subcommunicators.
773: $ `PETSC_SUBCOMM_CONTIGUOUS` - the first communicator contains rank 0,1 the second rank 2,3 and the third rank 4,5 in the original ordering of the original communicator
774: $ `PETSC_SUBCOMM_INTERLACED` - the first communicator contains rank 0,3, the second 1,4 and the third 2,5
776: Developer Note:
777: This is used in objects such as `PCREDUNDANT` to manage the subcommunicators on which the redundant computations
778: are performed.
780: .seealso: `PetscSubcommCreate()`, `PetscSubcommSetNumber()`, `PetscSubcommSetType()`, `PetscSubcommView()`, `PetscSubcommSetFromOptions()`
782: S*/
783: typedef struct _n_PetscSubcomm *PetscSubcomm;
784: typedef enum {
785: PETSC_SUBCOMM_GENERAL = 0,
786: PETSC_SUBCOMM_CONTIGUOUS = 1,
787: PETSC_SUBCOMM_INTERLACED = 2
788: } PetscSubcommType;
790: /*S
791: PetscHeap - A simple class for managing heaps
793: Level: intermediate
795: .seealso: `PetscHeapCreate()`, `PetscHeapAdd()`, `PetscHeapPop()`, `PetscHeapPeek()`, `PetscHeapStash()`, `PetscHeapUnstash()`, `PetscHeapView()`, `PetscHeapDestroy()`
796: S*/
797: typedef struct _PetscHeap *PetscHeap;
799: typedef struct _n_PetscShmComm *PetscShmComm;
800: typedef struct _n_PetscOmpCtrl *PetscOmpCtrl;
802: /*S
803: PetscSegBuffer - a segmented extendable buffer
805: Level: developer
807: .seealso: `PetscSegBufferCreate()`, `PetscSegBufferGet()`, `PetscSegBufferExtract()`, `PetscSegBufferDestroy()`
808: S*/
809: typedef struct _n_PetscSegBuffer *PetscSegBuffer;
811: typedef struct _n_PetscOptionsHelpPrinted *PetscOptionsHelpPrinted;
812: #endif