1 /* Portions of this code are under: 2 Copyright (c) 2022 Advanced Micro Devices, Inc. All rights reserved. 3 */ 4 5 #ifndef PETSCSYSTYPES_H 6 #define PETSCSYSTYPES_H 7 8 #include <petscconf.h> 9 #include <petscconf_poison.h> 10 #include <petscfix.h> 11 #include <stddef.h> 12 13 /* SUBMANSEC = Sys */ 14 15 /*MC 16 PetscErrorCode - datatype used for return error code from almost all PETSc functions 17 18 Level: beginner 19 20 .seealso: `PetscCall()`, `SETERRQ()` 21 M*/ 22 typedef int PetscErrorCode; 23 24 /*MC 25 26 PetscClassId - A unique id used to identify each PETSc class. 27 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. 31 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`. 35 36 Level: developer 37 38 .seealso: `PetscClassIdRegister()`, `PetscLogEventRegister()`, `PetscHeaderCreate()` 39 M*/ 40 typedef int PetscClassId; 41 42 /*MC 43 PetscMPIInt - datatype used to represent 'int' parameters to MPI functions. 44 45 Level: intermediate 46 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. 50 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. 53 54 .seealso: `PetscBLASInt`, `PetscInt`, `PetscMPIIntCast()` 55 56 M*/ 57 typedef int PetscMPIInt; 58 59 /*MC 60 PetscSizeT - datatype used to represent sizes in memory (like size_t) 61 62 Level: intermediate 63 64 Notes: 65 This is equivalent to size_t, but defined for consistency with Fortran, which lacks a native equivalent of size_t. 66 67 .seealso: `PetscInt`, `PetscInt64`, `PetscCount` 68 69 M*/ 70 typedef size_t PetscSizeT; 71 72 /*MC 73 PetscCount - signed datatype used to represent counts 74 75 Level: intermediate 76 77 Notes: 78 This is equivalent to ptrdiff_t, but defined for consistency with Fortran, which lacks a native equivalent of ptrdiff_t. 79 80 Use `PetscCount_FMT` to format with `PetscPrintf()`, `printf()`, and related functions. 81 82 .seealso: `PetscInt`, `PetscInt64`, `PetscSizeT` 83 84 M*/ 85 typedef ptrdiff_t PetscCount; 86 #define PetscCount_FMT "td" 87 88 /*MC 89 PetscEnum - datatype used to pass enum types within PETSc functions. 90 91 Level: intermediate 92 93 .seealso: `PetscOptionsGetEnum()`, `PetscOptionsEnum()`, `PetscBagRegisterEnum()` 94 M*/ 95 typedef enum { 96 ENUM_DUMMY 97 } PetscEnum; 98 99 typedef short PetscShort; 100 typedef char PetscChar; 101 typedef float PetscFloat; 102 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. 106 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. 109 110 Level: beginner 111 112 .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT` 113 M*/ 114 115 #if defined(PETSC_HAVE_STDINT_H) 116 #include <stdint.h> 117 #endif 118 #if defined(PETSC_HAVE_INTTYPES_H) 119 #if !defined(__STDC_FORMAT_MACROS) 120 #define __STDC_FORMAT_MACROS /* required for using PRId64 from c++ */ 121 #endif 122 #include <inttypes.h> 123 #if !defined(PRId64) 124 #define PRId64 "ld" 125 #endif 126 #endif 127 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 137 138 #if defined(PETSC_USE_64BIT_INDICES) 139 typedef PetscInt64 PetscInt; 140 #else 141 typedef int PetscInt; 142 #endif 143 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 156 157 /*MC 158 PetscBLASInt - datatype used to represent 'int' parameters to BLAS/LAPACK functions. 159 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. 164 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 167 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 171 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] 174 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 177 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 179 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. 183 184 Level: intermediate 185 186 .seealso: `PetscMPIInt`, `PetscInt`, `PetscBLASIntCast()` 187 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 196 197 /*MC 198 PetscCuBLASInt - datatype used to represent 'int' parameters to cuBLAS/cuSOLVER functions. 199 200 Notes: 201 As of this writing PetscCuBLASInt is always the system `int`. 202 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 205 206 Level: intermediate 207 208 .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscCuBLASIntCast()` 209 210 M*/ 211 typedef int PetscCuBLASInt; 212 213 /*MC 214 PetscHipBLASInt - datatype used to represent 'int' parameters to hipBLAS/hipSOLVER functions. 215 216 Notes: 217 As of this writing PetscHipBLASInt is always the system `int`. 218 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 221 222 Level: intermediate 223 224 .seealso: PetscBLASInt, PetscMPIInt, PetscInt, PetscHipBLASIntCast() 225 226 M*/ 227 typedef int PetscHipBLASInt; 228 229 /*E 230 PetscBool - Logical variable. Actually an enum in C and a logical in Fortran. 231 232 Level: beginner 233 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. 237 238 .seealso: `PETSC_TRUE`, `PETSC_FALSE`, `PetscNot()`, `PetscBool3` 239 E*/ 240 typedef enum { 241 PETSC_FALSE, 242 PETSC_TRUE 243 } PetscBool; 244 245 /*E 246 PetscBool3 - Ternary logical variable. Actually an enum in C and a 4 byte integer in Fortran. 247 248 Level: beginner 249 250 Note: 251 Should not be used with the if (flg) or if (!flg) syntax. 252 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; 260 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) 263 264 /*MC 265 PetscReal - PETSc type that represents a real number version of `PetscScalar` 266 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`. 270 271 See `PetscScalar` for details on how to ./configure the size of `PetscReal`. 272 273 Level: beginner 274 275 .seealso: `PetscScalar`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT` 276 M*/ 277 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_* */ 294 295 /*MC 296 PetscComplex - PETSc type that represents a complex number with precision matching that of `PetscReal`. 297 298 Synopsis: 299 #include <petscsys.h> 300 PetscComplex number = 1. + 2.*PETSC_i; 301 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`. 305 306 See PetscScalar for details on how to ./configure the size of `PetscReal` 307 308 Complex numbers are automatically available if PETSc was able to find a working complex implementation 309 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. 313 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. 316 317 Level: beginner 318 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) 334 #if !defined(__cplusplus) && defined(PETSC_HAVE_C99_COMPLEX) /* enable complex for library code */ 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 */ 342 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 358 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 367 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 */ 383 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 388 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`. 391 392 Level: beginner 393 394 .seealso: `PetscReal`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PetscRealPart()`, `PetscImaginaryPart()` 395 M*/ 396 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 */ 402 403 /*E 404 PetscCopyMode - Determines how an array or `PetscObject` passed to certain functions is copied or retained by the aggregate `PetscObject` 405 406 Level: beginner 407 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. 414 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. 420 421 E*/ 422 typedef enum { 423 PETSC_COPY_VALUES, 424 PETSC_OWN_POINTER, 425 PETSC_USE_POINTER 426 } PetscCopyMode; 427 428 /*MC 429 PETSC_FALSE - False value of `PetscBool` 430 431 Level: beginner 432 433 Note: 434 Zero integer 435 436 .seealso: `PetscBool`, `PetscBool3`, `PETSC_TRUE` 437 M*/ 438 439 /*MC 440 PETSC_TRUE - True value of `PetscBool` 441 442 Level: beginner 443 444 Note: 445 Nonzero integer 446 447 .seealso: `PetscBool`, `PetscBool3`, `PETSC_FALSE` 448 M*/ 449 450 /*MC 451 PetscLogDouble - Used for logging times 452 453 Notes: 454 Contains double precision numbers that are not used in the numerical computations, but rather in logging, timing etc. 455 456 Level: developer 457 458 M*/ 459 typedef double PetscLogDouble; 460 461 /*E 462 PetscDataType - Used for handling different basic data types. 463 464 Level: beginner 465 466 Notes: 467 Use of this should be avoided if one can directly use `MPI_Datatype` instead. 468 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. 471 472 Developer Notes: 473 It would be nice if we could always just use MPI Datatypes, why can we not? 474 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 477 478 TODO: Add PETSC_INT32 and remove use of improper PETSC_ENUM 479 480 .seealso: `PetscBinaryRead()`, `PetscBinaryWrite()`, `PetscDataTypeToMPIDataType()`, 481 `PetscDataTypeGetSize()` 482 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; 505 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 517 518 #if defined(PETSC_USE_COMPLEX) 519 #define PETSC_SCALAR PETSC_COMPLEX 520 #else 521 #define PETSC_SCALAR PETSC_REAL 522 #endif 523 524 #define PETSC_FORTRANADDR PETSC_LONG 525 526 /*S 527 PetscToken - 'Token' used for managing tokenizing strings 528 529 Level: intermediate 530 531 .seealso: `PetscTokenCreate()`, `PetscTokenFind()`, `PetscTokenDestroy()` 532 S*/ 533 typedef struct _p_PetscToken *PetscToken; 534 535 /*S 536 PetscObject - any PETSc object, `PetscViewer`, `Mat`, `Vec`, `KSP` etc 537 538 Level: beginner 539 540 Notes: 541 This is the base class from which all PETSc objects are derived from. 542 543 In certain situations one can cast an object, for example a `Vec`, to a `PetscObject` with (`PetscObject`)vec 544 545 .seealso: `PetscObjectDestroy()`, `PetscObjectView()`, `PetscObjectGetName()`, `PetscObjectSetName()`, `PetscObjectReference()`, `PetscObjectDereference()` 546 S*/ 547 typedef struct _p_PetscObject *PetscObject; 548 549 /*MC 550 PetscObjectId - unique integer Id for a `PetscObject` 551 552 Level: developer 553 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. 557 558 .seealso: `PetscObjectState`, `PetscObjectGetId()` 559 M*/ 560 typedef PetscInt64 PetscObjectId; 561 562 /*MC 563 PetscObjectState - integer state for a `PetscObject` 564 565 Level: developer 566 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. 570 571 .seealso: `PetscObjectId`, `PetscObjectStateGet()`, `PetscObjectStateIncrease()`, `PetscObjectStateSet()` 572 M*/ 573 typedef PetscInt64 PetscObjectState; 574 575 /*S 576 PetscFunctionList - Linked list of functions, possibly stored in dynamic libraries, accessed 577 by string name 578 579 Level: advanced 580 581 .seealso: `PetscFunctionListAdd()`, `PetscFunctionListDestroy()` 582 S*/ 583 typedef struct _n_PetscFunctionList *PetscFunctionList; 584 585 /*E 586 PetscFileMode - Access mode for a file. 587 588 Level: beginner 589 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 596 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; 607 608 typedef void *PetscDLHandle; 609 typedef enum { 610 PETSC_DL_DECIDE = 0, 611 PETSC_DL_NOW = 1, 612 PETSC_DL_LOCAL = 2 613 } PetscDLMode; 614 615 /*S 616 PetscObjectList - Linked list of PETSc objects, each accessible by string name 617 618 Level: developer 619 620 Note: 621 Used by `PetscObjectCompose()` and `PetscObjectQuery()` 622 623 .seealso: `PetscObjectListAdd()`, `PetscObjectListDestroy()`, `PetscObjectListFind()`, `PetscObjectCompose()`, `PetscObjectQuery()`, `PetscFunctionList` 624 S*/ 625 typedef struct _n_PetscObjectList *PetscObjectList; 626 627 /*S 628 PetscDLLibrary - Linked list of dynamics libraries to search for functions 629 630 Level: advanced 631 632 .seealso: `PetscDLLibraryOpen()` 633 S*/ 634 typedef struct _n_PetscDLLibrary *PetscDLLibrary; 635 636 /*S 637 PetscContainer - Simple PETSc object that contains a pointer to any required data 638 639 Level: advanced 640 641 Note: 642 This is useful to attach arbitrary data to a `PetscObject` with `PetscObjectCompose()` and `PetscObjectQuery()` 643 644 .seealso: `PetscObject`, `PetscContainerCreate()`, `PetscObjectCompose()`, `PetscObjectQuery()` 645 S*/ 646 typedef struct _p_PetscContainer *PetscContainer; 647 648 /*S 649 PetscRandom - Abstract PETSc object that manages generating random numbers 650 651 Level: intermediate 652 653 .seealso: `PetscRandomCreate()`, `PetscRandomGetValue()`, `PetscRandomType` 654 S*/ 655 typedef struct _p_PetscRandom *PetscRandom; 656 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) 669 670 /*E 671 PetscBinarySeekType - argument to `PetscBinarySeek()` 672 673 Level: advanced 674 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; 682 683 /*E 684 PetscBuildTwoSidedType - algorithm for setting up two-sided communication 685 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. 693 694 Level: developer 695 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; 705 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 709 710 Level: beginner 711 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; 727 728 /*MC 729 INSERT_VALUES - Put a value into a vector or matrix, overwrites any previous value 730 731 Level: beginner 732 733 .seealso: `InsertMode`, `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`, 734 `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`, `ADD_VALUES`, 735 `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`, `MAX_VALUES` 736 737 M*/ 738 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 742 743 Level: beginner 744 745 .seealso: `InsertMode`, `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`, 746 `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`, `INSERT_VALUES`, 747 `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`, `MAX_VALUES` 748 749 M*/ 750 751 /*MC 752 MAX_VALUES - Puts the maximum of the scattered/gathered value and the current value into each location 753 754 Level: beginner 755 756 .seealso: `InsertMode`, `VecScatterBegin()`, `VecScatterEnd()`, `ADD_VALUES`, `INSERT_VALUES` 757 758 M*/ 759 760 /*MC 761 MIN_VALUES - Puts the minimal of the scattered/gathered value and the current value into each location 762 763 Level: beginner 764 765 .seealso: `InsertMode`, `VecScatterBegin()`, `VecScatterEnd()`, `ADD_VALUES`, `INSERT_VALUES` 766 767 M*/ 768 769 /*S 770 PetscSubcomm - A decomposition of an MPI communicator into subcommunicators 771 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 776 777 Sample Usage: 778 .vb 779 `PetscSubcommCreate()` 780 `PetscSubcommSetNumber()` 781 `PetscSubcommSetType`(`PETSC_SUBCOMM_INTERLACED`); 782 ccomm = `PetscSubcommChild()` 783 `PetscSubcommDestroy()` 784 .ve 785 786 Level: advanced 787 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 792 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 796 797 Developer Note: 798 This is used in objects such as `PCREDUNDANT` to manage the subcommunicators on which the redundant computations 799 are performed. 800 801 .seealso: `PetscSubcommCreate()`, `PetscSubcommSetNumber()`, `PetscSubcommSetType()`, `PetscSubcommView()`, `PetscSubcommSetFromOptions()` 802 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; 810 811 /*S 812 PetscHeap - A simple class for managing heaps 813 814 Level: intermediate 815 816 .seealso: `PetscHeapCreate()`, `PetscHeapAdd()`, `PetscHeapPop()`, `PetscHeapPeek()`, `PetscHeapStash()`, `PetscHeapUnstash()`, `PetscHeapView()`, `PetscHeapDestroy()` 817 S*/ 818 typedef struct _PetscHeap *PetscHeap; 819 820 typedef struct _n_PetscShmComm *PetscShmComm; 821 typedef struct _n_PetscOmpCtrl *PetscOmpCtrl; 822 823 /*S 824 PetscSegBuffer - a segmented extendable buffer 825 826 Level: developer 827 828 .seealso: `PetscSegBufferCreate()`, `PetscSegBufferGet()`, `PetscSegBufferExtract()`, `PetscSegBufferDestroy()` 829 S*/ 830 typedef struct _n_PetscSegBuffer *PetscSegBuffer; 831 832 typedef struct _n_PetscOptionsHelpPrinted *PetscOptionsHelpPrinted; 833 #endif 834