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: #ifndef PETSCSYSTYPES_H
  6: #define PETSCSYSTYPES_H

  8: #include <petscconf.h>
  9: #include <petscconf_poison.h>
 10: #include <petscfix.h>
 11: #include <stddef.h>

 13: /* SUBMANSEC = Sys */

 15: /*MC
 16:     PetscErrorCode - datatype used for return error code from almost all PETSc functions

 18:     Level: beginner

 20: .seealso: `PetscCall()`, `SETERRQ()`
 21: M*/
 22: typedef int PetscErrorCode;

 24: /*MC

 26:     PetscClassId - A unique id used to identify each PETSc class.

 28:     Notes:
 29:     Use `PetscClassIdRegister()` to obtain a new value for a new class being created. Usually
 30:          XXXInitializePackage() calls it for each class it defines.

 32:     Developer Notes:
 33:     Internal integer stored in the `_p_PetscObject` data structure.
 34:          These are all computed by an offset from the lowest one, `PETSC_SMALLEST_CLASSID`.

 36:     Level: developer

 38: .seealso: `PetscClassIdRegister()`, `PetscLogEventRegister()`, `PetscHeaderCreate()`
 39: M*/
 40: typedef int PetscClassId;

 42: /*MC
 43:     PetscMPIInt - datatype used to represent 'int' parameters to MPI functions.

 45:     Level: intermediate

 47:     Notes:
 48:     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
 49:            standard C/Fortran integers are 32 bit then this is NOT the same as `PetscInt`; it remains 32 bit.

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

 54: .seealso: `PetscBLASInt`, `PetscInt`, `PetscMPIIntCast()`

 56: M*/
 57: typedef int PetscMPIInt;

 59: /*MC
 60:     PetscSizeT - datatype used to represent sizes in memory (like size_t)

 62:     Level: intermediate

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

 67: .seealso: `PetscInt`, `PetscInt64`, `PetscCount`

 69: M*/
 70: typedef size_t PetscSizeT;

 72: /*MC
 73:     PetscCount - signed datatype used to represent counts

 75:     Level: intermediate

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

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

 82: .seealso: `PetscInt`, `PetscInt64`, `PetscSizeT`

 84: M*/
 85: typedef ptrdiff_t PetscCount;
 86: #define PetscCount_FMT "td"

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

 91:     Level: intermediate

 93: .seealso: `PetscOptionsGetEnum()`, `PetscOptionsEnum()`, `PetscBagRegisterEnum()`
 94: M*/
 95: typedef enum {
 96:   ENUM_DUMMY
 97: } PetscEnum;

 99: typedef short PetscShort;
100: typedef char  PetscChar;
101: typedef float PetscFloat;

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

107:   Notes:
108:   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.

110:   Level: beginner

112: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`
113: M*/

115: #if defined(PETSC_HAVE_STDINT_H)
116:   #include <stdint.h>
117: #endif
118: #if defined(PETSC_HAVE_INTTYPES_H)
121:   #endif
122:   #include <inttypes.h>
123:   #if !defined(PRId64)
124:     #define PRId64 "ld"
125:   #endif
126: #endif

128: #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 */
129: typedef int64_t PetscInt64;
130: #elif (PETSC_SIZEOF_LONG_LONG == 8)
131: typedef long long PetscInt64;
132: #elif defined(PETSC_HAVE___INT64)
133: typedef __int64 PetscInt64;
134: #else
135:   #error "cannot determine PetscInt64 type"
136: #endif

138: #if defined(PETSC_USE_64BIT_INDICES)
139: typedef PetscInt64 PetscInt;
140: #else
141: typedef int       PetscInt;
142: #endif

144: #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 */
145:   #define MPIU_INT64     MPI_INT64_T
146:   #define PetscInt64_FMT PRId64
147: #elif (PETSC_SIZEOF_LONG_LONG == 8)
148:   #define MPIU_INT64     MPI_LONG_LONG_INT
149:   #define PetscInt64_FMT "lld"
150: #elif defined(PETSC_HAVE___INT64)
151:   #define MPIU_INT64     MPI_INT64_T
152:   #define PetscInt64_FMT "ld"
153: #else
154:   #error "cannot determine PetscInt64 type"
155: #endif

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

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

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

168:    Installation Notes:
169:     ./configure automatically determines the size of the integers used by BLAS/LAPACK except when --with-batch is used
170:     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

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

175:     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
176:     against the 64 bit version, otherwise it use the 32 bit version

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

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

184:    Level: intermediate

186: .seealso: `PetscMPIInt`, `PetscInt`, `PetscBLASIntCast()`

188: M*/
189: #if defined(PETSC_HAVE_64BIT_BLAS_INDICES)
190:   #define PetscBLASInt_FMT PetscInt64_FMT
191: typedef PetscInt64 PetscBLASInt;
192: #else
193:   #define PetscBLASInt_FMT "d"
194: typedef int       PetscBLASInt;
195: #endif

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

200:    Notes:
201:     As of this writing PetscCuBLASInt is always the system `int`.

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

206:    Level: intermediate

208: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscCuBLASIntCast()`

