xref: /petsc/doc/changes/34.md (revision b11d9968bc79904c690b122f9399be46447eb113)

# Changes: 3.4

```{rubric} 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++.

```{rubric} Logging:
```

```{rubric} config/configure.py:
```

```{rubric} 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().

```{rubric} 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().

```{rubric} PF:
```

```{rubric} 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
  `petsc-maint@mcs.anl.gov` 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.

```{rubric} VecScatter:
```

```{rubric} 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.

```{rubric} 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](http://www.columbia.edu/~ma2325/prometheus/). Use
  "-pc_type gamg -pc_gamg_type agg" as alternative.
- PC_FIELDSPLIT_SCHUR_PRE_DIAG changed to
  PC_FIELDSPLIT_SCHUR_PRE_A11.

```{rubric} 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.

```{rubric} 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().

```{rubric} SNESLineSearch:
```

```{rubric} 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`.

```{rubric} 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()

```{rubric} DMComplex/DMPlex:
```

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

```{rubric} DMMesh:
```

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

```{rubric} DMMG:
```

```{rubric} PetscViewer:
```

```{rubric} SYS:
```

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

```{rubric} AO:
```

```{rubric} Sieve:
```

```{rubric} Fortran:
```

```{rubric} ExternalPackages:
```

- Added Elemental interface
- Remove Spooles interface