=============
Changes: 3.19
=============

..
   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 perfstubs package, see :ref:`Users Manual: Profiling: Using TAU <sec_using_tau>` for more information on usage

.. rubric:: Configure/Build:

- Remove unused preprocessor variables ``PETSC_HAVE_VPRINTF_CHAR``, ``PETSC_HAVE_VFPRINTF_CHAR``, ``PETSC_STAT_MACROS_BROKEN``, ``PETSC_HAVE_FORTRAN_GETARG``, ``PETSC_uid_t``, ``PETSC_gid_t``, ``PETSC_HAVE_PTHREAD_BARRIER_T``, ``PETSC_HAVE_SCHED_CPU_SET_T``, ``PETSC_HAVE_SYS_SYSCTL_H``, ``PETSC_HAVE_SYS_SYSINFO_H``, ``PETSC_HAVE_SYSINFO_3ARG``, ``PETSC_SIZEOF_SHORT``, and ``PETSC_SIZEOF_ENUM``
- Deprecate ``--with-gcov`` configure option in favor of ``--with-coverage``
- Add ``--with-coverage-exec`` configure option to specify the coverage-collection tool to be used e.g. ``gcov`` or ``/path/to/llvm-cov-15``
- Add ``--with-strict-petscerrorcode`` configure option to enable compile-time checking for correct usage of ``PetscErrorCode``, see below
- Add support for C++20
- Add support for CUDA-12
- Improved C++ dialect handling for non-conformal cases. In general ``configure`` will fail faster and with a more informative error message when the C++ compiler does not comply with restraints

.. rubric:: Sys:

- Change ``PetscOptionsMonitorDefault()`` to also take in the option source, and ``PetscOptionsMonitorSet()`` to take the new monitor function
- Deprecate ``PetscTable`` and related functions. Previous users of ``PetscTable`` are encouraged to use the more performant ``PetscHMapI`` instead, though they should note that this requires additional steps and limitations:

  #. ``#include <petscctable.h>`` must be swapped for ``#include <petsc/private/hashmapi.h>``. This of course requires that you have access to the private PETSc headers.
  #. While most of the old ``PetscTable`` routines have direct analogues in ``PetscHMapI``, ``PetscAddCount()`` does not. All uses of this routine should be replaced with the following snippet:

     ::

        // PetscHMapI hash_table;
        // PetscInt   key;

        PetscHashIter it;
        PetscBool     missing;

        PetscCall(PetscHMapIPut(hash_table, key, &it, &missing));
        if (missing) {
          PetscInt size;

          PetscCall(PetscHMapIGetSize(hash_table, &size));
          PetscCall(PetscHMapIIterSet(hash_table, it, size));
        }


  Furthermore, users should note that ``PetscHMapI`` is based on -- and directly ``#include`` s -- ``${PETSC_DIR}/include/petsc/private/khash/khash.h``. This file contains external source code that is licensed under the MIT license, which is separate from the PETSc license.

- Remove undocumented ``PETSC_MPI_WIN_FMT`` and ``PETSC_MPI_COMM_FMT``. Users should cast both ``MPI_Comm`` and ``MPI_Win`` to ``PETSC_INTPTR_T`` and use the ``PETSC_INTPTR_T_FMT`` format specifier instead:

     ::

        MPI_Comm comm;
        MPI_Win  win;

        // old
        PetscCall(PetscPrintf(..., "MPI Comm %" PETSC_MPI_COMM_FMT, comm));
        PetscCall(PetscPrintf(..., "MPI Window %" PETSC_MPI_WIN_FMT, win));

        // new
        PetscCall(PetscPrintf(..., "MPI Comm %" PETSC_INTPTR_T_FMT, (PETSC_INTPTR_T)comm));
        PetscCall(PetscPrintf(..., "MPI Window %" PETSC_INTPTR_T_FMT, (PETSC_INTPTR_T)win));


