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