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

# Changes: 3.8

```{rubric} General:
```

- `--download-metis` is changed to not builds metis with flag
  `-DMETIS_USE_DOUBLEPRECISION=1` to have consistent behavior
  between single/double/quad precision builds (and with external
  build of metis). This affects parmetis as well

```{rubric} Configure/Build:
```

- removed with-mpiuni-fortran-binding option
- removed with-fortran-interfaces option
- removed with-fortran-datatypes option
- Added --download-openblas --download-openblas-64-bit-blas-indices

```{rubric} IS:
```

- Changed IS_COLORING_GHOSTED to IS_COLORING_LOCAL to match
  convention.
- Added ISRenumber to renumber an IS into a contiguous set.
- ISGlobalToLocalMappingType is now ISGlobalToLocalMappingMode.
- Added ISGlobalToLocalMappingSetType() to change the algorithm used
  to apply the mapping. Choices are ISGLOBALTOLOCALMAPPINGBASIC
  (faster) or ISGLOBALTOLOCALMAPPINGHASH (for large problems, much
  more scalable in memory usage)

```{rubric} PetscDraw:
```

```{rubric} PetscRandom:
```

- Added PETSCRANDOM123, a wrapper to the counter-based random number
  generator
  [Random123](http://www.deshawresearch.com/resources_random123.html).

```{rubric} PF:
```

```{rubric} Vec:
```

```{rubric} VecScatter:
```

```{rubric} PetscSection:
```

```{rubric} Mat:
```

- Added a new argument in MatCreateLRC() to express the low-rank
  correction as A+U\*C\*V'.
- MatTranspose() now properly handles MAT_INITIAL_MATRIX,
  MAT_REUSE_MATRIX, MAT_INPLACE_MATRIX.
- Renamed MatCreateSubMatrix() to MatCreateSubMatrixVirtual().
- Renamed MatSubMatrixUpdate() to MatSubMatrixUpdateVirtual().
- Renamed MatGetSubMatrices() to MatCreateSubMatrices().
- Added MatDestroySubMatrices().
- Renamed MatGetSubMatricesMPI() to MatCreateSubMatricesMPI().
- Renamed MatGetSubMatrix() to MatCreateSubMatrix().
- Renamed MatGetSubMatrixOption() to MatCreateSubMatrixOption().
- MatSetOption(mat,MAT_IGNORE_ZERO_ENTRIES,PETSC_TRUE) no longer
  applies to zero values set or added to the matrix diagonal, they
  are now not ignored and are included in the matrix nonzero
  structure. This is useful for Jacobians passed to TS.
- Added MatFactorSchurStatus.
  MatFactorGet/Restore/CreateSchurComplement now take an extra
  status argument.
- Added MatMatSolveTranspose to solve transposed linear systems for
  multiple right-hand sides.
- Added MATAIJMKL and MATBAIJMKL to facilitate use of Intel MKL
  sparse BLAS routines with matrices stored in AIJ/BAIJ format.

```{rubric} PC:
```

- The is_local argument to PCASMSetLocalSubdomains() is now ignored
  UNLESS the PCASMType is set to restrict
- Added PCMGSetNumberSmooth()
- PCMGSetGalerkin() and -pc_mg_galerkin now take
  PC_MG_GALERKIN_BOTH,PC_MG_GALERKIN_PMAT,PC_MG_GALERKIN_MAT,
  PC_MG_GALERKIN_NONE as arguments instead of PetscBool
- Added PCBDDCSetDivergenceMat to help BDDC to compute the flux
  across the subdomain interfaces.
- Removed PCBDDCSetNullSpace. Local nullspace information should now
  be attached to the subdomain matrix via MatSetNullSpace.
- Added additional PetscBool parameter to
  PCBDDCCreateFETIDPOperators for the specification of the type of
  multipliers.
- Added additional string parameter to PCBDDCCreateFETIDPOperators
  for the specification of the prefix (can be NULL).
- FIELDSPLIT now extracts off-diag fieldsplit blocks from the
  preconditioner instead of the jacobian by default. Use
  -pc_fieldsplit_off_diag_use_amat to use the jacobian matrix.
- Added PCFieldSplitSetSchurScale to control the scaling factor of
  the Schur complement with the DIAG factorization. The
  corresponding command line option is -pc_fieldsplit_schur_scale.

```{rubric} KSP:
```

- Added KSPFETIDP, a linear system solver based on the FETI-DP
  method.
- Added the KSPGuess class: available methods are KSPGUESSFISCHER
  and KSPGUESSPOD. The new KSPGUESSPOD computes an initial guess
  using the Proper Orthogonal Decomposition technique.
- KSPFischerGuessCreate has been removed: see the man page of
  KSPGUESSFISCHER for how to create a Fischer type initial guess.
- KSPCHEBYSHEV: replace KSPChebyshevEstEigSetUseRandom() with
  KSPChebyshevEstEigSetUseNoisy(), using a deterministic algorithm
  to generate noisy vectors.

```{rubric} SNES:
```

```{rubric} SNESLineSearch:
```

```{rubric} TS:
```

- Changed TSGL to TSGLLE.
- -ts_monitor binary now saves the timestep information as a REAL
  entry consisting of the REAL_FILE_CLASSID followed by the real
  value. PetscBinaryRead.m and PetscBinaryIO.py can read these in
  automatically.
- Added TSRK5BS scheme to TSRK.
- Added TSADAPTDSP adaptive controller based on digital signal
  processing techniques.
- Removed command line option `-ts_theta_adapt`, use
  `-ts_adapt_type basic` to turn on adaptivity in TSTHETA.
- Remove command line option `-ts_alpha_adapt` and routines
  TSAlphaUseAdapt()/TSAlpha2UseAdapt(), use `-ts_adapt_type basic`
  to turn on adaptivity in TSALPHA/TSALPHA2.
- Removed TSBDFUseAdapt(), using time step adaptivity in TSBDF is
  now the default, use `-ts_adapt_type none` to turn adaptivity
  off.
- Added TSAdaptSetAlwaysAccept() to set whether to always accept
  steps.
- Added TSAdapt{Set|Get}Safety() to set safety factors and renamed
  option `-ts_adapt_basic_[reject_]safety` to
  `-ts_adapt_[reject_]safety`.
- Renamed TSAdaptBasic{Set|Get}Clip() and option
  `-ts_adapt_basic_clip` to TSAdapt{Set|Get}Clip() and
  `-ts_adapt_clip`.
- Added TSAdaptGetStepLimits() to get minimum and maximum allowed
  time step.
- Calling TSAdaptSetType() will reset all option values (safety
  factors, clipping factors, etc) to default values.
- Added TS{Set|Get}MaxSteps() and TS{Set|Get}MaxTime(), deprecated
  TS{Set|Get}Duration().
- Added TSGetStepNumber(), deprecated TSGetTimeStepNumber() and
  TSGetTotalSteps().
- Deprecated TSSetInitialTimeStep(), use TSSetTime() and
  TSSetTimeStep().

```{rubric} DM/DA:
```

- Changed prototypes for DMCompositeGather() and
  DMCompositeGatherArray()
- Replace calls to DMDACreateXd() with DMDACreateXd(),
  [DMSetFromOptions()] DMSetUp()
- DMDACreateXd() no longer can take negative values for dimensions,
  instead pass positive values and call DMSetFromOptions()
  immediately after
- Added DMSwarm which supports data management and data movement of
  arbitrary fields defined on a point set. Such functionality is
  useful for partcle based methods. High level support for
  particle-in-cell methods is provided when using either a DMDA or
  DMPLEX mesh.

```{rubric} DMPlex:
```

- Added DMPlexRefineSimplexToTensor to refine simplicial into tensor
  product cell meshes.
- Added PTScotch partitioner.

```{rubric} PetscViewer:
```

```{rubric} SYS:
```

- -help now has the option -help intro that only prints the programs
  help string and then exits the program
- Petsc64bitInt -> PetscInt64, PetscIntMult64bit() ->
  PetscInt64Mult(), PetscBagRegister64bitInt() ->
  PetscBagRegisterInt64()

```{rubric} AO:
```

```{rubric} Sieve:
```

```{rubric} Fortran:
```

PETSC_NULL_INTEGER, PETSC_NULL_REAL etc are now declared as arrays of
size one instead of as scalar values.
New shorter calling sequence for PetscError() from Fortran
SETERRQ(), and CHKERRQ from Fortran now have the same behavior as in
C and automatically return on errors, they do not abort.
Correspondingly SERERRA() and CHKERRA() should be used in 'program
main' - as return is not possible from it. These macros should be
used from .F90 files because they require long lines
Simplified Fortran usage. Now you only include
petsc/finclude/petscXXX and use petscXXX

- For each Fortran function (and main) use the following

  ```
       subroutine mysubroutine(.....)
  #include <petsc/finclude/petscxxx.h>
       use petscxxx
       implicit none
  ```

  For example if you are using SNES in your code you would have

  ```
  #include <petsc/finclude/petscsnes.h>
       use petscsnes
       implicit none
  ```

- Instead of PETSC_NULL_OBJECT you must pass PETSC_NULL_XXX (for
  example PETSC_NULL_VEC) using the specific object type XXX that
  the function call is expecting.

- Objects can be declared either as XXX a or type(tXXX) a, for
  example Mat a or type(tMat) a. (Note that previously for those who
  used types it was type(Mat) but that can no longer be used.

Notes:

- There are no longer any .h90 files that may or need to be included

- Like C the include files are now nested so you no longer need to
  include for example

  ```
  #include <petsc/finclude/petscsys.h>
  #include <petsc/finclude/petscvec.h>
  #include <petsc/finclude/petscmat.h>
  #include <petsc/finclude/petscpc.h>
  #include <petsc/finclude/petscksp.h>
  ```

  you can just include

  ```
  #include <petsc/finclude/petscksp.h>
  ```

- there is now type checking of most function calls. This will help
  eliminate bugs due to incorrect calling sequences. Note that
  Fortran distinguishes between a argument that is a scalar (zero
  dimensional array), a one dimensional array and a two dimensional
  array (etc). So you may get compile warnings because you are
  passing in an array when PETSc expects a scalar or vis-versa. If
  you get these simply fix your declaration of the variable to match
  what is expected. In some routines like MatSetValues() and friends
  you can pass either scalars, one dimensional arrays or two
  dimensional arrays, if you get errors here please send mail to
  <mailto:petsc-maint@mcs.anl.gov> and include enough of your code so we can
  see the dimensions of all your variables so we can fix the
  problems.

- You can continue to use either fixed (.F extension) or free format
  (.F90 extension) for your source

- All the examples in PETSc have been updated so consult them for
  clarifications.