Actual source code: petscsys.h
1: /*
2: This is the main PETSc include file (for C and C++), included by petscvec.h and higher-level headers.
3: Portions of this code are under:
4: Copyright (c) 2022 Advanced Micro Devices, Inc. All rights reserved.
5: */
6: #pragma once
8: /* ========================================================================== */
9: /*
10: petscconf.h is contained in ${PETSC_ARCH}/include/petscconf.h it is
11: found automatically by the compiler due to the -I${PETSC_DIR}/${PETSC_ARCH}/include that
12: PETSc's makefiles add to the compiler rules.
13: For --prefix installs the directory ${PETSC_ARCH} does not exist and petscconf.h is in the same
14: directory as the other PETSc include files.
15: */
16: #include <petscconf.h>
17: #include <petscmacros.h>
19: /* SUBMANSEC = Sys */
21: #if PetscDefined(DESIRE_FEATURE_TEST_MACROS)
22: /*
23: Feature test macros must be included before headers defined by IEEE Std 1003.1-2001
24: We only turn these in PETSc source files that require them by setting PETSC_DESIRE_FEATURE_TEST_MACROS
25: */
26: #if PetscDefined(_POSIX_C_SOURCE_200112L) && !defined(_POSIX_C_SOURCE)
27: #define _POSIX_C_SOURCE 200112L
28: #endif
29: #if PetscDefined(_BSD_SOURCE) && !defined(_BSD_SOURCE)
30: #define _BSD_SOURCE
31: #endif
32: #if PetscDefined(_DEFAULT_SOURCE) && !defined(_DEFAULT_SOURCE)
33: #define _DEFAULT_SOURCE
34: #endif
35: #if PetscDefined(_GNU_SOURCE) && !defined(_GNU_SOURCE)
36: #define _GNU_SOURCE
37: #endif
38: #endif
40: #include <petscsystypes.h>
42: /* ========================================================================== */
44: /*
45: Need to put stdio.h AFTER mpi.h for MPICH2 with C++ compiler
46: see the top of mpicxx.h in the MPICH2 distribution.
47: */
48: #include <stdio.h>
50: /* MSMPI on 32-bit Microsoft Windows requires this yukky hack - that breaks MPI standard compliance */
51: #if !defined(MPIAPI)
52: #define MPIAPI
53: #endif
55: PETSC_EXTERN MPI_Datatype MPIU_ENUM PETSC_ATTRIBUTE_MPI_TYPE_TAG(PetscEnum);
57: PETSC_EXTERN MPI_Datatype MPIU_FORTRANADDR;
59: /*
60: For the rare cases when one needs to send a size_t object with MPI
61: */
62: PETSC_EXTERN MPI_Datatype MPIU_SIZE_T PETSC_ATTRIBUTE_MPI_TYPE_TAG(size_t);
64: /*
65: You can use PETSC_STDOUT as a replacement of stdout. You can also change
66: the value of PETSC_STDOUT to redirect all standard output elsewhere
67: */
68: PETSC_EXTERN FILE *PETSC_STDOUT;
70: /*
71: You can use PETSC_STDERR as a replacement of stderr. You can also change
72: the value of PETSC_STDERR to redirect all standard error elsewhere
73: */
74: PETSC_EXTERN FILE *PETSC_STDERR;
76: /*
77: Handle inclusion when using clang compiler with CUDA support
78: __float128 is not available for the device
79: */
80: #if defined(__clang__) && (defined(__CUDA_ARCH__) || defined(__HIPCC__))
81: #define PETSC_SKIP_REAL___FLOAT128
82: #endif
84: /*
85: Declare extern C stuff after including external header files
86: */
88: PETSC_EXTERN PetscBool PETSC_RUNNING_ON_VALGRIND;
89: /*
90: Defines elementary mathematics functions and constants.
91: */
92: #include <petscmath.h>
94: /*MC
95: PETSC_MPI_THREAD_REQUIRED - the required threading support used if PETSc initializes MPI with `MPI_Init_thread()`.
97: Deprecated, use `PetscSetMPIThreadRequiredType()`
99: Level: beginner
101: Note:
102: By default `PETSC_MPI_THREAD_REQUIRED` equals `MPI_THREAD_FUNNELED` when the MPI implementation provides `MPI_Init_thread()`, otherwise it equals `MPI_THREAD_SINGLE`
104: .seealso: `PetscInitialize()`, `PetscSetMPIThreadRequiredType()`
105: M*/
106: PETSC_EXTERN PetscMPIInt PETSC_MPI_THREAD_REQUIRED;
108: /*MC
109: PetscBeganMPI - indicates if PETSc initialized MPI using `MPI_Init()` during `PetscInitialize()` or if MPI was already initialized with `MPI_Init()`
111: Synopsis:
112: #include <petscsys.h>
113: PetscBool PetscBeganMPI;
115: No Fortran Support
117: Level: developer
119: Note:
120: `MPI_Init()` can never be called after `PetscInitialize()`
122: .seealso: `PetscInitialize()`, `PetscInitializeCalled`
123: M*/
124: PETSC_EXTERN PetscBool PetscBeganMPI;
126: PETSC_EXTERN PetscBool PetscErrorHandlingInitialized;
127: PETSC_EXTERN PetscBool PetscInitializeCalled;
128: PETSC_EXTERN PetscBool PetscFinalizeCalled;
129: PETSC_EXTERN PetscBool PetscViennaCLSynchronize;
131: PETSC_EXTERN PetscErrorCode PetscSetHelpVersionFunctions(PetscErrorCode (*)(MPI_Comm), PetscErrorCode (*)(MPI_Comm));
132: PETSC_EXTERN PetscErrorCode PetscCommDuplicate(MPI_Comm, MPI_Comm *, int *);
133: PETSC_EXTERN PetscErrorCode PetscCommDestroy(MPI_Comm *);
134: PETSC_EXTERN PetscErrorCode PetscCommGetComm(MPI_Comm, MPI_Comm *);
135: PETSC_EXTERN PetscErrorCode PetscCommRestoreComm(MPI_Comm, MPI_Comm *);
136: PETSC_EXTERN PetscErrorCode PetscCommCreateNonempty(MPI_Comm, const PetscInt[], MPI_Comm *);
137: PETSC_EXTERN PetscErrorCode PetscCommDestroyNonempty(MPI_Comm, MPI_Comm *);
139: #if PetscDefined(HAVE_KOKKOS)
140: PETSC_EXTERN PetscErrorCode PetscKokkosInitializeCheck(void); /* Initialize Kokkos if not yet. */
141: #endif
143: #if PetscDefined(HAVE_NVSHMEM)
144: PETSC_EXTERN PetscBool PetscBeganNvshmem;
145: PETSC_EXTERN PetscBool PetscNvshmemInitialized;
146: PETSC_EXTERN PetscErrorCode PetscNvshmemFinalize(void);
147: #endif
149: #if PetscDefined(HAVE_ELEMENTAL)
150: PETSC_EXTERN PetscErrorCode PetscElementalInitializePackage(void);
151: PETSC_EXTERN PetscErrorCode PetscElementalInitialized(PetscBool *);
152: PETSC_EXTERN PetscErrorCode PetscElementalFinalizePackage(void);
153: #endif
155: #include <petscmem.h>
157: PETSC_EXTERN PetscErrorCode PetscDataTypeToMPIDataType(PetscDataType, MPI_Datatype *);
158: PETSC_EXTERN PetscErrorCode PetscMPIDataTypeToPetscDataType(MPI_Datatype, PetscDataType *);
159: PETSC_EXTERN PetscErrorCode PetscDataTypeGetSize(PetscDataType, size_t *);
160: PETSC_EXTERN PetscErrorCode PetscDataTypeFromString(const char *, PetscDataType *, PetscBool *);
162: /*
163: These are MPI operations for MPI_Allreduce() etc
164: */
165: PETSC_EXTERN MPI_Op MPIU_MAXSUM_OP;
166: #if PetscDefined(USE_REAL___FLOAT128) || PetscDefined(USE_REAL___FP16)
167: PETSC_EXTERN MPI_Op MPIU_SUM;
168: PETSC_EXTERN MPI_Op MPIU_MAX;
169: PETSC_EXTERN MPI_Op MPIU_MIN;
170: #else
171: #define MPIU_SUM MPI_SUM
172: #define MPIU_MAX MPI_MAX
173: #define MPIU_MIN MPI_MIN
174: #endif
175: PETSC_EXTERN MPI_Op Petsc_Garbage_SetIntersectOp;
176: PETSC_EXTERN PetscErrorCode PetscMaxSum(MPI_Comm, const PetscInt[], PetscInt *, PetscInt *);
178: #if (PetscDefined(HAVE_REAL___FLOAT128) && !PetscDefined(SKIP_REAL___FLOAT128)) || (PetscDefined(HAVE_REAL___FP16) && !PetscDefined(SKIP_REAL___FP16))
179: /*MC
180: MPIU_SUM___FP16___FLOAT128 - `MPI_Op` that acts as a replacement for `MPI_SUM` with
181: custom `MPI_Datatype` `MPIU___FLOAT128`, `MPIU___COMPLEX128`, and `MPIU___FP16`.
183: Level: advanced
185: Developer Note:
186: This should be unified with `MPIU_SUM`
188: .seealso: `MPI_Op`, `MPI_Datatype`, `MPIU_REAL`, `MPIU_SCALAR`, `MPIU_COMPLEX`
189: M*/
190: PETSC_EXTERN MPI_Op MPIU_SUM___FP16___FLOAT128;
191: #endif
193: /*
194: These are so that in extern C code we can cast function pointers to non-extern C
195: function pointers. Since the regular C++ code expects its function pointers to be C++
196: */
198: /*S
199: PetscVoidFn - A prototype of a `void fn(void)` function
201: Level: advanced
203: Notes:
204: `PetscVoidFn *` plays the role of `void *` for function pointers in the PETSc API that do not return an error code.
205: It is used where a function pointer is needed but it is not possible to use the full prototype of the function.
207: `PetscErrorCodeFn` is similar to `PetscVoidFn` but should be used when the function returns a `PetscErrorCode`
209: .seealso: `PetscErrorCodeFn`, `PetscObject`, `PetscObjectDestroy()`
210: S*/
211: PETSC_EXTERN_TYPEDEF typedef void PetscVoidFn(void);
213: PETSC_EXTERN_TYPEDEF typedef PetscVoidFn *PetscVoidFunction PETSC_DEPRECATED_TYPEDEF(3, 26, 0, "PetscVoidFn*", );
214: PETSC_EXTERN_TYPEDEF typedef PetscVoidFn **PetscVoidStarFunction PETSC_DEPRECATED_TYPEDEF(3, 26, 0, "PetscVoidFn**", );
216: /*S
217: PetscErrorCodeFn - a function typedef that represents abstractly a function that returns a PETSc error code
218: and takes any number of arguments. Since C/C++ has no way to express this concept, it is implemented as `void (fn)(void)`.
220: Level: advanced
222: Notes:
223: `PetscErrorCodeFn *` plays the role of `void *` for function pointers in the PETSc API that return an error code.
224: It is used where a function pointer is needed but it is not possible to use the full prototype of the function,
225: for example `VecSetOperation()`.
227: `PetscVoidFn` is similar to `PetscErrorCodeFn` but should be used when the function does not return a `PetscErrorCode`.
229: Developer Notes:
230: This function type is equivalent to `PetscVoidFn`*.
232: At the C/C++ syntax level this construct adds nothing of value to the PETSc source code. It provides a way, at the abstract
233: PETSc API level, to indicate specifically functions that return PETSc error codes as opposed to any C/C++ function.
235: .seealso: `PetscVoidFn`, `PetscObject`, `PetscObjectDestroy()`, `VecSetOperation()`
236: S*/
237: PETSC_EXTERN_TYPEDEF typedef void PetscErrorCodeFn(void);
239: /*
240: Defines PETSc error handling.
241: */
242: #include <petscerror.h>
244: PETSC_EXTERN PetscBool PetscCIEnabled; /* code is running in the PETSc test harness CI */
245: PETSC_EXTERN PetscBool PetscCIEnabledPortableErrorOutput; /* error output is stripped to ensure portability of error messages across systems */
246: PETSC_EXTERN const char *PetscCIFilename(const char *);
247: PETSC_EXTERN int PetscCILinenumber(int);
249: #define PETSC_SMALLEST_CLASSID 1211211
250: PETSC_EXTERN PetscClassId PETSC_LARGEST_CLASSID;
251: PETSC_EXTERN PetscClassId PETSC_OBJECT_CLASSID;
252: PETSC_EXTERN PetscErrorCode PetscClassIdRegister(const char[], PetscClassId *);
254: /*
255: Routines that get memory usage information from the OS
256: */
257: PETSC_EXTERN PetscErrorCode PetscMemoryGetCurrentUsage(PetscLogDouble *);
258: PETSC_EXTERN PetscErrorCode PetscMemoryGetMaximumUsage(PetscLogDouble *);
259: PETSC_EXTERN PetscErrorCode PetscMemorySetGetMaximumUsage(void);
260: PETSC_EXTERN PetscErrorCode PetscMemoryTrace(const char[]);
262: PETSC_EXTERN PetscErrorCode PetscSleep(PetscReal);
264: /*
265: Initialization of PETSc
266: */
267: PETSC_EXTERN PetscErrorCode PetscInitialize(int *, char ***, const char[], const char[]);
268: PETSC_EXTERN PetscErrorCode PetscInitializeNoPointers(int, char *[], const char[], const char[]);
269: PETSC_EXTERN PetscErrorCode PetscInitializeNoArguments(void);
270: PETSC_EXTERN PetscErrorCode PetscInitialized(PetscBool *);
271: PETSC_EXTERN PetscErrorCode PetscFinalized(PetscBool *);
272: PETSC_EXTERN PetscErrorCode PetscFinalize(void);
273: PETSC_EXTERN PetscErrorCode PetscInitializeFortran(void);
274: PETSC_EXTERN PetscErrorCode PetscGetArgs(int *, char ***);
275: PETSC_EXTERN PetscErrorCode PetscGetArguments(char ***);
276: PETSC_EXTERN PetscErrorCode PetscFreeArguments(char **);
277: PETSC_EXTERN PetscErrorCode PetscSetMPIThreadRequiredType(PetscMPIInt);
279: PETSC_EXTERN PetscErrorCode PetscEnd(void);
280: PETSC_EXTERN PetscErrorCode PetscSysInitializePackage(void);
281: PETSC_EXTERN PetscErrorCode PetscSysFinalizePackage(void);
283: PETSC_EXTERN PetscErrorCode PetscPythonInitialize(const char[], const char[]);
284: PETSC_EXTERN PetscErrorCode PetscPythonFinalize(void);
285: PETSC_EXTERN PetscErrorCode PetscPythonPrintError(void);
286: PETSC_EXTERN PetscErrorCode PetscPythonMonitorSet(PetscObject, const char[]);
288: /*
289: Functions that can act on any PETSc object.
290: */
291: PETSC_EXTERN PetscErrorCode PetscObjectDestroy(PetscObject *);
292: PETSC_EXTERN PetscErrorCode PetscObjectGetComm(PetscObject, MPI_Comm *);
293: PETSC_EXTERN PetscErrorCode PetscObjectGetClassId(PetscObject, PetscClassId *);
294: PETSC_EXTERN PetscErrorCode PetscObjectGetClassName(PetscObject, const char *[]);
295: PETSC_EXTERN PetscErrorCode PetscObjectGetType(PetscObject, const char *[]);
296: PETSC_EXTERN PetscErrorCode PetscObjectSetName(PetscObject, const char[]);
297: PETSC_EXTERN PetscErrorCode PetscObjectGetName(PetscObject, const char *[]);
298: PETSC_EXTERN PetscErrorCode PetscObjectSetTabLevel(PetscObject, PetscInt);
299: PETSC_EXTERN PetscErrorCode PetscObjectGetTabLevel(PetscObject, PetscInt *);
300: PETSC_EXTERN PetscErrorCode PetscObjectIncrementTabLevel(PetscObject, PetscObject, PetscInt);
301: PETSC_EXTERN PetscErrorCode PetscObjectReference(PetscObject);
302: PETSC_EXTERN PetscErrorCode PetscObjectGetReference(PetscObject, PetscInt *);
303: PETSC_EXTERN PetscErrorCode PetscObjectDereference(PetscObject);
304: PETSC_EXTERN PetscErrorCode PetscObjectGetNewTag(PetscObject, PetscMPIInt *);
305: PETSC_EXTERN PetscErrorCode PetscObjectCompose(PetscObject, const char[], PetscObject);
306: PETSC_EXTERN PetscErrorCode PetscObjectRemoveReference(PetscObject, const char[]);
307: PETSC_EXTERN PetscErrorCode PetscObjectQuery(PetscObject, const char[], PetscObject *);
308: PETSC_EXTERN PetscErrorCode PetscObjectComposeFunction_Private(PetscObject, const char[], PetscErrorCodeFn *);
309: #define PetscObjectComposeFunction(a, b, ...) PetscObjectComposeFunction_Private((a), (b), (PetscErrorCodeFn *)(__VA_ARGS__))
310: PETSC_EXTERN PetscErrorCode PetscObjectSetFromOptions(PetscObject);
311: PETSC_EXTERN PetscErrorCode PetscObjectSetUp(PetscObject);
312: PETSC_EXTERN PetscErrorCode PetscObjectSetPrintedOptions(PetscObject);
313: PETSC_EXTERN PetscErrorCode PetscObjectInheritPrintedOptions(PetscObject, PetscObject);
314: PETSC_EXTERN PetscErrorCode PetscCommGetNewTag(MPI_Comm, PetscMPIInt *);
315: PETSC_EXTERN PetscErrorCode PetscObjectGetId(PetscObject, PetscObjectId *);
316: PETSC_EXTERN PetscErrorCode PetscObjectCompareId(PetscObject, PetscObjectId, PetscBool *);
318: /*MC
319: PetscObjectParameterSetDefault - sets a parameter default value in a `PetscObject` to a new default value.
320: If the current value matches the old default value, then the current value is also set to the new value.
322: No Fortran Support
324: Synopsis:
325: #include <petscsys.h>
326: PetscBool PetscObjectParameterSetDefault(PetscObject obj, char* NAME, PetscReal value);
328: Input Parameters:
329: + obj - the `PetscObject`
330: . NAME - the name of the parameter, unquoted
331: - value - the new value
333: Level: developer
335: Notes:
336: The defaults for an object are the values set when the object's type is set.
338: This should only be used in object constructors, such as, `SNESCreate_NGS()`.
340: This only works for parameters that are declared in the struct with `PetscObjectParameterDeclare()`
342: .seealso: `PetscObjectParameterDeclare()`, `PetscInitialize()`, `PetscFinalize()`, `PetscObject`, `SNESParametersInitialize()`
343: M*/
344: #define PetscObjectParameterSetDefault(obj, NAME, value) \
345: do { \
346: if ((obj)->NAME == (obj)->default_##NAME) (obj)->NAME = value; \
347: (obj)->default_##NAME = value; \
348: } while (0)
350: /*MC
351: PetscObjectParameterDeclare - declares a parameter in a `PetscObject` and a location to store its default
353: No Fortran Support
355: Synopsis:
356: #include <petscsys.h>
357: PetscObjectParameterDeclare(type, NAME)
359: Input Parameters:
360: + type - the type of the parameter, for example `PetscInt`
361: - NAME - the name of the parameter, unquoted
363: Level: developer.
365: .seealso: `PetscObjectParameterSetDefault()`, `PetscInitialize()`, `PetscFinalize()`, `PetscObject`, `SNESParametersInitialize()`
366: M*/
367: #define PetscObjectParameterDeclare(type, NAME) type NAME, default_##NAME
369: /*MC
370: PetscObjectParameterDeclarePtr - declares a pointer-valued parameter inside a `PetscObject` together with a slot for its default
372: No Fortran Support
374: Synopsis:
375: #include <petscsys.h>
376: PetscObjectParameterDeclarePtr(type, NAME)
378: Input Parameters:
379: + type - the pointee type of the parameter, for example `PetscReal`
380: - NAME - the name of the parameter, unquoted
382: Level: developer
384: Note:
385: Equivalent to `PetscObjectParameterDeclare()` but for pointer-valued parameters: declares `type *NAME` and `type *default_##NAME` so that `PetscObjectParameterSetDefault()` can record and propagate the default value.
387: .seealso: `PetscObjectParameterDeclare()`, `PetscObjectParameterSetDefault()`, `PetscInitialize()`, `PetscFinalize()`, `PetscObject`, `SNESParametersInitialize()`
388: M*/
389: #define PetscObjectParameterDeclarePtr(type, NAME) type *NAME, *default_##NAME
391: PETSC_EXTERN PetscCtxDestroyFn PetscCtxDestroyDefault;
392: PETSC_DEPRECATED_FUNCTION(3, 23, 0, "PetscCtxDestroyDefault()", ) static inline PetscErrorCode PetscContainerCtxDestroyDefault(PetscCtxRt a)
393: {
394: return PetscCtxDestroyDefault(a);
395: }
397: PETSC_EXTERN PetscErrorCode PetscMonitorCompare(PetscErrorCode (*)(void), void *, PetscCtxDestroyFn *, PetscErrorCode (*)(void), void *, PetscCtxDestroyFn *, PetscBool *);
399: /* generatefortranbindings.py requires the next line */
400: #include <petscviewertypes.h>
401: #include <petscoptionstypes.h>
403: PETSC_EXTERN PetscErrorCode PetscMallocTraceSet(PetscViewer, PetscBool, PetscLogDouble);
404: PETSC_EXTERN PetscErrorCode PetscMallocTraceGet(PetscBool *);
406: PETSC_EXTERN PetscErrorCode PetscObjectsListGetGlobalNumbering(MPI_Comm, PetscInt, PetscObject[], PetscInt *, PetscInt *);
408: PETSC_EXTERN PetscErrorCode PetscMemoryView(PetscViewer, const char[]);
409: PETSC_EXTERN PetscErrorCode PetscObjectPrintClassNamePrefixType(PetscObject, PetscViewer);
410: PETSC_EXTERN PetscErrorCode PetscObjectView(PetscObject, PetscViewer);
411: /*MC
412: PetscObjectQueryFunction - Retrieve a function pointer that was previously composed onto a `PetscObject` with `PetscObjectComposeFunction()`
414: Synopsis:
415: #include <petscsys.h>
416: PetscErrorCode PetscObjectQueryFunction(PetscObject obj, const char name[], void (**fptr)(void))
418: Logically Collective
420: Input Parameters:
421: + obj - the `PetscObject`
422: - name - the string under which the function was composed
424: Output Parameter:
425: . fptr - the address into which the function pointer is written; set to `NULL` if no function of this name is composed onto `obj`
427: Level: advanced
429: Note:
430: The macro casts `fptr` to the internal `PetscErrorCodeFn **` representation before calling `PetscObjectQueryFunction_Private()`
431: so that any function-pointer type can be supplied without an explicit cast.
433: .seealso: `PetscObjectComposeFunction()`, `PetscObjectHasFunction()`, `PetscObject`
434: M*/
435: #define PetscObjectQueryFunction(obj, name, fptr) PetscObjectQueryFunction_Private((obj), (name), (PetscErrorCodeFn **)(fptr))
436: PETSC_EXTERN PetscErrorCode PetscObjectHasFunction(PetscObject, const char[], PetscBool *);
437: PETSC_EXTERN PetscErrorCode PetscObjectQueryFunction_Private(PetscObject, const char[], PetscErrorCodeFn **);
438: PETSC_EXTERN PetscErrorCode PetscObjectSetOptionsPrefix(PetscObject, const char[]);
439: PETSC_EXTERN PetscErrorCode PetscObjectAppendOptionsPrefix(PetscObject, const char[]);
440: PETSC_EXTERN PetscErrorCode PetscObjectPrependOptionsPrefix(PetscObject, const char[]);
441: PETSC_EXTERN PetscErrorCode PetscObjectGetOptionsPrefix(PetscObject, const char *[]);
442: PETSC_EXTERN PetscErrorCode PetscObjectChangeTypeName(PetscObject, const char[]);
443: PETSC_EXTERN PetscErrorCode PetscObjectRegisterDestroy(PetscObject);
444: PETSC_EXTERN PetscErrorCode PetscObjectRegisterDestroyAll(void);
445: PETSC_EXTERN PetscErrorCode PetscObjectViewFromOptions(PetscObject, PetscObject, const char[]);
446: PETSC_EXTERN PetscErrorCode PetscObjectViewSynchronizedFromOptions(PetscObject, PetscObject, const char[]);
447: PETSC_EXTERN PetscErrorCode PetscObjectName(PetscObject);
448: PETSC_EXTERN PetscErrorCode PetscObjectTypeCompare(PetscObject, const char[], PetscBool *);
449: PETSC_EXTERN PetscErrorCode PetscObjectObjectTypeCompare(PetscObject, PetscObject, PetscBool *);
450: PETSC_EXTERN PetscErrorCode PetscObjectBaseTypeCompare(PetscObject, const char[], PetscBool *);
451: PETSC_EXTERN PetscErrorCode PetscObjectTypeCompareAny(PetscObject, PetscBool *, const char[], ...);
452: PETSC_EXTERN PetscErrorCode PetscObjectBaseTypeCompareAny(PetscObject, PetscBool *, const char[], ...);
453: PETSC_EXTERN PetscErrorCode PetscRegisterFinalize(PetscErrorCode (*)(void));
454: PETSC_EXTERN PetscErrorCode PetscRegisterFinalizeAll(void);
456: #if PetscDefined(HAVE_SAWS)
457: PETSC_EXTERN PetscErrorCode PetscSAWsBlock(void);
458: PETSC_EXTERN PetscErrorCode PetscObjectSAWsViewOff(PetscObject);
459: PETSC_EXTERN PetscErrorCode PetscObjectSAWsSetBlock(PetscObject, PetscBool);
460: PETSC_EXTERN PetscErrorCode PetscObjectSAWsBlock(PetscObject);
461: PETSC_EXTERN PetscErrorCode PetscObjectSAWsGrantAccess(PetscObject);
462: PETSC_EXTERN PetscErrorCode PetscObjectSAWsTakeAccess(PetscObject);
463: PETSC_EXTERN PetscErrorCode PetscStackViewSAWs(void);
464: PETSC_EXTERN PetscErrorCode PetscStackSAWsViewOff(void);
466: #else
467: #define PetscSAWsBlock() PETSC_SUCCESS
468: #define PetscObjectSAWsViewOff(obj) PETSC_SUCCESS
469: #define PetscObjectSAWsSetBlock(obj, flg) PETSC_SUCCESS
470: #define PetscObjectSAWsBlock(obj) PETSC_SUCCESS
471: #define PetscObjectSAWsGrantAccess(obj) PETSC_SUCCESS
472: #define PetscObjectSAWsTakeAccess(obj) PETSC_SUCCESS
473: #define PetscStackViewSAWs() PETSC_SUCCESS
474: #define PetscStackSAWsViewOff() PETSC_SUCCESS
476: #endif
478: PETSC_EXTERN PetscErrorCode PetscDLOpen(const char[], PetscDLMode, PetscDLHandle *);
479: PETSC_EXTERN PetscErrorCode PetscDLClose(PetscDLHandle *);
480: PETSC_EXTERN PetscErrorCode PetscDLSym(PetscDLHandle, const char[], void **);
481: PETSC_EXTERN PetscErrorCode PetscDLAddr(PetscVoidFn *, char *[]);
482: PETSC_EXTERN PetscErrorCode PetscDemangleSymbol(const char *, char *[]);
484: PETSC_EXTERN PetscErrorCode PetscMallocGetStack(void *, PetscStack **);
486: PETSC_EXTERN PetscErrorCode PetscObjectsDump(FILE *, PetscBool);
487: PETSC_EXTERN PetscErrorCode PetscObjectsView(PetscViewer);
488: PETSC_EXTERN PetscErrorCode PetscObjectsGetObject(const char *, PetscObject *, const char *[]);
489: PETSC_EXTERN PetscErrorCode PetscObjectListDestroy(PetscObjectList *);
490: PETSC_EXTERN PetscErrorCode PetscObjectListFind(PetscObjectList, const char[], PetscObject *);
491: PETSC_EXTERN PetscErrorCode PetscObjectListReverseFind(PetscObjectList, PetscObject, const char *[], PetscBool *);
492: PETSC_EXTERN PetscErrorCode PetscObjectListAdd(PetscObjectList *, const char[], PetscObject);
493: PETSC_EXTERN PetscErrorCode PetscObjectListRemoveReference(PetscObjectList *, const char[]);
494: PETSC_EXTERN PetscErrorCode PetscObjectListDuplicate(PetscObjectList, PetscObjectList *);
496: /*
497: Dynamic library lists. Lists of names of routines in objects or in dynamic
498: link libraries that will be loaded as needed.
499: */
501: /*MC
502: PetscFunctionListAdd - Add a function pointer to a `PetscFunctionList`, under a string name
504: Synopsis:
505: #include <petscsys.h>
506: PetscErrorCode PetscFunctionListAdd(PetscFunctionList *list, const char name[], void (*fptr)(void))
508: Not Collective
510: Input Parameters:
511: + list - the function list; if `*list` is `NULL`, a new list is created
512: . name - string under which to register the function
513: - fptr - the function pointer; if `NULL`, any previous registration under `name` is removed
515: Level: developer
517: Notes:
518: Users who wish to register new classes for use by a particular PETSc component (e.g., `SNES`) should generally call the registration routine for that particular component (e.g., `SNESRegister()`) instead of calling `PetscFunctionListAdd()` directly.
520: The macro casts `fptr` to the internal `PetscErrorCodeFn *` representation before calling `PetscFunctionListAdd_Private()` so that any error-code-returning function-pointer type may be supplied without an explicit cast.
522: .seealso: `PetscFunctionList`, `PetscFunctionListFind()`, `PetscFunctionListDestroy()`, `PetscFunctionListDuplicate()`, `PetscFunctionListView()`, `PetscObjectComposeFunction()`,
523: `SNESRegister()`, `KSPRegister()`, `PCRegister()`, `TSRegister()`
524: M*/
525: #define PetscFunctionListAdd(list, name, fptr) PetscFunctionListAdd_Private((list), (name), (PetscErrorCodeFn *)(fptr))
526: PETSC_EXTERN PetscErrorCode PetscFunctionListAdd_Private(PetscFunctionList *, const char[], PetscErrorCodeFn *);
527: PETSC_EXTERN PetscErrorCode PetscFunctionListDestroy(PetscFunctionList *);
528: PETSC_EXTERN PetscErrorCode PetscFunctionListClear(PetscFunctionList);
529: /*MC
530: PetscFunctionListFind - Look up a function pointer in a `PetscFunctionList` by its registered string name
532: Synopsis:
533: #include <petscsys.h>
534: PetscErrorCode PetscFunctionListFind(PetscFunctionList list, const char name[], void (**fptr)(void))
536: Not Collective; No Fortran Support
538: Input Parameters:
539: + list - the function list
540: - name - string under which the function was registered with `PetscFunctionListAdd()`
542: Output Parameter:
543: . fptr - the address into which the function pointer is written; set to `NULL` if no function of this name is registered
545: Level: developer
547: Note:
548: The macro casts `fptr` to the internal `PetscErrorCodeFn **` representation before calling `PetscFunctionListFind_Private()` so that any function-pointer type can be supplied without an explicit cast.
550: .seealso: `PetscFunctionList`, `PetscFunctionListAdd()`, `PetscFunctionListDestroy()`, `PetscObjectQueryFunction()`
551: M*/
552: #define PetscFunctionListFind(list, name, fptr) PetscFunctionListFind_Private((list), (name), (PetscErrorCodeFn **)(fptr))
553: PETSC_EXTERN PetscErrorCode PetscFunctionListFind_Private(PetscFunctionList, const char[], PetscErrorCodeFn **);
554: PETSC_EXTERN PetscErrorCode PetscFunctionListPrintTypes(MPI_Comm, FILE *, const char[], const char[], const char[], const char[], PetscFunctionList, const char[], const char[]);
555: PETSC_EXTERN PetscErrorCode PetscFunctionListDuplicate(PetscFunctionList, PetscFunctionList *);
556: PETSC_EXTERN PetscErrorCode PetscFunctionListView(PetscFunctionList, PetscViewer);
557: PETSC_EXTERN PetscErrorCode PetscFunctionListGet(PetscFunctionList, const char ***, int *);
558: PETSC_EXTERN PetscErrorCode PetscFunctionListPrintNonEmpty(PetscFunctionList);
559: PETSC_EXTERN PetscErrorCode PetscFunctionListPrintAll(void);
561: PETSC_EXTERN PetscDLLibrary PetscDLLibrariesLoaded;
562: PETSC_EXTERN PetscErrorCode PetscDLLibraryAppend(MPI_Comm, PetscDLLibrary *, const char[]);
563: PETSC_EXTERN PetscErrorCode PetscDLLibraryPrepend(MPI_Comm, PetscDLLibrary *, const char[]);
564: PETSC_EXTERN PetscErrorCode PetscDLLibrarySym(MPI_Comm, PetscDLLibrary *, const char[], const char[], void **);
565: PETSC_EXTERN PetscErrorCode PetscDLLibraryPrintPath(PetscDLLibrary);
566: PETSC_EXTERN PetscErrorCode PetscDLLibraryRetrieve(MPI_Comm, const char[], char *, size_t, PetscBool *);
567: PETSC_EXTERN PetscErrorCode PetscDLLibraryOpen(MPI_Comm, const char[], PetscDLLibrary *);
568: PETSC_EXTERN PetscErrorCode PetscDLLibraryClose(PetscDLLibrary);
570: /*
571: Useful utility routines
572: */
573: PETSC_EXTERN PetscErrorCode PetscSplitOwnership(MPI_Comm, PetscInt *, PetscInt *);
574: PETSC_EXTERN PetscErrorCode PetscSplitOwnershipBlock(MPI_Comm, PetscInt, PetscInt *, PetscInt *);
575: PETSC_EXTERN PetscErrorCode PetscSplitOwnershipEqual(MPI_Comm, PetscInt *, PetscInt *);
576: PETSC_EXTERN PetscErrorCode PetscSequentialPhaseBegin(MPI_Comm, PetscMPIInt);
577: PETSC_EXTERN PetscErrorCode PetscSequentialPhaseEnd(MPI_Comm, PetscMPIInt);
578: PETSC_EXTERN PetscErrorCode PetscBarrier(PetscObject);
579: PETSC_EXTERN PetscErrorCode PetscMPIDump(FILE *);
580: PETSC_EXTERN PetscErrorCode PetscGlobalMinMaxInt(MPI_Comm, const PetscInt[2], PetscInt[2]);
581: PETSC_EXTERN PetscErrorCode PetscGlobalMinMaxReal(MPI_Comm, const PetscReal[2], PetscReal[2]);
583: /*MC
584: PetscNot - negates a logical type value and returns result as a `PetscBool`
586: Level: beginner
588: Note:
589: This is useful in cases like
590: .vb
591: int *a;
592: PetscBool flag = PetscNot(a)
593: .ve
594: where !a would not return a `PetscBool` because we cannot provide a cast from int to `PetscBool` in C.
596: .seealso: `PetscBool`, `PETSC_TRUE`, `PETSC_FALSE`
597: M*/
598: #define PetscNot(a) ((a) ? PETSC_FALSE : PETSC_TRUE)
600: /*MC
601: PetscHelpPrintf - Prints help messages.
603: Synopsis:
604: #include <petscsys.h>
605: PetscErrorCode (*PetscHelpPrintf)(MPI_Comm comm, const char format[], ...);
607: Not Collective, only applies on MPI rank 0; No Fortran Support
609: Input Parameters:
610: + comm - the MPI communicator over which the help message is printed
611: . format - the usual printf() format string
612: - args - arguments to be printed
614: Level: developer
616: Notes:
617: You can change how help messages are printed by replacing the function pointer with a function that does not simply write to stdout.
619: To use, write your own function, for example,
620: .vb
621: PetscErrorCode mypetschelpprintf(MPI_Comm comm,const char format[],....)
622: {
623: PetscFunctionReturn(PETSC_SUCCESS);
624: }
625: .ve
626: then do the assignment
627: .vb
628: PetscHelpPrintf = mypetschelpprintf;
629: .ve
631: You can do the assignment before `PetscInitialize()`.
633: The default routine used is called `PetscHelpPrintfDefault()`.
635: .seealso: `PetscFPrintf()`, `PetscSynchronizedPrintf()`, `PetscErrorPrintf()`, `PetscHelpPrintfDefault()`
636: M*/
637: PETSC_EXTERN PetscErrorCode (*PetscHelpPrintf)(MPI_Comm, const char[], ...) PETSC_ATTRIBUTE_FORMAT(2, 3);
639: /*
640: Defines PETSc profiling.
641: */
642: #include <petsclog.h>
644: /*
645: Simple PETSc parallel IO for ASCII printing
646: */
647: PETSC_EXTERN PetscErrorCode PetscFixFilename(const char[], char[]);
648: PETSC_EXTERN PetscErrorCode PetscFOpen(MPI_Comm, const char[], const char[], FILE **);
649: PETSC_EXTERN PetscErrorCode PetscFClose(MPI_Comm, FILE *);
650: PETSC_EXTERN PetscErrorCode PetscFPrintf(MPI_Comm, FILE *, const char[], ...) PETSC_ATTRIBUTE_FORMAT(3, 4);
651: PETSC_EXTERN PetscErrorCode PetscFFlush(FILE *);
652: PETSC_EXTERN PetscErrorCode PetscPrintf(MPI_Comm, const char[], ...) PETSC_ATTRIBUTE_FORMAT(2, 3);
653: PETSC_EXTERN PetscErrorCode PetscSNPrintf(char *, size_t, const char[], ...) PETSC_ATTRIBUTE_FORMAT(3, 4);
654: PETSC_EXTERN PetscErrorCode PetscSNPrintfCount(char *, size_t, const char[], size_t *, ...) PETSC_ATTRIBUTE_FORMAT(3, 5);
655: PETSC_EXTERN PetscErrorCode PetscFormatRealArray(char[], size_t, const char *, PetscInt, const PetscReal[]);
657: PETSC_EXTERN PetscErrorCode PetscErrorPrintfDefault(const char[], ...) PETSC_ATTRIBUTE_FORMAT(1, 2);
658: PETSC_EXTERN PetscErrorCode PetscErrorPrintfNone(const char[], ...) PETSC_ATTRIBUTE_FORMAT(1, 2);
659: PETSC_EXTERN PetscErrorCode PetscHelpPrintfDefault(MPI_Comm, const char[], ...) PETSC_ATTRIBUTE_FORMAT(2, 3);
661: PETSC_EXTERN PetscErrorCode PetscFormatConvertGetSize(const char *, size_t *);
662: PETSC_EXTERN PetscErrorCode PetscFormatConvert(const char *, char *);
664: PETSC_EXTERN PetscErrorCode PetscPOpen(MPI_Comm, const char[], const char[], const char[], FILE **);
665: PETSC_EXTERN PetscErrorCode PetscPClose(MPI_Comm, FILE *);
666: PETSC_EXTERN PetscErrorCode PetscPOpenSetMachine(const char[]);
668: PETSC_EXTERN PetscErrorCode PetscSynchronizedPrintf(MPI_Comm, const char[], ...) PETSC_ATTRIBUTE_FORMAT(2, 3);
669: PETSC_EXTERN PetscErrorCode PetscSynchronizedFPrintf(MPI_Comm, FILE *, const char[], ...) PETSC_ATTRIBUTE_FORMAT(3, 4);
670: PETSC_EXTERN PetscErrorCode PetscSynchronizedFlush(MPI_Comm, FILE *);
671: PETSC_EXTERN PetscErrorCode PetscSynchronizedFGets(MPI_Comm, FILE *, size_t, char[]);
672: PETSC_EXTERN PetscErrorCode PetscStartMatlab(MPI_Comm, const char[], const char[], FILE **);
673: PETSC_EXTERN PetscErrorCode PetscGetPetscDir(const char *[]);
675: PETSC_EXTERN PetscClassId PETSC_CONTAINER_CLASSID;
676: PETSC_EXTERN PetscErrorCode PetscContainerGetPointer(PetscContainer, void *);
677: PETSC_EXTERN PetscErrorCode PetscContainerSetPointer(PetscContainer, void *);
678: PETSC_EXTERN PetscErrorCode PetscContainerDestroy(PetscContainer *);
679: PETSC_EXTERN PetscErrorCode PetscContainerCreate(MPI_Comm, PetscContainer *);
680: PETSC_EXTERN PetscErrorCode PetscContainerSetCtxDestroy(PetscContainer, PetscCtxDestroyFn *);
681: PETSC_EXTERN PETSC_DEPRECATED_FUNCTION(3, 23, 0, "PetscContainerSetCtxDestroy()", ) PetscErrorCode PetscContainerSetUserDestroy(PetscContainer, PetscErrorCode (*)(void *));
682: PETSC_EXTERN PetscErrorCode PetscObjectContainerCompose(PetscObject, const char *name, void *, PetscCtxDestroyFn *);
683: PETSC_EXTERN PetscErrorCode PetscObjectContainerQuery(PetscObject, const char *, PetscCtxRt);
685: /*
686: For use in debuggers
687: */
688: PETSC_EXTERN PetscMPIInt PetscGlobalRank;
689: PETSC_EXTERN PetscMPIInt PetscGlobalSize;
690: PETSC_EXTERN PetscErrorCode PetscIntViewNumColumns(PetscInt, PetscInt, const PetscInt[], PetscViewer);
691: PETSC_EXTERN PetscErrorCode PetscRealViewNumColumns(PetscInt, PetscInt, const PetscReal[], PetscViewer);
692: PETSC_EXTERN PetscErrorCode PetscScalarViewNumColumns(PetscInt, PetscInt, const PetscScalar[], PetscViewer);
693: PETSC_EXTERN PetscErrorCode PetscIntView(PetscInt, const PetscInt[], PetscViewer);
694: PETSC_EXTERN PetscErrorCode PetscIntCSRView(PetscInt, const PetscInt[], const PetscInt[], PetscViewer);
695: PETSC_EXTERN PetscErrorCode PetscRealView(PetscInt, const PetscReal[], PetscViewer);
696: PETSC_EXTERN PetscErrorCode PetscScalarView(PetscInt, const PetscScalar[], PetscViewer);
698: /*
699: Basic memory and string operations. These are usually simple wrappers
700: around the basic Unix system calls, but a few of them have additional
701: functionality and/or error checking.
702: */
703: #include <petscstring.h>
705: #include <stddef.h>
706: #include <stdlib.h>
708: #if PetscDefined(CLANG_STATIC_ANALYZER)
709: #define PetscPrefetchBlock(a, b, c, d)
710: #else
711: /*MC
712: PetscPrefetchBlock - Prefetches a block of memory
714: Synopsis:
715: #include <petscsys.h>
716: void PetscPrefetchBlock(const anytype *a, size_t n, int rw, int t)
718: Not Collective
720: Input Parameters:
721: + a - pointer to first element to fetch (any type but usually `PetscInt` or `PetscScalar`)
722: . n - number of elements to fetch
723: . rw - 1 if the memory will be written to, otherwise 0 (ignored by many processors)
724: - t - temporal locality (PETSC_PREFETCH_HINT_{NTA,T0,T1,T2}), see note
726: Level: developer
728: Notes:
729: The last two arguments (`rw` and `t`) must be compile-time constants.
731: Adopting Intel's x86/x86-64 conventions, there are four levels of temporal locality. Not all architectures offer
732: equivalent locality hints, but the following macros are always defined to their closest analogue.
733: + `PETSC_PREFETCH_HINT_NTA` - Non-temporal. Prefetches directly to L1, evicts to memory (skips higher level cache unless it was already there when prefetched).
734: . `PETSC_PREFETCH_HINT_T0` - Fetch to all levels of cache and evict to the closest level. Use this when the memory will be reused regularly despite necessary eviction from L1.
735: . `PETSC_PREFETCH_HINT_T1` - Fetch to level 2 and higher (not L1). On many systems, `PETSC_PREFETCH_HINT_T0` and `PETSC_PREFETCH_HINT_T1` are equivalent.
736: - `PETSC_PREFETCH_HINT_T2` - Fetch to high-level cache only.
738: This function does nothing on architectures that do not support prefetch and never errors (even if passed an invalid
739: address).
741: .seealso: `PETSC_PREFETCH_HINT_NTA`, `PETSC_PREFETCH_HINT_T0`, `PETSC_PREFETCH_HINT_T1`, `PETSC_PREFETCH_HINT_T2`
742: M*/
743: #define PetscPrefetchBlock(a, n, rw, t) \
744: do { \
745: const char *_p = (const char *)(a), *_end = (const char *)((a) + (n)); \
746: for (; _p < _end; _p += PETSC_LEVEL1_DCACHE_LINESIZE) PETSC_Prefetch(_p, (rw), (t)); \
747: } while (0)
748: #endif
749: /*
750: Determine if some of the kernel computation routines use
751: Fortran (rather than C) for the numerical calculations. On some machines
752: and compilers (like complex numbers) the Fortran version of the routines
753: is faster than the C/C++ versions. The flag --with-fortran-kernels
754: should be used with ./configure to turn these on.
755: */
756: #if PetscDefined(USE_FORTRAN_KERNELS)
758: #if !PetscDefined(USE_FORTRAN_KERNEL_MULTCRL)
759: #define PETSC_USE_FORTRAN_KERNEL_MULTCRL
760: #endif
762: #if !PetscDefined(USE_FORTRAN_KERNEL_MULTAIJ)
763: #define PETSC_USE_FORTRAN_KERNEL_MULTAIJ
764: #endif
766: #if !PetscDefined(USE_FORTRAN_KERNEL_MULTTRANSPOSEAIJ)
767: #define PETSC_USE_FORTRAN_KERNEL_MULTTRANSPOSEAIJ
768: #endif
770: #if !PetscDefined(USE_FORTRAN_KERNEL_MAXPY)
771: #define PETSC_USE_FORTRAN_KERNEL_MAXPY
772: #endif
774: #if !PetscDefined(USE_FORTRAN_KERNEL_SOLVEAIJ)
775: #define PETSC_USE_FORTRAN_KERNEL_SOLVEAIJ
776: #endif
778: #if !PetscDefined(USE_FORTRAN_KERNEL_SOLVEBAIJ)
779: #define PETSC_USE_FORTRAN_KERNEL_SOLVEBAIJ
780: #endif
782: #if !PetscDefined(USE_FORTRAN_KERNEL_MULTADDAIJ)
783: #define PETSC_USE_FORTRAN_KERNEL_MULTADDAIJ
784: #endif
786: #if !PetscDefined(USE_FORTRAN_KERNEL_MDOT)
787: #define PETSC_USE_FORTRAN_KERNEL_MDOT
788: #endif
790: #if !PetscDefined(USE_FORTRAN_KERNEL_XTIMESY)
791: #define PETSC_USE_FORTRAN_KERNEL_XTIMESY
792: #endif
794: #if !PetscDefined(USE_FORTRAN_KERNEL_AYPX)
795: #define PETSC_USE_FORTRAN_KERNEL_AYPX
796: #endif
798: #if !PetscDefined(USE_FORTRAN_KERNEL_WAXPY)
799: #define PETSC_USE_FORTRAN_KERNEL_WAXPY
800: #endif
802: #endif
804: /*
805: Macros for indicating code that should be compiled with a C interface,
806: rather than a C++ interface. Any routines that are dynamically loaded
807: (such as the PCCreate_XXX() routines) must be wrapped so that the name
808: mangler does not change the functions symbol name. This just hides the
809: ugly extern "C" {} wrappers.
810: */
811: #if defined(__cplusplus)
812: #define EXTERN_C_BEGIN extern "C" {
813: #define EXTERN_C_END }
814: #else
815: #define EXTERN_C_BEGIN
816: #define EXTERN_C_END
817: #endif
819: /*MC
820: MPI_Comm - the basic object used by MPI to determine which processes are involved in a
821: communication
823: Level: beginner
825: Note:
826: This manual page is a place-holder because MPICH does not have a manual page for `MPI_Comm`
828: .seealso: `PETSC_COMM_WORLD`, `PETSC_COMM_SELF`
829: M*/
831: #if PetscDefined(HAVE_MPIIO)
832: PETSC_EXTERN PetscErrorCode MPIU_File_write_all(MPI_File, void *, PetscMPIInt, MPI_Datatype, MPI_Status *) PETSC_ATTRIBUTE_MPI_POINTER_WITH_TYPE(2, 4);
833: PETSC_EXTERN PetscErrorCode MPIU_File_read_all(MPI_File, void *, PetscMPIInt, MPI_Datatype, MPI_Status *) PETSC_ATTRIBUTE_MPI_POINTER_WITH_TYPE(2, 4);
834: PETSC_EXTERN PetscErrorCode MPIU_File_write_at(MPI_File, MPI_Offset, void *, PetscMPIInt, MPI_Datatype, MPI_Status *) PETSC_ATTRIBUTE_MPI_POINTER_WITH_TYPE(3, 5);
835: PETSC_EXTERN PetscErrorCode MPIU_File_read_at(MPI_File, MPI_Offset, void *, PetscMPIInt, MPI_Datatype, MPI_Status *) PETSC_ATTRIBUTE_MPI_POINTER_WITH_TYPE(3, 5);
836: PETSC_EXTERN PetscErrorCode MPIU_File_write_at_all(MPI_File, MPI_Offset, void *, PetscMPIInt, MPI_Datatype, MPI_Status *) PETSC_ATTRIBUTE_MPI_POINTER_WITH_TYPE(3, 5);
837: PETSC_EXTERN PetscErrorCode MPIU_File_read_at_all(MPI_File, MPI_Offset, void *, PetscMPIInt, MPI_Datatype, MPI_Status *) PETSC_ATTRIBUTE_MPI_POINTER_WITH_TYPE(3, 5);
838: #endif
840: /*MC
841: MPIU_Count - PETSc datatype used to hold message-size counts for large MPI messages
843: Level: intermediate
845: Note:
846: When the underlying MPI implementation supports `MPI_Count` (which is wide enough to express counts that do not fit in `int`), `MPIU_Count` is a typedef for `MPI_Count`; otherwise it is defined as `PetscInt64`. Use `MPIU_Count` together with the PETSc MPI wrappers such as `MPIU_Send()`, `MPIU_Recv()`, and `MPIU_Allreduce()` so that codes can be written portably regardless of the available MPI version.
848: .seealso: `MPI_Count`, `MPIU_COUNT`, `MPIU_Send()`, `MPIU_Recv()`, `MPIU_Reduce()`, `PetscInt64`
849: M*/
850: #if PetscDefined(HAVE_MPI_COUNT)
851: typedef MPI_Count MPIU_Count;
852: #else
853: typedef PetscInt64 MPIU_Count;
854: #endif
856: /*@
857: PetscIntCast - casts a `MPI_Count`, `PetscInt64`, `PetscCount`, or `size_t` to a `PetscInt` (which may be 32-bits in size), generates an
858: error if the `PetscInt` is not large enough to hold the number.
860: Not Collective; No Fortran Support
862: Input Parameter:
863: . a - the `PetscInt64` value
865: Output Parameter:
866: . b - the resulting `PetscInt` value, or `NULL` if the result is not needed
868: Level: advanced
870: Note:
871: If integers needed for the applications are too large to fit in 32-bit ints you can ./configure using `--with-64-bit-indices` to make `PetscInt` use 64-bit integers
873: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscMPIIntCast()`, `PetscBLASIntCast()`, `PetscCIntCast()`, `PetscIntMultError()`, `PetscIntSumError()`
874: @*/
875: static inline PetscErrorCode PetscIntCast(MPIU_Count a, PetscInt *b)
876: {
877: PetscFunctionBegin;
878: if (b) *b = 0; /* to prevent compilers erroneously suggesting uninitialized variable */
879: PetscCheck(sizeof(MPIU_Count) <= sizeof(PetscInt) || (a <= (MPIU_Count)PETSC_INT_MAX && a >= (MPIU_Count)PETSC_INT_MIN), PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "%" PetscInt64_FMT " is too big for PetscInt, you may need to ./configure using --with-64-bit-indices", (PetscInt64)a);
880: if (b) *b = (PetscInt)a;
881: PetscFunctionReturn(PETSC_SUCCESS);
882: }
884: /*@
885: PetscBLASIntCast - casts a `MPI_Count`, `PetscInt`, `PetscCount` or `PetscInt64` to a `PetscBLASInt` (which may be 32-bits in size), generates an
886: error if the `PetscBLASInt` is not large enough to hold the number.
888: Not Collective; No Fortran Support
890: Input Parameter:
891: . a - the `PetscInt` value
893: Output Parameter:
894: . b - the resulting `PetscBLASInt` value, or `NULL` if the result is not needed
896: Level: advanced
898: Note:
899: Errors if the integer is negative since PETSc calls to BLAS/LAPACK never need to cast negative integer inputs
901: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscMPIIntCast()`, `PetscCIntCast()`, `PetscIntCast()`
902: @*/
903: static inline PetscErrorCode PetscBLASIntCast(MPIU_Count a, PetscBLASInt *b)
904: {
905: PetscFunctionBegin;
906: if (b) *b = 0; /* to prevent compilers erroneously suggesting uninitialized variable */
907: PetscCheck(sizeof(MPIU_Count) <= sizeof(PetscBLASInt) || a <= (MPIU_Count)PETSC_BLAS_INT_MAX, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "%" PetscInt64_FMT " is too big for BLAS/LAPACK, which is restricted to 32-bit integers. Either you have an invalidly large integer error in your code or you must ./configure PETSc with --with-64-bit-blas-indices for the case you are running", (PetscInt64)a);
908: PetscCheck(a >= 0, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Passing negative integer to BLAS/LAPACK routine");
909: if (b) *b = (PetscBLASInt)a;
910: PetscFunctionReturn(PETSC_SUCCESS);
911: }
913: /*@
914: PetscCuBLASIntCast - like `PetscBLASIntCast()`, but for `PetscCuBLASInt`.
916: Not Collective; No Fortran Support
918: Input Parameter:
919: . a - the `PetscInt` value
921: Output Parameter:
922: . b - the resulting `PetscCuBLASInt` value, or `NULL` if the result is not needed
924: Level: advanced
926: Note:
927: Errors if the integer is negative since PETSc calls to cuBLAS and friends never need to cast negative integer inputs
929: .seealso: `PetscCuBLASInt`, `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscBLASIntCast()`, `PetscMPIIntCast()`, `PetscCIntCast()`, `PetscIntCast()`
930: @*/
931: static inline PetscErrorCode PetscCuBLASIntCast(MPIU_Count a, PetscCuBLASInt *b)
932: {
933: PetscFunctionBegin;
934: if (b) *b = 0; /* to prevent compilers erroneously suggesting uninitialized variable */
935: PetscCheck(sizeof(MPIU_Count) <= sizeof(PetscCuBLASInt) || a <= (MPIU_Count)PETSC_CUBLAS_INT_MAX, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "%" PetscInt64_FMT " is too big for cuBLAS, which is restricted to 32-bit integers.", (PetscInt64)a);
936: PetscCheck(a >= 0, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Passing negative integer %" PetscInt64_FMT "to cuBLAS routine", (PetscInt64)a);
937: if (b) *b = (PetscCuBLASInt)a;
938: PetscFunctionReturn(PETSC_SUCCESS);
939: }
941: /*@
942: PetscHipBLASIntCast - like `PetscBLASIntCast()`, but for `PetscHipBLASInt`.
944: Not Collective; No Fortran Support
946: Input Parameter:
947: . a - the `PetscInt` value
949: Output Parameter:
950: . b - the resulting `PetscHipBLASInt` value, or `NULL` if the result is not needed
952: Level: advanced
954: Note:
955: Errors if the integer is negative since PETSc calls to hipBLAS and friends never need to cast negative integer inputs
957: .seealso: `PetscHipBLASInt`, `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscBLASIntCast()`, `PetscMPIIntCast()`, `PetscCIntCast()`, `PetscIntCast()`
958: @*/
959: static inline PetscErrorCode PetscHipBLASIntCast(MPIU_Count a, PetscHipBLASInt *b)
960: {
961: PetscFunctionBegin;
962: if (b) *b = 0; /* to prevent compilers erroneously suggesting uninitialized variable */
963: PetscCheck(sizeof(MPIU_Count) <= sizeof(PetscHipBLASInt) || a <= (MPIU_Count)PETSC_HIPBLAS_INT_MAX, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "%" PetscInt64_FMT " is too big for hipBLAS, which is restricted to 32-bit integers.", (PetscInt64)a);
964: PetscCheck(a >= 0, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "Passing negative integer %" PetscInt64_FMT "to hipBLAS routine", (PetscInt64)a);
965: if (b) *b = (PetscHipBLASInt)a;
966: PetscFunctionReturn(PETSC_SUCCESS);
967: }
969: /*@
970: PetscMPIIntCast - casts a `MPI_Count`, `PetscInt`, `PetscCount`, or `PetscInt64` to a `PetscMPIInt` (which is always 32-bits in size), generates an
971: error if the `PetscMPIInt` is not large enough to hold the number.
973: Not Collective; No Fortran Support
975: Input Parameter:
976: . a - the `PetscInt` value
978: Output Parameter:
979: . b - the resulting `PetscMPIInt` value, or `NULL` if the result is not needed
981: Level: advanced
983: .seealso: [](stylePetscCount), `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscBLASIntCast()`, `PetscIntCast()`
984: @*/
985: static inline PetscErrorCode PetscMPIIntCast(MPIU_Count a, PetscMPIInt *b)
986: {
987: PetscFunctionBegin;
988: if (b) *b = 0; /* to prevent compilers erroneously suggesting uninitialized variable */
989: PetscCheck(a <= (MPIU_Count)PETSC_MPI_INT_MAX && a >= (MPIU_Count)PETSC_MPI_INT_MIN, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "%" PetscInt64_FMT " is too big for MPI buffer length. Maximum supported value is %d", (PetscInt64)a, PETSC_MPI_INT_MAX);
990: if (b) *b = (PetscMPIInt)a;
991: PetscFunctionReturn(PETSC_SUCCESS);
992: }
994: /*@
995: PetscCIntCast - casts a `MPI_Count`, `PetscInt`, `PetscCount`, or `PetscInt64` to a `int`, generates an error if the `int` is not large enough to hold the number.
997: Not Collective; No Fortran Support
999: Input Parameter:
1000: . a - the `PetscInt` value
1002: Output Parameter:
1003: . b - the resulting `int` value, or `NULL` if the result is not needed
1005: Level: advanced
1007: .seealso: [](stylePetscCount), `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscMPIIntCast()`, `PetscBLASIntCast()`, `PetscIntCast()`
1008: @*/
1009: static inline PetscErrorCode PetscCIntCast(MPIU_Count a, int *b)
1010: {
1011: PetscFunctionBegin;
1012: if (b) *b = 0; /* to prevent compilers erroneously suggesting uninitialized variable */
1013: PetscCheck(a <= INT_MAX && a >= INT_MIN, PETSC_COMM_SELF, PETSC_ERR_ARG_OUTOFRANGE, "%" PetscInt64_FMT " is too big to be casted to an int. Maximum supported value is %d", (PetscInt64)a, INT_MAX);
1014: if (b) *b = (int)a;
1015: PetscFunctionReturn(PETSC_SUCCESS);
1016: }
1018: /*MC
1019: PetscInt64Mult - Computes the product of two variables after casting them to `PetscInt64`.
1021: Not Collective; No Fortran Support
1023: Input Parameters:
1024: + a - the first variable
1025: - b - the second variable
1027: Level: advanced
1029: .seealso: [](stylePetscCount), `PetscIntMultError()`, `PetscIntMultTruncate()`
1030: M*/
1031: #if PetscDefined(USE_64BIT_INDICES)
1032: #define PetscInt64Mult(a, b) ((a) * (b))
1033: #else
1034: #define PetscInt64Mult(a, b) (((PetscInt64)(a)) * ((PetscInt64)(b)))
1035: #endif
1037: /*@
1038: PetscRealIntMultTruncate - Computes the product of a positive `PetscReal` and a positive
1039: `PetscInt` and truncates the value to slightly less than the maximal possible value.
1041: Not Collective; No Fortran Support
1043: Input Parameters:
1044: + a - The `PetscReal` value
1045: - b - The `PetscInt` value
1047: Level: advanced
1049: Notes:
1050: Returns the result as a `PetscInt` value.
1052: Use `PetscInt64Mult()` to compute the product of two `PetscInt` as a `PetscInt64`.
1054: Use `PetscIntMultTruncate()` to compute the product of two positive `PetscInt` and truncate
1055: to fit a `PetscInt`.
1057: Use `PetscIntMultError()` to compute the product of two `PetscInt` if you wish to generate an
1058: error if the result will not fit in a `PetscInt`.
1060: Developer Notes:
1061: We currently assume that `PetscInt` addition can never overflow, this is obviously wrong but
1062: requires many more checks.
1064: This is used where we compute approximate sizes for workspace and need to insure the
1065: workspace is index-able.
1067: .seealso: `PetscReal`, `PetscInt`, `PetscInt64Mult()`, `PetscIntMultError()`, `PetscIntSumError()`
1068: @*/
1069: static inline PetscInt PetscRealIntMultTruncate(PetscReal a, PetscInt b)
1070: {
1071: PetscInt64 r = (PetscInt64)(a * (PetscReal)b);
1072: if (r > PETSC_INT_MAX - 100) r = PETSC_INT_MAX - 100;
1073: #if PetscDefined(USE_64BIT_INDICES)
1074: return r;
1075: #else
1076: return (PetscInt)r;
1077: #endif
1078: }
1080: /*@
1081: PetscIntMultTruncate - Computes the product of two positive `PetscInt` and truncates the value to slightly less than the maximal possible value
1083: Not Collective; No Fortran Support
1085: Input Parameters:
1086: + a - the `PetscInt` value
1087: - b - the second value
1089: Returns:
1090: The result as a `PetscInt` value
1092: Level: advanced
1094: Notes:
1095: Use `PetscInt64Mult()` to compute the product of two `PetscInt` as a `PetscInt64`
1097: Use `PetscRealIntMultTruncate()` to compute the product of a `PetscReal` and a `PetscInt` and truncate to fit a `PetscInt`
1099: Use `PetscIntMultError()` to compute the product of two `PetscInt` if you wish to generate an error if the result will not fit in a `PetscInt`
1101: Developer Notes:
1102: We currently assume that `PetscInt` addition can never overflow, this is obviously wrong but requires many more checks.
1104: This is used where we compute approximate sizes for workspace and need to insure the workspace is index-able.
1106: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscBLASIntCast()`, `PetscInt64Mult()`, `PetscIntMultError()`, `PetscIntSumError()`,
1107: `PetscIntSumTruncate()`
1108: @*/
1109: static inline PetscInt PetscIntMultTruncate(PetscInt a, PetscInt b)
1110: {
1111: PetscInt64 r = PetscInt64Mult(a, b);
1112: if (r > PETSC_INT_MAX - 100) r = PETSC_INT_MAX - 100;
1113: #if PetscDefined(USE_64BIT_INDICES)
1114: return r;
1115: #else
1116: return (PetscInt)r;
1117: #endif
1118: }
1120: /*@
1121: PetscIntSumTruncate - Computes the sum of two positive `PetscInt` and truncates the value to slightly less than the maximal possible value
1123: Not Collective; No Fortran Support
1125: Input Parameters:
1126: + a - the `PetscInt` value
1127: - b - the second value
1129: Returns:
1130: The result as a `PetscInt` value
1132: Level: advanced
1134: Notes:
1135: Use `PetscInt64Mult()` to compute the product of two `PetscInt` as a `PetscInt64`
1137: Use `PetscRealIntMultTruncate()` to compute the product of a `PetscReal` and a `PetscInt` and truncate to fit a `PetscInt`
1139: Use `PetscIntMultError()` to compute the product of two `PetscInt` if you wish to generate an error if the result will not fit in a `PetscInt`
1141: Developer Note:
1142: This is used where we compute approximate sizes for workspace and need to insure the workspace is index-able.
1144: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscBLASIntCast()`, `PetscInt64Mult()`, `PetscIntMultError()`
1145: @*/
1146: static inline PetscInt PetscIntSumTruncate(PetscInt a, PetscInt b)
1147: {
1148: PetscInt64 r = a;
1150: r += b;
1151: if (r > PETSC_INT_MAX - 100) r = PETSC_INT_MAX - 100;
1152: #if PetscDefined(USE_64BIT_INDICES)
1153: return r;
1154: #else
1155: return (PetscInt)r;
1156: #endif
1157: }
1159: /*@
1160: PetscIntMultError - Computes the product of two positive `PetscInt` and generates an error with overflow.
1162: Not Collective; No Fortran Support
1164: Input Parameters:
1165: + a - the `PetscInt` value
1166: - b - the second value
1168: Output Parameter:
1169: . result - the result as a `PetscInt` value, or `NULL` if you do not want the result, you just want to check if it overflows
1171: Level: advanced
1173: Notes:
1174: Use `PetscInt64Mult()` to compute the product of two `PetscInt` and store in a `PetscInt64`
1176: Use `PetscIntMultTruncate()` to compute the product of two `PetscInt` and truncate it to fit in a `PetscInt`
1178: Developer Note:
1179: In most places in the source code we currently assume that `PetscInt` addition does not overflow, this is obviously wrong but requires many more checks.
1180: `PetscIntSumError()` can be used to check for this situation.
1182: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscBLASIntCast()`, `PetscInt64Mult()`, `PetscIntSumError()`
1183: @*/
1184: static inline PetscErrorCode PetscIntMultError(PetscInt a, PetscInt b, PetscInt *result)
1185: {
1186: PetscInt64 r = PetscInt64Mult(a, b);
1188: PetscFunctionBegin;
1189: #if PetscDefined(USE_64BIT_INDICES)
1190: if (result) *result = r;
1191: #else
1192: if (result) *result = (PetscInt)r;
1193: #endif
1194: if (!PetscDefined(USE_64BIT_INDICES)) {
1195: PetscCheck(r <= PETSC_INT_MAX, PETSC_COMM_SELF, PETSC_ERR_SUP, "Product of two integers %" PetscInt_FMT " %" PetscInt_FMT " overflow, either you have an invalidly large integer error in your code or you must ./configure PETSc with --with-64-bit-indices for the case you are running", a, b);
1196: }
1197: PetscFunctionReturn(PETSC_SUCCESS);
1198: }
1200: /*@
1201: PetscIntSumError - Computes the sum of two positive `PetscInt` and generates an error with overflow.
1203: Not Collective; No Fortran Support
1205: Input Parameters:
1206: + a - the `PetscInt` value
1207: - b - the second value
1209: Output Parameter:
1210: . c - the result as a `PetscInt` value, or `NULL` if you do not want the result, you just want to check if it overflows
1212: Level: advanced
1214: Notes:
1215: Use `PetscInt64Mult()` to compute the product of two 32-bit `PetscInt` and store in a `PetscInt64`
1217: Use `PetscIntMultTruncate()` to compute the product of two `PetscInt` and truncate it to fit in a `PetscInt`
1219: .seealso: `PetscBLASInt`, `PetscMPIInt`, `PetscInt`, `PetscBLASIntCast()`, `PetscInt64Mult()`, `PetscIntMultError()`
1220: @*/
1221: static inline PetscErrorCode PetscIntSumError(PetscInt a, PetscInt b, PetscInt *result)
1222: {
1223: PetscInt64 r = a;
1225: PetscFunctionBegin;
1226: r += b;
1227: #if PetscDefined(USE_64BIT_INDICES)
1228: if (result) *result = r;
1229: #else
1230: if (result) *result = (PetscInt)r;
1231: #endif
1232: if (!PetscDefined(USE_64BIT_INDICES)) {
1233: PetscCheck(r <= PETSC_INT_MAX, PETSC_COMM_SELF, PETSC_ERR_SUP, "Sum of two integers %" PetscInt_FMT " %" PetscInt_FMT " overflow, either you have an invalidly large integer error in your code or you must ./configure PETSc with --with-64-bit-indices for the case you are running", a, b);
1234: }
1235: PetscFunctionReturn(PETSC_SUCCESS);
1236: }
1238: /*
1239: The IBM include files define hz, here we hide it so that it may be used as a regular user variable.
1240: */
1241: #if defined(hz)
1242: #undef hz
1243: #endif
1245: #if PetscDefined(HAVE_SYS_TYPES_H)
1246: #include <sys/types.h>
1247: #endif
1249: /*MC
1251: PETSC_VERSION - This manual page provides information about how PETSc documents and uses its version information. This information is available to both C/C++
1252: and Fortran compilers when `petscsys.h` is included.
1254: The current PETSc version and the API for accessing it are defined in <A HREF="../include/petscversion.h.html">include/petscversion.html</A>
1256: The complete version number is given as the triple PETSC_VERSION_MAJOR.PETSC_VERSION_MINOR.PETSC_VERSION_SUBMINOR (in short hand x.y.z)
1258: A change in the minor version number (y) indicates possible/likely changes in the PETSc API. Note this is different than with the semantic versioning convention
1259: where only a change in the major version number (x) indicates a change in the API.
1261: A subminor greater than zero indicates a patch release. Version x.y.z maintains source and binary compatibility with version x.y.w for all z and w
1263: Use the macros PETSC_VERSION_EQ(x,y,z), PETSC_VERSION_LT(x,y,z), PETSC_VERSION_LE(x,y,z), PETSC_VERSION_GT(x,y,z),
1264: PETSC_VERSION_GE(x,y,z) to determine if the current version is equal to, less than, less than or equal to, greater than or greater than or equal to a given
1265: version number (x.y.z).
1267: `PETSC_RELEASE_DATE` is the date the x.y version was released (i.e. the version before any patch releases)
1269: `PETSC_VERSION_DATE` is the date the x.y.z version was released
1271: `PETSC_VERSION_GIT` is the last git commit to the repository given in the form vx.y.z-wwwww
1273: `PETSC_VERSION_DATE_GIT` is the date of the last git commit to the repository
1275: `PETSC_VERSION_()` is deprecated and will eventually be removed.
1277: Level: intermediate
1278: M*/
1280: PETSC_EXTERN PetscErrorCode PetscGetArchType(char[], size_t);
1281: PETSC_EXTERN PetscErrorCode PetscGetHostName(char[], size_t);
1282: PETSC_EXTERN PetscErrorCode PetscGetUserName(char[], size_t);
1283: PETSC_EXTERN PetscErrorCode PetscGetProgramName(char[], size_t);
1284: PETSC_EXTERN PetscErrorCode PetscSetProgramName(const char[]);
1285: PETSC_EXTERN PetscErrorCode PetscGetDate(char[], size_t);
1286: PETSC_EXTERN PetscErrorCode PetscGetVersion(char[], size_t);
1287: PETSC_EXTERN PetscErrorCode PetscGetVersionNumber(PetscInt *, PetscInt *, PetscInt *, PetscInt *);
1288: PETSC_EXTERN PetscErrorCode PetscGetConfiguration(const char *[]);
1290: PETSC_EXTERN PetscErrorCode PetscSortedInt(PetscCount, const PetscInt[], PetscBool *);
1291: PETSC_EXTERN PetscErrorCode PetscSortedInt64(PetscCount, const PetscInt64[], PetscBool *);
1292: PETSC_EXTERN PetscErrorCode PetscSortedMPIInt(PetscCount, const PetscMPIInt[], PetscBool *);
1293: PETSC_EXTERN PetscErrorCode PetscSortedReal(PetscCount, const PetscReal[], PetscBool *);
1294: PETSC_EXTERN PetscErrorCode PetscSortInt(PetscCount, PetscInt[]);
1295: PETSC_EXTERN PetscErrorCode PetscSortInt64(PetscCount, PetscInt64[]);
1296: PETSC_EXTERN PetscErrorCode PetscSortCount(PetscCount, PetscCount[]);
1297: PETSC_EXTERN PetscErrorCode PetscSortReverseInt(PetscCount, PetscInt[]);
1298: PETSC_EXTERN PetscErrorCode PetscSortedRemoveDupsInt(PetscInt *, PetscInt[]);
1299: PETSC_EXTERN PetscErrorCode PetscSortedCheckDupsInt(PetscCount, const PetscInt[], PetscBool *);
1300: PETSC_EXTERN PetscErrorCode PetscSortedCheckDupsCount(PetscCount, const PetscCount[], PetscBool *);
1301: PETSC_EXTERN PetscErrorCode PetscSortRemoveDupsInt(PetscInt *, PetscInt[]);
1302: PETSC_EXTERN PetscErrorCode PetscCheckDupsInt(PetscInt, const PetscInt[], PetscBool *);
1303: PETSC_EXTERN PetscErrorCode PetscFindInt(PetscInt, PetscCount, const PetscInt[], PetscInt *);
1304: PETSC_EXTERN PetscErrorCode PetscFindMPIInt(PetscMPIInt, PetscCount, const PetscMPIInt[], PetscInt *);
1305: PETSC_EXTERN PetscErrorCode PetscFindCount(PetscCount, PetscCount, const PetscCount[], PetscCount *);
1306: PETSC_EXTERN PetscErrorCode PetscSortIntWithPermutation(PetscInt, const PetscInt[], PetscInt[]);
1307: PETSC_EXTERN PetscErrorCode PetscSortStrWithPermutation(PetscInt, const char *[], PetscInt[]);
1308: PETSC_EXTERN PetscErrorCode PetscSortIntWithArray(PetscCount, PetscInt[], PetscInt[]);
1309: PETSC_EXTERN PetscErrorCode PetscSortIntWithCountArray(PetscCount, PetscInt[], PetscCount[]);
1310: PETSC_EXTERN PetscErrorCode PetscSortIntWithMPIIntArray(PetscCount, PetscInt[], PetscMPIInt[]);
1311: PETSC_EXTERN PetscErrorCode PetscSortIntWithArrayPair(PetscCount, PetscInt[], PetscInt[], PetscInt[]);
1312: PETSC_EXTERN PetscErrorCode PetscSortIntWithIntCountArrayPair(PetscCount, PetscInt[], PetscInt[], PetscCount[]);
1313: PETSC_EXTERN PetscErrorCode PetscSortMPIInt(PetscCount, PetscMPIInt[]);
1314: PETSC_EXTERN PetscErrorCode PetscSortRemoveDupsMPIInt(PetscInt *, PetscMPIInt[]);
1315: PETSC_EXTERN PetscErrorCode PetscSortMPIIntWithArray(PetscCount, PetscMPIInt[], PetscMPIInt[]);
1316: PETSC_EXTERN PetscErrorCode PetscSortMPIIntWithIntArray(PetscCount, PetscMPIInt[], PetscInt[]);
1317: PETSC_EXTERN PetscErrorCode PetscSortIntWithScalarArray(PetscCount, PetscInt[], PetscScalar[]);
1318: PETSC_EXTERN PetscErrorCode PetscSortIntWithDataArray(PetscCount, PetscInt[], void *, size_t, void *);
1319: PETSC_EXTERN PetscErrorCode PetscSortReal(PetscCount, PetscReal[]);
1320: PETSC_EXTERN PetscErrorCode PetscSortRealWithArrayInt(PetscCount, PetscReal[], PetscInt[]);
1321: PETSC_EXTERN PetscErrorCode PetscSortRealWithPermutation(PetscInt, const PetscReal[], PetscInt[]);
1322: PETSC_EXTERN PetscErrorCode PetscSortRemoveDupsReal(PetscInt *, PetscReal[]);
1323: PETSC_EXTERN PetscErrorCode PetscFindReal(PetscReal, PetscCount, const PetscReal[], PetscReal, PetscInt *);
1324: PETSC_EXTERN PetscErrorCode PetscSortSplit(PetscInt, PetscInt, PetscScalar[], PetscInt[]);
1325: PETSC_EXTERN PetscErrorCode PetscSortSplitReal(PetscInt, PetscInt, PetscReal[], PetscInt[]);
1326: PETSC_EXTERN PetscErrorCode PetscProcessTree(PetscInt, const PetscBool[], const PetscInt[], PetscInt *, PetscInt *[], PetscInt *[], PetscInt *[], PetscInt *[]);
1327: PETSC_EXTERN PetscErrorCode PetscMergeIntArrayPair(PetscInt, const PetscInt[], const PetscInt[], PetscInt, const PetscInt[], const PetscInt[], PetscInt *, PetscInt *[], PetscInt *[]);
1328: PETSC_EXTERN PetscErrorCode PetscMergeIntArray(PetscInt, const PetscInt[], PetscInt, const PetscInt[], PetscInt *, PetscInt *[]);
1329: PETSC_EXTERN PetscErrorCode PetscMergeMPIIntArray(PetscInt, const PetscMPIInt[], PetscInt, const PetscMPIInt[], PetscInt *, PetscMPIInt *[]);
1330: PETSC_EXTERN PetscErrorCode PetscParallelSortedInt(MPI_Comm, PetscInt, const PetscInt[], PetscBool *);
1332: PETSC_EXTERN PetscErrorCode PetscTimSort(PetscInt, void *, size_t, int (*)(const void *, const void *, void *), void *);
1333: PETSC_EXTERN PetscErrorCode PetscIntSortSemiOrdered(PetscInt, PetscInt[]);
1334: PETSC_EXTERN PetscErrorCode PetscMPIIntSortSemiOrdered(PetscInt, PetscMPIInt[]);
1335: PETSC_EXTERN PetscErrorCode PetscRealSortSemiOrdered(PetscInt, PetscReal[]);
1336: PETSC_EXTERN PetscErrorCode PetscTimSortWithArray(PetscInt, void *, size_t, void *, size_t, int (*)(const void *, const void *, void *), void *);
1337: PETSC_EXTERN PetscErrorCode PetscIntSortSemiOrderedWithArray(PetscInt, PetscInt[], PetscInt[]);
1338: PETSC_EXTERN PetscErrorCode PetscMPIIntSortSemiOrderedWithArray(PetscInt, PetscMPIInt[], PetscMPIInt[]);
1339: PETSC_EXTERN PetscErrorCode PetscRealSortSemiOrderedWithArrayInt(PetscInt, PetscReal[], PetscInt[]);
1341: PETSC_EXTERN PetscErrorCode PetscSetDisplay(void);
1342: PETSC_EXTERN PetscErrorCode PetscGetDisplay(char[], size_t);
1344: /* Logging support */
1345: PETSC_EXTERN PetscClassId PETSC_RANDOM_CLASSID;
1347: PETSC_EXTERN PetscErrorCode PetscRandomInitializePackage(void);
1348: PETSC_EXTERN PetscErrorCode PetscRandomFinalizePackage(void);
1350: /* Dynamic creation and loading functions */
1351: PETSC_EXTERN PetscFunctionList PetscRandomList;
1353: PETSC_EXTERN PetscErrorCode PetscRandomRegister(const char[], PetscErrorCode (*)(PetscRandom));
1354: PETSC_EXTERN PetscErrorCode PetscRandomSetType(PetscRandom, PetscRandomType);
1355: PETSC_EXTERN PetscErrorCode PetscRandomSetOptionsPrefix(PetscRandom, const char[]);
1356: PETSC_EXTERN PetscErrorCode PetscRandomAppendOptionsPrefix(PetscRandom, const char[]);
1357: PETSC_EXTERN PetscErrorCode PetscRandomGetOptionsPrefix(PetscRandom, const char *[]);
1358: PETSC_EXTERN PetscErrorCode PetscRandomSetFromOptions(PetscRandom);
1359: PETSC_EXTERN PetscErrorCode PetscRandomGetType(PetscRandom, PetscRandomType *);
1360: PETSC_EXTERN PetscErrorCode PetscRandomViewFromOptions(PetscRandom, PetscObject, const char[]);
1361: PETSC_EXTERN PetscErrorCode PetscRandomView(PetscRandom, PetscViewer);
1363: PETSC_EXTERN PetscErrorCode PetscRandomCreate(MPI_Comm, PetscRandom *);
1364: PETSC_EXTERN PetscErrorCode PetscRandomGetValue(PetscRandom, PetscScalar *);
1365: PETSC_EXTERN PetscErrorCode PetscRandomGetValueReal(PetscRandom, PetscReal *);
1366: PETSC_EXTERN PetscErrorCode PetscRandomGetValues(PetscRandom, PetscInt, PetscScalar *);
1367: PETSC_EXTERN PetscErrorCode PetscRandomGetValuesReal(PetscRandom, PetscInt, PetscReal *);
1368: PETSC_EXTERN PetscErrorCode PetscRandomGetInterval(PetscRandom, PetscScalar *, PetscScalar *);
1369: PETSC_EXTERN PetscErrorCode PetscRandomSetInterval(PetscRandom, PetscScalar, PetscScalar);
1370: PETSC_EXTERN PetscErrorCode PetscRandomSetSeed(PetscRandom, PetscInt64);
1371: PETSC_EXTERN PetscErrorCode PetscRandomGetSeed(PetscRandom, PetscInt64 *);
1372: PETSC_EXTERN PetscErrorCode PetscRandomSeed(PetscRandom);
1373: PETSC_EXTERN PetscErrorCode PetscRandomDestroy(PetscRandom *);
1375: PETSC_EXTERN PetscErrorCode PetscGetFullPath(const char[], char[], size_t);
1376: PETSC_EXTERN PetscErrorCode PetscGetRelativePath(const char[], char[], size_t);
1377: PETSC_EXTERN PetscErrorCode PetscGetWorkingDirectory(char[], size_t);
1378: PETSC_EXTERN PetscErrorCode PetscGetRealPath(const char[], char[]);
1379: PETSC_EXTERN PetscErrorCode PetscGetHomeDirectory(char[], size_t);
1380: PETSC_EXTERN PetscErrorCode PetscTestFile(const char[], char, PetscBool *);
1381: PETSC_EXTERN PetscErrorCode PetscTestDirectory(const char[], char, PetscBool *);
1382: PETSC_EXTERN PetscErrorCode PetscMkdir(const char[]);
1383: PETSC_EXTERN PetscErrorCode PetscMkdtemp(char[]);
1384: PETSC_EXTERN PetscErrorCode PetscRMTree(const char[]);
1386: /*MC
1387: PetscBinaryBigEndian - indicates if values in memory are stored with big endian format
1389: Synopsis:
1390: #include <petscsys.h>
1391: PetscBool PetscBinaryBigEndian(void);
1393: Not Collective; No Fortran Support
1395: Level: developer
1397: .seealso: `PetscInitialize()`, `PetscFinalize()`, `PetscInitializeCalled`
1398: M*/
1399: static inline PetscBool PetscBinaryBigEndian(void)
1400: {
1401: long _petsc_v = 1;
1402: return ((char *)&_petsc_v)[0] ? PETSC_FALSE : PETSC_TRUE;
1403: }
1405: PETSC_EXTERN PetscErrorCode PetscBinaryRead(int, void *, PetscCount, PetscInt *, PetscDataType);
1406: PETSC_EXTERN PetscErrorCode PetscBinarySynchronizedRead(MPI_Comm, int, void *, PetscInt, PetscInt *, PetscDataType);
1407: PETSC_EXTERN PetscErrorCode PetscBinaryWrite(int, const void *, PetscCount, PetscDataType);
1408: PETSC_EXTERN PetscErrorCode PetscBinarySynchronizedWrite(MPI_Comm, int, const void *, PetscInt, PetscDataType);
1409: PETSC_EXTERN PetscErrorCode PetscBinaryOpen(const char[], PetscFileMode, int *);
1410: PETSC_EXTERN PetscErrorCode PetscBinaryClose(int);
1411: PETSC_EXTERN PetscErrorCode PetscSharedTmp(MPI_Comm, PetscBool *);
1412: PETSC_EXTERN PetscErrorCode PetscSharedWorkingDirectory(MPI_Comm, PetscBool *);
1413: PETSC_EXTERN PetscErrorCode PetscGetTmp(MPI_Comm, char[], size_t);
1414: PETSC_EXTERN PetscErrorCode PetscFileRetrieve(MPI_Comm, const char[], char[], size_t, PetscBool *);
1415: PETSC_EXTERN PetscErrorCode PetscLs(MPI_Comm, const char[], char[], size_t, PetscBool *);
1416: #if PetscDefined(USE_SOCKET_VIEWER)
1417: PETSC_EXTERN PetscErrorCode PetscOpenSocket(const char[], int, int *);
1418: #endif
1420: PETSC_EXTERN PetscErrorCode PetscBinarySeek(int, off_t, PetscBinarySeekType, off_t *);
1421: PETSC_EXTERN PetscErrorCode PetscBinarySynchronizedSeek(MPI_Comm, int, off_t, PetscBinarySeekType, off_t *);
1422: PETSC_EXTERN PetscErrorCode PetscByteSwap(void *, PetscDataType, PetscCount);
1424: PETSC_EXTERN PetscErrorCode PetscSetDebugTerminal(const char[]);
1425: PETSC_EXTERN PetscErrorCode PetscSetDebugger(const char[], PetscBool);
1426: PETSC_EXTERN PetscErrorCode PetscSetDefaultDebugger(void);
1427: PETSC_EXTERN PetscErrorCode PetscSetDebuggerFromString(const char *);
1428: PETSC_EXTERN PetscErrorCode PetscAttachDebugger(void);
1429: PETSC_EXTERN PetscErrorCode PetscStopForDebugger(void);
1430: PETSC_EXTERN PetscErrorCode PetscWaitOnError(void);
1432: PETSC_EXTERN PetscErrorCode PetscGatherNumberOfMessages(MPI_Comm, const PetscMPIInt[], const PetscMPIInt[], PetscMPIInt *);
1433: PETSC_EXTERN PetscErrorCode PetscGatherMessageLengths(MPI_Comm, PetscMPIInt, PetscMPIInt, const PetscMPIInt[], PetscMPIInt *[], PetscMPIInt *[]);
1434: PETSC_EXTERN PetscErrorCode PetscGatherMessageLengths2(MPI_Comm, PetscMPIInt, PetscMPIInt, const PetscMPIInt[], const PetscMPIInt[], PetscMPIInt *[], PetscMPIInt *[], PetscMPIInt *[]);
1435: PETSC_EXTERN PetscErrorCode PetscPostIrecvInt(MPI_Comm, PetscMPIInt, PetscMPIInt, const PetscMPIInt[], const PetscMPIInt[], PetscInt ***, MPI_Request **);
1436: PETSC_EXTERN PetscErrorCode PetscPostIrecvScalar(MPI_Comm, PetscMPIInt, PetscMPIInt, const PetscMPIInt[], const PetscMPIInt[], PetscScalar ***, MPI_Request **);
1437: PETSC_EXTERN PetscErrorCode PetscCommBuildTwoSided(MPI_Comm, PetscMPIInt, MPI_Datatype, PetscMPIInt, const PetscMPIInt[], const void *, PetscMPIInt *, PetscMPIInt *[], void *) PETSC_ATTRIBUTE_MPI_POINTER_WITH_TYPE(6, 3);
1438: PETSC_EXTERN PetscErrorCode PetscCommBuildTwoSidedF(MPI_Comm, PetscMPIInt, MPI_Datatype, PetscMPIInt, const PetscMPIInt[], const void *, PetscMPIInt *, PetscMPIInt **, void *, PetscMPIInt, PetscErrorCode (*send)(MPI_Comm, const PetscMPIInt[], PetscMPIInt, PetscMPIInt, void *, MPI_Request[], void *), PetscErrorCode (*recv)(MPI_Comm, const PetscMPIInt[], PetscMPIInt, void *, MPI_Request[], void *), void *) PETSC_ATTRIBUTE_MPI_POINTER_WITH_TYPE(6, 3);
1439: PETSC_EXTERN PetscErrorCode PetscCommBuildTwoSidedFReq(MPI_Comm, PetscMPIInt, MPI_Datatype, PetscMPIInt, const PetscMPIInt[], const void *, PetscMPIInt *, PetscMPIInt **, void *, PetscMPIInt, MPI_Request **, MPI_Request **, PetscErrorCode (*send)(MPI_Comm, const PetscMPIInt[], PetscMPIInt, PetscMPIInt, void *, MPI_Request[], void *), PetscErrorCode (*recv)(MPI_Comm, const PetscMPIInt[], PetscMPIInt, void *, MPI_Request[], void *), PetscCtx ctx) PETSC_ATTRIBUTE_MPI_POINTER_WITH_TYPE(6, 3);
1441: PETSC_EXTERN PetscErrorCode PetscCommBuildTwoSidedSetType(MPI_Comm, PetscBuildTwoSidedType);
1442: PETSC_EXTERN PetscErrorCode PetscCommBuildTwoSidedGetType(MPI_Comm, PetscBuildTwoSidedType *);
1444: PETSC_DEPRECATED_FUNCTION(3, 24, 0, "PetscSSEIsEnabled()", ) static inline PetscErrorCode PetscSSEIsEnabled(PETSC_UNUSED MPI_Comm comm, PetscBool *lflag, PetscBool *gflag)
1445: {
1446: if (lflag) *lflag = PETSC_FALSE;
1447: if (gflag) *gflag = PETSC_FALSE;
1448: return PETSC_SUCCESS;
1449: }
1451: PETSC_EXTERN MPI_Comm PetscObjectComm(PetscObject);
1453: struct _n_PetscSubcomm {
1454: MPI_Comm parent; /* parent communicator */
1455: MPI_Comm dupparent; /* duplicate parent communicator, under which the processors of this subcomm have contiguous rank */
1456: MPI_Comm child; /* the sub-communicator */
1457: PetscMPIInt n; /* num of subcommunicators under the parent communicator */
1458: PetscMPIInt color; /* color of processors belong to this communicator */
1459: PetscMPIInt *subsize; /* size of subcommunicator[color] */
1460: PetscSubcommType type;
1461: char *subcommprefix;
1462: };
1464: static inline MPI_Comm PetscSubcommParent(PetscSubcomm scomm)
1465: {
1466: return scomm->parent;
1467: }
1468: static inline MPI_Comm PetscSubcommChild(PetscSubcomm scomm)
1469: {
1470: return scomm->child;
1471: }
1472: static inline MPI_Comm PetscSubcommContiguousParent(PetscSubcomm scomm)
1473: {
1474: return scomm->dupparent;
1475: }
1476: PETSC_EXTERN PetscErrorCode PetscSubcommCreate(MPI_Comm, PetscSubcomm *);
1477: PETSC_EXTERN PetscErrorCode PetscSubcommDestroy(PetscSubcomm *);
1478: PETSC_EXTERN PetscErrorCode PetscSubcommSetNumber(PetscSubcomm, PetscInt);
1479: PETSC_EXTERN PetscErrorCode PetscSubcommSetType(PetscSubcomm, PetscSubcommType);
1480: PETSC_EXTERN PetscErrorCode PetscSubcommSetTypeGeneral(PetscSubcomm, PetscMPIInt, PetscMPIInt);
1481: PETSC_EXTERN PetscErrorCode PetscSubcommView(PetscSubcomm, PetscViewer);
1482: PETSC_EXTERN PetscErrorCode PetscSubcommSetFromOptions(PetscSubcomm);
1483: PETSC_EXTERN PetscErrorCode PetscSubcommSetOptionsPrefix(PetscSubcomm, const char[]);
1484: PETSC_EXTERN PetscErrorCode PetscSubcommGetParent(PetscSubcomm, MPI_Comm *);
1485: PETSC_EXTERN PetscErrorCode PetscSubcommGetContiguousParent(PetscSubcomm, MPI_Comm *);
1486: PETSC_EXTERN PetscErrorCode PetscSubcommGetChild(PetscSubcomm, MPI_Comm *);
1488: PETSC_EXTERN PetscErrorCode PetscHeapCreate(PetscInt, PetscHeap *);
1489: PETSC_EXTERN PetscErrorCode PetscHeapAdd(PetscHeap, PetscInt, PetscInt);
1490: PETSC_EXTERN PetscErrorCode PetscHeapPop(PetscHeap, PetscInt *, PetscInt *);
1491: PETSC_EXTERN PetscErrorCode PetscHeapPeek(PetscHeap, PetscInt *, PetscInt *);
1492: PETSC_EXTERN PetscErrorCode PetscHeapStash(PetscHeap, PetscInt, PetscInt);
1493: PETSC_EXTERN PetscErrorCode PetscHeapUnstash(PetscHeap);
1494: PETSC_EXTERN PetscErrorCode PetscHeapDestroy(PetscHeap *);
1495: PETSC_EXTERN PetscErrorCode PetscHeapView(PetscHeap, PetscViewer);
1497: PETSC_EXTERN PetscErrorCode PetscProcessPlacementView(PetscViewer);
1498: PETSC_EXTERN PetscErrorCode PetscShmCommGet(MPI_Comm, PetscShmComm *);
1499: PETSC_EXTERN PetscErrorCode PetscShmCommGlobalToLocal(PetscShmComm, PetscMPIInt, PetscMPIInt *);
1500: PETSC_EXTERN PetscErrorCode PetscShmCommLocalToGlobal(PetscShmComm, PetscMPIInt, PetscMPIInt *);
1501: PETSC_EXTERN PetscErrorCode PetscShmCommGetMpiShmComm(PetscShmComm, MPI_Comm *);
1503: /* routines to better support OpenMP multithreading needs of some PETSc third party libraries */
1504: PETSC_EXTERN PetscErrorCode PetscOmpCtrlCreate(MPI_Comm, PetscInt, PetscOmpCtrl *);
1505: PETSC_EXTERN PetscErrorCode PetscOmpCtrlGetOmpComms(PetscOmpCtrl, MPI_Comm *, MPI_Comm *, PetscBool *);
1506: PETSC_EXTERN PetscErrorCode PetscOmpCtrlDestroy(PetscOmpCtrl *);
1507: PETSC_EXTERN PetscErrorCode PetscOmpCtrlBarrier(PetscOmpCtrl);
1508: PETSC_EXTERN PetscErrorCode PetscOmpCtrlOmpRegionOnMasterBegin(PetscOmpCtrl);
1509: PETSC_EXTERN PetscErrorCode PetscOmpCtrlOmpRegionOnMasterEnd(PetscOmpCtrl);
1511: PETSC_EXTERN PetscErrorCode PetscSegBufferCreate(size_t, PetscCount, PetscSegBuffer *);
1512: PETSC_EXTERN PetscErrorCode PetscSegBufferDestroy(PetscSegBuffer *);
1513: PETSC_EXTERN PetscErrorCode PetscSegBufferGet(PetscSegBuffer, PetscCount, void *);
1514: PETSC_EXTERN PetscErrorCode PetscSegBufferExtractAlloc(PetscSegBuffer, void *);
1515: PETSC_EXTERN PetscErrorCode PetscSegBufferExtractTo(PetscSegBuffer, void *);
1516: PETSC_EXTERN PetscErrorCode PetscSegBufferExtractInPlace(PetscSegBuffer, void *);
1517: PETSC_EXTERN PetscErrorCode PetscSegBufferGetSize(PetscSegBuffer, PetscCount *);
1518: PETSC_EXTERN PetscErrorCode PetscSegBufferUnuse(PetscSegBuffer, PetscCount);
1520: /*MC
1521: PetscSegBufferGetInts - access an array of `PetscInt` from a `PetscSegBuffer`
1523: Synopsis:
1524: #include <petscsys.h>
1525: PetscErrorCode PetscSegBufferGetInts(PetscSegBuffer seg, size_t count, PetscInt *PETSC_RESTRICT *slot);
1527: No Fortran Support
1529: Input Parameters:
1530: + seg - `PetscSegBuffer` buffer
1531: - count - number of entries needed
1533: Output Parameter:
1534: . buf - address of new buffer for contiguous data
1536: Level: intermediate
1538: Developer Note:
1539: Type-safe wrapper to encourage use of PETSC_RESTRICT. Does not use PetscFunctionBegin because the error handling
1540: prevents the compiler from completely erasing the stub. This is called in inner loops so it has to be as fast as
1541: possible.
1543: .seealso: `PetscSegBuffer`, `PetscSegBufferGet()`, `PetscInitialize()`, `PetscFinalize()`, `PetscInitializeCalled`
1544: M*/
1545: static inline PetscErrorCode PetscSegBufferGetInts(PetscSegBuffer seg, PetscCount count, PetscInt *PETSC_RESTRICT *slot)
1546: {
1547: return PetscSegBufferGet(seg, count, (void **)slot);
1548: }
1550: extern PetscOptionsHelpPrinted PetscOptionsHelpPrintedSingleton;
1551: PETSC_EXTERN PetscErrorCode PetscOptionsHelpPrintedDestroy(PetscOptionsHelpPrinted *);
1552: PETSC_EXTERN PetscErrorCode PetscOptionsHelpPrintedCreate(PetscOptionsHelpPrinted *);
1553: PETSC_EXTERN PetscErrorCode PetscOptionsHelpPrintedCheck(PetscOptionsHelpPrinted, const char *, const char *, PetscBool *);
1555: #include <stdarg.h>
1556: PETSC_EXTERN PetscErrorCode PetscVSNPrintf(char *, size_t, const char[], size_t *, va_list);
1557: PETSC_EXTERN PetscErrorCode (*PetscVFPrintf)(FILE *, const char[], va_list);
1559: PETSC_EXTERN PetscErrorCode PetscCitationsRegister(const char[], PetscBool *);
1561: PETSC_EXTERN PetscErrorCode PetscGoogleDriveAuthorize(MPI_Comm, char[], char[], size_t);
1562: PETSC_EXTERN PetscErrorCode PetscGoogleDriveRefresh(MPI_Comm, const char[], char[], size_t);
1563: PETSC_EXTERN PetscErrorCode PetscGoogleDriveUpload(MPI_Comm, const char[], const char[]);
1565: PETSC_EXTERN PetscErrorCode PetscBoxAuthorize(MPI_Comm, char[], char[], size_t);
1566: PETSC_EXTERN PetscErrorCode PetscBoxRefresh(MPI_Comm, const char[], char[], char[], size_t);
1567: PETSC_EXTERN PetscErrorCode PetscBoxUpload(MPI_Comm, const char[], const char[]);
1569: PETSC_EXTERN PetscErrorCode PetscGlobusGetTransfers(MPI_Comm, const char[], char[], size_t);
1570: PETSC_EXTERN PetscErrorCode PetscGlobusAuthorize(MPI_Comm, char[], size_t);
1571: PETSC_EXTERN PetscErrorCode PetscGlobusUpload(MPI_Comm, const char[], const char[]);
1573: PETSC_EXTERN PetscErrorCode PetscPullJSONValue(const char[], const char[], char[], size_t, PetscBool *);
1574: PETSC_EXTERN PetscErrorCode PetscPushJSONValue(char[], const char[], const char[], size_t);
1576: #if !PetscDefined(HAVE_MPI_LARGE_COUNT)
1577: /*
1578: Cast PetscCount <a> to PetscMPIInt <b>, where <a> is likely used for the 'count' argument in MPI routines.
1579: It is similar to PetscMPIIntCast() except that here it returns an MPI error code.
1580: */
1581: #define PetscMPIIntCast_Internal(a, b) \
1582: do { \
1583: *(b) = 0; \
1584: if (PetscUnlikely((a) > (MPIU_Count)PETSC_MPI_INT_MAX)) return MPI_ERR_COUNT; \
1585: *(b) = (PetscMPIInt)(a); \
1586: } while (0)
1588: static inline PetscMPIInt MPIU_Get_count(MPI_Status *status, MPI_Datatype dtype, PetscCount *count)
1589: {
1590: PetscMPIInt count2, err;
1592: *count = 0; /* to prevent incorrect warnings of uninitialized variables */
1593: err = MPI_Get_count(status, dtype, &count2);
1594: *count = count2;
1595: return err;
1596: }
1598: static inline PetscMPIInt MPIU_Send(const void *buf, MPIU_Count count, MPI_Datatype dtype, PetscMPIInt dest, PetscMPIInt tag, MPI_Comm comm)
1599: {
1600: PetscMPIInt count2, err;
1602: PetscMPIIntCast_Internal(count, &count2);
1603: err = MPI_Send((void *)buf, count2, dtype, dest, tag, comm);
1604: return err;
1605: }
1607: static inline PetscMPIInt MPIU_Send_init(const void *buf, MPIU_Count count, MPI_Datatype dtype, PetscMPIInt dest, PetscMPIInt tag, MPI_Comm comm, MPI_Request *request)
1608: {
1609: PetscMPIInt count2, err;
1611: PetscMPIIntCast_Internal(count, &count2);
1612: err = MPI_Send_init((void *)buf, count2, dtype, dest, tag, comm, request);
1613: return err;
1614: }
1616: static inline PetscMPIInt MPIU_Isend(const void *buf, MPIU_Count count, MPI_Datatype dtype, PetscMPIInt dest, PetscMPIInt tag, MPI_Comm comm, MPI_Request *request)
1617: {
1618: PetscMPIInt count2, err;
1620: PetscMPIIntCast_Internal(count, &count2);
1621: err = MPI_Isend((void *)buf, count2, dtype, dest, tag, comm, request);
1622: return err;
1623: }
1625: static inline PetscMPIInt MPIU_Recv(const void *buf, MPIU_Count count, MPI_Datatype dtype, PetscMPIInt source, PetscMPIInt tag, MPI_Comm comm, MPI_Status *status)
1626: {
1627: PetscMPIInt count2, err;
1629: PetscMPIIntCast_Internal(count, &count2);
1630: err = MPI_Recv((void *)buf, count2, dtype, source, tag, comm, status);
1631: return err;
1632: }
1634: static inline PetscMPIInt MPIU_Recv_init(const void *buf, MPIU_Count count, MPI_Datatype dtype, PetscMPIInt source, PetscMPIInt tag, MPI_Comm comm, MPI_Request *request)
1635: {
1636: PetscMPIInt count2, err;
1638: PetscMPIIntCast_Internal(count, &count2);
1639: err = MPI_Recv_init((void *)buf, count2, dtype, source, tag, comm, request);
1640: return err;
1641: }
1643: static inline PetscMPIInt MPIU_Irecv(const void *buf, MPIU_Count count, MPI_Datatype dtype, PetscMPIInt source, PetscMPIInt tag, MPI_Comm comm, MPI_Request *request)
1644: {
1645: PetscMPIInt count2, err;
1647: PetscMPIIntCast_Internal(count, &count2);
1648: err = MPI_Irecv((void *)buf, count2, dtype, source, tag, comm, request);
1649: return err;
1650: }
1652: static inline PetscMPIInt MPIU_Reduce(const void *inbuf, void *outbuf, MPIU_Count count, MPI_Datatype dtype, MPI_Op op, PetscMPIInt root, MPI_Comm comm)
1653: {
1654: PetscMPIInt count2, err;
1656: PetscMPIIntCast_Internal(count, &count2);
1657: err = MPI_Reduce((void *)inbuf, outbuf, count2, dtype, op, root, comm);
1658: return err;
1659: }
1661: #if PetscDefined(HAVE_MPI_REDUCE_LOCAL)
1662: static inline PetscMPIInt MPIU_Reduce_local(const void *inbuf, void *inoutbuf, MPIU_Count count, MPI_Datatype dtype, MPI_Op op)
1663: {
1664: PetscMPIInt count2, err;
1666: PetscMPIIntCast_Internal(count, &count2);
1667: err = MPI_Reduce_local((void *)inbuf, inoutbuf, count2, dtype, op);
1668: return err;
1669: }
1670: #endif
1672: #if !PetscDefined(USE_64BIT_INDICES)
1673: #define MPIU_Scatterv(sendbuf, sendcounts, displs, sendtype, recvbuf, recvcount, recvtype, root, comm) MPI_Scatterv(sendbuf, sendcounts, displs, sendtype, recvbuf, recvcount, recvtype, root, comm)
1674: #define MPIU_Gatherv(sendbuf, sendcount, sendtype, recvbuf, recvcounts, displs, recvtype, root, comm) MPI_Gatherv(sendbuf, sendcount, sendtype, recvbuf, recvcounts, displs, recvtype, root, comm)
1675: #else
1676: #define MPIU_Scatterv(sendbuf, sendcount, displs, sendtype, recvbuf, recvcount, recvtype, root, comm) \
1677: ((void)PetscError(comm, __LINE__, PETSC_FUNCTION_NAME, __FILE__, PETSC_ERR_SUP, PETSC_ERROR_INITIAL, "Must have MPI 4 support for MPI_Scatterv_c() for this functionality, upgrade your MPI"), MPI_ERR_COUNT)
1678: #define MPIU_Gatherv(sendbuf, sendcount, sendtype, recvbuf, recvcounts, displs, recvtype, root, comm) \
1679: ((void)PetscError(comm, __LINE__, PETSC_FUNCTION_NAME, __FILE__, PETSC_ERR_SUP, PETSC_ERROR_INITIAL, "Must have MPI 4 support for MPI_Scatterv_c() for this functionality, upgrade your MPI"), MPI_ERR_COUNT)
1680: #endif
1682: #else
1684: /* on 32 bit systems MPI_Count maybe 64-bit while PetscCount is 32-bit */
1685: #define PetscCountCast_Internal(a, b) \
1686: do { \
1687: *(b) = 0; \
1688: if (PetscUnlikely((a) > (MPI_Count)PETSC_COUNT_MAX)) return MPI_ERR_COUNT; \
1689: *(b) = (PetscMPIInt)(a); \
1690: } while (0)
1692: static inline PetscMPIInt MPIU_Get_count(MPI_Status *status, MPI_Datatype dtype, PetscCount *count)
1693: {
1694: MPI_Count count2;
1695: PetscMPIInt err;
1697: *count = 0; /* to prevent incorrect warnings of uninitialized variables */
1698: err = MPI_Get_count_c(status, dtype, &count2);
1699: if (err) return err;
1700: PetscCountCast_Internal(count2, count);
1701: return MPI_SUCCESS;
1702: }
1704: #define MPIU_Reduce(inbuf, outbuf, count, dtype, op, root, comm) MPI_Reduce_c(inbuf, outbuf, (MPI_Count)(count), dtype, op, root, comm)
1705: #define MPIU_Send(buf, count, dtype, dest, tag, comm) MPI_Send_c(buf, (MPI_Count)(count), dtype, dest, tag, comm)
1706: #define MPIU_Send_init(buf, count, dtype, dest, tag, comm, request) MPI_Send_init_c(buf, (MPI_Count)(count), dtype, dest, tag, comm, request)
1707: #define MPIU_Isend(buf, count, dtype, dest, tag, comm, request) MPI_Isend_c(buf, (MPI_Count)(count), dtype, dest, tag, comm, request)
1708: #define MPIU_Recv(buf, count, dtype, source, tag, comm, status) MPI_Recv_c(buf, (MPI_Count)(count), dtype, source, tag, comm, status)
1709: #define MPIU_Recv_init(buf, count, dtype, source, tag, comm, request) MPI_Recv_init_c(buf, (MPI_Count)(count), dtype, source, tag, comm, request)
1710: #define MPIU_Irecv(buf, count, dtype, source, tag, comm, request) MPI_Irecv_c(buf, (MPI_Count)(count), dtype, source, tag, comm, request)
1711: #if PetscDefined(HAVE_MPI_REDUCE_LOCAL)
1712: #define MPIU_Reduce_local(inbuf, inoutbuf, count, dtype, op) MPI_Reduce_local_c(inbuf, inoutbuf, (MPI_Count)(count), dtype, op)
1713: #endif
1715: /*MC
1716: MPIU_Scatterv - A replacement for `MPI_Scatterv()` that can be called with `PetscInt` types when PETSc is built for either 32-bit indices or 64-bit indices.
1718: Synopsis:
1719: #include <petscsys.h>
1720: PetscMPIInt MPIU_Scatterv(const void *sendbuf, const PetscInt sendcounts[], const PetscInt displs[], MPI_Datatype sendtype, void *recvbuf, PetscInt recvcount, MPI_Datatype recvtype, PetscMPIInt root, MPI_Comm comm)
1722: Collective
1724: Input Parameters:
1725: + sendbuf - address of send buffer
1726: . sendcounts - non-negative `PetscInt` array (of length `comm` group size) specifying the number of elements to send to each MPI process
1727: . displs - `PetscInt` array (of length `comm` group size). Entry i specifies the displacement (relative to `sendbuf`) from which to take the outgoing data to process i
1728: . sendtype - data type of `sendbuf` elements
1729: . recvcount - number of elements in `recvbuf` (non-negative integer)
1730: . recvtype - data type of `recvbuf` elements
1731: . root - Rank of the MPI root process, which will dispatch the data to scatter
1732: - comm - `MPI_Comm` communicator
1734: Output Parameter:
1735: . recvbuf - the resulting scattered values on this MPI process
1737: Level: developer
1739: Notes:
1740: Should be wrapped with `PetscCallMPI()` for error checking
1742: This is different than most of the `MPIU_` wrappers in that all the count arguments are in `PetscInt`
1744: .seealso: [](stylePetscCount), `MPI_Allreduce()`, `MPIU_Gatherv()`
1745: M*/
1747: #if !PetscDefined(USE_64BIT_INDICES)
1748: #define MPIU_Scatterv(sendbuf, sendcounts, displs, sendtype, recvbuf, recvcount, recvtype, root, comm) MPI_Scatterv(sendbuf, sendcounts, displs, sendtype, recvbuf, recvcount, recvtype, root, comm)
1749: #define MPIU_Gatherv(sendbuf, sendcount, sendtype, recvbuf, recvcounts, displs, recvtype, root, comm) MPI_Gatherv(sendbuf, sendcount, sendtype, recvbuf, recvcounts, displs, recvtype, root, comm)
1750: #else
1751: #define MPIU_Scatterv(sendbuf, sendcounts, displs, sendtype, recvbuf, recvcount, recvtype, root, comm) MPI_Scatterv_c(sendbuf, (const MPI_Count *)(sendcounts), (const MPI_Aint *)(displs), sendtype, recvbuf, recvcount, recvtype, root, comm)
1752: #define MPIU_Gatherv(sendbuf, sendcount, sendtype, recvbuf, recvcounts, displs, recvtype, root, comm) MPI_Gatherv_c(sendbuf, sendcount, sendtype, recvbuf, (const MPI_Count *)(recvcounts), (const MPI_Aint *)(displs), recvtype, root, comm)
1753: #endif
1755: #endif
1757: PETSC_EXTERN PetscMPIInt MPIU_Allreduce_Private(const void *, void *, MPIU_Count, MPI_Datatype, MPI_Op, MPI_Comm);
1758: PETSC_EXTERN PetscErrorCode PetscCheckAllreduceSameLineAndCount_Private(MPI_Comm, const char *, PetscMPIInt, PetscMPIInt);
1760: static inline unsigned int PetscStrHash(const char *str)
1761: {
1762: unsigned int c, hash = 5381;
1764: while ((c = (unsigned int)*str++)) hash = ((hash << 5) + hash) + c; /* hash * 33 + c */
1765: return hash;
1766: }
1768: /*MC
1769: MPIU_Allreduce - A replacement for `MPI_Allreduce()` that (1) performs single-count `MPIU_INT` operations in `PetscInt64` to detect
1770: integer overflows and (2) tries to determine if the call from all the MPI ranks occur in the
1771: same place in the PETSc code. This helps to detect bugs where different MPI ranks follow different code paths
1772: resulting in inconsistent and incorrect calls to `MPI_Allreduce()`.
1774: Synopsis:
1775: #include <petscsys.h>
1776: PetscMPIInt MPIU_Allreduce(void *indata, void *outdata, PetscCount count, MPI_Datatype dtype, MPI_Op op, MPI_Comm comm);
1778: Collective
1780: Input Parameters:
1781: + a - pointer to the input data to be reduced
1782: . count - the number of MPI data items in `a` and `b`
1783: . dtype - the `MPI_Datatype`, for example `MPI_INT`
1784: . op - the `MPI_Op`, for example `MPI_SUM`
1785: - comm - the `MPI_Comm` on which the operation occurs
1787: Output Parameter:
1788: . b - the reduced values
1790: Level: developer
1792: Note:
1793: Should be wrapped with `PetscCallMPI()` for error checking
1795: .seealso: [](stylePetscCount), `MPI_Allreduce()`
1796: M*/
1797: #if PetscDefined(USE_DEBUG)
1798: #define MPIU_Allreduce(a, b, count, dtype, op, comm) \
1799: PetscMacroReturnStandard( \
1800: PetscCall(PetscCheckAllreduceSameLineAndCount_Private((comm), __FILE__, (PetscMPIInt)__LINE__, (PetscMPIInt)(count))); \
1801: PetscCallMPI(MPIU_Allreduce_Private((a), (b), (count), (dtype), (op), (comm)));)
1802: #else
1803: #define MPIU_Allreduce(a, b, count, dtype, op, comm) MPIU_Allreduce_Private((a), (b), (count), (dtype), (op), (comm))
1804: #endif
1806: /* this is a vile hack */
1807: #if PetscDefined(HAVE_NECMPI)
1808: #if !defined(PETSC_NECMPI_VERSION_MAJOR) || !defined(PETSC_NECMPI_VERSION_MINOR) || PETSC_NECMPI_VERSION_MAJOR < 2 || (PETSC_NECMPI_VERSION_MAJOR == 2 && PETSC_NECMPI_VERSION_MINOR < 18)
1809: #define MPI_Type_free(a) (*(a) = MPI_DATATYPE_NULL, 0);
1810: #endif
1811: #endif
1813: /*
1814: List of external packages and queries on it
1815: */
1816: PETSC_EXTERN PetscErrorCode PetscHasExternalPackage(const char[], PetscBool *);
1818: /* this cannot go here because it may be in a different shared library */
1819: PETSC_EXTERN PetscErrorCode PCMPIServerBegin(void);
1820: PETSC_EXTERN PetscErrorCode PCMPIServerEnd(void);
1821: PETSC_EXTERN PetscBool PCMPIServerActive;
1822: PETSC_EXTERN PetscBool PCMPIServerInSolve;
1823: PETSC_EXTERN PetscBool PCMPIServerUseShmget;
1824: PETSC_EXTERN PetscErrorCode PetscShmgetAllocateArray(size_t, size_t, void **);
1825: PETSC_EXTERN PetscErrorCode PetscShmgetDeallocateArray(void **);
1826: PETSC_EXTERN PetscErrorCode PetscShmgetMapAddresses(MPI_Comm, PetscInt, const void **, void **);
1827: PETSC_EXTERN PetscErrorCode PetscShmgetUnmapAddresses(PetscInt, void **);
1828: PETSC_EXTERN PetscErrorCode PetscShmgetAddressesFinalize(void);
1829: PETSC_EXTERN PetscErrorCode PCMPIServerAddressesDestroy(PetscCtxRt);
1831: #define PETSC_HAVE_FORTRAN PETSC_DEPRECATED_MACRO(3, 20, 0, "PETSC_USE_FORTRAN_BINDINGS", ) PETSC_USE_FORTRAN_BINDINGS
1833: PETSC_EXTERN PetscErrorCode PetscBLASSetNumThreads(PetscInt);
1834: PETSC_EXTERN PetscErrorCode PetscBLASGetNumThreads(PetscInt *);
1836: /*MC
1837: PetscSafePointerPlusOffset - Checks that a pointer is not `NULL` before applying an offset
1839: Level: beginner
1841: Note:
1842: This is needed to avoid errors with undefined-behavior sanitizers such as
1843: UBSan, assuming PETSc has been configured with `-fsanitize=undefined` as part of the compiler flags
1845: .seealso: `PetscInitialize()`
1846: M*/
1847: #define PetscSafePointerPlusOffset(ptr, offset) ((ptr) ? (ptr) + (offset) : NULL)
1849: /* this is required to force PetscDevice to be visible at the system level for the Fortran interface */
1850: #include <petscdevicetypes.h>
1852: #if PetscDefined(USE_DEBUG)
1853: PETSC_EXTERN PetscErrorCode PetscStackView(FILE *);
1854: #else
1855: #define PetscStackView(file) PETSC_SUCCESS
1856: #endif
1858: /*MC
1859: PetscOverrideIntelMKLCPUVendorDetection - a macro to override Intel MKL's CPU vendor detection routines
1861: Level: developer
1863: Note:
1864: Intel MKL may detect the CPU vendor at runtime and select less optimized code paths on non-Intel CPUs, such as AMD processors.
1865: A common workaround is to intercept MKL's CPU detection functions (`mkl_serv_intel_cpu_true()` or `mkl_serv_get_cpu_true()`)
1866: and force them to report that the processor is an Intel CPU, thus enabling the optimized code paths of MKL.
1868: Put `PetscOverrideIntelMKLCPUVendorDetection();` before
1869: `main()`, and then compile and link the main object file before the MKL libraries (which is typically already the case).
1870: See <https://danieldk.eu/software/misc/intel-mkl-on-amd-zen>.
1872: .seealso: `PetscInitialize()`
1873: M*/
1874: #define PetscOverrideIntelMKLCPUVendorDetection() \
1875: PETSC_EXTERN int mkl_serv_intel_cpu_true(void) \
1876: { \
1877: return 1; \
1878: } \
1879: typedef int (*fakeintel_fptr)(void); \
1880: PETSC_EXTERN fakeintel_fptr mkl_serv_get_cpu_true(void) \
1881: { \
1882: return &mkl_serv_intel_cpu_true; \
1883: }
1885: /*
1886: The options database and viewer APIs are used throughout PETSc, so for convenience they are made available to
1887: any file that includes petscsys.h. These are included at the end of petscsys.h, after all of its own declarations,
1888: so that petscviewer.h and petscoptions.h see the complete petscsys.h; this avoids an include cycle even though
1889: both of them, in turn, depend on the basic PETSc types.
1890: */
1891: #include <petscviewer.h>
1892: #include <petscoptions.h>