- Deprecate ``PETSC_NULL`` in favor of ``PETSC_NULLPTR`` as it does the right thing in both C and C++
- Significantly improve lookup and deletion performance of ``PetscFunctionList``. This also improves performance of ``PetscObjectComposeFunction()`` and ``PetscObjectQueryFunction()``.
- Optionally define ``PetscErrorCode`` as an ``enum``, and tag it as ``PETSC_NODISCARD``. This feature may be enabled by configuring PETSc with ``--with-strict-petscerrorcode`` configure option. This feature allows catching the following logical errors at compile-time:

  #. Not properly checking the return-code of PETSc calls via ``PetscCall()``. PETSc is left in an inconsistent state when errors are detected and cannot generally recover from them, so is not supported.
  #. Using the wrong ``PetscCall()`` variant, for example using ``PetscCall()`` on MPI functions (instead of ``PetscCallMPI()``).
  #. Returning ``PetscErrorCode`` from ``main()`` instead of ``int``.

  Users should note that this comes with the following additional changes:

  #. Add ``PETSC_SUCCESS`` to indicate success, always guaranteed to equal ``0``.
  #. ``PetscFunctionReturn(0)`` should be changed to ``PetscFunctionReturn(PETSC_SUCCESS)``. While the original ``0``-form will continue to work in C, it is required for C++.
  #. Any user-defined macros using boolean short-circuiting to chain multiple calls in the same line, which logically return a ``PetscErrorCode``, should now explicitly cast the "result" of the macro with ``PetscErrorCode``:


     ::

        // Both foo() and bar() defined as returning PetscErrorCode
        extern PetscErrorCode foo(int);
        extern PetscErrorCode bar(int);

        // The following macros logically "return" a PetscErrorCode, i.e. can
        // be used:
        //
        // PetscCall(MY_USER_MACRO(a, b));
        //
        // but use boolean short-circuiting to chain the calls together. bar()
        // only executes if foo() returns PETSC_SUCCESS

        // old
        #define MY_USER_MACRO(a, b) (foo(a) || bar(b))

        // new
        #define MY_BETTER_USER_MACRO(a, b) ((PetscErrorCode)(foo(a) || bar(b)))


  While currently opt-in, this feature **will be enabled by default in a future release**. Users are highly encourage to enable it and fix any discrepancies before that point. Note that ``PETSC_SUCCESS`` is defined whether or not the feature is enabled, so users may incrementally update.

- Add ``PetscFFlush()``
- Soft-deprecate ``PetscStrcpy()`` and ``PetscStrcat()``. No diagnostics will be emitted if these routines are used, but users are highly encouraged to switch to the more secure (and possibly performant) ``PetscStrncpy()`` and ``PetscStrlcat()``
- Add ``PETSC_REAL_MIN`` for smallest normalized floating point number
- Add ``PETSC_ATTRIBUTE_MAY_ALIAS`` to inform compilers that a type is not subjected to type-based alias analysis

.. rubric:: Event Logging:

.. rubric:: PetscViewer:

- The VTK viewers (``.vts``, ``.vtr``, and ``.vtu``) now use ``header_type="UInt64"`` to enable writing large binary appended blocks

.. rubric:: PetscDraw:

- Add ``PetscDrawSetVisible()`` to set if the drawing surface (the 'window') is visible on its display

.. rubric:: AO:

.. rubric:: IS:

- Change ``ISDuplicate()`` to preserve the block size of the input in the output
- Deprecate ``ISCompressIndicesSorted()``

.. rubric:: VecScatter / PetscSF:

- Add experimental support in PetscSF for MPICH MPIX_Stream (with MPICH-4.2.0 and higher). One can enable it via ``-sf_use_stream_aware_mpi``
- Add an alias option ``-sf_use_gpu_aware_mpi`` to ``-use_gpu_aware_mpi``

- Remove ``SCATTER_LOCAL`` from the enum type since it is not a public value
- Change ``PetscSFConcatenate()`` to accept ``PetscSFConcatenateRootMode`` parameter; add option to concatenate root spaces globally
- Add ``PetscSFSetGraphFromCoordinates()`` to construct a graph from fuzzy matching of coordinates; such as occurs for projections between different dimensions or for overlapping meshes

.. rubric:: PF:

.. rubric:: Vec:

- Document ``VecOperation``
- Add ``VECOP_SET``
- Significantly improve performance of ``VecMDot()``, ``VecMAXPY()`` and ``VecDotNorm2()`` for CUDA and HIP vector types. These routines should be between 2x and 4x faster.
- Enforce the rule that ``VecAssemblyBegin()`` and ``VecAssemblyEnd()`` must be called on even sequential vectors after calls to ``VecSetValues()``. This also applies to assignment of vector entries in petsc4py

.. rubric:: PetscSection:

.. rubric:: PetscPartitioner:

.. rubric:: Mat:

- ``MatSetValues()`` and friends will now provide reasonable performance when no preallocation information is provided
- Add ``MatEliminateZeros()``
- Improve efficiency of ``MatConvert()`` from ``MATNORMAL`` to ``MATHYPRE``
- Add ``MatDenseGetArrayAndMemType()``, ``MatDenseRestoreArrayAndMemType()``, ``MatDenseGetArrayReadAndMemType()``, ``MatDenseRestoreArrayReadAndMemType()``, ``MatDenseGetArrayWriteAndMemType()`` and ``MatDenseRestoreArrayWriteAndMemType()`` to return the array and memory type of a dense matrix
- Deprecate all MatPreallocate* routines. These are no longer needed since non-preallocated matrices will now be as fast as using them
- Significantly improve performance of ``MatScale()`` and ``MatAXPY()`` for ``MATDENSECUDA`` and ``MATDENSEHIP`` in the case where the leading dimension is greater than the number of columns/rows. This situation arises when using e.g. sub-matrices. These routines should be between 3x and 4x faster

