Changes: 3.20#
General:
- Add - PetscOptionsBegin(),- PetscOptionsEnd(),- PetscOptionsInt(),- PetscOptionsBool(),- PetscOptionsIntArray(),- PetscOptionsReal(),- PetscOptionsRealArray(), and- PetscOptionsScalar()for Fortran
- Add - PetscAssertPointer()as a replacement for- PetscValidPointer(),- PetscValidCharPointer(),- PetscValidIntPointer(),- PetscValidInt64Pointer(),- PetscValidCountPointer(),- PetscValidBoolPointer(),- PetscvalidScalarPointer(), and- PetscValidRealPointer()
- 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.hused 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
Configure/Build:
- 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=mainoption - configure download and builds from MPICH git repository
- Add support for external package SLATE, optional dependency for STRUMPACK 
- Add support for external package ZFP, optional dependency for STRUMPACK 
- Add support for external package ButterflyPACK, optional dependency for STRUMPACK 
Sys:
- Add - PetscDeviceContextGetStreamHandle()to return a handle to the stream the current device context is using
- Add utility functions - PetscGetCurrentCUDAStream()and- PetscGetCurrentHIPStream()to return the GPU stream the current device context is using
- Add - PetscStrcmpAny()to compare against multiple non-empty strings
- Change arguments 4 and 5 of - PetscViewerBinaryReadAll()and- PetscViewerBinaryWriteAll()to- PetscInt64
- Add - PetscIsCloseAtTolScalar()
- Remove - PetscTellMyCell()and related runtime option
- Remove - PetscTextBelt()and related runtime option
- Remove deprecated - -malloc [no]startup option
- Remove deprecated - -malloc_infostartup option
- Remove deprecated - -log_summaryoption
- Remove - PetscURLShorten(), it has not worked since 2019
- Move - PetscIntStackCreate(),- PetscIntStackDestroy(),- PetscIntStackPush(),- PetscIntStackPop(), and- PetscIntStackEmpty()declarations to public API in petsclog.h
- Add - -on_error_malloc_dumpoption
Event Logging:
- Add - PetscLogStateinterface for describing profiling events and stages
- Add - PetscLogHandlerinterface that interprets the profiling events of a- PetscLogState
- Add - PETSCLOGHANDLERDEFAULTimplementation of- PetscLogHandler
- Add - PETSCLOGHANDLERNESTEDimplementation of- PetscLogHandler
- Add - PETSCLOGHANDLERTRACEimplementation of- PetscLogHandler
- Add - PETSCLOGHANDLERMPEimplementation of- PetscLogHandler
- Add - PETSCLOGHANDLERPERFSTUBSimplementation of- PetscLogHandler
- Add - PETSCLOGHANDLERLEGACYimplementation of- PetscLogHandler
- Add - PetscLogPerfstubsBegin()for log handling with PerfStubs/TAU
- Add - PetscLogLegacyCallbacksBegin()to transition old log handler callbacks to the- PetscLogHandler-based approach
- Add - PetscLogHandlerStart()to connect a- PetscLogHandlerto PETSc’s global logging events
- Add - PetscLogStageGetName()
- Add - PetscLogEventGetName()
- Add - PetscLogEventsPause()and- PetscLogEventsResume()to isolate a logging event from unrelated in-process events
- Add - PetscLogClassGetClassId()
- Add - PetscLogClassIdGetName()
- Deprecate - PetscLogClassPerfInfoClear()` , ``PetscLogClassPerfLogCreate(), and- PetscLogClassPerfLogDestroy()
- Deprecate - PetscClassPerfLogEnsureSize(),- PetscClassRegInfoDestroy(),- PetscClassRegLogCreate(),- PetscClassRegLogDestroy(),- PetscClassRegLogGetClass(), and- PetscClassRegLogRegister()
- Deprecate - PetscEventPerfInfoClear()and- PetscEventPerfInfoCopy()
- Deprecate - PetscEventPerfLogActivate(),- PetscEventPerfLogActivateClass(),- PetscEventPerfLogCreate(),- PetscEventPerfLogDeactivate(),- PetscEventPerfLogDeactivateClass(),- PetscEventPerfLogDeactivatePop(),- PetscEventPerfLogDeactivatePush(),- PetscEventPerfLogDestroy(),- PetscEventPerfLogEnsureSize(),- PetscEventPerfLogGetVisible(), and- PetscEventPerfLogSetVisible()
- Deprecate - PetscEventRegLogCreate(),- PetscEventRegLogDestroy(),- PetscEventRegLogGetEvent(), and- PetscEventRegLogRegister()
- Deprecate - PetscStageLogCreate(),- PetscStageLogDestroy(),- PetscStageLogGetActive(),- PetscStageLogGetClassPerfLog(),- PetscStageLogGetClassRegLog(),- PetscStageLogGetEventRegLog(),- PetscStageLogGetStage(),- PetscStageLogGetVisible(),- PetscStageLogPop(),- PetscStageLogPush(),- PetscStageLogRegister(),- PetscStageLogSetActive(),- PetscStageLogSetVisible(),- PetscStageLogGetCurrent(), and- PetscStageLogGetEventPerfLog()
- Deprecate - PetscLogGetStageLog()
- Deprecate - PetscLogPushCurrentEvent_Internal()
- Deprecate - PetscLogPopCurrentEvent_Internal()
- Deprecate - PetscLogAllBegin()
- Deprecate - PetscLogSet()
- Add - PetscLogHandlerDump()
- Add - PetscLogStageGetPerfInfo()
- Add - PETSCLOGHANDLERNVTXimplementation of- PetscLogHandler
PetscViewer:
PetscDraw:
AO:
IS:
VecScatter / PetscSF:
PF:
Vec:
- Add - VecErrorWeightedNorms()to unify weighted local truncation error norms used in- TS
- Add CUDA/HIP implementations for - VecAbs(),- VecSqrt(),- VecExp(),- VecLog(),- VecPointwiseMax(),- VecPointwiseMaxAbs(), and- VecPointwiseMin()
- Add - VecMAXPBY()
- Deprecate - VecChop()in favor of- VecFilter()
- Add - VecCreateFromOptions()
PetscSection:
PetscPartitioner:
Mat:
- Add support for calling - MatDuplicate()on a matrix preallocated via- MatSetPreallocationCOO(), and then- MatSetValuesCOO()on the new matrix
- Remove - MATSOLVERSPARSEELEMENTALsince it is no longer functional
- Add - MATSELLCUDA. It supports fast- MatMult(),- MatMultTranspose(), and- MatMultAdd()on GPUs
- Add support for - MAT_FACTOR_LUand- MAT_FACTOR_CHOLESKYwith- MATSOLVERMUMPSfor- MATNEST
- MatGetFactor()can now return- NULLfor 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)
- Remove - MatSetValuesDevice(),- MatCUSPARSEGetDeviceMatWrite(),- MatKokkosGetDeviceMatWrite
- Add - MatDenseCUDASetPreallocation()and- MatDenseHIPSetPreallocation()
- Add support for KOKKOS in - MATH2OPUS
- Add - -pc_precision singleoption for use with- MATSOLVERSUPERLU_DIST
- Add - MATDIAGONALwhich can be created with- MatCreateDiagonal()
- Add - MatDiagonalGetDiagonal(),- MatDiagonalRestoreDiagonal(),- MatDiagonalGetInverseDiagonal(), and- MatDiagonalRestoreInverseDiagonal()
- Add support for - MatLoad()and- MatView()to load and store- MATMPIAIJmatrices that have more than- PETSC_INT_MAXnonzeros, so long as each rank has fewer than- PETSC_INT_MAX
- Add - MatLRCSetMats()and register creation routine for- MatLRC
- Add CUDA/HIP implementation for - MatGetDiagonal()
- Add a Boolean parameter to - MatEliminateZeros()to force the removal of zero diagonal coefficients
- Expose - MatComputeVariableBlockEnvelope()in public headers
- Add - MatEliminateZeros()implementations for- MatBAIJand- MatSBAIJ
- Deprecate - MatChop()in favor of- MatFilter(), with two additional Boolean parameters to compress the underlying storage and keep or discard near-zero diagonal coefficients
- Add - MatCreateFromOptions()
- Add - MatSTRUMPACKGetReordering(),- MatSTRUMPACKSetGeometricNxyz(),- MatSTRUMPACKSetGeometricComponents(),- MatSTRUMPACKSetGeometricWidth(),- MatSTRUMPACKGetColPerm(),- MatSTRUMPACKSetGPU(),- MatSTRUMPACKGetGPU(),- MatSTRUMPACKSetCompression(),- MatSTRUMPACKGetCompression(),- MatSTRUMPACKSetCompRelTol(),- MatSTRUMPACKGetCompRelTol(),- MatSTRUMPACKSetCompAbsTol(),- MatSTRUMPACKGetCompAbsTol(),- MatSTRUMPACKSetCompMinSepSize(),- MatSTRUMPACKGetCompMinSepSize(),- MatSTRUMPACKSetCompLeafSize(),- MatSTRUMPACKGetCompLeafSize(),- MatSTRUMPACKSetCompLossyPrecision(),- MatSTRUMPACKGetCompLossyPrecision(),- MatSTRUMPACKSetCompButterflyLevels(),- MatSTRUMPACKGetCompButterflyLevels()
- Add - MAT_STRUMPACK_GEOMETRIC,- MAT_STRUMPACK_AMD,- MAT_STRUMPACK_MMD,- MAT_STRUMPACK_AND,- MAT_STRUMPACK_MLF,- MAT_STRUMPACK_SPECTRALto- MatSTRUMPACKReordering
- Remove - MatSTRUMPACKSetHSSLeafSize(),- MatSTRUMPACKSetHSSMaxRank(),- MatSTRUMPACKSetHSSMinSize(),- MatSTRUMPACKSetHSSMinSepSize(),- MatSTRUMPACKSetHSSAbsTol(),- MatSTRUMPACKSetHSSRelCompTol(),- MatSTRUMPACKSetHSSRelTol()
MatCoarsen:
PC:
- Add - PCMatGetApplyOperation()and- PCMatSetApplyOperation()
- Add - PCReduceFailedReason()
- Add - PCSetKSPNestLevel()and- PCSetKSPNestLevel()
- Refactor - PCMPIto be a private system used automatically when- -mpi_linear_solver_serveris used. The- KSPand- PCobjects that solve the system now inherit any prefix provided initially with- KSPSetPrefix()and do not require the previously required- mpi_prefix
- Add option - -fieldsplit_1_pc_hpddm_schur_preconditionto use- PCHPDDMon the Schur complements from- PCFIELDSPLIT
- Add - PCGAMGSetAggressiveSquareGraph()to use square graph method for aggressive coarsening that was the previous default coarsening approach before release 3.19
- Add - PCGAMGSetAggressiveMISk()to set the number of levels (k) of aggressive MIS-k coarsening (2 is very common)
- Add - PCGAMGSetMinDegreeOrderingMISk()to use a minimum degree ordering for the (greedy) MIS-k algorithm
- Change - PCGAMGSetUseParallelCoarseGridSolve()to- PCGAMGSetParallelCoarseGridSolve()
- Add - PCGAMGSetRecomputeEstEig()to set flag to have Chebyshev recompute its eigen estimates (default set to true)
KSP:
- Add - KSPSetMinimumIterations()and- KSPGetMinimumIterations()
- Add - KSPSetNestLevel()and- KSPGetNestLevel()
- Support - KSPSetInitialGuessNonzero()with- KSPPREONLYand- PCDISTRIBUTEwhen it is called on both the outer and inner- KSP
SNES:
- Add a convenient, developer-level - SNESConverged()function that runs the convergence test and updates the internal converged reason
- Swap the order of monitor and convergence test. Now monitors are always called after a convergence test 
- Deprecate option - -snes_ms_normsin favor of- -snes_norm_schedule always
SNESLineSearch:
TS:
- Remove - TSErrorWeightedNormInfinity(),- TSErrorWeightedNorm2(),- TSErrorWeightedENormInfinity(),- TSErrorWeightedENorm2()since the same functionality can be obtained with- VecErrorWeightedNorms()
- Add support for time-dependent solvers with varying solution size using - TSSetResize()
- Add support for Diagonally Implicit Runge-Kutta methods with the new - TSDIRKtype
TAO:
- Add - TAOBNCG,- TaoBNCGGetType()and- TaoBNCGSetType()
DM/DA:
- Add support for - DMDAGetElements()for Fortran
- Add support for clearing named vectors with - DMClearNamedGlobalVectors()and- DMClearNamedLocalVectors()
- Add - DMPrintCellIndices()for debugging
- Add - DMUseTensorOrder()
- Add - DMCeedCreate(),- DMCeedComputeGeometry(), and- DMCeedDestroy()
DMSwarm:
- Add scatter mode to - DMSwarmProjectFields()and no longer create vectors
- Promote - DMSwarmDataFieldGetEntries(),- DMSwarmDataFieldRestoreEntries(),- DMSwarmDataBucketGetDMSwarmDataFieldByName(),- DMSwarmDataBucketGetDMSwarmDataFieldIdByName(), and- DMSwarmDataBucketQueryDMSwarmDataFieldByName()to public interface
DMPlex:
- Add - DMPlexTransformExtrudeGetPeriodic()and- DMPlexTransformExtrudeSetPeriodic()
- Replace - DMPlexGetGhostCellStratum()with- DMPlexGetCellTypeStratum()
- Add - DMPlexSetUseMatClosurePermutation()and- DMPlexGetUseMatClosurePermutation()
- Add - DMPlexGetUseCeed(),- DMPlexSetUseCeed(), and- DMPlexSNESComputeResidualCEED()
FE/FV:
- Add - PLEXFE_QFUNCTIONmacro to create CEED QFunctions from Plex pointwise functions
DMNetwork:
- Add - DMNetworkViewSetShowRanks(),- DMNetworkViewSetViewRanks(),- DMNetworkViewSetShowGlobal(),- DMNetworkViewSetShowVertices(),- DMNetworkViewSetShowNumbering()
- Add - -dmnetwork_view_all_ranks- -dmnetwork_view_rank_range- -dmnetwork_view_no_vertices- -dmnetwork_view_no_numberingfor viewing DMNetworks with the Matplotlib viewer
- Add - -dmnetwork_view_zoomin_vertices- -dmnetwork_view_zoomin_vertices_paddingfor viewing DMNetworks with the Matplotlib viewer
DMStag:
DT:
- Add - PETSCFEVECTORfor making a finite element that is a vector of copies of another finite element
- Add - PetscFECreateVector()
- Add - PETSCDUALSPACESUMfor a finite element dual basis that is the sum of other dual bases
- Add - PetscDualSpaceCreateSum()
Fortran:
- Add - PetscCheck()and- PetscCheckA()for Fortran
- Change - PETSC_HAVE_FORTRANto- PETSC_USE_FORTRAN_BINDINGSto indicate if PETSc is built with Fortran bindings