210: M*/
211: typedef int PetscCuBLASInt;

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

216:    Notes:
217:     As of this writing PetscHipBLASInt is always the system `int`.

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

222:    Level: intermediate

224: .seealso: PetscBLASInt, PetscMPIInt, PetscInt, PetscHipBLASIntCast()

226: M*/
227: typedef int PetscHipBLASInt;

229: /*E
230:     PetscBool  - Logical variable. Actually an enum in C and a logical in Fortran.

232:    Level: beginner

234:    Developer Note:
235:    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
236:       boolean values. It is not easy to have a simple macro that that will work properly in all circumstances with all three mechanisms.

238: .seealso: `PETSC_TRUE`, `PETSC_FALSE`, `PetscNot()`, `PetscBool3`
239: E*/
240: typedef enum {
241:   PETSC_FALSE,
242:   PETSC_TRUE
243: } PetscBool;

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

248:    Level: beginner

250:    Note:
251:    Should not be used with the if (flg) or if (!flg) syntax.

253: .seealso: `PETSC_TRUE`, `PETSC_FALSE`, `PetscNot()`, `PETSC_BOOL3_TRUE`, `PETSC_BOOL3_FALSE`, `PETSC_BOOL3_UKNOWN`
254: E*/
255: typedef enum {
256:   PETSC_BOOL3_FALSE,
257:   PETSC_BOOL3_TRUE,
258:   PETSC_BOOL3_UNKNOWN = -1
259: } PetscBool3;

261: #define PetscBool3ToBool(a) ((a) == PETSC_BOOL3_TRUE ? PETSC_TRUE : PETSC_FALSE)
262: #define PetscBoolToBool3(a) ((a) == PETSC_TRUE ? PETSC_BOOL3_TRUE : PETSC_BOOL3_FALSE)

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

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

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

273:    Level: beginner

275: .seealso: `PetscScalar`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`
276: M*/

278: #if defined(PETSC_USE_REAL_SINGLE)
279: typedef float PetscReal;
280: #elif defined(PETSC_USE_REAL_DOUBLE)
281: typedef double    PetscReal;
282: #elif defined(PETSC_USE_REAL___FLOAT128)
283:   #if defined(__cplusplus)
284: extern "C" {
285:   #endif
286:   #include <quadmath.h>
287:   #if defined(__cplusplus)
288: }
289:   #endif
290: typedef __float128 PetscReal;
291: #elif defined(PETSC_USE_REAL___FP16)
292: typedef __fp16 PetscReal;
293: #endif /* PETSC_USE_REAL_* */

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

298:    Synopsis:
299: #include <petscsys.h>
300:    PetscComplex number = 1. + 2.*PETSC_i;

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

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

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

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

314:     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`
315:     at the beginning of the C++ file to skip the fix.

317:    Level: beginner

