=============
Changes: 3.22
=============

..
   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 ``-mpiuni-allow-multiprocess-launch`` to allow mpiexec to launch multiple indendent MPI-Uni jobs. Previously a sanity check
  error message was always produced

.. rubric:: Configure/Build:

- Add ``--with-openmp-kernels``
- Update to work with python-3.13
- Change ``MPIU_Allreduce()`` to always returns an MPI error code that should be checked with ``PetscCallMPI()``
- Add ``PetscCallReturnMPI()``, ``PetscCallMPIReturnMPI()``, and ``PetscCheckReturnMPI()`` to check for in PETSc provided MPI callbacks

.. rubric:: Sys:

- Add ``PetscPragmaUseOMPKernels``
- Deprecate ``PetscOptionsRestoreViewer()`` in favor of ``PetscViewerDestroy()``
- Deprecate ``PetscOptionsGetViewer()`` and ``PetscOptionsGetViewers()`` in favor of ``PetscOptionsCreateViewer()`` and ``PetscOptionsCreateViewers()``
- Deprecate ``PetscOptionsPushGetViewerOff()``, ``PetscOptionsPopGetViewerOff()``, and ``PetscOptionsGetViewerOff()`` in favor of
  ``PetscOptionsPushCreateViewerOff()``, ``PetscOptionsPopCreateViewerOff()``, and ``PetscOptionsGetCreateViewerOff()``
- Add ``PetscObjectContainerCompose()`` and ``PetscObjectContainerQuery()``
- Add ``size_t`` argument to ``PetscMPIErrorString()``
- Add ``PetscCallExternalAbort()`` for calling external library functions from functions not returning ``PetscErrorCode``
- Add ``PetscRandomSetOptionsPrefix()``
- Add ``PetscOptionsGetBool3()`` to get a ternary logical value from a command line option

.. rubric:: Event Logging:

.. rubric:: PetscViewer:

- Add ``PetscViewerASCIIStdoutSetFileUnit()``
- Add ``PetscShmgetAllocateArrayScalar()``, ``PetscShmgetDeallocateArrayScalar()``, ``PetscShmgetAllocateArrayInt()``, and ``PetscShmgetDeallocateArrayInt()`` for Fortran

.. rubric:: PetscDraw:

.. rubric:: AO:

.. rubric:: IS:

.. rubric:: VecScatter / PetscSF:

- Add ``PetscSFRegisterPersistent()`` and ``PetscSFDeregisterPersistent()`` for safe optimization of persistent communication

.. rubric:: PF:

.. rubric:: Vec:

- The ``IS`` passed to ``VecISAXPY()`` and ``VecISCopy()``. ``VecISSet()`` and ``VecISShift()`` must have the same communicator of the vectors used
- Make ``VecLock`` API active in optimized mode
- ``VecNestSetSubVec()`` and ``VecNestSetSubVecs()`` now take references to input vectors rather than creating duplicates
- Deprecate ``VecSetInf()`` with ``VecFlag()``

.. rubric:: PetscSection:

.. rubric:: PetscPartitioner:

.. rubric:: Mat:

-  Change ``MatProductSetFill()`` to support ``PETSC_DETERMINE`` and ``PETSC_CURRENT``. ``MatMatMult()`` and its friends and relations now accept
   ``PETSC_DETERMINE`` and ``PETSC_CURRENT`` in the ``fill`` argument. ``PETSC_DEFAULT`` is deprecated for those functions
- Change the default ``MatType`` of the output ``Mat`` of ``MatSchurComplementComputeExplicitOperator()`` to be ``MATDENSE``. It may be changed from the command line, e.g., ``-fieldsplit_1_explicit_operator_mat_type aij``
- Add ``MATOP_GET_BLOCK_DIAGONAL`` and ``MATOP_GET_VBLOCK_DIAGONAL`` to set methods returning the diagonal point blocks of a matrix

.. rubric:: MatCoarsen:

.. rubric:: PC:

