petsc-3.15.0 2021-03-30
Report Typos and Errors

# Documentation: Changes: 3.15

## CHANGES in the PETSc Development Version

#### General:

- Add PetscKokkosInitializeCheck(), which initializes Kokkos if it is not yet initialized
- Add support for -debug_terminal Terminal to use Apple's Terminal instead of xterm, allowing use of cut-paste
- Make Terminal the default device to display the debugger on Apple instead of xterm
- Add PetscHasExternalPackage() determining whether PETSc has been configured with the given external package such as "hdf5"

#### Configure/Build:

- On macOS, `MACOS_FIREWALL=1` or `MACOS_FIREWALL_REFRESH=1` can be passed to make to automatically add firewall rules preventing firewall popups during testing. See `make -f gmakefile.test help` for details
- `./configure --with-macos-firewall-rules` makes `MACOS_FIREWALL=1` the default
- Change --download-petsc4py to --with-petsc4py to have PETSc build and use petsc4py
- Add --download-mmg and --download-parmmg, 3D unstructured mesh adaptation package (interaction with DMPlex not available yet)
- Improve detection of Git repositories when a --download-package option is used
  - Support `ssh://*.git` and `https://*.git` URLs without the additional `git://` prefix
  - Local directories can be specified without the `git://` prefix as well
  - Any valid Git repository (including bare and with `--separate-git-dir`) is now correctly detected
- `--download-yaml` or `--with-yaml` are no longer required for YAML support (but can still be used to avoid compiling source included with PETSc)

#### Sys:

- Add PETSCRANDOMCURAND to support CURAND random number generator
- Add PetscRandomGetValues and PetscRandomGetValuesReal to retrieve an array of random numbers
- Add PetscOptions argument to PetscOptionsInsertFileYAML()
- Add PetscCalloc to allocate zeroed memory
- Automatically detect YAML and JSON option files by extension or particular first line
- Update YAML options file processing to ignore keys starting with `$`, Add some special processing
- Add PetscBagViewFromOptions()
- Add PetscLogEventDeactivatePush(), PetscLogEventDeactivatePop()
- Add new option to `-log_view` to view nested event timing information as a flame graph

#### PetscViewer:

- PetscViewerAndFormat now allows a payload
- Change PetscViewerFlowControlStepMaster(), PetscViewerFlowControlEndMaster() to PetscViewerFlowControlStepMain(), PetscViewerFlowControlEndMain()
- HDF5: FILE_MODE_APPEND (= FILE_MODE_UPDATE) now creates a new file if it does not exist yet
- VU: PetscViewerVUSetMode() is now deprecated, please use standard PetscViewerFileSetMode() instead

#### PetscDraw:

#### AO:

#### IS:

#### VecScatter / PetscSF:

- VecScatter is now the same type as PetscSF, in other words, we have typedef PetscSF VecScatter
- Remove VecScatter types VECSCATTER{SEQ,MPI1,MPI3,MPI3NODE,SF}. One can use all PetcSF types as VecScatter types
- Rename PetscLayoutsCreateSF() to PetscSFCreateFromLayouts() and move its declaration from petscis.h to petscsf.h
- Deprecate MPIU_REPLACE; Use MPI_REPLACE instead
- Deprecate PetscSFBcastAndOp variants; Use PetscSFBcast instead
- Deprecate PetscSFCreateEmbeddedSF; Use PetscSFCreateEmbeddedRootSF instead
- Add experimental NVIDIA NVSHMEM support; For details on how to use it, contact petsc-maint@mcs.anl.gov
- Add PetscSFCreateByMatchingIndices() to create SF by matching root and leaf indices

#### PF:

#### Vec:

- Change Vec{Get,Restore}Array{Read}Inplace to Vec{Get,Restore}Array{Read}AndMemType() and add an extra argument to also return the memory type of the array
- Remove vector type VECNODE
- Add VecConcatenate() function for vertically concatenating an array of vectors into a single vector. Also returns an array of index sets to access the original components within the concatenated final vector

#### PetscSection:

#### PetscPartitioner:

#### Mat:

