xref: /petsc/doc/changes/322.md (revision 7f296bb328fcd4c99f2da7bfe8ba7ed8a4ebceee)

# 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 $M$ for
  $P = (A + alpha M) M^{-1} (alpha M + B)$
- Reuse the result of $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 $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