.. rubric:: MatCoarsen:

.. rubric:: PC:

- Add ``PCHPDDMSetSTShareSubKSP()``

.. rubric:: KSP:

- Add ``KSPMonitorDynamicToleranceCreate()`` and ``KSPMonitorDynamicToleranceSetCoefficient()``
- Change ``-sub_ksp_dynamic_tolerance_param`` to ``-sub_ksp_dynamic_tolerance``
- Add support for ``MATAIJCUSPARSE`` and ``VECCUDA`` to ``KSPHPDDM``
- Deprecate ``KSP_CONVERGED_CG_NEG_CURVE`` in favor of ``KSP_CONVERGED_NEG_CURVE``
- Deprecate ``KSP_CONVERGED_CG_CONSTRAINED`` in favor of ``KSP_CONVERGED_STEP_LENGTH``
- Add fourth kind Chebyshev polynomials; see ``KSPChebyshevKind`` and ``KSPChebyshevSetKind()``
- Add ``KSPSetConvergedNegativeCurvature()`` to declare convergence if negative curvature is detected by the Krylov solver
- Add MINRES-QLP, available via ``KSPMINRESSetUseQLP()`` or the command line ``-ksp_minres_qlp``
- Replace old MINRES implementation
- Add ``KSPMatSolveTranspose()``

.. rubric:: SNES:

- Add ``SNESPruneJacobianColor()`` to improve the MFFD coloring
- Add ``SNESVIGetVariableBounds()`` to access variable bounds of a ``SNESVI``

.. rubric:: SNESLineSearch:

.. rubric:: TS:

- Add ``TSPruneIJacobianColor()`` to improve the MFFD coloring
- Add argument to ``TSMonitorSPCtxCreate()`` to enable multispecies plots
- Add ``TSMonitorHGCtxCreate()``, ``TSMonitorHGCtxDestroy()``, ``TSMonitorHGSwarmSolution()`` to support histogram plots of particle swarms
- Add support for first-order adjoint calculation for ``TSARKIMEX``

.. rubric:: TAO:

.. rubric:: DM/DA:

- Add ``DMLabelGetType()``, ``DMLabelSetType()``, ``DMLabelSetUp()``, ``DMLabelRegister()``, ``DMLabelRegisterAll()``, ``DMLabelRegisterDestroy()``
- Add ``DMLabelEphemeralGetLabel()``, ``DMLabelEphemeralSetLabel()``, ``DMLabelEphemeralGetTransform()``, ``DMLabelEphemeralSetTransform()``
- Now ``DMGetCellDS()``, ``DMGetRegionDS()``, ``DMSetRegionDS()``, ``DMGetRegionNumDS()``, ``DMSetRegionNumDS()`` can also set and return an input DS

.. rubric:: DMSwarm:

- Add ``DMSwarmGetMigrateType()`` and ``DMSwarmSetMigrateType()``

.. rubric:: DMPlex:

- Add ``DMPlexGetOrientedCone()`` and ``DMPlexRestoreOrientedCone()`` to return both cone and orientation together
- Add ``DMPlexTransformGetChart()``, ``DMPlexTransformGetCellType()``, ``DMPlexTransformGetDepth()``, ``DMPlexTransformGetDepthStratum()``, ``DMPlexTransformGetConeSize()`` to enable ephemeral meshes
- Remove ``DMPlexAddConeSize()``
- Add ``DMPlexCreateEphemeral()``
- Both ``DMView()`` and ``DMLoad()`` now support parallel I/O with a new HDF5 format (see the manual for details)
- Remove ``DMPlexComputeGeometryFEM()`` since it was broken
- Change ``DMPlexMarkBoundaryFaces()`` to avoid marking faces on the parallel boundary. To get the prior behavior, you can temporarily remove the ``PointSF`` from the ``DM``
- Add ``-dm_localize_height`` to localize edges and faces
- Add ``DMPlexCreateHypercubicMesh()`` to create hypercubic meshes needed for QCD
- Add ``-dm_plex_shape zbox`` option to ``DMSetFromOptions()`` to generated born-parallel meshes in Z-ordering (a space-filling curve). This may be used as-is with ``-petscpartitioner_type simple`` or redistributed using ``-petscpartitioner_type parmetis`` (or ``ptscotch``, etc.), which is more scalable than creating a serial mesh to partition and distribute.
- Add ``DMPlexSetIsoperiodicFaceSF()`` to wrap a non-periodic mesh into periodic while preserving the local point representation for both donor and image sheet. This is supported with ``zbox`` above, and allows single-element periodicity.
- Now ``DMPlexGetCompressedClosure()`` also takes the point orientation
- Add ``DMPlexReorderCohesiveSupports()``