319: .seealso: `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PETSC_i`
320: M*/
321: #if !defined(PETSC_SKIP_COMPLEX)
322:   #if defined(PETSC_CLANGUAGE_CXX)
323:     #if !defined(PETSC_USE_REAL___FP16) && !defined(PETSC_USE_REAL___FLOAT128)
324:       #if defined(__cplusplus) && defined(PETSC_HAVE_CXX_COMPLEX) /* enable complex for library code */
325:         #define PETSC_HAVE_COMPLEX 1
326:       #elif !defined(__cplusplus) && defined(PETSC_HAVE_C99_COMPLEX) && defined(PETSC_HAVE_CXX_COMPLEX) /* User code only - conditional on library code complex support */
327:         #define PETSC_HAVE_COMPLEX 1
328:       #endif
329:     #elif defined(PETSC_USE_REAL___FLOAT128) && defined(PETSC_HAVE_C99_COMPLEX)
330:       #define PETSC_HAVE_COMPLEX 1
331:     #endif
332:   #else /* !PETSC_CLANGUAGE_CXX */
333:     #if !defined(PETSC_USE_REAL___FP16)
335:         #define PETSC_HAVE_COMPLEX 1
336:       #elif defined(__cplusplus) && defined(PETSC_HAVE_C99_COMPLEX) && defined(PETSC_HAVE_CXX_COMPLEX) /* User code only - conditional on library code complex support */
337:         #define PETSC_HAVE_COMPLEX 1
338:       #endif
339:     #endif
340:   #endif /* PETSC_CLANGUAGE_CXX */
341: #endif   /* !PETSC_SKIP_COMPLEX */

343: #if defined(PETSC_HAVE_COMPLEX)
344:   #if defined(__cplusplus) /* C++ complex support */
345:     /* Locate a C++ complex template library */
346:     #if defined(PETSC_DESIRE_KOKKOS_COMPLEX) /* Defined in petscvec_kokkos.hpp for *.kokkos.cxx files */
347:       #define petsccomplexlib Kokkos
348:       #include <Kokkos_Complex.hpp>
349:     #elif defined(__CUDACC__) || defined(__HIPCC__)
350:       #define petsccomplexlib thrust
351:       #include <thrust/complex.h>
352:     #elif defined(PETSC_USE_REAL___FLOAT128)
353:       #include <complex.h>
354:     #else
355:       #define petsccomplexlib std
356:       #include <complex>
357:     #endif

359:     /* Define PetscComplex based on the precision */
360:     #if defined(PETSC_USE_REAL_SINGLE)
361: typedef petsccomplexlib::complex<float> PetscComplex;
362:     #elif defined(PETSC_USE_REAL_DOUBLE)
363: typedef petsccomplexlib::complex<double> PetscComplex;
364:     #elif defined(PETSC_USE_REAL___FLOAT128)
365: typedef __complex128 PetscComplex;
366:     #endif

368:     /* Include a PETSc C++ complex 'fix'. Check PetscComplex manual page for details */
369:     #if defined(PETSC_HAVE_CXX_COMPLEX_FIX) && !defined(PETSC_SKIP_CXX_COMPLEX_FIX)
370: #include <petsccxxcomplexfix.h>
371:     #endif
372:   #else /* c99 complex support */
373:     #include <complex.h>
374:     #if defined(PETSC_USE_REAL_SINGLE) || defined(PETSC_USE_REAL___FP16)
375: typedef float _Complex PetscComplex;
376:     #elif defined(PETSC_USE_REAL_DOUBLE)
377: typedef double _Complex PetscComplex;
378:     #elif defined(PETSC_USE_REAL___FLOAT128)
379: typedef __complex128 PetscComplex;
380:     #endif /* PETSC_USE_REAL_* */
381:   #endif   /* !__cplusplus */
382: #endif     /* PETSC_HAVE_COMPLEX */

384: /*MC
385:    PetscScalar - PETSc type that represents either a double precision real number, a double precision
386:        complex number, a single precision real number, a __float128 real or complex or a __fp16 real - if the code is configured
387:        with --with-scalar-type=real,complex --with-precision=single,double,__float128,__fp16

389:    Notes:
390:    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`.

392:    Level: beginner

394: .seealso: `PetscReal`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PetscRealPart()`, `PetscImaginaryPart()`
395: M*/

