xref: /petsc/doc/changes/323.md (revision 0f5843cc88a1f2490c9cb5df20c0244c01aa9124)

# Changes: 3.23

% 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 `PetscCtxDestroyFn` as the prototype for all context destroy functions. It is `PetscErrorCode ()(void **)`. Previously some context destructor
  setters took `PetscErrorCode ()(void *)`. But these would not work directly with PETSc objects as contexts and having two different
  context destructor models added unneeded complexity to the library. This change is not backward compatible
- Deprecate `PetscContainerSetUserDestroy()` with `PetscContainerSetCtxDestroy()`, updating will require a small change in calling code
- Deprecate `PetscContainerCtxDestroyDefault` with `PetscCtxDestroyDefault()`
- Add `PetscIntViewNumColumns()`, `PetscScalarViewNumColumns()`, and `PetscRealViewNumColumns()`
- Change `PetscGetKokkosExecutionSpace()` to return the `Kokkos::DefaultExecutionSpace` object instead of a reference to it

```{rubric} Configure/Build:
```

- Update `--download-pastix` to use CMake build, with additional dependency on LAPACKE and CBLAS, can use for ex. MKL with `--with-blaslapack-dir=${MKLROOT}`, or Netlib LAPACK with `--download-netlib-lapack --with-netlib-lapack-c-bindings`
- Add option `--with-library-name-suffix=<suffix>`

```{rubric} Sys:
```

- Add `PetscCIntCast()`
- Add `PetscObjectHasFunction()` to query for the presence of a composed method
- Add `PetscSortedCheckDupsCount()` and `PetscFindCount()`

```{rubric} Event Logging:
```

```{rubric} PetscViewer:
```

```{rubric} PetscDraw:
```

- Add `PetscDrawHGAddWeightedValue()`

```{rubric} AO:
```

```{rubric} IS:
```

- Add `ISGetCompressOutput()` and `ISSetCompressOutput()`

```{rubric} VecScatter / PetscSF:
```

```{rubric} PF:
```

```{rubric} Vec:
```

- Add `PetscKDTree`, an implementation of K-d trees for efficient nearest-neighbor point searches. Includes `PetscKDTreeCreate()`, `PetscKDTreeDestroy()`, `PetscKDTreeView()`, and then `PetscKDTreeQueryPointsNearestNeighbor()` for actually doing the nearest-neighbor query
- Add `VecKokkosPlaceArray()` and `VecKokkosResetArray()`

```{rubric} PetscSection:
```

```{rubric} PetscPartitioner:
```

```{rubric} Mat:
```

- Add `MatCopyHashToXAIJ()` which allows assembling an XAIJ matrix in hash table form into another XAIJ matrix
- Add `MatResetHash()` which allows resetting an XAIJ matrix to use a hash table
- Add `MatCreateSeqAIJKokkosWithKokkosViews()` which allows creation of a `MATSEQAIJKOKKOS` matrix with AIJ data in Kokkos views
- Change `MatCreateMPIAIJWithSeqAIJ()` so that B can be passed in with local indices and compactification skipped
- Change option `-mat_factor_bind_factorization <host | device>` to `-pc_factor_mat_factor_on_host <bool>` for `MATAIJ` device matrices
- Add option `-pc_factor_mat_solve_on_host <bool>` for `MATSEQAIJKOKKOS` matrices

```{rubric} MatCoarsen:
```

```{rubric} PC:
```

- Add `PCHYPREGetCFMarkers()` to extract Coarse/Fine splittings created by BoomerAMG from `PCHYPRE`, similar to `PCGetInterpolations()` and `PCGetCoarseOperators()`

```{rubric} KSP:
```

```{rubric} SNES:
```

- Add `DMPlexSetSNESVariableBounds()`

```{rubric} SNESLineSearch:
```

- Add `SNESLINESEARCHBISECTION` as new SNES line search type, performing a bisection line search on the directional derivative
- Add `SNESLineSearchVIDirDerivFn` to compute directional derivative taking into account VI bounds, and update `SNESLineSearchGetVIFunctions()` and `SNESLineSearchSetVIFunctions()` accordingly

```{rubric} TS:
```

- Add `TSSetEvaluationTimes()`, `TSGetEvaluationTimes()`, and `TSGetEvaluationSolutions()` for evaluating solutions a given list of times. Also activatable via `-ts_eval_times`
- Deprecate `TSGetTimeSpan()` --> `TSGetEvaluationTimes()` and `TSGetTimeSpanSolutions()` --> `TSGetEvaluationSolutions()`
- v3.23.3: Add `TSGetIJacobianP()`

```{rubric} TAO:
```

```{rubric} DM/DA:
```

- Deprecate `DMGetSection()` and `DMSetSection()` for existing `DMGetLocalSection()` and `DMSetLocalSection()`
- Replace the Fortran array `DMDALocalInfo` with a derived type whose entries match the C struct
- Change the Fortran `DMDAGetNeighbors()` to return a `PetscMPIInt, pointer :: n(:)` and add a Fortran `DMDARestoreNeighbors()`
- Change the Fortran `DMDAGetOwnershipRanges()` to return `PetscInt, pointer :: n(:)` and add a Fortran `DMDARestoreOwnershipRanges()`