.. rubric:: FE/FV:

- Add ``DMPlexGetLocalOffsetsSupport()`` for interaction with libCEED for FV
- Now ``PetscFEIntegrateHybridResidual()`` and ``PetscFEIntegrateHybridJacobian()`` also take the input DS

.. rubric:: DMNetwork:

- Add DMNetworkGetNumVertices to retrieve the local and global number of vertices in DMNetwork
- Add DMNetworkGetNumEdges to retrieve the local and global number of edges in DMNetwork
- Add the ability to use ``DMView()`` on a DMNetwork with a PetscViewer with format ``PETSC_VIEWER_ASCII_CSV``
- Add the ability to use ``-dmnetwork_view draw`` and ``-dmnetwork_view_distributed draw`` to visualize a DMNetwork with an associated coordinate DM. This currently requires the configured Python environment to have ``matplotlib`` and ``pandas`` installed

.. rubric:: DMStag:

.. rubric:: DT:

- Add ``PetscDTCreateDefaultQuadrature()``
- Add ``PetscQuadratureComputePermutations()`` to compute the quadrature permutation corresponding to a k-cell orientation and ``PetscDSPermuteQuadPoint()``
- Add ``PetscQuadratureGetCellType()`` and ``PetscQuadratureSetCellType()``
- Add ``PetscDSCopy()``

.. rubric:: Fortran:

- Add ``MatMPIAIJGetSeqAIJF90()``, ``MatMPIAIJRestoreSeqAIJF90()``
- Deprecate ``ISGetIndices()`` in favor of ``ISGetIndicesF90()``
- Deprecate ``ISRestoreIndices()`` in favor of ``ISRestoreIndicesF90()``
- Deprecate ``ISLocalToGlobalMappingGetIndices()`` in favor of ``ISLocalToGlobalMappingGetIndicesF90()``
- Deprecate ``ISLocalToGlobalMappingRestoreIndices()`` in favor of ``ISLocalToGlobalMappingRestoreIndicesF90()``
- Deprecate ``VecGetArray()`` in favor of ``VecGetArrayF90()``
- Deprecate ``VecRestoreArray()`` in favor of ``VecRestoreArrayF90()``
- Deprecate ``VecGetArrayRead()`` in favor of ``VecGetArrayReadF90()``
- Deprecate ``VecRestoreArrayRead()`` in favor of ``VecRestoreArrayReadF90()``
- Deprecate ``VecDuplicateVecs()`` in favor of ``VecDuplicateVecsF90()``
- Deprecate ``VecDestroyVecs()`` in favor of ``VecDestroyVecsF90()``
- Deprecate ``DMDAVecGetArray()`` in favor of ``DMDAVecGetArrayF90()``
- Deprecate ``DMDAVecRestoreArray()`` in favor of ``DMDAVecRestoreArrayF90()``
- Deprecate ``DMDAVecGetArrayRead()`` in favor of ``DMDAVecGetArrayReadF90()``
- Deprecate ``DMDAVecRestoreArrayRead()`` in favor of ``DMDAVecRestoreArrayReadF90()``
- Deprecate ``DMDAVecGetArrayWrite()`` in favor of ``DMDAVecGetArrayWriteF90()``
- Deprecate ``DMDAVecRestoreArrayWrite()`` in favor of ``DMDAVecRestoreArrayWriteF90()``
- Deprecate ``MatGetRowIJ()`` in favor of ``MatGetRowIJF90()``
- Deprecate ``MatRestoreRowIJ()`` in favor of ``MatRestoreRowIJF90()``
- Deprecate ``MatSeqAIJGetArray()`` in favor of ``MatSeqAIJGetArrayF90()``
- Deprecate ``MatSeqAIJRestoreArray()`` in favor of ``MatSeqAIJRestoreArrayF90()``
- Deprecate ``MatMPIAIJGetSeqAIJ()`` in favor of ``MatMPIAIJGetSeqAIJF90()``
- Deprecate ``MatDenseGetArray()`` in favor of ``MatDenseGetArrayF90()``
- Deprecate ``MatDenseRestoreArray()`` in favor of ``MatDenseRestoreArrayF90()``