1# Changes: 3.20 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 `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsInt()`, `PetscOptionsBool()`, `PetscOptionsIntArray()`, 13 `PetscOptionsReal()`, `PetscOptionsRealArray()`, and `PetscOptionsScalar()` for Fortran 14- Add `PetscAssertPointer()` as a replacement for `PetscValidPointer()`, `PetscValidCharPointer()`, `PetscValidIntPointer()`, `PetscValidInt64Pointer()`, `PetscValidCountPointer()`, `PetscValidBoolPointer()`, `PetscvalidScalarPointer()`, and `PetscValidRealPointer()` 15- Convert standard header-guards in PETSc header-files to `#pragma once`. Users relying on specific preprocessor definitions to determine whether particular PETSc headers (e.g. `petscdm.h` used to be guarded by `PETSCDM_H`) have been included will find that this no longer works. While header-guards are technically "public" (insofar that they appear in public header-files), their name and value are considered implementation details 16 17```{rubric} Configure/Build: 18``` 19 20- Add support for external-packages to prefer tarball download for regular use - as currently all packages prefer git clones. MPICH is a package using this feature. Here MPICH tarball will be downloaded for regular use. However on providing `--download-mpich-commit=main` option - configure download and builds from MPICH git repository 21- Add support for external package SLATE, optional dependency for STRUMPACK 22- Add support for external package ZFP, optional dependency for STRUMPACK 23- Add support for external package ButterflyPACK, optional dependency for STRUMPACK 24 25```{rubric} Sys: 26``` 27 28- Add `PetscDeviceContextGetStreamHandle()` to return a handle to the stream the current device context is using 29- Add utility functions `PetscGetCurrentCUDAStream()` and `PetscGetCurrentHIPStream()` to return the GPU stream the current device context is using 30- Add `PetscStrcmpAny()` to compare against multiple non-empty strings 31- Change arguments 4 and 5 of `PetscViewerBinaryReadAll()` and `PetscViewerBinaryWriteAll()` to `PetscInt64` 32- Add `PetscIsCloseAtTolScalar()` 33- Remove `PetscTellMyCell()` and related runtime option 34- Remove `PetscTextBelt()` and related runtime option 35- Remove deprecated `-malloc [no]` startup option 36- Remove deprecated `-malloc_info` startup option 37- Remove deprecated `-log_summary` option 38- Remove `PetscURLShorten()`, it has not worked since 2019 39- Move `PetscIntStackCreate()`, `PetscIntStackDestroy()`, `PetscIntStackPush()`, `PetscIntStackPop()`, and `PetscIntStackEmpty()` declarations to public API in `petsclog.h` 40- Add `-on_error_malloc_dump` option 41 42```{rubric} Event Logging: 43``` 44 45- Add `PetscLogState` interface for describing profiling events and stages 46- Add `PetscLogHandler` interface that interprets the profiling events of a `PetscLogState` 47- Add `PETSCLOGHANDLERDEFAULT` implementation of `PetscLogHandler` 48- Add `PETSCLOGHANDLERNESTED` implementation of `PetscLogHandler` 49- Add `PETSCLOGHANDLERTRACE` implementation of `PetscLogHandler` 50- Add `PetscLogHandlerCreateTrace()` 51- Add `PETSCLOGHANDLERMPE` implementation of `PetscLogHandler` 52- Add `PETSCLOGHANDLERPERFSTUBS` implementation of `PetscLogHandler` 53- Add `PETSCLOGHANDLERLEGACY` implementation of `PetscLogHandler` 54- Add `PetscLogHandlerCreateLegacy()` 55- Add `PetscLogPerfstubsBegin()` for log handling with PerfStubs/TAU 56- Add `PetscLogLegacyCallbacksBegin()` to transition old log handler callbacks to the `PetscLogHandler`-based approach 57- Add `PetscLogHandlerStart()` to connect a `PetscLogHandler` to PETSc's global logging events 58- Add `PetscLogStageGetName()` 59- Add `PetscLogEventGetName()` 60- Add `PetscLogEventsPause()` and `PetscLogEventsResume()` to isolate a logging event from unrelated in-process events 61- Add `PetscLogClassGetClassId()` 62- Add `PetscLogClassIdGetName()` 63- Deprecate `PetscLogClassPerfInfoClear()` , `PetscLogClassPerfLogCreate()`, and `PetscLogClassPerfLogDestroy()` 64- Deprecate `PetscClassPerfLogEnsureSize()`, `PetscClassRegInfoDestroy()`, `PetscClassRegLogCreate()`, `PetscClassRegLogDestroy()`, `PetscClassRegLogGetClass()`, and `PetscClassRegLogRegister()` 65- Deprecate `PetscEventPerfInfoClear()` and `PetscEventPerfInfoCopy()` 66- Deprecate `PetscEventPerfLogActivate()`, `PetscEventPerfLogActivateClass()`, `PetscEventPerfLogCreate()`, `PetscEventPerfLogDeactivate()`, `PetscEventPerfLogDeactivateClass()`, `PetscEventPerfLogDeactivatePop()`, `PetscEventPerfLogDeactivatePush()`, `PetscEventPerfLogDestroy()`, `PetscEventPerfLogEnsureSize()`, `PetscEventPerfLogGetVisible()`, and `PetscEventPerfLogSetVisible()` 67- Deprecate `PetscEventRegLogCreate()`, `PetscEventRegLogDestroy()`, `PetscEventRegLogGetEvent()`, and `PetscEventRegLogRegister()` 68- Deprecate `PetscStageLogCreate()`, `PetscStageLogDestroy()`, `PetscStageLogGetActive()`, `PetscStageLogGetClassPerfLog()`, `PetscStageLogGetClassRegLog()`, `PetscStageLogGetEventRegLog()`, `PetscStageLogGetStage()`, `PetscStageLogGetVisible()`, `PetscStageLogPop()`, `PetscStageLogPush()`, `PetscStageLogRegister()`, `PetscStageLogSetActive()`, `PetscStageLogSetVisible()`, `PetscStageLogGetCurrent()`, and `PetscStageLogGetEventPerfLog()` 69- Deprecate `PetscLogGetStageLog()` 70- Deprecate `PetscLogPushCurrentEvent_Internal()` 71- Deprecate `PetscLogPopCurrentEvent_Internal()` 72- Deprecate `PetscLogAllBegin()` 73- Deprecate `PetscLogSet()` 74- Add `PetscLogHandlerGetEventPerfInfo()` 75- Add `PetscLogHandlerSetLogActions()` 76- Add `PetscLogHandlerSetLogObjects()` 77- Add `PetscLogHandlerLogObjectState()` 78- Add `PetscLogHandlerGetNumObjects()` 79- Add `PetscLogHandlerEventDeactivatePush()` 80- Add `PetscLogHandlerEventDeactivatePop()` 81- Add `PetscLogHandlerEventsPause()` 82- Add `PetscLogHandlerEventsResume()` 83- Add `PetscLogHandlerDump()` 84- Add `PetscLogHandlerStageSetVisible()` 85- Add `PetscLogHandlerStageGetVisible()` 86- Add `PetscLogHandlerGetStagePerfInfo()` 87- Add `PetscLogStageGetPerfInfo()` 88- Add `PETSCLOGHANDLERNVTX` implementation of `PetscLogHandler` 89 90```{rubric} PetscViewer: 91``` 92 93- Add `PetscViewerASCIIOpenWithFileUnit()` and `PetscViewerASCIISetFileUnit()` 94 95```{rubric} PetscDraw: 96``` 97 98```{rubric} AO: 99``` 100 101```{rubric} IS: 102``` 103 104```{rubric} VecScatter / PetscSF: 105``` 106 107```{rubric} PF: 108``` 109 110```{rubric} Vec: 111``` 112 113- Add `VecErrorWeightedNorms()` to unify weighted local truncation error norms used in `TS` 114- Add CUDA/HIP implementations for `VecAbs()`, `VecSqrtAbs()`, `VecExp()`, `VecLog()`, `VecPointwiseMax()`, `VecPointwiseMaxAbs()`, and `VecPointwiseMin()` 115- Add `VecMAXPBY()` 116- Deprecate `VecChop()` in favor of `VecFilter()` 117- Add `VecCreateFromOptions()` 118 119```{rubric} PetscSection: 120``` 121 122- Add `PetscSectionResetClosurePermutation()` 123 124```{rubric} PetscPartitioner: 125``` 126 127```{rubric} Mat: 128``` 129 130- Add `MatCreateDenseFromVecType()` 131- Add support for calling `MatDuplicate()` on a matrix preallocated via `MatSetPreallocationCOO()`, and then `MatSetValuesCOO()` on the new matrix 132- Remove `MATSOLVERSPARSEELEMENTAL` since it is no longer functional 133- Add `MATSELLCUDA`. It supports fast `MatMult()`, `MatMultTranspose()`, and `MatMultAdd()` on GPUs 134- Add support for `MAT_FACTOR_LU` and `MAT_FACTOR_CHOLESKY` with `MATSOLVERMUMPS` for `MATNEST` 135- `MatGetFactor()` can now return `NULL` for some combinations of matrices and solvers types. This is to support those combinations that can only be inspected at runtime (i.e. MatNest with AIJ blocks vs MatNest with SHELL blocks) 136- Remove `MatSetValuesDevice()`, `MatCUSPARSEGetDeviceMatWrite()`, `MatKokkosGetDeviceMatWrite` 137- Add `MatDenseCUDASetPreallocation()` and `MatDenseHIPSetPreallocation()` 138- Add support for KOKKOS in `MATH2OPUS` 139- Add `-pc_precision single` option for use with `MATSOLVERSUPERLU_DIST` 140- Add `MATDIAGONAL` which can be created with `MatCreateDiagonal()` 141- Add `MatDiagonalGetDiagonal()`, `MatDiagonalRestoreDiagonal()`, `MatDiagonalGetInverseDiagonal()`, and `MatDiagonalRestoreInverseDiagonal()` 142- Add support for `MatLoad()` and `MatView()` to load and store `MATMPIAIJ` matrices that have more than `PETSC_INT_MAX` nonzeros, so long as each rank has fewer than `PETSC_INT_MAX` 143- Add `MatLRCSetMats()` and register creation routine for `MatLRC` 144- Add CUDA/HIP implementation for `MatGetDiagonal()` 145- Add a Boolean parameter to `MatEliminateZeros()` to force the removal of zero diagonal coefficients 146- Expose `MatComputeVariableBlockEnvelope()` in public headers 147- Add `MatEliminateZeros()` implementations for `MatBAIJ` and `MatSBAIJ` 148- Deprecate `MatChop()` in favor of `MatFilter()`, with two additional Boolean parameters to compress the underlying storage and keep or discard near-zero diagonal coefficients 149- Add `MatCreateFromOptions()` 150- Add `MatSTRUMPACKGetReordering()`, `MatSTRUMPACKSetGeometricNxyz()`, `MatSTRUMPACKSetGeometricComponents()`, `MatSTRUMPACKSetGeometricWidth()`, `MatSTRUMPACKGetColPerm()`, `MatSTRUMPACKSetGPU()`, `MatSTRUMPACKGetGPU()`, `MatSTRUMPACKSetCompression()`, `MatSTRUMPACKGetCompression()`, `MatSTRUMPACKSetCompRelTol()`, `MatSTRUMPACKGetCompRelTol()`, `MatSTRUMPACKSetCompAbsTol()`, `MatSTRUMPACKGetCompAbsTol()`, `MatSTRUMPACKSetCompMinSepSize()`, `MatSTRUMPACKGetCompMinSepSize()`, `MatSTRUMPACKSetCompLeafSize()`, `MatSTRUMPACKGetCompLeafSize()`, `MatSTRUMPACKSetCompLossyPrecision()`, `MatSTRUMPACKGetCompLossyPrecision()`, `MatSTRUMPACKSetCompButterflyLevels()`, `MatSTRUMPACKGetCompButterflyLevels()` 151- Add `MAT_STRUMPACK_GEOMETRIC`, `MAT_STRUMPACK_AMD`, `MAT_STRUMPACK_MMD`, `MAT_STRUMPACK_AND`, `MAT_STRUMPACK_MLF`, `MAT_STRUMPACK_SPECTRAL` to `MatSTRUMPACKReordering` 152- Add `MatSTRUMPACKCompressionType` 153- Remove `MatSTRUMPACKSetHSSLeafSize()`, `MatSTRUMPACKSetHSSMaxRank()`, `MatSTRUMPACKSetHSSMinSize()`, `MatSTRUMPACKSetHSSMinSepSize()`, `MatSTRUMPACKSetHSSAbsTol()`, `MatSTRUMPACKSetHSSRelCompTol()`, `MatSTRUMPACKSetHSSRelTol()` 154 155```{rubric} MatCoarsen: 156``` 157 158```{rubric} PC: 159``` 160 161- Add `PCMatGetApplyOperation()` and `PCMatSetApplyOperation()` 162- Add `PCReduceFailedReason()` 163- Add `PCSetKSPNestLevel()` and `PCSetKSPNestLevel()` 164- Refactor `PCMPI` to be a private system used automatically when `-mpi_linear_solver_server` is used. The `KSP` and `PC` objects that solve the system now inherit any prefix provided 165 initially with `KSPSetPrefix()` and do not require the previously required `mpi_` prefix 166- Add option `-fieldsplit_1_pc_hpddm_schur_precondition` to use `PCHPDDM` on the Schur complements from `PCFIELDSPLIT` 167- Add `PCGAMGSetAggressiveSquareGraph()` to use square graph method for aggressive coarsening that was the previous default coarsening approach before release 3.19 168- Add `PCGAMGSetAggressiveMISk()` to set the number of levels (k) of aggressive MIS-k coarsening (2 is very common) 169- Add `PCGAMGSetMinDegreeOrderingMISk()` to use a minimum degree ordering for the (greedy) MIS-k algorithm 170- Change `PCGAMGSetUseParallelCoarseGridSolve()` to `PCGAMGSetParallelCoarseGridSolve()` 171- Add `PCGAMGSetRecomputeEstEig()` to set flag to have Chebyshev recompute its eigen estimates (default set to true) 172 173```{rubric} KSP: 174``` 175 176- Add `KSPSetMinimumIterations()` and `KSPGetMinimumIterations()` 177- Add `KSPSetNestLevel()` and `KSPGetNestLevel()` 178- Support `KSPSetInitialGuessNonzero()` with `KSPPREONLY` and `PCDISTRIBUTE` when it is called on both the outer and inner `KSP` 179 180```{rubric} SNES: 181``` 182 183- Add a convenient, developer-level `SNESConverged()` function that runs the convergence test and updates the internal converged reason 184- Swap the order of monitor and convergence test. Now monitors are always called after a convergence test 185- Deprecate option `-snes_ms_norms` in favor of `-snes_norm_schedule always` 186 187```{rubric} SNESLineSearch: 188``` 189 190```{rubric} TS: 191``` 192 193- Remove `TSErrorWeightedNormInfinity()`, `TSErrorWeightedNorm2()`, `TSErrorWeightedENormInfinity()`, `TSErrorWeightedENorm2()` since the same functionality can be obtained with `VecErrorWeightedNorms()` 194- Add support for time-dependent solvers with varying solution size using `TSSetResize()` 195- Add support for Diagonally Implicit Runge-Kutta methods with the new `TSDIRK` type 196 197```{rubric} TAO: 198``` 199 200- Add `TaoADMMGetRegularizerCoefficient()` 201- Add `TAOBNCG`, `TaoBNCGGetType()` and `TaoBNCGSetType()` 202 203```{rubric} DM/DA: 204``` 205 206- Add support for `DMDAGetElements()` for Fortran 207- Add support for clearing named vectors with `DMClearNamedGlobalVectors()` and `DMClearNamedLocalVectors()` 208- Add `DMPrintCellIndices()` for debugging 209- Add `DMUseTensorOrder()` 210- Add `DMCeedCreate()`, `DMCeedComputeGeometry()`, and `DMCeedDestroy()` 211 212```{rubric} DMSwarm: 213``` 214 215- Add scatter mode to `DMSwarmProjectFields()` and no longer create vectors 216- Promote `DMSwarmDataFieldGetEntries()`, `DMSwarmDataFieldRestoreEntries()`, `DMSwarmDataBucketGetDMSwarmDataFieldByName()`, `DMSwarmDataBucketGetDMSwarmDataFieldIdByName()`, and `DMSwarmDataBucketQueryDMSwarmDataFieldByName()` to public interface 217 218```{rubric} DMPlex: 219``` 220 221- Add `DMPlexTransformExtrudeGetPeriodic()` and `DMPlexTransformExtrudeSetPeriodic()` 222- Replace `DMPlexGetGhostCellStratum()` with `DMPlexGetCellTypeStratum()` 223- Add `DMPlexSetUseMatClosurePermutation()` and `DMPlexGetUseMatClosurePermutation()` 224- Add `DMPlexGetUseCeed()`, `DMPlexSetUseCeed()`, and `DMPlexSNESComputeResidualCEED()` 225- Add `DMPlexSNESComputeResidualDS()` 226 227```{rubric} FE/FV: 228``` 229 230- Add `PLEXFE_QFUNCTION` macro to create CEED QFunctions from Plex pointwise functions 231 232```{rubric} DMNetwork: 233``` 234 235- Add `DMNetworkViewSetShowRanks()`, `DMNetworkViewSetViewRanks()`, `DMNetworkViewSetShowGlobal()`, `DMNetworkViewSetShowVertices()`, `DMNetworkViewSetShowNumbering()` 236- Add `-dmnetwork_view_all_ranks` `-dmnetwork_view_rank_range` `-dmnetwork_view_no_vertices` `-dmnetwork_view_no_numbering` for viewing DMNetworks with the Matplotlib viewer 237- Add `-dmnetwork_view_zoomin_vertices` `-dmnetwork_view_zoomin_vertices_padding` for viewing DMNetworks with the Matplotlib viewer 238 239```{rubric} DMStag: 240``` 241 242```{rubric} DT: 243``` 244 245- Add `PETSCFEVECTOR` for making a finite element that is a vector of copies of another finite element 246- Add `PetscFECreateVector()` 247- Add `PETSCDUALSPACESUM` for a finite element dual basis that is the sum of other dual bases 248- Add `PetscDualSpaceCreateSum()` 249- Add `PetscDualSpaceSumSetNumSubspaces()` 250- Add `PetscDualSpaceSumGetNumSubspaces()` 251- Add `PetscDualSpaceSumSetSubspace()` 252- Add `PetscDualSpaceSumGetSubspace()` 253- Add `PetscDualSpaceSumSetConcatenate()` 254- Add `PetscDualSpaceSumGetConcatenate()` 255- Add `PetscDualSpaceSumSetInterleave()` 256- Add `PetscDualSpaceSumGetInterleave()` 257- Add `PetscSpaceSumSetInterleave()` 258- Add `PetscSpaceSumGetInterleave()` 259- Add `PetscDualSpaceGetInteriorSection()` 260 261```{rubric} Fortran: 262``` 263 264- Add `PetscCheck()` and `PetscCheckA()` for Fortran 265- Change `PETSC_HAVE_FORTRAN` to `PETSC_USE_FORTRAN_BINDINGS` to indicate if PETSc is built with Fortran bindings 266