397: #if defined(PETSC_USE_COMPLEX) && defined(PETSC_HAVE_COMPLEX)
398: typedef PetscComplex PetscScalar;
399: #else  /* PETSC_USE_COMPLEX */
400: typedef PetscReal PetscScalar;
401: #endif /* PETSC_USE_COMPLEX */

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

406:    Level: beginner

408:    For the array input:
409: $   `PETSC_COPY_VALUES` - the array values are copied into new space, the user is free to reuse or delete the passed in array
410: $   `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
411: $                       delete the array. The array MUST have been obtained with PetscMalloc(). Hence this mode cannot be used in Fortran.
412: $   `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
413: $                       the array but the user must delete the array after the object is destroyed.

415:    For the PetscObject input:
416: $   `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.
417: $   `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.)
418:    For either case above, the input `PetscObject` should be destroyed by the user when no longer needed (the aggregate object increases its reference count).
419: $   `PETSC_USE_POINTER` - invalid for `PetscObject` inputs.

421: E*/
422: typedef enum {
423:   PETSC_COPY_VALUES,
424:   PETSC_OWN_POINTER,
425:   PETSC_USE_POINTER
426: } PetscCopyMode;

428: /*MC
429:     PETSC_FALSE - False value of `PetscBool`

431:     Level: beginner

433:     Note:
434:     Zero integer

436: .seealso: `PetscBool`, `PetscBool3`, `PETSC_TRUE`
437: M*/

439: /*MC
440:     PETSC_TRUE - True value of `PetscBool`

442:     Level: beginner

444:     Note:
445:     Nonzero integer

447: .seealso: `PetscBool`, `PetscBool3`, `PETSC_FALSE`
448: M*/

450: /*MC
451:     PetscLogDouble - Used for logging times

453:   Notes:
454:   Contains double precision numbers that are not used in the numerical computations, but rather in logging, timing etc.

456:   Level: developer

458: M*/
459: typedef double PetscLogDouble;

461: /*E
462:     PetscDataType - Used for handling different basic data types.

464:    Level: beginner

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

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

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

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

478:    TODO: Add PETSC_INT32 and remove use of improper PETSC_ENUM

480: .seealso: `PetscBinaryRead()`, `PetscBinaryWrite()`, `PetscDataTypeToMPIDataType()`,
481:           `PetscDataTypeGetSize()`

483: E*/
484: typedef enum {
485:   PETSC_DATATYPE_UNKNOWN = 0,
486:   PETSC_DOUBLE           = 1,
487:   PETSC_COMPLEX          = 2,
488:   PETSC_LONG             = 3,
489:   PETSC_SHORT            = 4,
490:   PETSC_FLOAT            = 5,
491:   PETSC_CHAR             = 6,
492:   PETSC_BIT_LOGICAL      = 7,
493:   PETSC_ENUM             = 8,
494:   PETSC_BOOL             = 9,
495:   PETSC___FLOAT128       = 10,
496:   PETSC_OBJECT           = 11,
497:   PETSC_FUNCTION         = 12,
498:   PETSC_STRING           = 13,
499:   PETSC___FP16           = 14,
500:   PETSC_STRUCT           = 15,
501:   PETSC_INT              = 16,
502:   PETSC_INT64            = 17,
503:   PETSC_COUNT            = 18
504: } PetscDataType;

506: #if defined(PETSC_USE_REAL_SINGLE)
507:   #define PETSC_REAL PETSC_FLOAT
508: #elif defined(PETSC_USE_REAL_DOUBLE)
509:   #define PETSC_REAL PETSC_DOUBLE
510: #elif defined(PETSC_USE_REAL___FLOAT128)
511:   #define PETSC_REAL PETSC___FLOAT128
512: #elif defined(PETSC_USE_REAL___FP16)
513:   #define PETSC_REAL PETSC___FP16
514: #else
515:   #define PETSC_REAL PETSC_DOUBLE
516: #endif

