1# Changes: 3.18 2 3Changes you should make for main and version 3.18 so that it is portable to previous versions of PETSc 4 5- Remove the error handling from uses of `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscObjectOptionsBegin()`, `PetscOptionsHead()`, and `PetscOptionsTail()` 6- Remove the error handling from uses of `PetscDrawCollectiveBegin()` and `PetscDrawCollectiveEnd()` 7- Remove the error handling from uses of `MatPreallocateInitialize()` and `MatPreallocateFinalize()` 8- Replace `MatUpdateMPIAIJWithArrays()` with `MatUpdateMPIAIJWithArray()` 9 10Changes you can make for main and version 3.18 so that is not portable to previous versions of PETSc. This will remove all deprecation warnings when you build. 11In addition to the changes above 12 13- Change `PetscOptionsHead()` and `PetscOptionsTail()` to `PetscOptionsHeadBegin()` and `PetscOptionsHeadEnd()` 14- Change `MatPreallocateInitialize()` and `MatPreallocateFinalize()` to `MatPreallocateBegin()` and `MatPreallocateEnd()` 15- Change uses of `MatGetOption()` with `MAT_SYMMETRIC`, `MAT_STRUCTURALLY_SYMMETRIC`, `MAT_HERMITIAN`, `MAT_SPD` to calls to `MatIsSymmetric()`, `MatIsSymmetricKnown()` etc. 16- Whenever you call `MatSetOption()` with one of the above options and it is intended to stay with the matrix through calls to `MatSetValues()` etc add a call 17 to `MatSetOption()` with `MAT_SYMMETRY_ETERNAL` etc 18 19% STYLE GUIDELINES: 20% * Capitalize sentences 21% * Use imperative, e.g., Add, Improve, Change, etc. 22% * Don't use a period (.) at the end of entries 23% * If multiple sentences are needed, use a period or semicolon to divide sentences, but not at the end of the final sentence 24 25```{rubric} General: 26``` 27 28- Add native PETSc/HIP backend for AMD GPUs 29 30- Add `PETSC_ERR_RETURN` to signal when an error handler returns 0 in `PetscError()` 31 32- Change behavior of `SETERRQ()` when `PetscError()` returns 0 via user-set error handler. In such cases `SETERRQ()` now returns `PETSC_ERR_RETURN` (a nonzero value) instead. Previously the value (0) would be propagated as-is. Note that while returning 0 from error handlers in `PetscError()` is supported, doing so is discouraged 33 34- Change `PetscOptionsBegin()`, `PetscOptionsEnd()`, and `PetscObjectOptionsBegin()` to not return an error code 35 36- Change `PetscOptionsHead()`, `PetscOptionsTail()`, to `PetscOptionsHeadBegin()` and `PetscOptionsHeadEnd()` and to not return an error code 37 38- Enable `MPI_Datatype` type-checking to ensure that the type of the pointer passed to communication routines (e.g. `PetscSFBcastBegin()`) matches the corresponding `MPI_Datatype` argument. Compilers supporting this feature will emit a warning in case of mismatch. These may be disabled by defining `PETSC_SKIP_ATTRIBUTE_MPI_TYPE_TAG` prior to all PETSc header-file inclusions 39 40- Add `PETSC_ATTRIBUTE_FORMAT()` to enable compile-time `printf()`-style format specifier checking and apply it any PETSc functions taking a format string 41 42- Deprecate the use of `%D` for printing `PetscInt` in favor of `%" PetscInt_FMT "`. Compilers may now emit warnings when using `%D` as a result of applying `PETSC_ATTRIBUTE_FORMAT`. Users that need to support older versions of PETSc may do one of two things: 43 44 1. **Recommended** Insert the following code block *after* all PETSc header-file inclusions 45 46 ``` 47 #if !defined(PetscInt_FMT) 48 # if defined(PETSC_USE_64BIT_INDICES) 49 # if !defined(PetscInt64_FMT) 50 # if defined(PETSC_HAVE_STDINT_H) && defined(PETSC_HAVE_INTTYPES_H) && defined(PETSC_HAVE_MPI_INT64_T) 51 # include <inttypes.h> 52 # define PetscInt64_FMT PRId64 53 # elif (PETSC_SIZEOF_LONG_LONG == 8) 54 # define PetscInt64_FMT "lld" 55 # elif defined(PETSC_HAVE___INT64) 56 # define PetscInt64_FMT "ld" 57 # else 58 # error "cannot determine PetscInt64 type" 59 # endif 60 # endif 61 # define PetscInt_FMT PetscInt64_FMT 62 # else 63 # define PetscInt_FMT "d" 64 # endif 65 #endif 66 ``` 67 68 This will ensure that the appropriate format specifiers are defined regardless of PETSc version. 69 70 2. **Not Recommended** Compilers warnings can be permanently suppressed by defining `PETSC_SKIP_ATTRIBUTE_FORMAT` prior to all PETSc header-file inclusions 71 72- `chkerrconvert.py` (`${PETSC_DIR}/share/petsc/chkerrconvert.py`) now also handles possible spaces between the semi-colon and `CHKERR` construct when replacing. 73 74```{rubric} Configure/Build: 75``` 76 77- Remove python2 support, python-3.4+ is now required 78 79```{rubric} Sys: 80``` 81 82- Change calling sequence of `PetscObjectProcessOptionsHandler()` to flip the role of the first two arguments 83- Change `-log_view` to no longer print out the amount of memory associated with different types of objects. That data was often incorrect 84- Change `PetscCall()` from Fortran so that `call PetscFunction(args,ierr);CHKERRQ(ierr);` can be replaced with `PetscCall(PetscFunction(args,ierr))` 85- Add `PetscCallA()` from Fortran so that `call PetscFunction(args,ierr);CHKERRA(ierr);` can be replaced with `PetscCallA(PetscFunction(args,ierr))` 86- Add `PetscCallMPI()` and `PetscCallMPIA()` that may be used to call MPI functions from Fortran 87- Change the `PetscCheck()` and `PetscAssert()` macros to behave like function calls by wrapping in `do { } while (0)`. Previously these macros expanded to `if (...) SETERRQ(...)`, which meant they could be chained with subsequent conditionals 88- Change `PetscStackCallStandard()` to `PetscCallExternal()` 89- Change `PetscStackCall()` to `PetscStackCallExternalVoid()` 90- Change `PetscStackCallXXX()` to `PetscCallXXX()` 91- Add `PetscCallBack()` for calling all PETSc callbacks (usually to user code) to replace the use of `PetscStackPush()` and `PetscStackPop` 92- Add `PetscTryTypeMethod()` and `PetscUseTypeMethod()` to replace direct calls of the form `(\*obj->ops->op)(obj,...)` 93- Add `PetscMemTypeToString()` to convert `PetscMemType` to string 94- Add `PetscOffloadMaskToString()` to (shockingly) convert `PetscOffloadMask` to string 95- Add `PetscOffloadMaskToMemType()` 96- Add `PetscDeviceCopyMode` 97- Add `PetscMemoryAccessMode` 98- Split off CUDA and HIP specific headers from `petscdevice.h` into `petscdevice_cuda.h` and `petscdevice_hip.h` 99- Add `petscdevice_cupm.h` 100- Allow `PetscDevice` and `PetscDeviceContext` API to be callable from C via stub macros 101- Replace `PETSC_DEVICE_INVALID` with `PETSC_DEVICE_HOST` 102- Make `PETSC_DEVICE_DEFAULT()` a function 103- Add `PetscDeviceSetDefaultDeviceType()` 104- Make `PetscDeviceContext` into a `PetscObject` 105- Add `PetscDeviceContextGetDeviceType()` convenience function 106- Add `PetscDeviceContextForkWithStreamType()` 107- Change `PetscDeviceContextSetFromOptions()` to no longer accept the options prefix (`PetscDeviceContext` now has one as a `PetscObject`) 108- Add `PetscDeviceContextView()` 109- Add `PetscDeviceContextViewFromOptions()` 110- Add `PetscDeviceMalloc()` 111- Add `PetscDeviceCalloc()` 112- Add `PetscDeviceFree()` 113- Add `PetscDeviceMemcpy()` 114- Add `PetscDeviceArrayCopy()` 115- Add `PetscDeviceMemset()` 116- Add `PetscDeviceArrayZero()` 117- Deprecate `PetscLogObjectParent()` 118- Deprecate `PetscLogObjectMemory()` 119- Deprecate `PetscNewLog()`, users should just use `PetscNew()` instead 120- Add `PetscHasBuiltin()` to detect whether a particular builtin function is supported by the compiler 121- Add `PetscAssume()` to indicate an invariant condition to the compiler 122- Add `PetscSortedInt64()`, `PetscSortInt64()` and `PetscSortCount()` for sorting and checking arrays of these types 123- Add `PetscHMapObjCreate()` and all associated hash map routines for holding PETSc objects 124- Add `PetscObjectDelayedDestroy()`, `PetscGarbageKeySortedIntersect()`, `PetscGarbageCleanup()` and `PetscGarbageView()` for memory cleanup operations in managed languages 125- Remove unused preprocessor variables `PETSC_Alignx`, `PETSC_const`, and `PETSC_HAVE_GETARG` 126 127```{rubric} Event Logging: 128``` 129 130Add NVIDIA NVTX sections to `Default` event logging. This tags code 131sections, like stages, with nvtxRangePushA(char name[]) and 132nvtxRangePop(), which can be visualized after the run with the NVIDIA Nsight GUI tool. To 133generate a data file, run code with `nsys profile -f true -o file-name 134exec-name`. 135 136```{rubric} PetscViewer: 137``` 138 139- Change `PetscViewerHDF5GetGroup()` to accept optional path relative to the pushed group and always return absolute path (newly allocated) 140- Change `PetscViewerHDF5OpenGroup()` to accept optional path relative to the pushed group 141- Add `PetscViewerHDF5WriteGroup()` 142 143```{rubric} PetscDraw: 144``` 145 146- Add `PetscDrawSPGetDimension()` 147- Change `PetscDrawCollectiveBegin()` and `PetscDrawCollectiveEnd()` to not return an error code. Users can remove the error code checking for 148 these functions and it will work correctly for all versions of PETSc 149 150```{rubric} AO: 151``` 152 153```{rubric} IS: 154``` 155 156- Add `ISShift()` 157 158```{rubric} VecScatter / PetscSF: 159``` 160 161- Add `PetscSFGetGraphLayout()` 162 163```{rubric} PF: 164``` 165 166```{rubric} Vec: 167``` 168 169- Add `VecSetPreallocationCOO()`, `VecSetValuesCOO()` and `VecSetPreallocationCOOLocal()` to support vector assembly with coordinates 170- Add `VecStrideSum()` and `VecStrideSumAll()` for summing subvectors of strided vectors 171- Add `VecCreateLocalVector()` to be used for calls involving `Vec{Get|Restore}LocalVector()` 172 173```{rubric} PetscSection: 174``` 175 176- Add `PetscSectionCreateSubdomainSection()` 177 178```{rubric} PetscPartitioner: 179``` 180 181```{rubric} Mat: 182``` 183 184- Change `MatPreallocateInitialize()` and `MatPreallocateFinalize()` to `MatPreallocateBegin()` and `MatPreallocateEnd()` and to not return an error code 185- Change `MatDenseGetSubMatrix()` to be able to retrieve only selected contiguous rows instead of all rows 186- Add `MatSetOptionsPrefixFactor()` and `MatAppendOptionsPrefixFactor()` to allow controlling the options prefix used by factors created from this matrix 187- Change `MatSetOptionsPrefix()` to no longer affect the options prefix used by factors created from this matrix 188- Change matrix factor options called from within `KSP`/`PC` to always inherit the options prefix from the `KSP`/`PC`, not the options prefix in the originating matrix 189- Add `MatIsStructurallySymmetricKnown()` and `MatIsSPDKnown()` 190- Change `MatGetOption()` to no longer produce results for `MAT_STRUCTURALLY_SYMMETRIC`, `MAT_SYMMETRIC`, `MAT_SPD`, and `MAT_HERMITIAN` 191- Add `MatCreateGraph()` to create a scalar matrix for use in graph algorithms 192- Add an option -mat_factor_bind_factorization \<host, device> to control where to do matrix factorization. Currently only supported with SEQAIJCUSPARSE matrices. 193- Add `MatUpdateMPIAIJWithArray()` and deprecate `MatUpdateMPIAIJWithArrays()` 194- Change the coordinate array parameters in `MatSetPreallocationCOO` from const to non-const 195- Add enforcement of the previously unenforced rule that `MAT_REUSE_MATRIX` with `MatTranspose()` can only be used after a call to `MatTranspose()` with `MAT_INITIAL_MATRIX`. Add `MatTransposeSetPrecursor()` to allow using `MAT_REUSE_MATRIX` with `MatTranspose()` without the initial call to `MatTranspose()`. 196- Add `MatTransposeSymbolic()` 197- Add `MatShellSetContextDestroy()` and add internal refrence counting for user defined `MatShell` context data 198- Add `MatShellSetContextDestroy()` and add internal reference counting for user defined `MatShell` context data 199- Change `MATTRANPOSEMAT` to `MATTRANPOSEVIRTUAL` 200- Add `MATHERMITIANTRANSPOSEVIRTUAL` 201 202```{rubric} MatCoarsen: 203``` 204 205- Add `MISK` coarsening type. Distance-k maximal independent set (MIS) C-F coarsening with a greedy, MIS based aggregation algorithm 206 207```{rubric} PC: 208``` 209 210- Add PC type of mpi which can be used in conjunction with -mpi_linear_solver_server to use MPI parallelism to solve a system created on a single MPI rank 211- Add `PCHYPREAMSSetInteriorNodes()` to set interior nodes for HYPRE AMS 212- Add `PCAMGX`, a PC interface for NVIDIA's AMGx AMG solver 213- Remove `PCGAMGSetSymGraph()` and `-pc_gamg_sym_graph`. The user should now indicate symmetry and structural symmetry using `MatSetOption()` and GAMG will symmetrize the graph if a symmetric options is not set 214- Change `-pc_gamg_reuse_interpolation` default from false to true. 215 216```{rubric} KSP: 217``` 218 219- Deprecate `KSPHPDDMGetDeflationSpace()` (resp. `KSPHPDDMSetDeflationSpace()`) in favor of `KSPHPDDMGetDeflationMat()` (resp. `KSPHPDDMSetDeflationMat()`) 220- Add `KSPNONE` as alias for `KSPPREONLY` 221 222```{rubric} SNES: 223``` 224 225- Add `DMDASNESSetFunctionLocalVec()`, `DMDASNESSetJacobianLocalVec()` and `DMDASNESSetObjectiveLocalVec()`, and associate types `DMDASNESFunctionVec`, `DMDASNESJacobianVec` and `DMDASNESObjectiveVec`, 226 which accept Vec parameters instead of void pointers in contrast to versions without the Vec suffix 227- Add `SNESLINESEARCHNONE` as alias for `SNESLINESEARCHBASIC` 228- Add `DMSNESSetFunctionContextDestroy()` and `DMSNESSetJacobianContextDestroy()` and use `PetscContainter` for user context to facilitate automatic destruction of user set context 229 230```{rubric} SNESLineSearch: 231``` 232 233```{rubric} TS: 234``` 235 236- Add `TSSetTimeSpan()`, `TSGetTimeSpan()` and `TSGetTimeSpanSolutions()` to support time span 237- Add `DMTSGetIFunctionLocal()`, `DMTSGetIJacobianLocal()`, and `DMTSGetRHSFunctionLocal()` 238- Add `DMTSSetIFunctionContextDestroy()`, `DMTSSetIJacobianContextDestroy()`, `DMTSSetRHSFunctionContextDestroy()`, `DMTSSetRHSJacobianContextDestroy()`, `DMTSSetI2FunctionContextDestroy()`, and `DMTSSetI2JacobianContextDestroy()` and use `PetscContainter` for user context to facilitate automatic destruction of user set context 239- Make public `SNESVIComputeMeritFunction()` and `SNESVIComputeFunction()` 240 241```{rubric} TAO: 242``` 243 244- Rename the command line option `-tao_nm_lamda` to `-tao_nm_lambda` 245 246```{rubric} DM/DA: 247``` 248 249- Add `DMDAMapMatStencilToGlobal()` to map MatStencils to global indices 250- Add `DMGetCellCoordinateDM()`, `DMSetCellCoordinateDM()`, `DMGetCellCoordinateSection()`, `DMSetCellCoordinateSection()`, `DMGetCellCoordinates()`, `DMSetCellCoordinates()`, `DMGetCellCoordinatesLocalSetup()`, `DMGetCellCoordinatesLocal()`, `DMGetCellCoordinatesLocalNoncollective()`, `DMSetCellCoordinatesLocal()` 251- Add `DMFieldCreateDSWithDG()` to allow multiple representations of a given field 252- Add `DMProjectFieldLabel()` 253- Make public `DMSetVI()` and `DMDestroyVI()` 254- Change `DMCountNonCyclicReferences()` to `DMCountNonCyclicReferences_Internal()` 255- Add `DMCountNonCyclicReferences()` as a more generic wrapper for `DMCountNonCyclicReferences_Internal()` 256 257```{rubric} DMSwarm: 258``` 259 260- Add `DMSwarmGetCoordinateFunction()`, `DMSwarmSetCoordinateFunction()`, `DMSwarmGetVelocityFunction()`, `DMSwarmSetVelocityFunction()` to allow flexible layout of particles 261 262```{rubric} DMPlex: 263``` 264 265- Add `DMLabelPropagateBegin()`, `DMLabelPropagatePush()`, and `DMLabelPropagateEnd()` 266- Add `DMPlexPointQueue` and API 267- Add label value argument to `DMPlexLabelCohesiveComplete()` and `DMPlexCreateHybridMesh()` 268- Change `DMPlexCheckPointSF()` to take optional `PetscSF` parameter 269- Add `DMPlexCheck()` 270- Add `DMPlexMetricDeterminantCreate()` for creating determinant fields for Riemannian metrics 271- Change `DMPlexMetricEnforceSPD()`: 272 : - pass determinant Vec, rather than its address 273 - pass output metric, rather than its address 274- Change `DMPlexMetricNormalize()`: 275 : - pass output metric, rather than its address 276 - pass determinant Vec, rather than its address 277- Change `DMPlexMetricAverage()`, `DMPlexMetricAverage2()` and `DMPlexMetricAverage3()` to pass output metric, rather than its address 278- Change `DMPlexMetricIntersection()`, `DMPlexMetricIntersection2()` and `DMPlexMetricIntersection3()` to pass output metric, rather than its address 279- Add capability to specify whether the DMPlex should be reordered by default: 280 : - add `DMPlexReorderDefaultFlag` 281 - add `DMPlexReorderGetDefault()` and `DMPlexReorderSetDefault()` to get and set this flag 282- Add `DMPlexCreateOverlapLabelFromLabels()` for more customized overlap 283- Add `DMPlexSetOverlap()` to promote an internal interface 284- Add `DMGetCellCoordinateDM()`, `DMSetCellCoordinateDM()`, `DMGetCellCoordinateSection()`, `DMSetCellCoordinateSection()`, `DMGetCellCoordinates()`, `DMSetCellCoordinates()`, `DMGetCellCoordinatesLocalSetUp()`, `DMGetCellCoordinatesLocal()`, `DMGetCellCoordinatesLocalNoncollective()`, and `DMSetCellCoordinatesLocal()` to provide an independent discontinuous representation of coordinates 285- Change `DMGetPeriodicity()` and `DMSetPeriodicity()` to get rid of the flag and boundary type. Since we have an independent representation, we can tell if periodicity was imposed, and boundary types were never used, so they can be inferred from the given L. We also add Lstart to allow tori that do not start at 0. 286- Add `DMPlexGetCellCoordinates()` and `DMPlexRestoreCellCoordinates()` for clean interface for periodicity 287- Add `DMPlexDistributionSetName()` and `DMPlexDistributionGetName()` to set/get the name of the specific parallel distribution of the DMPlex 288 289```{rubric} FE/FV: 290``` 291 292- Add `PetscFECreateFromSpaces()` to build similar space from pieces 293 294```{rubric} DMNetwork: 295``` 296 297- Add `DMNetworkFinalizeComponents()` to setup the internal data structures for components on a network. Previously this could only be done by calling DMSetUp 298 299```{rubric} DMStag: 300``` 301 302```{rubric} DT: 303``` 304 305- Add probability distributions `PetscPDFGaussian3D()`, `PetscPDFSampleGaussian3D()`, `PetscPDFConstant2D()`, `PetscCDFConstant2D()`, `PetscPDFSampleConstant2D()`, `PetscPDFConstant3D()`, `PetscCDFConstant3D()`, `PetscPDFSampleConstant3D()` 306 307```{rubric} Fortran: 308``` 309