=============
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()``

.. 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