518: #if defined(PETSC_USE_COMPLEX)
519:   #define PETSC_SCALAR PETSC_COMPLEX
520: #else
521:   #define PETSC_SCALAR PETSC_REAL
522: #endif

524: #define PETSC_FORTRANADDR PETSC_LONG

526: /*S
527:     PetscToken - 'Token' used for managing tokenizing strings

529:   Level: intermediate

531: .seealso: `PetscTokenCreate()`, `PetscTokenFind()`, `PetscTokenDestroy()`
532: S*/
533: typedef struct _p_PetscToken *PetscToken;

535: /*S
536:      PetscObject - any PETSc object, `PetscViewer`, `Mat`, `Vec`, `KSP` etc

538:    Level: beginner

540:    Notes:
541:    This is the base class from which all PETSc objects are derived from.

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

545: .seealso: `PetscObjectDestroy()`, `PetscObjectView()`, `PetscObjectGetName()`, `PetscObjectSetName()`, `PetscObjectReference()`, `PetscObjectDereference()`
546: S*/
547: typedef struct _p_PetscObject *PetscObject;

549: /*MC
550:     PetscObjectId - unique integer Id for a `PetscObject`

552:     Level: developer

554:     Note:
555:     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
556:     if the objects are the same. Never compare two object pointer values.

558: .seealso: `PetscObjectState`, `PetscObjectGetId()`
559: M*/
560: typedef PetscInt64 PetscObjectId;

562: /*MC
563:     PetscObjectState - integer state for a `PetscObject`

565:     Level: developer

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

571: .seealso: `PetscObjectId`, `PetscObjectStateGet()`, `PetscObjectStateIncrease()`, `PetscObjectStateSet()`
572: M*/
573: typedef PetscInt64 PetscObjectState;

575: /*S
576:      PetscFunctionList - Linked list of functions, possibly stored in dynamic libraries, accessed
577:       by string name

579:    Level: advanced

581: .seealso: `PetscFunctionListAdd()`, `PetscFunctionListDestroy()`
582: S*/
583: typedef struct _n_PetscFunctionList *PetscFunctionList;

585: /*E
586:   PetscFileMode - Access mode for a file.

588:   Level: beginner

590: $  `FILE_MODE_UNDEFINED` - initial invalid value
591: $  `FILE_MODE_READ` - open a file at its beginning for reading
592: $  `FILE_MODE_WRITE` - open a file at its beginning for writing (will create if the file does not exist)
593: $  `FILE_MODE_APPEND` - open a file at end for writing
594: $  `FILE_MODE_UPDATE` - open a file for updating, meaning for reading and writing
595: $  `FILE_MODE_APPEND_UPDATE` - open a file for updating, meaning for reading and writing, at the end

597: .seealso: `PetscViewerFileSetMode()`
598: E*/
599: typedef enum {
600:   FILE_MODE_UNDEFINED = -1,
601:   FILE_MODE_READ      = 0,
602:   FILE_MODE_WRITE,
603:   FILE_MODE_APPEND,
604:   FILE_MODE_UPDATE,
605:   FILE_MODE_APPEND_UPDATE
606: } PetscFileMode;

608: typedef void *PetscDLHandle;
609: typedef enum {
610:   PETSC_DL_DECIDE = 0,
611:   PETSC_DL_NOW    = 1,
612:   PETSC_DL_LOCAL  = 2
613: } PetscDLMode;

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

618:    Level: developer

620:    Note:
621:    Used by `PetscObjectCompose()` and `PetscObjectQuery()`

623: .seealso: `PetscObjectListAdd()`, `PetscObjectListDestroy()`, `PetscObjectListFind()`, `PetscObjectCompose()`, `PetscObjectQuery()`, `PetscFunctionList`
624: S*/
625: typedef struct _n_PetscObjectList *PetscObjectList;

627: /*S
628:      PetscDLLibrary - Linked list of dynamics libraries to search for functions

630:    Level: advanced

632: .seealso: `PetscDLLibraryOpen()`
633: S*/
634: typedef struct _n_PetscDLLibrary *PetscDLLibrary;

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

