Documentation: Changes: 3.4

General:

• PetscGetTime() is replaced with PetscTime(), in C you must include petsctime.h to use
• PetscViewerBinaryMatlabOpen() and friends are all removed, simply use PetscViewerBinaryOpen() followed by PetscViewerPushFormat(viewer,PETSC_VIEWER_BINARY_MATLAB)
• Users should use new PetscFunctionBeginUser in there code instead of PetscFunctionBegin to get more relevant diagnostics.
• Replaced the hodge-podge of -xxx_view -xxx_view_yyy with a single consistent scheme: -xxx_view [ascii,binary,draw,socket,matlab,vtk][:filename][:ascii_info,ascii_info_detail,ascii_matlab,draw_contour,etc].
• In PETSc options files, the comment characters ! and % are no longer supported, use #.
• PetscFList and PetscOList have been changed to PetscFunctionList and PetscObjectList. PetscFunctionListFind() no longer takes the path to a shared library or the string name of the function. Plugins distributed as shared libraries should register their implementations by calling suitable XXRegister() functions from within their PetscDLLibraryRegister_basename(), see documentation for PetscDLLibraryOpen().
• MatRegisterDynamic(), PCRegisterDynamic(), KSPRegisterDynamic(), etc., have been simplified to drop the string function name argument, and are simply named MatRegister(), PCRegister(), KSPRegister(), etc. PetscObjectComposeFunctionDynamic() also drops the string function name argument and is called PetscObjectComposeFunction().
• The configure options --with-c-support and --with-c++-support have been removed. A PETSc library built using C or C++ can be called from either C or C++. The primary functional reason to use --with-clanguage=C++ is to use std::complex data types. Other users will likely prefer --with-clanguage=C (the default) because it compiles somewhat faster. The --with-c-support option is no longer needed because it is now the default behavior when using --with-clanguage=c++.

Logging:

config/configure.py:

PetscSF:

• PetscSF was split into interface and impls. The internal interfaces PetscSFGetDataTypes(), PetscSFGetWindow(), PetscSFFindWindow(), andd PetscSFRestoreWindow() were made private. (It is unlikely that any users were calling these routines.) PetscSFSetSynchronizationType() and the enum PetscSFSynchronizationType were renamed to PetscSFWindowSetSyncType() and PetscSFWindowSyncType respectively.
• The location arguments to PetscSFGetRanks() were changed from PetscMPIInt (aka int) to PetscInt to (eventually) support very large local memory. The "window" implementation will not support such large sizes due to technical limitations of MPI one sided and "basic" does not currently due to PetscGatherMessageLengths().

IS:

• PetscSection was moved to IS and has become a PetscObject, thus reference counting works as usual, with functions like DMSetLocalSection() taking a reference to the PetscSection. The caller is thus obliged to release their reference using PetscSectionDestroy().

PF:

Vec:

• The options -vec_view, -vec_view_matlab, -vec_view_socket, -vec_view_binary, -vec_view_draw, -vec_view_lg have been replace by a more general systematic scheme of -vec_view [ascii,binary,draw, or socket][:filename][:format], for these cases they are exactly: -vec_view -vec_view ::ascii_matlab -vec_view socket -vec_view binary -vec_view draw -vec_view draw::draw_lg
• VecDotNorm2() now returns the square of the norm in a real number (PetscReal) rather than the real part of a complex number (PetscScalar)
• Added VecDotRealPart()
• The private header petsc/private/vecimpl.h is no longer included by petscvec.h. Users requiring direct access to internal members of Vec may need to include the private header, but may want to explain their use case to [email protected] so that we can provide a stable API.
• VecGetArray()/VecRestoreArray() and VecGhostGetLocalForm()/VecGhostRestoreLocalForm() are logically collective operations because their use invalidates norms, which must be known collectively. This is not a change in behavior, but prior documentation did not mark them as collective. Users should not rely on use such as lazy access occurring inside loops that could have length zero on some processors because it could lead to deadlock in a subsequent norm computation. VecGetArrayRead() and VecRestoreArrayRead() are not collective.

VecScatter:

Mat:

• The options -mat_view, -mat_view_info, -mat_view_info_detailed -mat_view_matlab, -mat_view_socket, -mat_view_binary, -mat_view_draw, -mat_view_contour have been replace by a more general systematic scheme of -mat_view [ascii,binary,draw, or socket][:filename][:format], for these cases they are exactly: -mat_view -mat_view ::ascii_info -mat_view ::ascii_info_detail -mat_view ::ascii_matlab -mat_view socket -mat_view binary -mat_view draw -mat_view draw::draw_contour
• MatGetArray()/MatRestoreArray() have been remove d. Use MatDenseGetArray()/MatDenseRestoreArray() or MatSeqAIJGetArray()/MatSeqAIJRestoreArray()
• PLAPACK interface has been removed.
• MatGetRowIJ() and MatGetColumnIJ() have been made const-correct; the index arrays have always been read-only.
• MatRestoreRow() and MatRestoreRowIJ() now zero their arguments. They should never have been accessed after restoring.
• MatPermute() can now be used for MPIAIJ, but contrary to prior documentation, the column IS should be parallel and contain only owned columns.

PC:

