# Changes: 3.19 % STYLE GUIDELINES: % * Capitalize sentences % * Use imperative, e.g., Add, Improve, Change, etc. % * Don't use a period (.) at the end of entries % * If multiple sentences are needed, use a period or semicolon to divide sentences, but not at the end of the final sentence ```{rubric} General: ``` - Add perfstubs package, see {ref}`Users Manual: Profiling: Using TAU ` for more information on usage ```{rubric} Configure/Build: ``` - 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` - Deprecate `--with-gcov` configure option in favor of `--with-coverage` - Add `--with-coverage-exec` configure option to specify the coverage-collection tool to be used e.g. `gcov` or `/path/to/llvm-cov-15` - Add `--with-strict-petscerrorcode` configure option to enable compile-time checking for correct usage of `PetscErrorCode`, see below - Add support for C++20 - Add support for CUDA-12 - 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 ```{rubric} Sys: ``` - Change `PetscOptionsMonitorDefault()` to also take in the option source, and `PetscOptionsMonitorSet()` to take the new monitor function - 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: 1. `#include ` must be swapped for `#include `. This of course requires that you have access to the private PETSc headers. 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: ``` // PetscHMapI hash_table; // PetscInt key; PetscHashIter it; PetscBool missing; PetscCall(PetscHMapIPut(hash_table, key, &it, &missing)); if (missing) { PetscInt size; PetscCall(PetscHMapIGetSize(hash_table, &size)); PetscCall(PetscHMapIIterSet(hash_table, it, size)); } ``` 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. - 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: ``` MPI_Comm comm; MPI_Win win; // old PetscCall(PetscPrintf(..., "MPI Comm %" PETSC_MPI_COMM_FMT, comm)); PetscCall(PetscPrintf(..., "MPI Window %" PETSC_MPI_WIN_FMT, win)); // new PetscCall(PetscPrintf(..., "MPI Comm %" PETSC_INTPTR_T_FMT, (PETSC_INTPTR_T)comm)); PetscCall(PetscPrintf(..., "MPI Window %" PETSC_INTPTR_T_FMT, (PETSC_INTPTR_T)win)); ``` - Deprecate `PETSC_NULL` in favor of `PETSC_NULLPTR` as it does the right thing in both C and C++ - Significantly improve lookup and deletion performance of `PetscFunctionList`. This also improves performance of `PetscObjectComposeFunction()` and `PetscObjectQueryFunction()`. - 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: 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. 2. Using the wrong `PetscCall()` variant, for example using `PetscCall()` on MPI functions (instead of `PetscCallMPI()`). 3. Returning `PetscErrorCode` from `main()` instead of `int`. Users should note that this comes with the following additional changes: 1. Add `PETSC_SUCCESS` to indicate success, always guaranteed to equal `0`. 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++. 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`: ``` // Both foo() and bar() defined as returning PetscErrorCode extern PetscErrorCode foo(int); extern PetscErrorCode bar(int); // The following macros logically "return" a PetscErrorCode, i.e. can // be used: // // PetscCall(MY_USER_MACRO(a, b)); // // but use boolean short-circuiting to chain the calls together. bar() // only executes if foo() returns PETSC_SUCCESS // old #define MY_USER_MACRO(a, b) (foo(a) || bar(b)) // new #define MY_BETTER_USER_MACRO(a, b) ((PetscErrorCode)(foo(a) || bar(b))) ``` 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. - Add `PetscFFlush()` - 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()` - Add `PETSC_REAL_MIN` for smallest normalized floating point number - Add `PETSC_ATTRIBUTE_MAY_ALIAS` to inform compilers that a type is not subjected to type-based alias analysis ```{rubric} Event Logging: ``` ```{rubric} PetscViewer: ``` - The VTK viewers (`.vts`, `.vtr`, and `.vtu`) now use `header_type="UInt64"` to enable writing large binary appended blocks ```{rubric} PetscDraw: ``` - Add `PetscDrawSetVisible()` to set if the drawing surface (the 'window') is visible on its display ```{rubric} AO: ``` ```{rubric} IS: ``` - Change `ISDuplicate()` to preserve the block size of the input in the output - Deprecate `ISCompressIndicesSorted()` ```{rubric} VecScatter / PetscSF: ``` - 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` - Add an alias option `-sf_use_gpu_aware_mpi` to `-use_gpu_aware_mpi` - Remove `SCATTER_LOCAL` from the enum type since it is not a public value - Change `PetscSFConcatenate()` to accept `PetscSFConcatenateRootMode` parameter; add option to concatenate root spaces globally - Add `PetscSFSetGraphFromCoordinates()` to construct a graph from fuzzy matching of coordinates; such as occurs for projections between different dimensions or for overlapping meshes ```{rubric} PF: ``` ```{rubric} Vec: ``` - Document `VecOperation` - Add `VECOP_SET` - Significantly improve performance of `VecMDot()`, `VecMAXPY()` and `VecDotNorm2()` for CUDA and HIP vector types. These routines should be between 2x and 4x faster. - 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 ```{rubric} PetscSection: ``` ```{rubric} PetscPartitioner: ``` ```{rubric} Mat: ``` - `MatSetValues()` and friends will now provide reasonable performance when no preallocation information is provided - Add `MatEliminateZeros()` - Improve efficiency of `MatConvert()` from `MATNORMAL` to `MATHYPRE` - Add `MatDenseGetArrayAndMemType()`, `MatDenseRestoreArrayAndMemType()`, `MatDenseGetArrayReadAndMemType()`, `MatDenseRestoreArrayReadAndMemType()`, `MatDenseGetArrayWriteAndMemType()` and `MatDenseRestoreArrayWriteAndMemType()` to return the array and memory type of a dense matrix - Deprecate all MatPreallocate\* routines. These are no longer needed since non-preallocated matrices will now be as fast as using them - 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 ```{rubric} MatCoarsen: ``` ```{rubric} PC: ``` - Add `PCHPDDMSetSTShareSubKSP()` ```{rubric} KSP: ``` - Add `KSPMonitorDynamicToleranceCreate()` and `KSPMonitorDynamicToleranceSetCoefficient()` - Change `-sub_ksp_dynamic_tolerance_param` to `-sub_ksp_dynamic_tolerance` - Add support for `MATAIJCUSPARSE` and `VECCUDA` to `KSPHPDDM` - Deprecate `KSP_CONVERGED_CG_NEG_CURVE` in favor of `KSP_CONVERGED_NEG_CURVE` - Deprecate `KSP_CONVERGED_CG_CONSTRAINED` in favor of `KSP_CONVERGED_STEP_LENGTH` - Add fourth kind Chebyshev polynomials; see `KSPChebyshevKind` and `KSPChebyshevSetKind()` - Add `KSPSetConvergedNegativeCurvature()` to declare convergence if negative curvature is detected by the Krylov solver - Add MINRES-QLP, available via `KSPMINRESSetUseQLP()` or the command line `-ksp_minres_qlp` - Replace old MINRES implementation - Add `KSPMatSolveTranspose()` ```{rubric} SNES: ``` - Add `SNESPruneJacobianColor()` to improve the MFFD coloring - Add `SNESVIGetVariableBounds()` to access variable bounds of a `SNESVI` ```{rubric} SNESLineSearch: ``` ```{rubric} TS: ``` - Add `TSPruneIJacobianColor()` to improve the MFFD coloring - Add argument to `TSMonitorSPCtxCreate()` to enable multispecies plots - Add `TSMonitorHGCtxCreate()`, `TSMonitorHGCtxDestroy()`, `TSMonitorHGSwarmSolution()` to support histogram plots of particle swarms - Add support for first-order adjoint calculation for `TSARKIMEX` ```{rubric} TAO: ``` ```{rubric} DM/DA: ``` - Add `DMLabelGetType()`, `DMLabelSetType()`, `DMLabelSetUp()`, `DMLabelRegister()`, `DMLabelRegisterAll()`, `DMLabelRegisterDestroy()` - Add `DMLabelEphemeralGetLabel()`, `DMLabelEphemeralSetLabel()`, `DMLabelEphemeralGetTransform()`, `DMLabelEphemeralSetTransform()` - Now `DMGetCellDS()`, `DMGetRegionDS()`, `DMSetRegionDS()`, `DMGetRegionNumDS()`, `DMSetRegionNumDS()` can also set and return an input DS ```{rubric} DMSwarm: ``` - Add `DMSwarmGetMigrateType()` and `DMSwarmSetMigrateType()` ```{rubric} DMPlex: ``` - Add `DMPlexGetOrientedCone()` and `DMPlexRestoreOrientedCone()` to return both cone and orientation together - Add `DMPlexTransformGetChart()`, `DMPlexTransformGetCellType()`, `DMPlexTransformGetDepth()`, `DMPlexTransformGetDepthStratum()`, `DMPlexTransformGetConeSize()` to enable ephemeral meshes - Remove `DMPlexAddConeSize()` - Add `DMPlexCreateEphemeral()` - Both `DMView()` and `DMLoad()` now support parallel I/O with a new HDF5 format (see the manual for details) - Remove `DMPlexComputeGeometryFEM()` since it was broken - Change `DMPlexMarkBoundaryFaces()` to avoid marking faces on the parallel boundary. To get the prior behavior, you can temporarily remove the `PointSF` from the `DM` - Add `-dm_localize_height` to localize edges and faces - Add `DMPlexCreateHypercubicMesh()` to create hypercubic meshes needed for QCD - 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. - 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. - Now `DMPlexGetCompressedClosure()` also takes the point orientation - Add `DMPlexReorderCohesiveSupports()` ```{rubric} FE/FV: ``` - Add `DMPlexGetLocalOffsetsSupport()` for interaction with libCEED for FV - Now `PetscFEIntegrateHybridResidual()` and `PetscFEIntegrateHybridJacobian()` also take the input DS ```{rubric} DMNetwork: ``` - Add DMNetworkGetNumVertices to retrieve the local and global number of vertices in DMNetwork - Add DMNetworkGetNumEdges to retrieve the local and global number of edges in DMNetwork - Add the ability to use `DMView()` on a DMNetwork with a PetscViewer with format `PETSC_VIEWER_ASCII_CSV` - 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 ```{rubric} DMStag: ``` ```{rubric} DT: ``` - Add `PetscDTCreateDefaultQuadrature()` - Add `PetscQuadratureComputePermutations()` to compute the quadrature permutation corresponding to a k-cell orientation and `PetscDSPermuteQuadPoint()` - Add `PetscQuadratureGetCellType()` and `PetscQuadratureSetCellType()` - Add `PetscDSCopy()` ```{rubric} Fortran: ``` - Add `MatMPIAIJGetSeqAIJF90()`, `MatMPIAIJRestoreSeqAIJF90()` - Deprecate `ISGetIndices()` in favor of `ISGetIndicesF90()` - Deprecate `ISRestoreIndices()` in favor of `ISRestoreIndicesF90()` - Deprecate `ISLocalToGlobalMappingGetIndices()` in favor of `ISLocalToGlobalMappingGetIndicesF90()` - Deprecate `ISLocalToGlobalMappingRestoreIndices()` in favor of `ISLocalToGlobalMappingRestoreIndicesF90()` - Deprecate `VecGetArray()` in favor of `VecGetArrayF90()` - Deprecate `VecRestoreArray()` in favor of `VecRestoreArrayF90()` - Deprecate `VecGetArrayRead()` in favor of `VecGetArrayReadF90()` - Deprecate `VecRestoreArrayRead()` in favor of `VecRestoreArrayReadF90()` - Deprecate `VecDuplicateVecs()` in favor of `VecDuplicateVecsF90()` - Deprecate `VecDestroyVecs()` in favor of `VecDestroyVecsF90()` - Deprecate `DMDAVecGetArray()` in favor of `DMDAVecGetArrayF90()` - Deprecate `DMDAVecRestoreArray()` in favor of `DMDAVecRestoreArrayF90()` - Deprecate `DMDAVecGetArrayRead()` in favor of `DMDAVecGetArrayReadF90()` - Deprecate `DMDAVecRestoreArrayRead()` in favor of `DMDAVecRestoreArrayReadF90()` - Deprecate `DMDAVecGetArrayWrite()` in favor of `DMDAVecGetArrayWriteF90()` - Deprecate `DMDAVecRestoreArrayWrite()` in favor of `DMDAVecRestoreArrayWriteF90()` - Deprecate `MatGetRowIJ()` in favor of `MatGetRowIJF90()` - Deprecate `MatRestoreRowIJ()` in favor of `MatRestoreRowIJF90()` - Deprecate `MatSeqAIJGetArray()` in favor of `MatSeqAIJGetArrayF90()` - Deprecate `MatSeqAIJRestoreArray()` in favor of `MatSeqAIJRestoreArrayF90()` - Deprecate `MatMPIAIJGetSeqAIJ()` in favor of `MatMPIAIJGetSeqAIJF90()` - Deprecate `MatDenseGetArray()` in favor of `MatDenseGetArrayF90()` - Deprecate `MatDenseRestoreArray()` in favor of `MatDenseRestoreArrayF90()`