- Add support in ``PCFieldSplitSetFields()`` including with ``-pc_fieldsplit_%d_fields fields`` for ``MATNEST``,  making it possible to
  utilize multiple levels of ``PCFIELDSPLIT`` with ``MATNEST`` from the command line
- Add ``PCCompositeSpecialSetAlphaMat()`` API to use a matrix other than the identity in
  preconditioners based on an alternating direction iteration, e.g., setting :math:`M` for
  :math:`P = (A + alpha M) M^{-1} (alpha M + B)`
- Reuse the result of :math:`T = A_{00}^-1 A_{01}` in ``PCApply_FieldSplit_Schur`` with ``-pc_fieldsplit_schur_fact_type full``
- Change the option database keys for coarsening for ``PCGAMG`` to use the prefix ``-pc_gamg_``, for example ``-pc_gamg_mat_coarsen_type``
- Add ``PCGAMGSetGraphSymmetrize()`` and ``-pc_gamg_graph_symmetrize`` to control symmetrization when coarsening the graph
- Add ``-pc_hypre_type ilu`` with ``-pc_hypre_ilu_type``, ``-pc_hypre_ilu_iterative_setup_type``, ``-pc_hypre_ilu_iterative_setup_maxiter``,
  ``-pc_hypre_ilu_iterative_setup_tolerance``, ``-pc_hypre_ilu_print_level``, ``-pc_hypre_ilu_logging``, ``-pc_hypre_ilu_level``,
  ``-pc_hypre_ilu_max_nnz_per_row``, ``-pc_hypre_ilu_tol``, ``-pc_hypre_ilu_maxiter``, ``-pc_hypre_ilu_drop_threshold``,
  ``-pc_hypre_ilu_tri_solve``, ``-pc_hypre_ilu_lower_jacobi_iters``, ``-pc_hypre_ilu_upper_jacobi_iters``, and ``-pc_hypre_ilu_local_reordering``
- Improve ``-pc_type boomeramg`` with ``-pc_hypre_boomeramg_smooth_num_sweeps``, ``-pc_hypre_boomeramg_ilu_type``, ``-pc_hypre_boomeramg_ilu_iterative_setup_type``,
  ``-pc_hypre_boomeramg_ilu_iterative_setup_option``, ``-pc_hypre_boomeramg_ilu_iterative_setup_maxiter``, ``-pc_hypre_boomeramg_ilu_iterative_setup_tolerance``,
  ``-pc_hypre_boomeramg_ilu_print_level``, ``-pc_hypre_boomeramg_ilu_logging``, ``-pc_hypre_boomeramg_ilu_level``, ``-pc_hypre_boomeramg_ilu_max_nnz_per_row``,
  ``-pc_hypre_boomeramg_ilu_maxiter``, ``-pc_hypre_boomeramg_ilu_drop_tol``, ``-pc_hypre_boomeramg_ilu_tri_solve``, ``-pc_hypre_boomeramg_ilu_lower_jacobi_iters``,
  ``-pc_hypre_boomeramg_ilu_upper_jacobi_iters``, and ``-pc_hypre_boomeramg_ilu_local_reordering``

.. rubric:: KSP:

- Add support for ``PETSC_DETERMINE`` as an argument to ``KSPSetTolerances()`` to set the parameter back to its initial value when the object's type was set
- Deprecate ``PETSC_DEFAULT`` in favor of ``PETSC_CURRENT`` for  ``KSPSetTolerances()``

.. rubric:: SNES:

