Documentation: Changes: 3.8

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 aswell

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

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)

PetscDraw:

PetscRandom:

• Added PETSCRANDOM123, a wrapper to the counter-based random number generator Random123.

PF:

Vec:

VecScatter:

PetscSection:

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.

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.

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.

SNES:

SNESLineSearch:

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().

DM/DA:

• Changed prototypes for DMCompositeGather() and DMCompositeGatherArray()
• Replace calls to DMDACreateXd() with DMDACreateXd(), [DMSetFromOptions()] DMSetUp()
• DMDACreateXd() no longer can take negative values for dimensons, 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.

DMPlex:

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

PetscViewer:

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()

AO:

Sieve:

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 [email protected] 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.