Changes: 3.19#
General:
- Add perfstubs package, see Users Manual: Profiling: Using TAU for more information on usage 
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-gcovconfigure option in favor of- --with-coverage
- Add - --with-coverage-execconfigure option to specify the coverage-collection tool to be used e.g.- gcovor- /path/to/llvm-cov-15
- Add - --with-strict-petscerrorcodeconfigure 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 - configurewill fail faster and with a more informative error message when the C++ compiler does not comply with restraints
Sys:
- Change - PetscOptionsMonitorDefault()to also take in the option source, and- PetscOptionsMonitorSet()to take the new monitor function
- Deprecate - PetscTableand related functions. Previous users of- PetscTableare encouraged to use the more performant- PetscHMapIinstead, though they should note that this requires additional steps and limitations:- #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.
- While most of the old - PetscTableroutines 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 - PetscHMapIis based on – and directly- #includes –- ${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_FMTand- PETSC_MPI_COMM_FMT. Users should cast both- MPI_Command- MPI_Winto- PETSC_INTPTR_Tand use the- PETSC_INTPTR_T_FMTformat 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_NULLin favor of- PETSC_NULLPTRas 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 - PetscErrorCodeas an- enum, and tag it as- PETSC_NODISCARD. This feature may be enabled by configuring PETSc with- --with-strict-petscerrorcodeconfigure option. This feature allows catching the following logical errors at compile-time:- 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.
- Using the wrong - PetscCall()variant, for example using- PetscCall()on MPI functions (instead of- PetscCallMPI()).
- Returning - PetscErrorCodefrom- main()instead of- int.
 - Users should note that this comes with the following additional changes: - Add - PETSC_SUCCESSto indicate success, always guaranteed to equal- 0.
- 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++.
- 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_SUCCESSis 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_MINfor smallest normalized floating point number
- Add - PETSC_ATTRIBUTE_MAY_ALIASto inform compilers that a type is not subjected to type-based alias analysis
Event Logging:
PetscViewer:
- The VTK viewers ( - .vts,- .vtr, and- .vtu) now use- header_type="UInt64"to enable writing large binary appended blocks
PetscDraw:
- Add - PetscDrawSetVisible()to set if the drawing surface (the ‘window’) is visible on its display
AO:
IS:
- Change - ISDuplicate()to preserve the block size of the input in the output
- Deprecate - ISCompressIndicesSorted()
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_mpito- -use_gpu_aware_mpi
- Remove - SCATTER_LOCALfrom the enum type since it is not a public value
- Change - PetscSFConcatenate()to accept- PetscSFConcatenateRootModeparameter; 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
PF:
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
PetscSection:
PetscPartitioner:
Mat:
- MatSetValues()and friends will now provide reasonable performance when no preallocation information is provided
- Add - MatEliminateZeros()
- Improve efficiency of - MatConvert()from- MATNORMALto- 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- MATDENSECUDAand- MATDENSEHIPin 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
MatCoarsen:
PC:
- Add - PCHPDDMSetSTShareSubKSP()
KSP:
- Add - KSPMonitorDynamicToleranceCreate()and- KSPMonitorDynamicToleranceSetCoefficient()
- Change - -sub_ksp_dynamic_tolerance_paramto- -sub_ksp_dynamic_tolerance
- Add support for - MATAIJCUSPARSEand- VECCUDAto- KSPHPDDM
- Deprecate - KSP_CONVERGED_CG_NEG_CURVEin favor of- KSP_CONVERGED_NEG_CURVE
- Deprecate - KSP_CONVERGED_CG_CONSTRAINEDin favor of- KSP_CONVERGED_STEP_LENGTH
- Add fourth kind Chebyshev polynomials; see - KSPChebyshevKindand- 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()
SNES:
- Add - SNESPruneJacobianColor()to improve the MFFD coloring
- Add - SNESVIGetVariableBounds()to access variable bounds of a- SNESVI
SNESLineSearch:
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
TAO:
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
DMSwarm:
- Add - DMSwarmGetMigrateType()and- DMSwarmSetMigrateType()
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- PointSFfrom the- DM
- Add - -dm_localize_heightto localize edges and faces
- Add - DMPlexCreateHypercubicMesh()to create hypercubic meshes needed for QCD
- Add - -dm_plex_shape zboxoption to- DMSetFromOptions()to generated born-parallel meshes in Z-ordering (a space-filling curve). This may be used as-is with- -petscpartitioner_type simpleor 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- zboxabove, and allows single-element periodicity.
- Now - DMPlexGetCompressedClosure()also takes the point orientation
FE/FV:
- Add - DMPlexGetLocalOffsetsSupport()for interaction with libCEED for FV
- Now - PetscFEIntegrateHybridResidual()and- PetscFEIntegrateHybridJacobian()also take the input DS
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 drawand- -dmnetwork_view_distributed drawto visualize a DMNetwork with an associated coordinate DM. This currently requires the configured Python environment to have- matplotliband- pandasinstalled
DMStag:
DT:
- Add - PetscQuadratureComputePermutations()to compute the quadrature permutation corresponding to a k-cell orientation and- PetscDSPermuteQuadPoint()
- Add - PetscQuadratureGetCellType()and- PetscQuadratureSetCellType()
- Add - PetscDSCopy()
Fortran:
- 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()