1# Changes: 3.19 2 3% STYLE GUIDELINES: 4% * Capitalize sentences 5% * Use imperative, e.g., Add, Improve, Change, etc. 6% * Don't use a period (.) at the end of entries 7% * If multiple sentences are needed, use a period or semicolon to divide sentences, but not at the end of the final sentence 8 9```{rubric} General: 10``` 11 12- Add perfstubs package, see {ref}`Users Manual: Profiling: Using TAU <sec_using_tau>` for more information on usage 13 14```{rubric} Configure/Build: 15``` 16 17- Remove unused preprocessor variables `PETSC_HAVE_VPRINTF_CHAR`, `PETSC_HAVE_VFPRINTF_CHAR`, `PETSC_STAT_MACROS_BROKEN`, `PETSC_HAVE_FORTRAN_GETARG`, `PETSC_uid_t`, `PETSC_gid_t`, `PETSC_HAVE_PTHREAD_BARRIER_T`, `PETSC_HAVE_SCHED_CPU_SET_T`, `PETSC_HAVE_SYS_SYSCTL_H`, `PETSC_HAVE_SYS_SYSINFO_H`, `PETSC_HAVE_SYSINFO_3ARG`, `PETSC_SIZEOF_SHORT`, and `PETSC_SIZEOF_ENUM` 18- Deprecate `--with-gcov` configure option in favor of `--with-coverage` 19- Add `--with-coverage-exec` configure option to specify the coverage-collection tool to be used e.g. `gcov` or `/path/to/llvm-cov-15` 20- Add `--with-strict-petscerrorcode` configure option to enable compile-time checking for correct usage of `PetscErrorCode`, see below 21- Add support for C++20 22- Add support for CUDA-12 23- Improved C++ dialect handling for non-conformal cases. In general `configure` will fail faster and with a more informative error message when the C++ compiler does not comply with restraints 24 25```{rubric} Sys: 26``` 27 28- Change `PetscOptionsMonitorDefault()` to also take in the option source, and `PetscOptionsMonitorSet()` to take the new monitor function 29 30- Deprecate `PetscTable` and related functions. Previous users of `PetscTable` are encouraged to use the more performant `PetscHMapI` instead, though they should note that this requires additional steps and limitations: 31 32 1. `#include <petscctable.h>` must be swapped for `#include <petsc/private/hashmapi.h>`. This of course requires that you have access to the private PETSc headers. 33 34 2. While most of the old `PetscTable` routines have direct analogues in `PetscHMapI`, `PetscAddCount()` does not. All uses of this routine should be replaced with the following snippet: 35 36 ``` 37 // PetscHMapI hash_table; 38 // PetscInt key; 39 40 PetscHashIter it; 41 PetscBool missing; 42 43 PetscCall(PetscHMapIPut(hash_table, key, &it, &missing)); 44 if (missing) { 45 PetscInt size; 46 47 PetscCall(PetscHMapIGetSize(hash_table, &size)); 48 PetscCall(PetscHMapIIterSet(hash_table, it, size)); 49 } 50 ``` 51 52 Furthermore, users should note that `PetscHMapI` is based on -- and directly `#include` s -- `${PETSC_DIR}/include/petsc/private/khash/khash.h`. This file contains external source code that is licensed under the MIT license, which is separate from the PETSc license. 53 54- Remove undocumented `PETSC_MPI_WIN_FMT` and `PETSC_MPI_COMM_FMT`. Users should cast both `MPI_Comm` and `MPI_Win` to `PETSC_INTPTR_T` and use the `PETSC_INTPTR_T_FMT` format specifier instead: 55 56 ``` 57 MPI_Comm comm; 58 MPI_Win win; 59 60 // old 61 PetscCall(PetscPrintf(..., "MPI Comm %" PETSC_MPI_COMM_FMT, comm)); 62 PetscCall(PetscPrintf(..., "MPI Window %" PETSC_MPI_WIN_FMT, win)); 63 64 // new 65 PetscCall(PetscPrintf(..., "MPI Comm %" PETSC_INTPTR_T_FMT, (PETSC_INTPTR_T)comm)); 66 PetscCall(PetscPrintf(..., "MPI Window %" PETSC_INTPTR_T_FMT, (PETSC_INTPTR_T)win)); 67 ``` 68 69- Deprecate `PETSC_NULL` in favor of `PETSC_NULLPTR` as it does the right thing in both C and C++ 70 71- Significantly improve lookup and deletion performance of `PetscFunctionList`. This also improves performance of `PetscObjectComposeFunction()` and `PetscObjectQueryFunction()`. 72 73- Optionally define `PetscErrorCode` as an `enum`, and tag it as `PETSC_NODISCARD`. This feature may be enabled by configuring PETSc with `--with-strict-petscerrorcode` configure option. This feature allows catching the following logical errors at compile-time: 74 75 1. Not properly checking the return-code of PETSc calls via `PetscCall()`. PETSc is left in an inconsistent state when errors are detected and cannot generally recover from them, so is not supported. 76 2. Using the wrong `PetscCall()` variant, for example using `PetscCall()` on MPI functions (instead of `PetscCallMPI()`). 77 3. Returning `PetscErrorCode` from `main()` instead of `int`. 78 79 Users should note that this comes with the following additional changes: 80 81 1. Add `PETSC_SUCCESS` to indicate success, always guaranteed to equal `0`. 82 83 2. `PetscFunctionReturn(0)` should be changed to `PetscFunctionReturn(PETSC_SUCCESS)`. While the original `0`-form will continue to work in C, it is required for C++. 84 85 3. Any user-defined macros using boolean short-circuiting to chain multiple calls in the same line, which logically return a `PetscErrorCode`, should now explicitly cast the "result" of the macro with `PetscErrorCode`: 86 87 ``` 88 // Both foo() and bar() defined as returning PetscErrorCode 89 extern PetscErrorCode foo(int); 90 extern PetscErrorCode bar(int); 91 92 // The following macros logically "return" a PetscErrorCode, i.e. can 93 // be used: 94 // 95 // PetscCall(MY_USER_MACRO(a, b)); 96 // 97 // but use boolean short-circuiting to chain the calls together. bar() 98 // only executes if foo() returns PETSC_SUCCESS 99 100 // old 101 #define MY_USER_MACRO(a, b) (foo(a) || bar(b)) 102 103 // new 104 #define MY_BETTER_USER_MACRO(a, b) ((PetscErrorCode)(foo(a) || bar(b))) 105 ``` 106 107 While currently opt-in, this feature **will be enabled by default in a future release**. Users are highly encourage to enable it and fix any discrepancies before that point. Note that `PETSC_SUCCESS` is defined whether or not the feature is enabled, so users may incrementally update. 108 109- Add `PetscFFlush()` 110 111- Soft-deprecate `PetscStrcpy()` and `PetscStrcat()`. No diagnostics will be emitted if these routines are used, but users are highly encouraged to switch to the more secure (and possibly performant) `PetscStrncpy()` and `PetscStrlcat()` 112 113- Add `PETSC_REAL_MIN` for smallest normalized floating point number 114 115- Add `PETSC_ATTRIBUTE_MAY_ALIAS` to inform compilers that a type is not subjected to type-based alias analysis 116 117```{rubric} Event Logging: 118``` 119 120```{rubric} PetscViewer: 121``` 122 123- The VTK viewers (`.vts`, `.vtr`, and `.vtu`) now use `header_type="UInt64"` to enable writing large binary appended blocks 124 125```{rubric} PetscDraw: 126``` 127 128- Add `PetscDrawSetVisible()` to set if the drawing surface (the 'window') is visible on its display 129 130```{rubric} AO: 131``` 132 133```{rubric} IS: 134``` 135 136- Change `ISDuplicate()` to preserve the block size of the input in the output 137- Deprecate `ISCompressIndicesSorted()` 138 139```{rubric} VecScatter / PetscSF: 140``` 141 142- Add experimental support in PetscSF for MPICH MPIX_Stream (with MPICH-4.2.0 and higher). One can enable it via `-sf_use_stream_aware_mpi` 143- Add an alias option `-sf_use_gpu_aware_mpi` to `-use_gpu_aware_mpi` 144- Remove `SCATTER_LOCAL` from the enum type since it is not a public value 145- Change `PetscSFConcatenate()` to accept `PetscSFConcatenateRootMode` parameter; add option to concatenate root spaces globally 146- Add `PetscSFSetGraphFromCoordinates()` to construct a graph from fuzzy matching of coordinates; such as occurs for projections between different dimensions or for overlapping meshes 147 148```{rubric} PF: 149``` 150 151```{rubric} Vec: 152``` 153 154- Document `VecOperation` 155- Add `VECOP_SET` 156- Significantly improve performance of `VecMDot()`, `VecMAXPY()` and `VecDotNorm2()` for CUDA and HIP vector types. These routines should be between 2x and 4x faster. 157- Enforce the rule that `VecAssemblyBegin()` and `VecAssemblyEnd()` must be called on even sequential vectors after calls to `VecSetValues()`. This also applies to assignment of vector entries in petsc4py 158 159```{rubric} PetscSection: 160``` 161 162```{rubric} PetscPartitioner: 163``` 164 165```{rubric} Mat: 166``` 167 168- `MatSetValues()` and friends will now provide reasonable performance when no preallocation information is provided 169- Add `MatEliminateZeros()` 170- Improve efficiency of `MatConvert()` from `MATNORMAL` to `MATHYPRE` 171- Add `MatDenseGetArrayAndMemType()`, `MatDenseRestoreArrayAndMemType()`, `MatDenseGetArrayReadAndMemType()`, `MatDenseRestoreArrayReadAndMemType()`, `MatDenseGetArrayWriteAndMemType()` and `MatDenseRestoreArrayWriteAndMemType()` to return the array and memory type of a dense matrix 172- Deprecate all MatPreallocate\* routines. These are no longer needed since non-preallocated matrices will now be as fast as using them 173- Significantly improve performance of `MatScale()` and `MatAXPY()` for `MATDENSECUDA` and `MATDENSEHIP` in the case where the leading dimension is greater than the number of columns/rows. This situation arises when using e.g. sub-matrices. These routines should be between 3x and 4x faster 174 175```{rubric} MatCoarsen: 176``` 177 178```{rubric} PC: 179``` 180 181- Add `PCHPDDMSetSTShareSubKSP()` 182 183```{rubric} KSP: 184``` 185 186- Add `KSPMonitorDynamicToleranceCreate()` and `KSPMonitorDynamicToleranceSetCoefficient()` 187- Change `-sub_ksp_dynamic_tolerance_param` to `-sub_ksp_dynamic_tolerance` 188- Add support for `MATAIJCUSPARSE` and `VECCUDA` to `KSPHPDDM` 189- Deprecate `KSP_CONVERGED_CG_NEG_CURVE` in favor of `KSP_CONVERGED_NEG_CURVE` 190- Deprecate `KSP_CONVERGED_CG_CONSTRAINED` in favor of `KSP_CONVERGED_STEP_LENGTH` 191- Add fourth kind Chebyshev polynomials; see `KSPChebyshevKind` and `KSPChebyshevSetKind()` 192- Add `KSPSetConvergedNegativeCurvature()` to declare convergence if negative curvature is detected by the Krylov solver 193- Add MINRES-QLP, available via `KSPMINRESSetUseQLP()` or the command line `-ksp_minres_qlp` 194- Replace old MINRES implementation 195- Add `KSPMatSolveTranspose()` 196 197```{rubric} SNES: 198``` 199 200- Add `SNESPruneJacobianColor()` to improve the MFFD coloring 201- Add `SNESVIGetVariableBounds()` to access variable bounds of a `SNESVI` 202 203```{rubric} SNESLineSearch: 204``` 205 206```{rubric} TS: 207``` 208 209- Add `TSPruneIJacobianColor()` to improve the MFFD coloring 210- Add argument to `TSMonitorSPCtxCreate()` to enable multispecies plots 211- Add `TSMonitorHGCtxCreate()`, `TSMonitorHGCtxDestroy()`, `TSMonitorHGSwarmSolution()` to support histogram plots of particle swarms 212- Add support for first-order adjoint calculation for `TSARKIMEX` 213 214```{rubric} TAO: 215``` 216 217```{rubric} DM/DA: 218``` 219 220- Add `DMLabelGetType()`, `DMLabelSetType()`, `DMLabelSetUp()`, `DMLabelRegister()`, `DMLabelRegisterAll()`, `DMLabelRegisterDestroy()` 221- Add `DMLabelEphemeralGetLabel()`, `DMLabelEphemeralSetLabel()`, `DMLabelEphemeralGetTransform()`, `DMLabelEphemeralSetTransform()` 222- Now `DMGetCellDS()`, `DMGetRegionDS()`, `DMSetRegionDS()`, `DMGetRegionNumDS()`, `DMSetRegionNumDS()` can also set and return an input DS 223 224```{rubric} DMSwarm: 225``` 226 227- Add `DMSwarmGetMigrateType()` and `DMSwarmSetMigrateType()` 228 229```{rubric} DMPlex: 230``` 231 232- Add `DMPlexGetOrientedCone()` and `DMPlexRestoreOrientedCone()` to return both cone and orientation together 233- Add `DMPlexTransformGetChart()`, `DMPlexTransformGetCellType()`, `DMPlexTransformGetDepth()`, `DMPlexTransformGetDepthStratum()`, `DMPlexTransformGetConeSize()` to enable ephemeral meshes 234- Remove `DMPlexAddConeSize()` 235- Add `DMPlexCreateEphemeral()` 236- Both `DMView()` and `DMLoad()` now support parallel I/O with a new HDF5 format (see the manual for details) 237- Remove `DMPlexComputeGeometryFEM()` since it was broken 238- Change `DMPlexMarkBoundaryFaces()` to avoid marking faces on the parallel boundary. To get the prior behavior, you can temporarily remove the `PointSF` from the `DM` 239- Add `-dm_localize_height` to localize edges and faces 240- Add `DMPlexCreateHypercubicMesh()` to create hypercubic meshes needed for QCD 241- Add `-dm_plex_shape zbox` option to `DMSetFromOptions()` to generated born-parallel meshes in Z-ordering (a space-filling curve). This may be used as-is with `-petscpartitioner_type simple` or redistributed using `-petscpartitioner_type parmetis` (or `ptscotch`, etc.), which is more scalable than creating a serial mesh to partition and distribute. 242- Add `DMPlexSetIsoperiodicFaceSF()` to wrap a non-periodic mesh into periodic while preserving the local point representation for both donor and image sheet. This is supported with `zbox` above, and allows single-element periodicity. 243- Now `DMPlexGetCompressedClosure()` also takes the point orientation 244- Add `DMPlexReorderCohesiveSupports()` 245 246```{rubric} FE/FV: 247``` 248 249- Add `DMPlexGetLocalOffsetsSupport()` for interaction with libCEED for FV 250- Now `PetscFEIntegrateHybridResidual()` and `PetscFEIntegrateHybridJacobian()` also take the input DS 251 252```{rubric} DMNetwork: 253``` 254 255- Add DMNetworkGetNumVertices to retrieve the local and global number of vertices in DMNetwork 256- Add DMNetworkGetNumEdges to retrieve the local and global number of edges in DMNetwork 257- Add the ability to use `DMView()` on a DMNetwork with a PetscViewer with format `PETSC_VIEWER_ASCII_CSV` 258- Add the ability to use `-dmnetwork_view draw` and `-dmnetwork_view_distributed draw` to visualize a DMNetwork with an associated coordinate DM. This currently requires the configured Python environment to have `matplotlib` and `pandas` installed 259 260```{rubric} DMStag: 261``` 262 263```{rubric} DT: 264``` 265 266- Add `PetscDTCreateDefaultQuadrature()` 267- Add `PetscQuadratureComputePermutations()` to compute the quadrature permutation corresponding to a k-cell orientation and `PetscDSPermuteQuadPoint()` 268- Add `PetscQuadratureGetCellType()` and `PetscQuadratureSetCellType()` 269- Add `PetscDSCopy()` 270 271```{rubric} Fortran: 272``` 273 274- Add `MatMPIAIJGetSeqAIJF90()`, `MatMPIAIJRestoreSeqAIJF90()` 275- Deprecate `ISGetIndices()` in favor of `ISGetIndicesF90()` 276- Deprecate `ISRestoreIndices()` in favor of `ISRestoreIndicesF90()` 277- Deprecate `ISLocalToGlobalMappingGetIndices()` in favor of `ISLocalToGlobalMappingGetIndicesF90()` 278- Deprecate `ISLocalToGlobalMappingRestoreIndices()` in favor of `ISLocalToGlobalMappingRestoreIndicesF90()` 279- Deprecate `VecGetArray()` in favor of `VecGetArrayF90()` 280- Deprecate `VecRestoreArray()` in favor of `VecRestoreArrayF90()` 281- Deprecate `VecGetArrayRead()` in favor of `VecGetArrayReadF90()` 282- Deprecate `VecRestoreArrayRead()` in favor of `VecRestoreArrayReadF90()` 283- Deprecate `VecDuplicateVecs()` in favor of `VecDuplicateVecsF90()` 284- Deprecate `VecDestroyVecs()` in favor of `VecDestroyVecsF90()` 285- Deprecate `DMDAVecGetArray()` in favor of `DMDAVecGetArrayF90()` 286- Deprecate `DMDAVecRestoreArray()` in favor of `DMDAVecRestoreArrayF90()` 287- Deprecate `DMDAVecGetArrayRead()` in favor of `DMDAVecGetArrayReadF90()` 288- Deprecate `DMDAVecRestoreArrayRead()` in favor of `DMDAVecRestoreArrayReadF90()` 289- Deprecate `DMDAVecGetArrayWrite()` in favor of `DMDAVecGetArrayWriteF90()` 290- Deprecate `DMDAVecRestoreArrayWrite()` in favor of `DMDAVecRestoreArrayWriteF90()` 291- Deprecate `MatGetRowIJ()` in favor of `MatGetRowIJF90()` 292- Deprecate `MatRestoreRowIJ()` in favor of `MatRestoreRowIJF90()` 293- Deprecate `MatSeqAIJGetArray()` in favor of `MatSeqAIJGetArrayF90()` 294- Deprecate `MatSeqAIJRestoreArray()` in favor of `MatSeqAIJRestoreArrayF90()` 295- Deprecate `MatMPIAIJGetSeqAIJ()` in favor of `MatMPIAIJGetSeqAIJF90()` 296- Deprecate `MatDenseGetArray()` in favor of `MatDenseGetArrayF90()` 297- Deprecate `MatDenseRestoreArray()` in favor of `MatDenseRestoreArrayF90()` 298