• The default behavior for PCILU was changed from -pc_factor_shift_type nonzero to -pc_factor_shift_type inblock (note it is -sub_pc_factor_shift_type if the ILU is used inside block Jacobi). If previously you had convergence of iterative solvers with ILU and now for the same code you get zero pivot errors or PC setup errors then try the option -pc_factor_shift_type nonzero.
• Merged PCBJacobiSetUseTrueLocal(), -pc_bjacobi_true_local, PCKSPSetUseTrue(), -pc_ksp_true, PCCompositeSetUseTrue() -pc_composite_true, PCFieldSplitSetRealDiagonal -pc_fieldpslit_real_diagonal to PCSetUseAmat(), -pc_use_amat.
• Added PCISSetSubdomainDiagonalScaling() if a user wants to set a custom scaling at the interface.
• Added initial version of FETI-DP in PCBDDC code.
• Added PCBDDCCreateFETIDPOperators() for creation of FETI-DP mat and the related Dirichlet preconditioner using an already existing PCBDDC object.
• Added PCBDDCMatFETIDPGetRHS() for assembling of right-hand side of FETI-DP linear system.
• Added PCBDDCMatFETIDPGetSolution() for assembling of physical solution from FETI-DP solution.
• Added support to deal with linear systems with non-trivial kernels via PCBDDCSetNullSpace().
• Added PCBDDCSetMaxLevels() to control the maximum number of levels when doing multilevel.
• Added PCBDDCSetCoarseningRatio() to control the coarsening ratio when doing multilevel.
• Added PCISSetUseStiffnessScaling() to build partition of unity using local matrices' diagonal.
• Removed PETSc interface to Prometheus. Use "-pc_type gamg -pc_gamg_type agg" as alternative.
• PC_FIELDSPLIT_SCHUR_PRE_DIAG changed to PC_FIELDSPLIT_SCHUR_PRE_A11.

KSP:

• Replace -ksp_view_binary with either -ksp_view_mat binary - save matrix to the default binary viewer or-ksp_view_pmat binary - save matrix to the default binary viewer followed by -ksp_view_rhs binary - save right hand side vector to the default binary viewer. Also many other combinations are possible.

SNES:

• Added added -snes_check_jacobian a very powerful way to check if your Jacobian is correct for small problems, see SNESUpdateCheckJacobian()
• SNESVIRS "virs" changed to SNESVINEWTONRSLS vinewtonrsls to clarify exactly what they do
• SNESVISS "viss" changed to SNESVINEWTONSSLS vinewtonssls
• SNESLS "ls" changed to SNESNEWTONLS newtonls
• SNESTR "tr" changed to SNESNEWTONTR newtontr
• SNESDefaultComputeJacobian(), SNESDefaultComputeJacobianColor(), SNESDefaultObjectiveComputeFunctionFD(), SNESDefaultConverged() changed to SNESComputeJacobianDefault(), SNESComputeJacobianDefaultColor(), SNESConvergedDefault(), SNESObjectiveComputeFunctionDefaultFD() to match more consistent naming standards.
• Added nonlinear additive Schwarz as SNESNASM "nasm"
• Added helper SNES type SNESASPIN "aspin" for setting up additive Schwarz preconditioned inexact Newton.
• Added Anderson Mixing as SNESANDERSON "anderson"
• SNESGetSNESLineSearch() and SNESSetSNESLineSearch() renamed to SNESGetLineSearch() and SNESSetLineSearch().

SNESLineSearch:

TS:

• Option -ts_monitor_solution changed to -ts_monitor_draw_solution. See TSSetFromOptions for additional monitoring options.
• TSSetExactFinalTime() now takes an enum instead of PetscBool, which includes a new feature TS_EXACTFINALTIME_MATCHSTEP that adjusts time step sizes to match an exact final time. See TSExactFinalTimeOption.

DM/DA:

• DMDAGetCoordinateDA(), DMDAGet/SetCoordinates(), DMDAGet/SetGhostedCoordinates(), and DMComplexGetCoordinateVec() have been removed in favor of DMGetCoordinateDM(), DMGet/SetCoordinates(), and DMGet/SetCoordinatesLocal()
• DMDASetLocalFunction() and DMDASetLocalJacobian() have been replaced with DMDASNESSetFunctionLocal() and DMDASNESSetJacobianLocal() -- note that the calling sequences of these functions are different and also the calling sequence of the Jacobian function you provide
• DMSetFunction() and DMSetJacobian() have been removed use SNESSetFunction() and SNESSetJacobian() instead, note the calling sequences are slightly different
• DMDACreatePatchIS() for getting the indices of an arbitrary subdomain on a DMDA
• DMDAGet/SetOverlap(),DMDAGet/SetOffset() for manipulating DMDA subdomains
• DMCreateDomainDecompositionScatters() gives VecScatter objects for transferring to/from subdomain DMs
• DMGet/RestoreNamedLocalVector()

DMComplex/DMPlex:

• DMComplex was renamed to DMPlex.
• There is now a manual section on unstructured grids.

DMMesh:

• This is deprecated in favor of DMPlex, and will be removed in 3.5.
• SectionRealToVecDM() was created to removed overloading.

DMMG:

PetscViewer:

SYS:

• PetscPClose() has an additional argument to return a nonzero error code without raising an error.
• Added PetscSortMPIInt() and PetscSortRemoveDupsMPIInt().

AO:

Sieve:

Fortran:

ExternalPackages:

• Added Elemental interface
• Remove Spooles interface