- Add MatSetPreallocationCOO and MatSetValuesCOO to preallocate and set values in a matrix using COO format. Currently efficiently implemented only for MATCUSPARSE
- Add the option MAT_FORCE_DIAGONAL_ENTRIES for MatSetOption(). It forces allocation of all diagonal entries
- Remove MAT_NEW_DIAGONALS from MatOption
- Add UNKNOW_NONZERO_PATTERN as new value for MatStructure. It indicates that the relationship is unknown, when set the AIJ matrices check if the two matrices have identical patterns and if so use the faster code
- Add MAT_FACTOR_QR, MatQRFactor(), MatQRFactorSymbolic(), and MatQRFactorNumeric() for QR factorizations. Currently the only built-in implementation uses LAPACK on sequential dense matrices
- Change option -mat_cusparse_transgen to -mat_form_explicit_transpose to hint PETSc to form an explicit transpose for repeated operations like MatMultTranspose. Currently implemented only for AIJCUSPARSE and AIJKOKKOS
- Add a MatOption MAT_FORM_EXPLICIT_TRANSPOSE

#### PC:

- Add PCGAMGSetRankReductionFactors(), provide an array, `-pc_gamg_rank_reduction_factors factors`, tp specify factor by which to reduce active processors on coarse grids in PCGAMG that overrides default heuristics
- Change PCCompositeAddPC() to PCCompositeAddPCType(), now PCCompositeAddPC() adds a specific PC object
- Add a Compatible Relaxation (CR) viewer PCMG with -pc_mg_adapt_cr
- Experimental: Add support for assembling AIJ (CUSPARSE and KOKKOS) matrix on the Cuda device with MatSetValuesDevice(), MatCUSPARSEGetDeviceMatWrite(), and Kokkos with MatKokkosGetDeviceMatWrite
- Add PCMGSetResidualTranspose() to support transposed linear solve using PCMG and GAMG

#### KSP:

- Add `-all_ksp_monitor` which turns on monitoring for all KSP solvers regardless of their prefix. This is useful for monitoring solvers with inner solvers such as PCMG, PCGAMG, PCFIELDSPLIT.
- Add support for monitor KSPPREONLY. This is useful for monitoring solvers with inner solvers such as PCMG, PCGAMG, PCFIELDSPLIT.
- Add KSPConvergedReasonViewSet() to set an ADDITIONAL function that is to be used at the end of the linear solver to display the convergence reason of the linear solver
- Add KSPConvergedReasonViewCancel() to remove all user-added converged reason view functions
- Add KSPGetConvergedReasonString() to retrieve a human readable string for ksp converged reason
- Change KSPReasonView() to KSPConvergenceReasonView()
- Change KSPReasonViewFromOptions() to KSPConvergedReasonViewFromOptions()
- Add KSPConvergedDefaultSetConvergedMaxits() to declare convergence when the maximum number of iterations is reached
- Fix many KSP implementations to actually perform the number of iterations requested
- Chebyshev uses MAT_SPD to default to CG for the eigen estimate
- Add KSPPIPECG2, a pipelined solver that reduces the number of allreduces to one per two iterations and overlaps it with two PCs and SPMVs using non-blocking allreduce
- Add KSPConvergedRateView() and KSPComputeConvergenceRate() to check the convergence rate of a linear solve
- Add KSPSetUseExplicitTranspose() to explicitly transpose the system in KSPSolveTranspose()
- Add KSPMonitorLGCreate(), and remove KSPMonitorLGResidualNorm*() and KSPMonitorLGTrueResidualNorm*()
- Add KSPMonitorError(), used by `-ksp_monitor_error`
- Add arguments to KSPMonitorSetFromOptions() to allow line graphs to be configured
- Deprecate KSP{Set|Get}MatSolveBlockSize(), use KSP{Set|Get}MatSolveBatchSize() instead
- Reduce default KSPView() ASCII output to a single subdomain's KSP/PC information for PCASM, resp. PCBJacobi. Use -ksp_view ::ascii_info_detail to output KSP/PC information for all subdomains

#### SNES:

- Add SNESConvergedCorrectPressure(), which can be selected using `-snes_convergence_test correct_pressure`
- Remove SNESMonitorLGCreate() and SNESMonitorLGResidualNorm() which are now handled by the default monitor
- Add SNESConvergedReasonViewSet() to set an ADDITIONAL function that is to be used at the end of the nonlinear solver to display the convergence reason of the nonlinear solver
- Add SNESConvergedReasonViewCancel() to remove all user-added converged reason view functions
- Add SNESGetConvergedReasonString() to retrieve a human readable string for snes converged reason
- Add SNESFASFullSetTotal() to use total residual restriction and total solution interpolation in the initial cycle of full FAS multigrid
- Deprecate -snes_nasm_sub_view, use -snes_view ::ascii_info_detail instead