639:    Level: advanced

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

644: .seealso: `PetscObject`, `PetscContainerCreate()`, `PetscObjectCompose()`, `PetscObjectQuery()`
645: S*/
646: typedef struct _p_PetscContainer *PetscContainer;

648: /*S
649:      PetscRandom - Abstract PETSc object that manages generating random numbers

651:    Level: intermediate

653: .seealso: `PetscRandomCreate()`, `PetscRandomGetValue()`, `PetscRandomType`
654: S*/
655: typedef struct _p_PetscRandom *PetscRandom;

657: /*
658:    In binary files variables are stored using the following lengths,
659:   regardless of how they are stored in memory on any one particular
660:   machine. Use these rather then sizeof() in computing sizes for
661:   PetscBinarySeek().
662: */
663: #define PETSC_BINARY_INT_SIZE    (32 / 8)
664: #define PETSC_BINARY_FLOAT_SIZE  (32 / 8)
665: #define PETSC_BINARY_CHAR_SIZE   (8 / 8)
666: #define PETSC_BINARY_SHORT_SIZE  (16 / 8)
667: #define PETSC_BINARY_DOUBLE_SIZE (64 / 8)
668: #define PETSC_BINARY_SCALAR_SIZE sizeof(PetscScalar)

670: /*E
671:   PetscBinarySeekType - argument to `PetscBinarySeek()`

673:   Level: advanced

675: .seealso: `PetscBinarySeek()`, `PetscBinarySynchronizedSeek()`
676: E*/
677: typedef enum {
678:   PETSC_BINARY_SEEK_SET = 0,
679:   PETSC_BINARY_SEEK_CUR = 1,
680:   PETSC_BINARY_SEEK_END = 2
681: } PetscBinarySeekType;

683: /*E
684:     PetscBuildTwoSidedType - algorithm for setting up two-sided communication

686: $  `PETSC_BUILDTWOSIDED_ALLREDUCE` - classical algorithm using an MPI_Allreduce with
687: $      a buffer of length equal to the communicator size. Not memory-scalable due to
688: $      the large reduction size. Requires only MPI-1.
689: $  `PETSC_BUILDTWOSIDED_IBARRIER` - nonblocking algorithm based on MPI_Issend and MPI_Ibarrier.
690: $      Proved communication-optimal in Hoefler, Siebert, and Lumsdaine (2010). Requires MPI-3.
691: $  `PETSC_BUILDTWOSIDED_REDSCATTER` - similar to above, but use more optimized function
692: $      that only communicates the part of the reduction that is necessary.  Requires MPI-2.

694:    Level: developer

696: .seealso: `PetscCommBuildTwoSided()`, `PetscCommBuildTwoSidedSetType()`, `PetscCommBuildTwoSidedGetType()`
697: E*/
698: typedef enum {
699:   PETSC_BUILDTWOSIDED_NOTSET     = -1,
700:   PETSC_BUILDTWOSIDED_ALLREDUCE  = 0,
701:   PETSC_BUILDTWOSIDED_IBARRIER   = 1,
702:   PETSC_BUILDTWOSIDED_REDSCATTER = 2
703:   /* Updates here must be accompanied by updates in finclude/petscsys.h and the string array in mpits.c */
704: } PetscBuildTwoSidedType;

706: /* NOTE: If you change this, you must also change the values in src/vec/f90-mod/petscvec.h */
707: /*E
708:   InsertMode - Whether entries are inserted or added into vectors or matrices

710:   Level: beginner

712: .seealso: `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`,
713:           `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`,
714:           `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`
715: E*/
716: typedef enum {
717:   NOT_SET_VALUES,
718:   INSERT_VALUES,
719:   ADD_VALUES,
720:   MAX_VALUES,
721:   MIN_VALUES,
722:   INSERT_ALL_VALUES,
723:   ADD_ALL_VALUES,
724:   INSERT_BC_VALUES,
725:   ADD_BC_VALUES
726: } InsertMode;

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

