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 <petscmacros.h> // PETSC_NODISCARD, PETSC_CPP_VERSION 12 #include <stddef.h> 13 14 /* SUBMANSEC = Sys */ 15 16 #include <limits.h> // INT_MIN, INT_MAX 17 18 #if defined(__clang__) || (PETSC_CPP_VERSION >= 17) 19 // clang allows both [[nodiscard]] and __attribute__((warn_unused_result)) on type 20 // definitions. GCC, however, does not, so check that we are using C++17 [[nodiscard]] 21 // instead of __attribute__((warn_unused_result)) 22 #define PETSC_ERROR_CODE_NODISCARD PETSC_NODISCARD 23 #else 24 #define PETSC_ERROR_CODE_NODISCARD 25 #endif 26 27 #ifdef PETSC_CLANG_STATIC_ANALYZER 28 #undef PETSC_USE_STRICT_PETSCERRORCODE 29 #endif 30 31 #ifdef PETSC_USE_STRICT_PETSCERRORCODE 32 #define PETSC_ERROR_CODE_TYPEDEF typedef 33 #define PETSC_ERROR_CODE_ENUM_NAME PetscErrorCode 34 #else 35 #define PETSC_ERROR_CODE_TYPEDEF 36 #define PETSC_ERROR_CODE_ENUM_NAME 37 #endif 38 39 /*E 40 PetscErrorCode - Datatype used to return PETSc error codes. 41 42 Level: beginner 43 44 Notes: 45 Virtually all PETSc functions return an error code. It is the callers responsibility to check 46 the value of the returned error code after each PETSc call to determine if any errors 47 occurred. A set of convenience macros (e.g. `PetscCall()`, `PetscCallVoid()`) are provided 48 for this purpose. Failing to properly check for errors is not supported, as errors may leave 49 PETSc in an undetermined state. 50 51 One can retrieve the error string corresponding to a particular error code using 52 `PetscErrorMessage()`. 53 54 The user can also configure PETSc with the `--with-strict-petscerrorcode` option to enable 55 compiler warnings when the returned error codes are not captured and checked. Users are 56 *heavily* encouraged to opt-in to this option, as it will become enabled by default in a 57 future release. 58 59 Developer Notes: 60 61 These are the generic error codes. These error codes are used in many different places in the 62 PETSc source code. The C-string versions are at defined in `PetscErrorStrings[]` in 63 `src/sys/error/err.c`, while the fortran versions are defined in 64 `src/sys/f90-mod/petscerror.h`. Any changes here must also be made in both locations. 65 66 .seealso: `PetscErrorMessage()`, `PetscCall()`, `SETERRQ()` 67 E*/ 68 PETSC_ERROR_CODE_TYPEDEF enum PETSC_ERROR_CODE_NODISCARD { 69 PETSC_SUCCESS = 0, 70 PETSC_ERR_BOOLEAN_MACRO_FAILURE = 1, /* do not use */ 71 72 PETSC_ERR_MIN_VALUE = 54, /* should always be one less then the smallest value */ 73 74 PETSC_ERR_MEM = 55, /* unable to allocate requested memory */ 75 PETSC_ERR_SUP = 56, /* no support for requested operation */ 76 PETSC_ERR_SUP_SYS = 57, /* no support for requested operation on this computer system */ 77 PETSC_ERR_ORDER = 58, /* operation done in wrong order */ 78 PETSC_ERR_SIG = 59, /* signal received */ 79 PETSC_ERR_FP = 72, /* floating point exception */ 80 PETSC_ERR_COR = 74, /* corrupted PETSc object */ 81 PETSC_ERR_LIB = 76, /* error in library called by PETSc */ 82 PETSC_ERR_PLIB = 77, /* PETSc library generated inconsistent data */ 83 PETSC_ERR_MEMC = 78, /* memory corruption */ 84 PETSC_ERR_CONV_FAILED = 82, /* iterative method (KSP or SNES) failed */ 85 PETSC_ERR_USER = 83, /* user has not provided needed function */ 86 PETSC_ERR_SYS = 88, /* error in system call */ 87 PETSC_ERR_POINTER = 70, /* pointer does not point to valid address */ 88 PETSC_ERR_MPI_LIB_INCOMP = 87, /* MPI library at runtime is not compatible with MPI user compiled with */ 89 90 PETSC_ERR_ARG_SIZ = 60, /* nonconforming object sizes used in operation */ 91 PETSC_ERR_ARG_IDN = 61, /* two arguments not allowed to be the same */ 92 PETSC_ERR_ARG_WRONG = 62, /* wrong argument (but object probably ok) */ 93 PETSC_ERR_ARG_CORRUPT = 64, /* null or corrupted PETSc object as argument */ 94 PETSC_ERR_ARG_OUTOFRANGE = 63, /* input argument, out of range */ 95 PETSC_ERR_ARG_BADPTR = 68, /* invalid pointer argument */ 96 PETSC_ERR_ARG_NOTSAMETYPE = 69, /* two args must be same object type */ 97 PETSC_ERR_ARG_NOTSAMECOMM = 80, /* two args must be same communicators */ 98 PETSC_ERR_ARG_WRONGSTATE = 73, /* object in argument is in wrong state, e.g. unassembled mat */ 99 PETSC_ERR_ARG_TYPENOTSET = 89, /* the type of the object has not yet been set */ 100 PETSC_ERR_ARG_INCOMP = 75, /* two arguments are incompatible */ 101 PETSC_ERR_ARG_NULL = 85, /* argument is null that should not be */ 102 PETSC_ERR_ARG_UNKNOWN_TYPE = 86, /* type name doesn't match any registered type */ 103 104 PETSC_ERR_FILE_OPEN = 65, /* unable to open file */ 105 PETSC_ERR_FILE_READ = 66, /* unable to read from file */ 106 PETSC_ERR_FILE_WRITE = 67, /* unable to write to file */ 107 PETSC_ERR_FILE_UNEXPECTED = 79, /* unexpected data in file */ 108 109 PETSC_ERR_MAT_LU_ZRPVT = 71, /* detected a zero pivot during LU factorization */ 110 PETSC_ERR_MAT_CH_ZRPVT = 81, /* detected a zero pivot during Cholesky factorization */ 111 112 PETSC_ERR_INT_OVERFLOW = 84, 113 PETSC_ERR_FLOP_COUNT = 90, 114 PETSC_ERR_NOT_CONVERGED = 91, /* solver did not converge */ 115 PETSC_ERR_MISSING_FACTOR = 92, /* MatGetFactor() failed */ 116 PETSC_ERR_OPT_OVERWRITE = 93, /* attempted to over write options which should not be changed */ 117 PETSC_ERR_WRONG_MPI_SIZE = 94, /* example/application run with number of MPI ranks it does not support */ 118 PETSC_ERR_USER_INPUT = 95, /* missing or incorrect user input */ 119 PETSC_ERR_GPU_RESOURCE = 96, /* unable to load a GPU resource, for example cuBLAS */ 120 PETSC_ERR_GPU = 97, /* An error from a GPU call, this may be due to lack of resources on the GPU or a true error in the call */ 121 PETSC_ERR_MPI = 98, /* general MPI error */ 122 PETSC_ERR_RETURN = 99, /* PetscError() incorrectly returned an error code of 0 */ 123 PETSC_ERR_MAX_VALUE = 100, /* this is always the one more than the largest error code */ 124 125 /* 126 do not use, exist purely to make the enum bounds equal that of a regular int (so conversion 127 to int in main() is not undefined behavior) 128 */ 129 PETSC_ERR_MIN_SIGNED_BOUND_DO_NOT_USE = INT_MIN, 130 PETSC_ERR_MAX_SIGNED_BOUND_DO_NOT_USE = INT_MAX 131 } PETSC_ERROR_CODE_ENUM_NAME; 132 133 #ifndef PETSC_USE_STRICT_PETSCERRORCODE 134 typedef int PetscErrorCode; 135 136 /* 137 Needed so that C++ lambdas can deduce the return type as PetscErrorCode from 138 PetscFunctionReturn(PETSC_SUCCESS). Otherwise we get 139 140 error: return type '(unnamed enum at include/petscsystypes.h:50:1)' must match previous 141 return type 'int' when lambda expression has unspecified explicit return type 142 PetscFunctionReturn(PETSC_SUCCESS); 143 ^ 144 */ 145 #define PETSC_SUCCESS ((PetscErrorCode)0) 146 #endif 147 148 #undef PETSC_ERROR_CODE_NODISCARD 149 #undef PETSC_ERROR_CODE_TYPEDEF 150 #undef PETSC_ERROR_CODE_ENUM_NAME 151 152 /*MC 153 154 PetscClassId - A unique id used to identify each PETSc class. 155 156 Notes: 157 Use `PetscClassIdRegister()` to obtain a new value for a new class being created. Usually 158 XXXInitializePackage() calls it for each class it defines. 159 160 Developer Notes: 161 Internal integer stored in the `_p_PetscObject` data structure. 162 These are all computed by an offset from the lowest one, `PETSC_SMALLEST_CLASSID`. 163 164 Level: developer 165 166 .seealso: `PetscClassIdRegister()`, `PetscLogEventRegister()`, `PetscHeaderCreate()` 167 M*/ 168 typedef int PetscClassId; 169 170 /*MC 171 PetscMPIInt - datatype used to represent 'int' parameters to MPI functions. 172 173 Level: intermediate 174 175 Notes: 176 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 177 standard C/Fortran integers are 32 bit then this is NOT the same as `PetscInt`; it remains 32 bit. 178 179 `PetscMPIIntCast`(a,&b) checks if the given `PetscInt` a will fit in a `PetscMPIInt`, if not it 180 generates a `PETSC_ERR_ARG_OUTOFRANGE` error. 181 182 .seealso: `PetscBLASInt`, `PetscInt`, `PetscMPIIntCast()` 183 184 M*/ 185 typedef int PetscMPIInt; 186 187 /* Limit MPI to 32-bits */ 188 enum { 189 PETSC_MPI_INT_MIN = INT_MIN, 190 PETSC_MPI_INT_MAX = INT_MAX 191 }; 192 193 /*MC 194 PetscSizeT - datatype used to represent sizes in memory (like size_t) 195 196 Level: intermediate 197 198 Notes: 199 This is equivalent to size_t, but defined for consistency with Fortran, which lacks a native equivalent of size_t. 200 201 .seealso: `PetscInt`, `PetscInt64`, `PetscCount` 202 203 M*/ 204 typedef size_t PetscSizeT; 205 206 /*MC 207 PetscCount - signed datatype used to represent counts 208 209 Level: intermediate 210 211 Notes: 212 This is equivalent to ptrdiff_t, but defined for consistency with Fortran, which lacks a native equivalent of ptrdiff_t. 213 214 Use `PetscCount_FMT` to format with `PetscPrintf()`, `printf()`, and related functions. 215 216 .seealso: `PetscInt`, `PetscInt64`, `PetscSizeT` 217 218 M*/ 219 typedef ptrdiff_t PetscCount; 220 #define PetscCount_FMT "td" 221 222 /*MC 223 PetscEnum - datatype used to pass enum types within PETSc functions. 224 225 Level: intermediate 226 227 .seealso: `PetscOptionsGetEnum()`, `PetscOptionsEnum()`, `PetscBagRegisterEnum()` 228 M*/ 229 typedef enum { 230 ENUM_DUMMY 231 } PetscEnum; 232 233 typedef short PetscShort; 234 typedef char PetscChar; 235 typedef float PetscFloat; 236 237 /*MC 238 PetscInt - PETSc type that represents an integer, used primarily to 239 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. 240 241 Notes: 242 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. 243 244 Level: beginner 245 246 .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT` 247 M*/ 248 249 #if defined(PETSC_HAVE_STDINT_H) 250 #include <stdint.h> 251 #endif 252 #if defined(PETSC_HAVE_INTTYPES_H) 253 #if !defined(__STDC_FORMAT_MACROS) 254 #define __STDC_FORMAT_MACROS /* required for using PRId64 from c++ */ 255 #endif 256 #include <inttypes.h> 257 #if !defined(PRId64) 258 #define PRId64 "ld" 259 #endif 260 #endif 261 262 #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 */ 263 typedef int64_t PetscInt64; 264 265 #define PETSC_INT64_MIN INT64_MIN 266 #define PETSC_INT64_MAX INT64_MAX 267 268 #elif (PETSC_SIZEOF_LONG_LONG == 8) 269 typedef long long PetscInt64; 270 271 #define PETSC_INT64_MIN LLONG_MIN 272 #define PETSC_INT64_MAX LLONG_MAX 273 274 #elif defined(PETSC_HAVE___INT64) 275 typedef __int64 PetscInt64; 276 277 #define PETSC_INT64_MIN INT64_MIN 278 #define PETSC_INT64_MAX INT64_MAX 279 280 #else 281 #error "cannot determine PetscInt64 type" 282 #endif 283 284 #if defined(PETSC_USE_64BIT_INDICES) 285 typedef PetscInt64 PetscInt; 286 287 #define PETSC_INT_MIN PETSC_INT64_MIN 288 #define PETSC_INT_MAX PETSC_INT64_MAX 289 #define PetscInt_FMT PetscInt64_FMT 290 #else 291 typedef int PetscInt; 292 293 enum { 294 PETSC_INT_MIN = INT_MIN, 295 PETSC_INT_MAX = INT_MAX 296 }; 297 298 #define PetscInt_FMT "d" 299 #endif 300 301 #define PETSC_MIN_INT PETSC_INT_MIN 302 #define PETSC_MAX_INT PETSC_INT_MAX 303 #define PETSC_MAX_UINT16 65535 304 305 #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 */ 306 #define MPIU_INT64 MPI_INT64_T 307 #define PetscInt64_FMT PRId64 308 #elif (PETSC_SIZEOF_LONG_LONG == 8) 309 #define MPIU_INT64 MPI_LONG_LONG_INT 310 #define PetscInt64_FMT "lld" 311 #elif defined(PETSC_HAVE___INT64) 312 #define MPIU_INT64 MPI_INT64_T 313 #define PetscInt64_FMT "ld" 314 #else 315 #error "cannot determine PetscInt64 type" 316 #endif 317 318 /*MC 319 PetscBLASInt - datatype used to represent 'int' parameters to BLAS/LAPACK functions. 320 321 Notes: 322 Usually this is the same as `PetscIn`t, but if PETSc was built with --with-64-bit-indices but 323 standard C/Fortran integers are 32 bit then this may not be the same as `PetscInt`, 324 except on some BLAS/LAPACK implementations that support 64 bit integers see the notes below. 325 326 `PetscErrorCode` `PetscBLASIntCast`(a,&b) checks if the given `PetscInt` a will fit in a `PetscBLASInt`, if not it 327 generates a `PETSC_ERR_ARG_OUTOFRANGE` error 328 329 Installation Notes: 330 ./configure automatically determines the size of the integers used by BLAS/LAPACK except when --with-batch is used 331 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 332 333 MATLAB ships with BLAS and LAPACK that use 64 bit integers, for example if you run ./configure with, the option 334 --with-blaslapack-lib=[/Applications/MATLAB_R2010b.app/bin/maci64/libmwblas.dylib,/Applications/MATLAB_R2010b.app/bin/maci64/libmwlapack.dylib] 335 336 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 337 against the 64 bit version, otherwise it use the 32 bit version 338 339 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 340 341 External packages such as hypre, ML, SuperLU etc do not provide any support for passing 64 bit integers to BLAS/LAPACK so cannot 342 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 343 these external libraries while using 64 bit integer BLAS/LAPACK. 344 345 Level: intermediate 346 347 .seealso: `PetscMPIInt`, `PetscInt`, `PetscBLASIntCast()` 348 349 M*/ 350 #if defined(PETSC_HAVE_64BIT_BLAS_INDICES) 351 typedef PetscInt64 PetscBLASInt; 352 353 #define PETSC_BLAS_INT_MIN PETSC_INT64_MIN 354 #define PETSC_BLAS_INT_MAX PETSC_INT64_MAX 355 #define PetscBLASInt_FMT PetscInt64_FMT 356 #else 357 typedef int PetscBLASInt; 358 359 enum { 360 PETSC_BLAS_INT_MIN = INT_MIN, 361 PETSC_BLAS_INT_MAX = INT_MAX 362 }; 363 364 #define PetscBLASInt_FMT "d" 365 #endif 366 367 /*MC 368 PetscCuBLASInt - datatype used to represent 'int' parameters to cuBLAS/cuSOLVER functions. 369 370 Notes: 371 As of this writing PetscCuBLASInt is always the system `int`. 372 373 `PetscErrorCode` `PetscCuBLASIntCast`(a,&b) checks if the given `PetscInt` a will fit in a `PetscCuBLASInt`, if not it 374 generates a `PETSC_ERR_ARG_OUTOFRANGE` error 375 376 Level: intermediate 377 378 .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscCuBLASIntCast()` 379 380 M*/ 381 typedef int PetscCuBLASInt; 382 383 enum { 384 PETSC_CUBLAS_INT_MIN = INT_MIN, 385 PETSC_CUBLAS_INT_MAX = INT_MAX 386 }; 387 388 /*MC 389 PetscHipBLASInt - datatype used to represent 'int' parameters to hipBLAS/hipSOLVER functions. 390 391 Notes: 392 As of this writing PetscHipBLASInt is always the system `int`. 393 394 PetscErrorCode PetscHipBLASIntCast(a,&b) checks if the given PetscInt a will fit in a PetscHipBLASInt, if not it 395 generates a PETSC_ERR_ARG_OUTOFRANGE error 396 397 Level: intermediate 398 399 .seealso: PetscBLASInt, PetscMPIInt, PetscInt, PetscHipBLASIntCast() 400 401 M*/ 402 typedef int PetscHipBLASInt; 403 404 enum { 405 PETSC_HIPBLAS_INT_MIN = INT_MIN, 406 PETSC_HIPBLAS_INT_MAX = INT_MAX 407 }; 408 409 /*E 410 PetscBool - Logical variable. Actually an enum in C and a logical in Fortran. 411 412 Level: beginner 413 414 Developer Note: 415 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 416 boolean values. It is not easy to have a simple macro that that will work properly in all circumstances with all three mechanisms. 417 418 .seealso: `PETSC_TRUE`, `PETSC_FALSE`, `PetscNot()`, `PetscBool3` 419 E*/ 420 typedef enum { 421 PETSC_FALSE, 422 PETSC_TRUE 423 } PetscBool; 424 PETSC_EXTERN const char *const PetscBools[]; 425 426 /*E 427 PetscBool3 - Ternary logical variable. Actually an enum in C and a 4 byte integer in Fortran. 428 429 Level: beginner 430 431 Note: 432 Should not be used with the if (flg) or if (!flg) syntax. 433 434 .seealso: `PETSC_TRUE`, `PETSC_FALSE`, `PetscNot()`, `PETSC_BOOL3_TRUE`, `PETSC_BOOL3_FALSE`, `PETSC_BOOL3_UNKNOWN` 435 E*/ 436 typedef enum { 437 PETSC_BOOL3_FALSE, 438 PETSC_BOOL3_TRUE, 439 PETSC_BOOL3_UNKNOWN = -1 440 } PetscBool3; 441 442 #define PetscBool3ToBool(a) ((a) == PETSC_BOOL3_TRUE ? PETSC_TRUE : PETSC_FALSE) 443 #define PetscBoolToBool3(a) ((a) == PETSC_TRUE ? PETSC_BOOL3_TRUE : PETSC_BOOL3_FALSE) 444 445 /*MC 446 PetscReal - PETSc type that represents a real number version of `PetscScalar` 447 448 Notes: 449 For MPI calls that require datatypes, use `MPIU_REAL` as the datatype for `PetscReal` and `MPIU_SUM`, `MPIU_MAX`, etc. for operations. 450 They will automatically work correctly regardless of the size of `PetscReal`. 451 452 See `PetscScalar` for details on how to ./configure the size of `PetscReal`. 453 454 Level: beginner 455 456 .seealso: `PetscScalar`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT` 457 M*/ 458 459 #if defined(PETSC_USE_REAL_SINGLE) 460 typedef float PetscReal; 461 #elif defined(PETSC_USE_REAL_DOUBLE) 462 typedef double PetscReal; 463 #elif defined(PETSC_USE_REAL___FLOAT128) 464 #if defined(__cplusplus) 465 extern "C" { 466 #endif 467 #include <quadmath.h> 468 #if defined(__cplusplus) 469 } 470 #endif 471 typedef __float128 PetscReal; 472 #elif defined(PETSC_USE_REAL___FP16) 473 typedef __fp16 PetscReal; 474 #endif /* PETSC_USE_REAL_* */ 475 476 /*MC 477 PetscComplex - PETSc type that represents a complex number with precision matching that of `PetscReal`. 478 479 Synopsis: 480 #include <petscsys.h> 481 PetscComplex number = 1. + 2.*PETSC_i; 482 483 Notes: 484 For MPI calls that require datatypes, use `MPIU_COMPLEX` as the datatype for `PetscComplex` and `MPIU_SUM` etc for operations. 485 They will automatically work correctly regardless of the size of `PetscComplex`. 486 487 See PetscScalar for details on how to ./configure the size of `PetscReal` 488 489 Complex numbers are automatically available if PETSc was able to find a working complex implementation 490 491 Petsc has a 'fix' for complex numbers to support expressions such as std::complex<PetscReal> + `PetscInt`, which are not supported by the standard 492 C++ library, but are convenient for petsc users. If the C++ compiler is able to compile code in petsccxxcomplexfix.h (This is checked by 493 configure), we include petsccxxcomplexfix.h to provide this convenience. 494 495 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` 496 at the beginning of the C++ file to skip the fix. 497 498 Level: beginner 499 500 .seealso: `PetscReal`, `PetscScalar`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PETSC_i` 501 M*/ 502 #if !defined(PETSC_SKIP_COMPLEX) 503 #if defined(PETSC_CLANGUAGE_CXX) 504 #if !defined(PETSC_USE_REAL___FP16) && !defined(PETSC_USE_REAL___FLOAT128) 505 #if defined(__cplusplus) && defined(PETSC_HAVE_CXX_COMPLEX) /* enable complex for library code */ 506 #define PETSC_HAVE_COMPLEX 1 507 #elif !defined(__cplusplus) && defined(PETSC_HAVE_C99_COMPLEX) && defined(PETSC_HAVE_CXX_COMPLEX) /* User code only - conditional on library code complex support */ 508 #define PETSC_HAVE_COMPLEX 1 509 #endif 510 #elif defined(PETSC_USE_REAL___FLOAT128) && defined(PETSC_HAVE_C99_COMPLEX) 511 #define PETSC_HAVE_COMPLEX 1 512 #endif 513 #else /* !PETSC_CLANGUAGE_CXX */ 514 #if !defined(PETSC_USE_REAL___FP16) 515 #if !defined(__cplusplus) && defined(PETSC_HAVE_C99_COMPLEX) /* enable complex for library code */ 516 #define PETSC_HAVE_COMPLEX 1 517 #elif defined(__cplusplus) && defined(PETSC_HAVE_C99_COMPLEX) && defined(PETSC_HAVE_CXX_COMPLEX) /* User code only - conditional on library code complex support */ 518 #define PETSC_HAVE_COMPLEX 1 519 #endif 520 #endif 521 #endif /* PETSC_CLANGUAGE_CXX */ 522 #endif /* !PETSC_SKIP_COMPLEX */ 523 524 #if defined(PETSC_HAVE_COMPLEX) 525 #if defined(__cplusplus) /* C++ complex support */ 526 /* Locate a C++ complex template library */ 527 #if defined(PETSC_DESIRE_KOKKOS_COMPLEX) /* Defined in petscvec_kokkos.hpp for *.kokkos.cxx files */ 528 #define petsccomplexlib Kokkos 529 #include <Kokkos_Complex.hpp> 530 #elif defined(__CUDACC__) || defined(__HIPCC__) 531 #define petsccomplexlib thrust 532 #include <thrust/complex.h> 533 #elif defined(PETSC_USE_REAL___FLOAT128) 534 #include <complex.h> 535 #else 536 #define petsccomplexlib std 537 #include <complex> 538 #endif 539 540 /* Define PetscComplex based on the precision */ 541 #if defined(PETSC_USE_REAL_SINGLE) 542 typedef petsccomplexlib::complex<float> PetscComplex; 543 #elif defined(PETSC_USE_REAL_DOUBLE) 544 typedef petsccomplexlib::complex<double> PetscComplex; 545 #elif defined(PETSC_USE_REAL___FLOAT128) 546 typedef __complex128 PetscComplex; 547 #endif 548 549 /* Include a PETSc C++ complex 'fix'. Check PetscComplex manual page for details */ 550 #if defined(PETSC_HAVE_CXX_COMPLEX_FIX) && !defined(PETSC_SKIP_CXX_COMPLEX_FIX) 551 #include <petsccxxcomplexfix.h> 552 #endif 553 #else /* c99 complex support */ 554 #include <complex.h> 555 #if defined(PETSC_USE_REAL_SINGLE) || defined(PETSC_USE_REAL___FP16) 556 typedef float _Complex PetscComplex; 557 #elif defined(PETSC_USE_REAL_DOUBLE) 558 typedef double _Complex PetscComplex; 559 #elif defined(PETSC_USE_REAL___FLOAT128) 560 typedef __complex128 PetscComplex; 561 #endif /* PETSC_USE_REAL_* */ 562 #endif /* !__cplusplus */ 563 #endif /* PETSC_HAVE_COMPLEX */ 564 565 /*MC 566 PetscScalar - PETSc type that represents either a double precision real number, a double precision 567 complex number, a single precision real number, a __float128 real or complex or a __fp16 real - if the code is configured 568 with --with-scalar-type=real,complex --with-precision=single,double,__float128,__fp16 569 570 Notes: 571 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`. 572 573 Level: beginner 574 575 .seealso: `PetscReal`, `PetscComplex`, `PetscInt`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`, `MPIU_INT`, `PetscRealPart()`, `PetscImaginaryPart()` 576 M*/ 577 578 #if defined(PETSC_USE_COMPLEX) && defined(PETSC_HAVE_COMPLEX) 579 typedef PetscComplex PetscScalar; 580 #else /* PETSC_USE_COMPLEX */ 581 typedef PetscReal PetscScalar; 582 #endif /* PETSC_USE_COMPLEX */ 583 584 /*E 585 PetscCopyMode - Determines how an array or `PetscObject` passed to certain functions is copied or retained by the aggregate `PetscObject` 586 587 Level: beginner 588 589 For the array input: 590 $ `PETSC_COPY_VALUES` - the array values are copied into new space, the user is free to reuse or delete the passed in array 591 $ `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 592 $ delete the array. The array MUST have been obtained with PetscMalloc(). Hence this mode cannot be used in Fortran. 593 $ `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 594 $ the array but the user must delete the array after the object is destroyed. 595 596 For the PetscObject input: 597 $ `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. 598 $ `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.) 599 For either case above, the input `PetscObject` should be destroyed by the user when no longer needed (the aggregate object increases its reference count). 600 $ `PETSC_USE_POINTER` - invalid for `PetscObject` inputs. 601 602 E*/ 603 typedef enum { 604 PETSC_COPY_VALUES, 605 PETSC_OWN_POINTER, 606 PETSC_USE_POINTER 607 } PetscCopyMode; 608 PETSC_EXTERN const char *const PetscCopyModes[]; 609 610 /*MC 611 PETSC_FALSE - False value of `PetscBool` 612 613 Level: beginner 614 615 Note: 616 Zero integer 617 618 .seealso: `PetscBool`, `PetscBool3`, `PETSC_TRUE` 619 M*/ 620 621 /*MC 622 PETSC_TRUE - True value of `PetscBool` 623 624 Level: beginner 625 626 Note: 627 Nonzero integer 628 629 .seealso: `PetscBool`, `PetscBool3`, `PETSC_FALSE` 630 M*/ 631 632 /*MC 633 PetscLogDouble - Used for logging times 634 635 Notes: 636 Contains double precision numbers that are not used in the numerical computations, but rather in logging, timing etc. 637 638 Level: developer 639 640 M*/ 641 typedef double PetscLogDouble; 642 643 /*E 644 PetscDataType - Used for handling different basic data types. 645 646 Level: beginner 647 648 Notes: 649 Use of this should be avoided if one can directly use `MPI_Datatype` instead. 650 651 `PETSC_INT` is the datatype for a `PetscInt`, regardless of whether it is 4 or 8 bytes. 652 `PETSC_REAL`, `PETSC_COMPLEX` and `PETSC_SCALAR` are the datatypes for `PetscReal`, `PetscComplex` and `PetscScalar`, regardless of their sizes. 653 654 Developer Notes: 655 It would be nice if we could always just use MPI Datatypes, why can we not? 656 657 If you change any values in `PetscDatatype` make sure you update their usage in 658 share/petsc/matlab/PetscBagRead.m and share/petsc/matlab/@PetscOpenSocket/read/write.m 659 660 TODO: Add PETSC_INT32 and remove use of improper PETSC_ENUM 661 662 .seealso: `PetscBinaryRead()`, `PetscBinaryWrite()`, `PetscDataTypeToMPIDataType()`, 663 `PetscDataTypeGetSize()` 664 665 E*/ 666 typedef enum { 667 PETSC_DATATYPE_UNKNOWN = 0, 668 PETSC_DOUBLE = 1, 669 PETSC_COMPLEX = 2, 670 PETSC_LONG = 3, 671 PETSC_SHORT = 4, 672 PETSC_FLOAT = 5, 673 PETSC_CHAR = 6, 674 PETSC_BIT_LOGICAL = 7, 675 PETSC_ENUM = 8, 676 PETSC_BOOL = 9, 677 PETSC___FLOAT128 = 10, 678 PETSC_OBJECT = 11, 679 PETSC_FUNCTION = 12, 680 PETSC_STRING = 13, 681 PETSC___FP16 = 14, 682 PETSC_STRUCT = 15, 683 PETSC_INT = 16, 684 PETSC_INT64 = 17, 685 PETSC_COUNT = 18 686 } PetscDataType; 687 PETSC_EXTERN const char *const PetscDataTypes[]; 688 689 #if defined(PETSC_USE_REAL_SINGLE) 690 #define PETSC_REAL PETSC_FLOAT 691 #elif defined(PETSC_USE_REAL_DOUBLE) 692 #define PETSC_REAL PETSC_DOUBLE 693 #elif defined(PETSC_USE_REAL___FLOAT128) 694 #define PETSC_REAL PETSC___FLOAT128 695 #elif defined(PETSC_USE_REAL___FP16) 696 #define PETSC_REAL PETSC___FP16 697 #else 698 #define PETSC_REAL PETSC_DOUBLE 699 #endif 700 701 #if defined(PETSC_USE_COMPLEX) 702 #define PETSC_SCALAR PETSC_COMPLEX 703 #else 704 #define PETSC_SCALAR PETSC_REAL 705 #endif 706 707 #define PETSC_FORTRANADDR PETSC_LONG 708 709 /*S 710 PetscToken - 'Token' used for managing tokenizing strings 711 712 Level: intermediate 713 714 .seealso: `PetscTokenCreate()`, `PetscTokenFind()`, `PetscTokenDestroy()` 715 S*/ 716 typedef struct _p_PetscToken *PetscToken; 717 718 /*S 719 PetscObject - any PETSc object, `PetscViewer`, `Mat`, `Vec`, `KSP` etc 720 721 Level: beginner 722 723 Notes: 724 This is the base class from which all PETSc objects are derived from. 725 726 In certain situations one can cast an object, for example a `Vec`, to a `PetscObject` with (`PetscObject`)vec 727 728 .seealso: `PetscObjectDestroy()`, `PetscObjectView()`, `PetscObjectGetName()`, `PetscObjectSetName()`, `PetscObjectReference()`, `PetscObjectDereference()` 729 S*/ 730 typedef struct _p_PetscObject *PetscObject; 731 732 /*MC 733 PetscObjectId - unique integer Id for a `PetscObject` 734 735 Level: developer 736 737 Note: 738 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 739 if the objects are the same. Never compare two object pointer values. 740 741 .seealso: `PetscObjectState`, `PetscObjectGetId()` 742 M*/ 743 typedef PetscInt64 PetscObjectId; 744 745 /*MC 746 PetscObjectState - integer state for a `PetscObject` 747 748 Level: developer 749 750 Notes: 751 Object state is always-increasing and (for objects that track state) can be used to determine if an object has 752 changed since the last time you interacted with it. It is 64-bit so that it will not overflow for a very long time. 753 754 .seealso: `PetscObjectId`, `PetscObjectStateGet()`, `PetscObjectStateIncrease()`, `PetscObjectStateSet()` 755 M*/ 756 typedef PetscInt64 PetscObjectState; 757 758 /*S 759 PetscFunctionList - Linked list of functions, possibly stored in dynamic libraries, accessed 760 by string name 761 762 Level: advanced 763 764 .seealso: `PetscFunctionListAdd()`, `PetscFunctionListDestroy()` 765 S*/ 766 typedef struct _n_PetscFunctionList *PetscFunctionList; 767 768 /*E 769 PetscFileMode - Access mode for a file. 770 771 Level: beginner 772 773 $ `FILE_MODE_UNDEFINED` - initial invalid value 774 $ `FILE_MODE_READ` - open a file at its beginning for reading 775 $ `FILE_MODE_WRITE` - open a file at its beginning for writing (will create if the file does not exist) 776 $ `FILE_MODE_APPEND` - open a file at end for writing 777 $ `FILE_MODE_UPDATE` - open a file for updating, meaning for reading and writing 778 $ `FILE_MODE_APPEND_UPDATE` - open a file for updating, meaning for reading and writing, at the end 779 780 .seealso: `PetscViewerFileSetMode()` 781 E*/ 782 typedef enum { 783 FILE_MODE_UNDEFINED = -1, 784 FILE_MODE_READ = 0, 785 FILE_MODE_WRITE, 786 FILE_MODE_APPEND, 787 FILE_MODE_UPDATE, 788 FILE_MODE_APPEND_UPDATE 789 } PetscFileMode; 790 PETSC_EXTERN const char *const PetscFileModes[]; 791 792 typedef void *PetscDLHandle; 793 typedef enum { 794 PETSC_DL_DECIDE = 0, 795 PETSC_DL_NOW = 1, 796 PETSC_DL_LOCAL = 2 797 } PetscDLMode; 798 799 /*S 800 PetscObjectList - Linked list of PETSc objects, each accessible by string name 801 802 Level: developer 803 804 Note: 805 Used by `PetscObjectCompose()` and `PetscObjectQuery()` 806 807 .seealso: `PetscObjectListAdd()`, `PetscObjectListDestroy()`, `PetscObjectListFind()`, `PetscObjectCompose()`, `PetscObjectQuery()`, `PetscFunctionList` 808 S*/ 809 typedef struct _n_PetscObjectList *PetscObjectList; 810 811 /*S 812 PetscDLLibrary - Linked list of dynamics libraries to search for functions 813 814 Level: advanced 815 816 .seealso: `PetscDLLibraryOpen()` 817 S*/ 818 typedef struct _n_PetscDLLibrary *PetscDLLibrary; 819 820 /*S 821 PetscContainer - Simple PETSc object that contains a pointer to any required data 822 823 Level: advanced 824 825 Note: 826 This is useful to attach arbitrary data to a `PetscObject` with `PetscObjectCompose()` and `PetscObjectQuery()` 827 828 .seealso: `PetscObject`, `PetscContainerCreate()`, `PetscObjectCompose()`, `PetscObjectQuery()` 829 S*/ 830 typedef struct _p_PetscContainer *PetscContainer; 831 832 /*S 833 PetscRandom - Abstract PETSc object that manages generating random numbers 834 835 Level: intermediate 836 837 .seealso: `PetscRandomCreate()`, `PetscRandomGetValue()`, `PetscRandomType` 838 S*/ 839 typedef struct _p_PetscRandom *PetscRandom; 840 841 /* 842 In binary files variables are stored using the following lengths, 843 regardless of how they are stored in memory on any one particular 844 machine. Use these rather then sizeof() in computing sizes for 845 PetscBinarySeek(). 846 */ 847 #define PETSC_BINARY_INT_SIZE (32 / 8) 848 #define PETSC_BINARY_FLOAT_SIZE (32 / 8) 849 #define PETSC_BINARY_CHAR_SIZE (8 / 8) 850 #define PETSC_BINARY_SHORT_SIZE (16 / 8) 851 #define PETSC_BINARY_DOUBLE_SIZE (64 / 8) 852 #define PETSC_BINARY_SCALAR_SIZE sizeof(PetscScalar) 853 854 /*E 855 PetscBinarySeekType - argument to `PetscBinarySeek()` 856 857 Level: advanced 858 859 .seealso: `PetscBinarySeek()`, `PetscBinarySynchronizedSeek()` 860 E*/ 861 typedef enum { 862 PETSC_BINARY_SEEK_SET = 0, 863 PETSC_BINARY_SEEK_CUR = 1, 864 PETSC_BINARY_SEEK_END = 2 865 } PetscBinarySeekType; 866 867 /*E 868 PetscBuildTwoSidedType - algorithm for setting up two-sided communication 869 870 $ `PETSC_BUILDTWOSIDED_ALLREDUCE` - classical algorithm using an MPI_Allreduce with 871 $ a buffer of length equal to the communicator size. Not memory-scalable due to 872 $ the large reduction size. Requires only MPI-1. 873 $ `PETSC_BUILDTWOSIDED_IBARRIER` - nonblocking algorithm based on MPI_Issend and MPI_Ibarrier. 874 $ Proved communication-optimal in Hoefler, Siebert, and Lumsdaine (2010). Requires MPI-3. 875 $ `PETSC_BUILDTWOSIDED_REDSCATTER` - similar to above, but use more optimized function 876 $ that only communicates the part of the reduction that is necessary. Requires MPI-2. 877 878 Level: developer 879 880 .seealso: `PetscCommBuildTwoSided()`, `PetscCommBuildTwoSidedSetType()`, `PetscCommBuildTwoSidedGetType()` 881 E*/ 882 typedef enum { 883 PETSC_BUILDTWOSIDED_NOTSET = -1, 884 PETSC_BUILDTWOSIDED_ALLREDUCE = 0, 885 PETSC_BUILDTWOSIDED_IBARRIER = 1, 886 PETSC_BUILDTWOSIDED_REDSCATTER = 2 887 /* Updates here must be accompanied by updates in finclude/petscsys.h and the string array in mpits.c */ 888 } PetscBuildTwoSidedType; 889 PETSC_EXTERN const char *const PetscBuildTwoSidedTypes[]; 890 891 /* NOTE: If you change this, you must also change the values in src/vec/f90-mod/petscvec.h */ 892 /*E 893 InsertMode - Whether entries are inserted or added into vectors or matrices 894 895 Level: beginner 896 897 .seealso: `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`, 898 `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`, 899 `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()` 900 E*/ 901 typedef enum { 902 NOT_SET_VALUES, 903 INSERT_VALUES, 904 ADD_VALUES, 905 MAX_VALUES, 906 MIN_VALUES, 907 INSERT_ALL_VALUES, 908 ADD_ALL_VALUES, 909 INSERT_BC_VALUES, 910 ADD_BC_VALUES 911 } InsertMode; 912 913 /*MC 914 INSERT_VALUES - Put a value into a vector or matrix, overwrites any previous value 915 916 Level: beginner 917 918 .seealso: `InsertMode`, `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`, 919 `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`, `ADD_VALUES`, 920 `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`, `MAX_VALUES` 921 922 M*/ 923 924 /*MC 925 ADD_VALUES - Adds a value into a vector or matrix, if there previously was no value, just puts the 926 value into that location 927 928 Level: beginner 929 930 .seealso: `InsertMode`, `VecSetValues()`, `MatSetValues()`, `VecSetValue()`, `VecSetValuesBlocked()`, 931 `VecSetValuesLocal()`, `VecSetValuesBlockedLocal()`, `MatSetValuesBlocked()`, `INSERT_VALUES`, 932 `MatSetValuesBlockedLocal()`, `MatSetValuesLocal()`, `VecScatterBegin()`, `VecScatterEnd()`, `MAX_VALUES` 933 934 M*/ 935 936 /*MC 937 MAX_VALUES - Puts the maximum of the scattered/gathered value and the current value into each location 938 939 Level: beginner 940 941 .seealso: `InsertMode`, `VecScatterBegin()`, `VecScatterEnd()`, `ADD_VALUES`, `INSERT_VALUES` 942 943 M*/ 944 945 /*MC 946 MIN_VALUES - Puts the minimal of the scattered/gathered value and the current value into each location 947 948 Level: beginner 949 950 .seealso: `InsertMode`, `VecScatterBegin()`, `VecScatterEnd()`, `ADD_VALUES`, `INSERT_VALUES` 951 952 M*/ 953 954 /*S 955 PetscSubcomm - A decomposition of an MPI communicator into subcommunicators 956 957 Notes: 958 After a call to `PetscSubcommSetType()`, `PetscSubcommSetTypeGeneral()`, or `PetscSubcommSetFromOptions()` one may call 959 $ `PetscSubcommChild()` returns the associated subcommunicator on this process 960 $ `PetscSubcommContiguousParent()` returns a parent communitor but with all child of the same subcommunicator having contiguous rank 961 962 Sample Usage: 963 .vb 964 `PetscSubcommCreate()` 965 `PetscSubcommSetNumber()` 966 `PetscSubcommSetType`(`PETSC_SUBCOMM_INTERLACED`); 967 ccomm = `PetscSubcommChild()` 968 `PetscSubcommDestroy()` 969 .ve 970 971 Level: advanced 972 973 Notes: 974 $ `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 975 $ `PETSC_SUBCOMM_CONTIGUOUS` - each new communicator contains a set of process with contiguous ranks in the original MPI communicator 976 $ `PETSC_SUBCOMM_INTERLACED` - each new communictor contains a set of processes equally far apart in rank from the others in that new communicator 977 978 Example: Consider a communicator with six processes split into 3 subcommunicators. 979 $ `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 980 $ `PETSC_SUBCOMM_INTERLACED` - the first communicator contains rank 0,3, the second 1,4 and the third 2,5 981 982 Developer Note: 983 This is used in objects such as `PCREDUNDANT` to manage the subcommunicators on which the redundant computations 984 are performed. 985 986 .seealso: `PetscSubcommCreate()`, `PetscSubcommSetNumber()`, `PetscSubcommSetType()`, `PetscSubcommView()`, `PetscSubcommSetFromOptions()` 987 988 S*/ 989 typedef struct _n_PetscSubcomm *PetscSubcomm; 990 typedef enum { 991 PETSC_SUBCOMM_GENERAL = 0, 992 PETSC_SUBCOMM_CONTIGUOUS = 1, 993 PETSC_SUBCOMM_INTERLACED = 2 994 } PetscSubcommType; 995 PETSC_EXTERN const char *const PetscSubcommTypes[]; 996 997 /*S 998 PetscHeap - A simple class for managing heaps 999 1000 Level: intermediate 1001 1002 .seealso: `PetscHeapCreate()`, `PetscHeapAdd()`, `PetscHeapPop()`, `PetscHeapPeek()`, `PetscHeapStash()`, `PetscHeapUnstash()`, `PetscHeapView()`, `PetscHeapDestroy()` 1003 S*/ 1004 typedef struct _PetscHeap *PetscHeap; 1005 1006 typedef struct _n_PetscShmComm *PetscShmComm; 1007 typedef struct _n_PetscOmpCtrl *PetscOmpCtrl; 1008 1009 /*S 1010 PetscSegBuffer - a segmented extendable buffer 1011 1012 Level: developer 1013 1014 .seealso: `PetscSegBufferCreate()`, `PetscSegBufferGet()`, `PetscSegBufferExtract()`, `PetscSegBufferDestroy()` 1015 S*/ 1016 typedef struct _n_PetscSegBuffer *PetscSegBuffer; 1017 1018 typedef struct _n_PetscOptionsHelpPrinted *PetscOptionsHelpPrinted; 1019 #endif 1020