============
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
   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.