731:     Level: beginner

733: .seealso: `InsertMode`, `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`,
734:           `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`, `ADD_VALUES`,
735:           `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`, `MAX_VALUES`

737: M*/

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

743:     Level: beginner

745: .seealso: `InsertMode`, `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`,
746:           `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`, `INSERT_VALUES`,
747:           `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`, `MAX_VALUES`

749: M*/

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

754:     Level: beginner

756: .seealso: `InsertMode`, `VecScatterBegin()`, `VecScatterEnd()`, `ADD_VALUES`, `INSERT_VALUES`

758: M*/

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

763:     Level: beginner

765: .seealso: `InsertMode`, `VecScatterBegin()`, `VecScatterEnd()`, `ADD_VALUES`, `INSERT_VALUES`

767: M*/

769: /*S
770:    PetscSubcomm - A decomposition of an MPI communicator into subcommunicators

772:    Notes:
773:    After a call to `PetscSubcommSetType()`, `PetscSubcommSetTypeGeneral()`, or `PetscSubcommSetFromOptions()` one may call
774: $     `PetscSubcommChild()` returns the associated subcommunicator on this process
775: $     `PetscSubcommContiguousParent()` returns a parent communitor but with all child of the same subcommunicator having contiguous rank

777:    Sample Usage:
778: .vb
779:        `PetscSubcommCreate()`
780:        `PetscSubcommSetNumber()`
781:        `PetscSubcommSetType`(`PETSC_SUBCOMM_INTERLACED`);
782:        ccomm = `PetscSubcommChild()`
783:        `PetscSubcommDestroy()`
784: .ve

786:    Level: advanced

788:    Notes:
789: $   `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
790: $   `PETSC_SUBCOMM_CONTIGUOUS` - each new communicator contains a set of process with contiguous ranks in the original MPI communicator
791: $   `PETSC_SUBCOMM_INTERLACED` - each new communictor contains a set of processes equally far apart in rank from the others in that new communicator

793:    Example: Consider a communicator with six processes split into 3 subcommunicators.
794: $     `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
795: $     `PETSC_SUBCOMM_INTERLACED` - the first communicator contains rank 0,3, the second 1,4 and the third 2,5

797:    Developer Note:
798:    This is used in objects such as `PCREDUNDANT` to manage the subcommunicators on which the redundant computations
799:    are performed.

801: .seealso: `PetscSubcommCreate()`, `PetscSubcommSetNumber()`, `PetscSubcommSetType()`, `PetscSubcommView()`, `PetscSubcommSetFromOptions()`

803: S*/
804: typedef struct _n_PetscSubcomm *PetscSubcomm;
805: typedef enum {
806:   PETSC_SUBCOMM_GENERAL    = 0,
807:   PETSC_SUBCOMM_CONTIGUOUS = 1,
808:   PETSC_SUBCOMM_INTERLACED = 2
809: } PetscSubcommType;

811: /*S
812:      PetscHeap - A simple class for managing heaps

814:    Level: intermediate

816: .seealso: `PetscHeapCreate()`, `PetscHeapAdd()`, `PetscHeapPop()`, `PetscHeapPeek()`, `PetscHeapStash()`, `PetscHeapUnstash()`, `PetscHeapView()`, `PetscHeapDestroy()`
817: S*/
818: typedef struct _PetscHeap *PetscHeap;

820: typedef struct _n_PetscShmComm *PetscShmComm;
821: typedef struct _n_PetscOmpCtrl *PetscOmpCtrl;

823: /*S
824:    PetscSegBuffer - a segmented extendable buffer

826:    Level: developer

828: .seealso: `PetscSegBufferCreate()`, `PetscSegBufferGet()`, `PetscSegBufferExtract()`, `PetscSegBufferDestroy()`
829: S*/
830: typedef struct _n_PetscSegBuffer *PetscSegBuffer;

832: typedef struct _n_PetscOptionsHelpPrinted *PetscOptionsHelpPrinted;
833: #endif