- Add support for ``PETSC_DETERMINE`` as an argument to ``SNESSetTolerances()`` to set the parameter back to its initial value when the object's type was set
- Deprecate ``PETSC_DEFAULT`` in favor of ``PETSC_CURRENT`` for  ``SNESSetTolerances()``
- Add ``DMAdaptorMonitor()``, ``DMAdaptorMonitorSet()``,  ``DMAdaptorMonitorCancel()``, and ``DMAdaptorMonitorSetFromOptions()``
- Add ``DMAdaptorMonitorSize()``, ``DMAdaptorMonitorError()``, ``DMAdaptorMonitorErrorDraw()``, ``DMAdaptorMonitorErrorDrawLGCreate()``, and ``DMAdaptorMonitorErrorDrawLG()``
- Add ``DMAdaptorMonitorRegister()``, ``DMAdaptorMonitorRegisterAll()``, and ``DMAdaptorMonitorRegisterDestroy()``
- Add ``DMAdaptorGetCriterion()`` and ``DMAdaptorSetCriterion()``
- Add ``DMAdaptorSetOptionsPrefix()``
- Add Newton's method with arc length continuation: ``SNESNEWTONAL`` with ``SNESNewtonALSetFunction()``, ``SNESNewtonALGetFunction()``, ``SNESNewtonALComputeFunction()``, ``SNESNewtonALGetLoadParameter()``, and ``SNESNewtonALSetCorrectionType()``
- Add ``SNESNewtonTRSetTolerances()`` and ``SNESNewtonTRSetUpdateParameters()`` to programmatically set trust region parameters
- Deprecate ``SNESSetTrustRegionTolerance()`` in favor of ``SNESNewtonTRSetTolerances()``
- Add ``SNESResetCounters()`` to reset counters for linear iterations and function evaluations

.. rubric:: SNESLineSearch:

.. rubric:: TS:

- Add Rosenbrock-W methods from :cite:`rang2015improved` with :math:`B_{PR}` stability: ``TSROSWR34PRW``, ``TSROSWR3PRL2``, ``TSROSWRODASPR``, and ``TSROSWRODASPR2``
- Add support for ``PETSC_DETERMINE`` as an argument to ``TSSetTolerances()`` to set the parameter back to its initial value when the object's type was set
- Deprecate ``PETSC_DEFAULT`` in favor of ``PETSC_CURRENT`` for  ``TSSetTolerances()``
- Add support for ``PETSC_DETERMINE`` as an argument to ``TSSetMaxSteps()`` and ``TSSetMaxTime()``
- Deprecate ``PETSC_DEFAULT`` in favor of ``PETSC_CURRENT`` for ``TSAdaptSetSafety()``
- Deprecate ``PETSC_DEFAULT`` in favor of ``PETSC_CURRENT`` for ``TSAdaptSetClip()``
- Deprecate ``PETSC_DEFAULT`` in favor of ``PETSC_CURRENT`` for ``TSAdaptSetStepLimits()``
- Add  ``TSGetStepResize()``
- Add  ``-ts_monitor_solution_vtk_interval`` to control the interval for dumping files
- Add a new ARKIMEX solver for fast-slow systems that are partitioned component-wise and additively at the same time
- Add ``TSRHSSplitSetIFunction()``, ``TSRHSSplitSetIJacobian()``, ``TSRHSSplitSetSNES()``, ``TSRHSSplitGetSNES()``, ``TSARKIMEXSetFastSlowSplit()``, and ``TSARKIMEXGetFastSlowSplit()`` to support the new solver

.. rubric:: TAO:

- Add support for ``PETSC_DETERMINE`` as an argument to ``TaoSetTolerances()`` and ``TaoSetConstraintTolerances()`` to set the parameter back to its initial value when the object's type was set
- Deprecate ``PETSC_DEFAULT`` in favor of ``PETSC_CURRENT`` for  ``TaoSetTolerances()`` and ``TaoSetConstraintTolerances()``

.. rubric:: DM/DA:

- Add ``DMGetSparseLocalize()`` and ``DMSetSparseLocalize()``
- Add ``DMGeomModelRegister()``, ``DMGeomModelRegisterAll()``, ``DMGeomModelRegisterDestroy()``, ``DMSnapToGeomModel()``, and ``DMSetSnapToGeomModel()`` to support registering geometric models
- Add ``DMGetOutputSequenceLength()``
- Add an additional return vector to ``DMCreateMassMatrixLumped()`` to retrieve the local mass lumping
- Add ``DMPlexMigrateGlobalToNaturalSF()`` modifies the NaturalSF to map from the SF's old global section to the new global section