#### SNESLineSearch:

#### TS:

- Change to --download-sundials2 to indicate the version of SUNDIALS PETSc downloads, which is very old and out-dated
- Add forward and adjoint sensitivity support for cases that involve parameterized mass matrices
- Add TSGetNumEvents() to retrieve the number of events
- Add -ts_monitor_cancel
- Now -ts_view_solution respects the TS prefix

#### TAO:

- Add TSSetMatStructure() to indicate the relationship between the nonzero structures of the I Jacobian and the RHS Jacobian
- Automatically set the MatStructure flag of TS to SAME_NONZERO_PATTERN if the RHS matrix is obtained with a MatDuplicate() from the I Jacobian
- Add TaoSetRecycleFlag() and TaoGetRecycleFlag() interfaces to enable some Tao algorithms to re-use iterate information from the previous TaoSolve() call
- Add new Augmented Lagrangian Multiplier Method (TAOALMM) for solving optimization problems with general nonlinear constraints

#### DM/DA:

- Remove unneeded Vec argument from DMPatchZoom()
- Change DMDACreatePatchIS() to collective operation and add an extra argument to indicate whether off processor values will be returned
- Add DMComputeError(), which uses PetscDS information for the exact solution
- Add DMShellGetGLobalVector()
- Add DMInterpolateSolution() for interpolating solutions between meshes in a potentially nonlinear way
- DMInterpolationSetUp() now can drop points outside the domain

#### DMSwarm:

- DMSwarmViewXDMF() can now use a full path for the filename
- Add DMSwarmSetPointCoordinatesRandom()
- Add -dm_view_radius to set size of drawn particles

#### DMPlex:

- Using -petscpartitioner_simple_node_grid and -petscpartitioner_simple_process_grid, the Simple partitioner can now make grid partitions
- Add DMGet/SetFieldAvoidTensor() to allow fields to exclude tensor cells in their definition
- Remove regular refinement and marking from DMPlexCreateDoublet()
- Add high order FEM interpolation to DMInterpolationEvaluate()

#### FE/FV:

- Add PetscDualSpaceTransformHessian(), PetscDualSpacePushforwardHessian(), and PetscFEPushforwardHessian()
- Now PetscFEGetCellTabulation() and PetscFEGetFaceTabulation() ask for the number of derivatives
- Add PetscDualSpaceLagrangeGet/SetUseMoments() and PetscDualSpaceLagrangeGet/SetMomentOrder() to allow a moment integral for P0

#### DMNetwork:

- Add DMNetworkAddSubnetwork() for network of subnetworks
- Add DMNetworkAdd/GetSharedVertices(), DMNetworkIsSharedVertex()
- Remove DMNetworkSetEdgeList(), DMNetworkSet/GetComponentNumVariables(), DMNetworkSet/Add/GetNumVariables(), DMNetworkGetComponentKeyOffset(), DMNetworkGetVariableOffset(), DMNetworkGetVariableGlobalOffset()
- Change the prototypes for DMNetworkAdd/GetComponent()
- Rename DMNetworkSet/GetSizes() to DMNetworkSet/GetNumSubNetworks()
- Rename DMNetworkGetComponentVariableOffset() to DMNetworkGetLocalVecOffset(), DMNetworkGetComponentVariableGlobalOffset() to DMNetworkGetGlobalVecOffset()
- Rename DMNetworkGetSubnetworkInfo() to DMNetworkGetSubnetwork()

#### DT:

- PetscDSCopyBoundary() now takes a list of fields for which boundary copying is done
- Add PetscDSGet/SetJetDegree(), and -dm_ds_jet_degree is needed to enable it under a DM
- Add PetscWeakForm class to manage function pointers for problem assembly

#### Fortran:

- Add configure option `--with-mpi-f90module-visibility` [default=1]. With `0` mpi.mod will not be visible in use code (via petscsys.mod) - so `mpi_f08` can now be used
- Add PetscDLAddr() to get name for a symbol