```{rubric} DMSwarm:
```

- Add `DMSwarmSortRestorePointsPerCell()`
- Change `DMSwarmVectorGetField()` and add `DMSwarmVectorDefineFields()` to handle multiple fields
- Add `DMSwarmComputeMoments()`
- Add `DMSwarmCellDMCreate()`, `DMSwarmCellDMDestroy()`, `DMSwarmCellDMView()`, `DMSwarmCellDMGetDM()`, `DMSwarmCellDMGetFields()`, `DMSwarmCellDMGetCoordinateFields()`, `DMSwarmCellDMGetCellID()`, `DMSwarmCellDMGetSort()`, `DMSwarmCellDMSetSort()`, and `DMSwarmCellDMGetBlockSize()`
- Add `DMSwarmAddCellDM()`, `DMSwarmSetCellDMActive()`, and `DMSwarmGetCellDMActive()`
- Add `DMSwarmCreateGlobalVectorFromFields()`, `DMSwarmDestroyGlobalVectorFromFields()`, `DMSwarmCreateLocalVectorFromFields()`, and `DMSwarmDestroyLocalVectorFromFields()`
- Add `DMSwarmSortDestroy()`
- Add `DMSwarmRemapType`, `DMSwarmRemap()`, and `DMSwarmDuplicate()`
- Add `DMSwarmGetType()`
- Add `DMSwarmGetCellDMByName()` and `DMSwarmGetCellDMNames()`

```{rubric} DMPlex:
```

- Add `DMPlexTransformGetMatchStrata()` and `DMPlexTransformSetMatchStrata()`
- Deprecate `DMPlexSetGlobalToNaturalSF()` and `DMPlexGetGlobalToNaturalSF()` for existing `DMSetNaturalSF()` and `DMGetNaturalSF()`
- Add `-dm_plex_box_label_bd` to setup isoperiodicity when using `-dm_plex_box_label_bd`
- Change `PetscViewerCGNSGetSolutionTime()` to no longer error if "TimeValues" array isn't found in CGNS file
- Add `PetscViewerCGNSGetSolutionIteration()`
- Add `DMPlexGetInterpolatePreferTensor()` and `DMPlexSetInterpolatePreferTensor()`
- Add `PetscCallEGADS()`
- Add `DMPlexTransformGetTransformTypes()` and `DMPlexTransformSetTransformTypes()`
- Several `DMPLEX` functions including `DMPlexVecGetClosure()` now requiring a dummy argument for the length of the returned array, for example `PETSC_NULL_INTEGER` that was previously missing not in the Fortran API.

```{rubric} FE/FV:
```

- Add `PetscFEGeomMode`
- Change `PetscFEGeomCreate()`, `DMFieldCreateFEGeom()`, and `DMSNESGetFEGeom()` to take `PetscFEGeomMode`

```{rubric} DMNetwork:
```

```{rubric} DMStag:
```

```{rubric} DT:
```

- Add `PetscDSGetLowerBound()`, `PetscDSSetLowerBound()`, `PetscDSGetUpperBound()`, `PetscDSSetUpperBound()`, `PetscDSCopyBounds()`
- Add `PetscProbComputeKSStatisticWeighted()` and `PetscProbComputeKSStatisticMagnitude()`

```{rubric} Fortran:
```

- Deprecate all Fortran function names with the suffix F90 with the equivalent function name without the suffix F90. Functions such as `VecGetArray()`
  now take a Fortran pointer as arguments and hence behave like the deprecated `VecGetArrayF90()`
- Add `PETSC_NULL_ENUM_XXX` to be used instead of `PETSC_NULL_INTEGER` when a pointer to an XXX `enum` is expected in a PETSc function call
- Add `PETSC_NULL_INTEGER_ARRAY`, `PETSC_NULL_SCALAR_ARRAY`, and `PETSC_NULL_REAL_ARRAY` for use instead of
  `PETSC_NULL_INTEGER`, `PETSC_NULL_SCALAR`, and `PETSC_NULL_REAL` when an input array is expected in a PETSc function call but not
  provided by the user
- Add `PETSC_NULL_INTEGER_POINTER` for arguments that return as arrays, for example, `PetscInt, pointer :: idx(:)` but not needed by the user.
- Add automatically generated interface definitions for most PETSc functions to detect illegal usage at compile time
- Add `PetscObjectIsNull()` for users to check if a PETSc object is `NULL`. All PETSc objects are now null when they are declared
- Change the PETSc Fortran API so that non-array values, `v`, passed to PETSc routines expecting arrays must be cast with `[v]` in the calling sequence. For example, with `VecSetValues()`
- Use of `case(e)` where `e` is any PETSc enum variable or value must be changed to `PetscEnumCase(e)` or `case(e%v)`
- `MatInfo` and similar are now derived data types instead of arrays, use e.g. `matinfo%nz_allocated` to access their components