.. rubric:: DMSwarm:

.. rubric:: DMPlex:

- Add ``DMLabelGetValueBounds()``
- Add ``DMPlexOrientLabel()``
- Add an argument to ``DMPlexLabelCohesiveComplete()`` in order to change behavior at surface boundary
- Remove ``DMPlexSnapToGeomModel()``
- Add refinement argument to ``DMPlexCreateHexCylinderMesh()``
- Now ``DMPlexComputeBdIntegral()`` takes one function per field
- Add ``DMPlexCreateEdgeNumbering()``
- Add ``DMPlexComputeL2FluxDiffVec()`` and ``DMPlexComputeL2FluxDiffVecLocal()``
- Add ``DMAdaptorSetType()``, ``DMAdaptorGetType()``, ``DMAdaptorRegister()``, ``DMAdaptorRegisterAll()``, and ``DMAdaptorRegisterDestroy()``
- Add ``DMAdaptorGetMixedSetupFunction()`` and ``DMAdaptorSetMixedSetupFunction()``
- Add ``DMPlexCreateCellNumbering()``
- Add ``DMPlexBuildFromCellSectionParallel()`` and ``DMPlexCreateFromCellSectionParallel()``
- Add ``-dm_plex_box_label`` to add "Face Sets" label with current "box" conventions
- Add "Face Sets" label to simplex meshes using current "box" conventions
- Update ``PetscViewerExodusII`` object to cache variable names  for faster and  more robust look-ups
- Add ``PetscViewerExodusIISetNodalVariable()``, ``PetscViewerExodusIISetZonalVariable()``, ``PetscViewerExodusIIGetNodalVariable()``, and ``PetscViewerExodusIIGetZonalVariable()`` to set or get the number of variables in a file
- Add ``PetscViewerExodusIISetNodalVariableName()``, ``PetscViewerExodusIISetZonalVariableName()``, ``PetscViewerExodusIIGetNodalVariableName()``, and ``PetscViewerExodusIIGetZonalVariableName()`` to set or get a single variable name
- Add ``PetscViewerExodusIISetNodalVariablesNames()``, ``PetscViewerExodusIISetZonalVariablesNames()``, ``PetscViewerExodusIIGetNodalVariablesNames()``, and ``PetscViewerExodusIIGetZonalVariablesNames()`` to set or get all variable names at the same time (not available in Fortran)
- Add degree bounds to ``DMCopyFields()``, ``DMCopyDS()``, ``PetscDSCopy()``, and ``PetscDSSelectDiscretizations()``
- Add ``PetscFELimitDegree()``
- Add localizationHeight and sparseLocalize arguments to ``DMPlexCreateBoxMesh()`` for coordinate localization on periodic meshes
- Add parallel CGNS reader, enabled by ``-dm_plex_cgns_parallel``
- Add CGNS function for ``VecLoad()`` of solutions in parallel (must be run with ``-dm_plex_cgns_parallel``)
- Add ``PetscViewerCGNSOpen()`` convenience function
- Add ``PetscViewerCGNSGetSolutionTime()``, ``PetscViewerCGNSGetSolutionName()``, ``PetscViewerCGNSSetSolutionIndex()``, and ``PetscViewerCGNSGetSolutionIndex()``
- Add ``DMPlexGetDepthStratumGlobalSize()``

.. rubric:: FE/FV:

.. rubric:: DMNetwork:

.. rubric:: DMStag:

.. rubric:: DT:

- Add ``PetscDSSetIntegrationParameters()`` and ``PetscDSSetCellParameters()``

.. rubric:: Fortran:

- Add ``PETSC_NULL_ENUM`` to be used instead of ``PETSC_NULL_INTEGER`` when a pointer to an ``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 array is expected in a PETSc function call
- 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``
- 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