Summary of User Interface Additions and Changes among
PETSc 2.0 Versions
http://www.mcs.anl.gov/petsc
Releases of PETSc:
- 2.0.24 - public release, April 6, 1999
- 2.0.23 - private release, September 29,1998
- 2.0.22 - public release, April 29, 1998
- 2.0.21 - public release, November 13, 1997
- 2.0.18, 2.0.19, 2.0.20 - private releases
- 2.0.17 - public release, April 5, 1997
- 2.0.16 - private release, December 10, 1996 for "Bring Your Own Code" Workshop
participants
- 2.0.15 - public release, October 4, 1996
- 2.0.13 - public release, April 18, 1996
- 2.0.Beta.10 - public release, December 15, 1995
- 2.0.Beta.8 - public release, October 13, 1995
- 2.0.Beta.6 - public release, July 30, 1995
- 2.0.Beta.4 - public release, June 21, 1995
We announce new PETSc releases to the petsc-users mailing list, which one can join by
sending e-mail to majordomo@mcs.anl.gov with
the message, "subscribe petsc-users".
We will continually add new features and enhanced functionality in upcoming releases; small
changes in usage and calling sequences of PETSc routines will continue to occur.
Although keeping one's code accordingly up-to-date can be somewhat annoying, all PETSc
users will be rewarded in the long run with a cleaner, better designed, and easier-to-use
interface. We suggest that users who want to upgrade their current PETSc application codes
from a particular version to the most recent release proceed through the changes listed in
this file in increasing order of version numbers. (Note: One can determine the release
number of any current PETSc installation by looking in the file include/petsc.h)
Many of the interface changes can be handled quickly and easily by using global
replacement via your favorite text editor. See the file docs/codemanagement.html
for some tips that we find helpful in keeping our own code up to date and that should be
generally useful for effective code management.
CHANGES in PETSc 2.0.24 (see new features
below)
General:
- Changed PETSC_ARCH on Windows platforms from nt to win32, and from nt_gnu to
win32_gnu.
- Moved all the compiler/optimization information for each PETSC_ARCH from the various base.g,
base.O_c++ etc. files all into the single file base_variables.
Now configuration for your system should require only editing the files ${PETSC_ARCH}/base
and ${PETSC_ARCH}/base.site
- The PETSC_ARCH rs6000 is now intended for IBM rs6000 workstations
running MPICH or LAM, while rs6000_sp is for IBM SPs.
- Removed the gvec directory from the distribution. If you are using this please let us
and know and we can provide it or provide alternative code to do what you need.
- Routines with the suffix "withcoloring" have been changed to
the suffix "color" to get around the 31 character limit in
names.
- The source code directory structure has changed slightly: pc and ksp are now
subdirectories of sles, and ao and da are subdirectories of a new directory called dm
(data management).
- The PETSc libraries are now: -lpetscts -lpetscsnes -lpetscsles -lpetscdm -lpetscmat
-lpetscvec -lpetsc. Each library is now only dependent on libraries to the right of it in
the list above. For example, if you are only using the linear solvers, you
only need to list "-lpetscsles -lpetscdm -lpetscmat -lpetscvec -lpetsc" and if
you are only using the vectors you only need to list "-lpetscvec -lpetsc".
- For users who previously could not use the PETSc makefiles because the PETSc rules for
making .o files conflicted with the user's rules, we have introduce a new file that may be
included by the user, ${PETSC_DIR}/bmake/${PETSC_ARCH}/base_variables,
which defines all the useful PETSc makefile variables, but not the rules. This should make
it easier for people who previously had trouble using the PETSc makefiles. We highly
recommend using the PETSc makefiles when possible because they are immediately portable
across all systems that support PETSc.
AO (Application Orderings):
TS (Timestepping Solvers):
- Removed TSSetRHSJacobianDefault() - you can now call TSSetRHSJacobian(...
TSDefaultJacobianColor,....) directly from Fortran
- Changed TSDefaultJacobianSlow() to TSDefaultJacobian()
SNES (Nonlinear Solvers):
- SNESSetConvergenceHistory() takes an additional argument; see the
manual page for details.
- Changed the interface for matrix-free methods in SNES so that is more flexible, in
particular:
Changed SNESDefaultMatrixFreeMatCreate() to MatSNESFDMFCreate().
Added routines
MatSNESFDMFSetHHistory(Mat,Scalar *,int);
MatSNESFDMFResetHHistory(Mat,Scalar *,int);
MatSNESFDMFSetParameters(Mat,double,double);
MatSNESFDMFGetH(Mat,Scalar *);
MatSNESFDMFKSPMonitor(KSP,int,double,void *); and the corresponding
option -snes_mf_ksp_monitor
Added support for an alternative way to compute the differencing parameter in matrix-free
methods
using the Walker-Pernice srategy, accessible via the option -snes_mf_type
wp
- Changed the calling sequence of SNESSetLineSearch() so that it accepts
an optional user-defined
context variable. Likewise, changed the calling sequences of the various line search
routines, e.g., SNESCubicLineSearch(), SNESQuadraticLineSearch(), etc.
SLES (Linear Solvers):
KSP (Krylov Subspace Methods):
- Changed the calling sequence of KSPComputeEigenvalues(KSP,int,double*,double*,int
*neig);
to return as the final value the number of eigenvalues computed; see the manual page for
more details.
- Changed GMRES to use the Gram-Schmidt method with one optional step of iterative
refinement as the default orthogonalization procedure, instead of the modified
Gram-Schmidt method.
This change was urged by Rich Lehoucq. It could cause very minor differences in
convergence
rates for codes run before and after this change.
- The option -ksp_bsmonitor is not longer needed; use -ksp_truemonitor
for the same affect.
- Added an additional argument to KSPSetResidualHistory(); see the manual
page for details. This change was suggested by Maria Murillo.
PC (Preconditioners):
- Removed support for block Gauss-Seidel from the distribution; -pc_type bgs
is no longer supported.
- The Eisenstat preconditioner (SSOR variant) now uses diagonal scaling by default, and
the options
PCEisenstatUseDiagonalScaling() and -pc_eisenstat_diagonal_scaling
have been
replaced with PCEisenstatNoDiagonalScaling() and -pc_eisenstat_no_diagonal_scaling
MAT (Matrices):
- Replaced MatGetSubMatrixCall() with MatReuse().
- Changed the calling sequence of MatILUFactor() and MatILUFactorSymbolic()
to increase
flexibility of adding new ILU options.
- Added an additional argument to MatCopy(); SAME_NONZERO_PATTERN
or DIFFERENT_NONZERO_PATTERN.
- Added an additional argument to MatDuplicate(), MAT_COPY_VALUES
or MAT_DO_NOT_COPY_VALUES.
- Changed the flag MAT_NEW_NONZERO_LOCATION_ERROR to MAT_NEW_NONZERO_LOCATION_ERR;
also changed MAT_NEW_ALLOCATION_ERROR to MAT_NEW_ALLOCATION_ERR
- Changed MatOrderxxx to MatOrderingxxx; changed MatOrderingType
to char* from enum
- Changed MatxxxReorderingxxx to MatxxxOrderingxxx
changed command line option -mat_order to -mat_ordering_type; changed
MatColoringType to char* from enum
- Changed Partitioningxxx to MatPartitioningxxx
DA (Distributed Arrays):
- DAGetInfo() has a new final argument, the stencil type. See the manual
page; to
change your current code to work, you only need add an extra PETSC_NULL
as a final argument.
VEC (Vectors):
- After a call to VecCreate() you MUST either call VecSetType()
or VecSetFromOptions() on the vector before using it for any purpose. The
VecCreatexxx() routines (e.g., VecCreateSeq(), VecCreateMPI())
do not need to have calls to VecSetType() or VecSetFromOptions() after them.
- All VecGetArray() calls MUST now be matched with a VecRestoreArray()
call; previous PETSc versions did not force compliance with this rule.
- The command line names for changing the vector type in VecCreate() are
now -vec_type mpi or -vec_type shared rather than -vec_mpi
or -vec_shared
- Changed the VecType variable type from an enum type to a string.
- Changed the calling sequence for VecGetType(); see the manual page for
details.
- Changed VecGhostGetLocalRepresentation() and VecGhostRestoreLocalRepresentation(),
to VecGhostGetLocalForm() and VecGhostRestoreLocalForm(),
respectively; the previous names had too many characters for some machines.
IS (Index Sets):
Draw (Graphics):
- Replaced VIEWER_DRAWX_.... with VIEWER_DRAW_....
- The arguments of ViewerDrawGetDraw() have been changed; see the manual
page for details.
- DrawTensorContour() has changed; its final argument is now an array
rather than a vector and it can only be used for a single processor. For DA vectors you
can now use VecView() to create the contour plot.
Viewers:
- Changed the names associated with the Matlab viewer to Socket viewer; this reflects our
plan to support additional graphics engines with PETSc.
- Changed ViewerFileOpenASCII() to ViewerASCIIOpen().
- Changed ViewerDrawOpenX() to ViewerDrawOpen().
- Changed ViewerFileOpenBinary() to ViewerBinaryOpen().
- Changed ViewerType from an enum to a char *.
System:
- Changed the calling sequence of PetscGetHomeDirectory(char dir[],int
maxlen).
- Changed the calling sequence of PetscFixFilename(const char filein[],char
fileout[]).
- Changed the calling sequence of PetscGetDate().
Error Handling:
Event Logging:
Fortran Interface:
New Features in PETSc 2.0.24 (see changes
above)
General:
- Add the routine OptionsGetAll().
- Added support for Sun Solaris running on Intel processors; PETSC_ARCH solaris_x86.
- Added option -optionsleft_off so BOPT=g version of code will not print
warnings about unused options.
- The environment variable PETSC_ARCH is now required to use the NT distribution.
- Added the routine OptionsGetLogical().
- We now include PETSC_ARCH of solaris_gnu, rs6000_gnu for those systems when using the
gnu compilers.
- Thanks to the generosity of the FreeBSD organization, we are now supporting freebsd
again.
- Added optional filename to -log_info <filename> option. PETSc
will open a seperate file, called filename.rank for each processor and print the output
there.
- Added PetscTypeCompare(); see the manual page.
AO (Application Orderings):
- AOPetscToApplicationIS() and AOApplicationToPetscIS(),
which used to crash
when passed a stride index set, now handle them correctly.
TS (Timestepping Solvers):
- Added TSSetTypeFromOptions().
SNES (Nonlinear Solvers):
- Added -snes_vecmonitor and SNESVecViewMonitor() to
allow graphically monitoring the solution.
- Added SNESSetTypeFromOptions().
- Added the routine SNESSetLineSearchCheck(), which sets a routine to
check the validity of new iterates computed by line search routines; see the manual page
for details.
SLES (Linear Solvers):
- See PC and KSP
- Added SLESSetTypesFromOptions().
KSP (Krylov Subspace Methods):
- Added the function KSPSetAvoidNorms() and corresponding option -ksp_avoid_norms.
For the methods CG, Richardson, Bi-CG-stab, CR, and CGS, this eliminates the computation
of the residual norm at each iteration (which is an expensive, collective operation). Then
the convergence criterion depends only on the maximum number of iterations the users sets
with KSPSetTolerances(). This is useful when using the Krylov method as a
smoother with a fixed number of iterations (say, e.g., 3 iterations).
- Added the KSP type of KSPBICG (contributed by Victor Eijkhout) and
added support to some of the preconditioners to apply the preconditioner transpose
(required by KSPBICG).
- Added -ksp_vecmonitor and KSPVecViewMonitor() to allow
graphically monitoring the solution's convergence.
- Added KSPSetTypeFromOptions().
PC (Preconditioners):
- Added PCLUSetReuseReordering() and PCLUSetReuseFill()
so that SLES can reuse the reordering and fill information for a new factorization of a
matrix with slightly different nonzero structure than the previous factorization. The
corresponding command line options are -pc_lu_reuse_reordering and -pc_lu_reuse_fill.
These two options only have an effect when the SLESSetOperators() option
of DIFFERENT_NONZERO_PATTERN is used; otherwise the ordering and fill
information is always
reused.
- Added PCGetVector(), not expected to be used by application
programmers.
- Added the option -pc_ilu_diagonal_fill and the corresponding
routine PCILUSetAllowDiagonalFill(); see the manual page for details;
helps ILU(k) on matrices with missing diagonal entries. Suggested by David Hysom.
- Added PCSetTypeFromOptions().
MAT (Matrices):
- Added MatSeqAIJSetColumnIndices() and MatSeqBAIJSetColumnIndices().
- If the option MAT_IGNORE_OFF_PROC_ENTRIES is used, then the routines MatAssemblyBegin()
and MatAssemblyEnd() will not cause any parallel communication or
synchronization.
- If the option MAT_NO_NEW_NONZERO_LOCATIONS is used, one less collective
call will be made in the MatAssemblyEnd() routines for MPIAIJ and
MPIBAIJ.
- Fixed bugs in MatReorderForNonzeroDiagonal() and made it more robust.
- Fixed bugs in factorization for AIJ matrices with variable size inodes.
- Indices that are negative passed into MatSetValues...() are now ignored
(rather than generating an error). This allows easily keeping homogeneous Dirichlet
boundary nodes out of the vectors and matrices for unstructured grid problems; just
indicate those node numbers with negative numbers.
- Added additional optimized code for BAIJ matrices with block sizes 2, 3, 5, 6, and 7.
- Improved the performance of MatSetValues() and MatAssemblyXXX()
for parallel matrices a great deal.
- Added the option -matstash_initial_size <stashsize> and -matstash_block_initial_size
<stashsize> and the routine MatSetStashInitialSize() to allow
further optimization of off-processor MatSetValues().
DA (Distributed Arrays):
- Added graphics support to DA vectors in 1d and 2d, with contour plotters
for 2d.
VEC (Vectors):
- Extended VecCreate() by allowing registration of new vector types with VecRegister()
see the manual page for details.
- Indices that are negative passed into VecSetValues...() are now ignored
(rather than generating an error). This allows easily keeping homogeneous Dirichlet
boundary nodes out of the vectors and matrices for unstructured grid problems; just
indicate those node numbers with negative numbers.
- Added VecDotBegin(), VecDotEnd(), VecNormBegin(),
VecNormEnd(), which reduce communication overhead in parallel; see
the manual pages for details (suggested by Victor Eijkhout).
- If the option VEC_IGNORE_OFF_PROC_ENTRIES is used, the VecAssemblyBegin()
and VecAssemblyEnd() routines will not cause any parallel communication
or synchronization (previously VecAssemblyBegin() still used a barrier).
- Added VIEWER_FORMAT_ASCII_INDEX which causes the index for each vector
entry to be printed with the vector values.
- Added three new vector scatter options; -vecscatter_merge and -vecscatter_ssend
and
-vecscatter_sendfirst; these may improve performance a great deal when
using MPICH for MPI on ethernet or fast ethernet.
- Added VecStrideNorm(), VecStrideScatter(), and VecStrideGather().
- Improved the performance of VecSetValues() and VecAssemblyXXX()
for parallel vectors.
- Added the option -vecstash_initial_size <stashsize> and -vecstash_block_initial_size
<stashsize> and the routine VecSetStashInitialSize() to allow
further optimization of off-processor VecSetValues().
IS (Index Sets):
- Added ISStrideToGeneral(), which converts a stride type index set to a
general type.
Draw (Graphics):
Viewers:
- Added ViewerASCIIPushTab(), ViewerASCIIPopTab() and ViewerASCIIPrintf().
These allow multi-level display of solver information (tabing the text further for each
inner solver). Thanks to Victor Eijkhout and Matt Knepley for pushing this.
System:
Error Handling:
Event Logging:
Fortran Interface:
- Added Fortran 90 interface support for HP Convex and Solaris.machine.
NEW FEATURES and CHANGES in PETSc 2.0.22
General:
- The Fortran90-specific routines such as VecGetArrayF90()
now work with the IBM Fortran compiler, the SGI Fortran 90 compiler, and the Cray T3E
Fortran compiler.
- The third argument for the Fortran versions of the routines VecGetArray()/VecRestoreArray(),
ISGetIndices()/ISRestoreIndices(), MatGetArray()/MatRestoreArray() and DAGetGlobalIndices()
has been changed from integer to PetscOffset.
See src/snes/examples/tutorials/ex5f.F for example usage.
- Changed the location of the manual pages from docs/www/www.html and
docs/www to docs/manualpages/manualpages.html and docs/manualpages.
- The location of the mpiuni include files (used in the base.site file when
not compiling with an MPI) has moved from src/mpiuni to src/sys/src/mpiuni
- Added the option -log_summary_exclude <vec,mat,sles,snes> to limit
the information printed in the summary table
- Added the option -log_info_exclude <vec,mat,sles,snes>
- Changed the calling sequences of PetscGetTime(),
PetscGetCPUTime(), PetscGetFlops() to return error codes like all other PETSc
functions.
- Changed the internal structure of the PETSc objects. This will not effect
most users but makes PETSc more extensible for the future.
- Removed the PETSc object child support and replaced it with
PetscObjectCompose(PetscObject,char *name,PetscObject);
PetscObjectQuery(PetscObject,char *name,PetscObject *);
PetscObjectComposeFunction(PetscObject,char *name, void *);
PetscObjectQueryFunction(PetscObject,char *name,void **);
These allow the user to attach objects and functions to any PETSc
object.
- Added a feeble example that demonstrates how to manage partitioning a
grid in parallel in src/mat/examples/tutorials/ex2.c
- The build command 'make all' in ${PETSC_DIR} will build the PETSc
libraries, including the fortran interface.
AO (Application Orderings):
TS (Timestepping Solvers):
- The calling sequence of TSSetType() has changed;
see the manual page.
- TSType is now a string, rather than enum type
SNES (Nonlinear Solvers):
- The calling sequence of SNESSetType() has changed;
see the manual page.
- SNESType is now a string, rather than enum type
SLES (Linear Solvers):
KSP (Krylov Subspace Methods):
- The calling sequence of KSPSetType() has changed;
see the manual page.
- KSPType is now a string, rather than enum type.
PC (Preconditioners):
- Added two new PC classes, PCSLES and PCCOMPOSITE
that allow use of any SLES object as a preconditioner and enable
combining several preconditioners.
- The calling sequence of PCSetType() has changed;
see the manual page.
- PCType is now a string, rather than enum type.
MAT (Matrices):
- Added support for partitioning using the ParMETIS parallel partitioning
package, see the manual page for PartitioningCreate()
- Added MatGetColumnVector()
- Added argument column size to MatGetSubMatrix()
- Changed the memory allocation algorithm in MatLUFactorSymbolic() and
MatILUFactorSymbolic() based on a suggestion by David Hysom of ODU.
- The third argument for the Fortran version of the routines MatGetArray()/MatRestoreArray()
has been changed from integer to PetscOffset.
DA (Distributed Arrays):
- Changed DAGetDistributedVector() and DAGetLocalVector()
to DACreateGlobalVector() and DACreateLocalVector().
You should destroy these vectors with a usual call to VecDestroy().
- The third argument for the Fortran version of the routine DAGetGlobalIndices()
has been changed from integer to PetscOffset.
VEC (Vectors):
- Added VecSetBlockSize(), VecSetValuesBlocked(),
VecSetValuesBlockedLocal(), VecSetLocalToGlobalMappingBlocked()
- Added VecCreatedShared(), which creates a parallel
vector in shared memory on the SGI machines
- Changed VEC_IGNORE_OFF_PROCESSOR_ENTRIES to VEC_IGNORE_OFF_PROC_ENTRIES
- The third argument for the Fortran versions of the routines VecGetArray()/VecRestoreArray(),
has been changed from integer to PetscOffset. See
src/snes/examples/tutorials/ex5f.F for example usage.
- VecGetArray(), VecRestoreArray() now work from Fortran
on all machines, finally after 3 long years!
- Changed the calling sequence of VecCreate(), now takes
both local and global size, see the manual page.
IS (Index Sets):
- The third argument for the Fortran versions of the routines ISGetIndices()/ISRestoreIndices()
has been changed from integer to PetscOffset.
Draw (Graphics):
Viewers:
System:
Error Handling:
Event Logging:
Fortran Interface:
- PETSC_NULL has been replaced with PETSC_NULL_INTEGER,
PETSC_NULL_SCALAR, PETSC_NULL_DOUBLE or PETSC_NULL_CHARACTER
depending on the context for usage. If the function expects an integer, a scalar (double
or complex depending if you compile with BOPT=*_complex), a double precision array, or a
string.
- The Fortran include files are now located in the directory
"include/finclude/*.", rather than "include/FINCLUDE/*.h". The include
files that used to be in "include/finclude/*.h (not recommended) are now in
"include/foldinclude/*.h"
- If you have stored PETSc objects in Fortran integer arrays, such as
user(3) = vec you have to declare those arrays to be of type PetscFortranAddr
instead of as integer. Note that PetscFortranAddr is simply integer on 32
bit machines and integer*8 on 64 bit machines.
- The Fortran90-specific routines such as VecGetArrayF90()
now work with the IBM Fortran compiler, the SGI Fortran 90 compiler, and the Cray T3E
Fortran compiler.
- PETSc objects can now be passed between C and Fortran directly. You do not have to use
the commands PetscCObjectToFortranObject() and PetscFortranObjectToCObject()
to translate the objects between languages.
- Changed Fortran object argument from type int to type PetscFortranAddr in the
routines PetscCObjectToFortranObject() and PetscFortranObjectToCObject().
- Added the routine PetscInitializeFortran() to assist in mixed-language
use of PETSc. See the manual page for details.
NEW FEATURES and CHANGES in PETSc
2.0.18-2.0.21.
General:
- Complex numbers performance upgrade: Added support for using optimized Fortran kernels
for some key complex numbers numerical routines (such as matrix-vector products, vector
norms, etc.) instead of the default C++ routines. This implementation exploits the
maturity of Fortran compilers while retaining the identical user interface. For example,
on rs6000 machines, the base single-node performance when using the Fortran kernels is 4-5
times faster than the default C++ code.
- Changed the names of various compiler flags, e.g., changed PETSC_COMPLEX to
USE_PETSC_COMPLEX.
- Changed PetscObjectInherit() to PetscObjectCompose() since
it really denotes a "has-a" relationship, not an "is-a" relationship.
AO (Application Orderings):
- Changed AOCreateDebug() to AOCreateBasic(); changed AOCreateDebugIS()
to AOCreateBasicIS().
- Removed the MPI_Comm argument from AOCreateBasicIS() since it is
contained in the IS arguments.
- Now the AOxxxToxxxXX() remapping routines will not map negative entries
in the input arrays. This allows, for example, the mapping of neighbor lists that use
negative entries to indicate non-existent neighbors due to boundaries, etc.
TS (Timestepping Solvers):
- Added an interface to PVODE, the stiff integrator package of Hindmarsh et al.
SNES (Nonlinear Solvers):
- Added support for using matrix colorings within finite difference Jacobian
approximations. See the section "Finite Difference Jacobian Approximations" of
the users manual for more details. Also see the man pages for SNESDefaultComputeJacobianWithColoring().
- Fixed a bug in method SNES_EQ_NLS.
- Increased the default maximum number of function evaluations to 100000.
SLES (Linear Solvers):
KSP (Krylov Subspace Methods):
- Added the routine KSPGetResidualNorm().
PC (Preconditioners):
- Added -pc_lu_fill and -pc_ilu_fill to replace -mat_lu_fill and -mat_ilu_fill; also added
the commands PCLUSetFill() and PCILUSetFill().
- Added PCLUSetMatReordering() and PCILUSetMatReordering().
MAT (Matrices):
- Added support for matrix colorings, which are intended primarily for use in finite
difference Jacobian approximations. See the SNES section above for more info. New routines
include:
- MatFDColoringCreate()
- MatFDColoringSetParameters()
- MatFDColoringSetFrequency()
- MatFDColoringSetFunction()
- MatFDColoringSetFromOptions()
- MatFDColoringView()
- MatFDColoringPrintHelp()
- MatFDColoringApply()
- MatFDColoringDestroy()
- Added the matrix option MatSetOption(mat,MAT_NEW_NONZERO_ALLOCATION_ERROR) that will
cause an error if a new entry that has not been preallocated is generated in a sparse
matrix. (currently implemented for AIJ and BAIJ matrices only). This is a useful flag when
debugging memory preallocation.
- Replaced the options -mat_lu_fill and -mat_ilu_fill with -pc_lu_fill and -pc_ilu_fill.
- Added the routine MatSetValuesBlockedLocal() for BAIJ matrices.
- Changed the final argument of MatGetTypeFromOptions() from type int* to PetscTruth*.
- Added MatCreateSeqAdj() for supplying adjacency matrices to PETSc to do reordering on
(for example RCM to reduce bandwidth and thus get better cache performance) and eventually
partitioners.
- MatSetLocalToGlobalMapping() and MatSetLocalToGlobalMappingBlocked() now take a
ISLocalToGlobalMapping object rather than a list of indices.
- Added the routine MatGetSubMatrix(), which extracts a parallel matrix from a parallel
matrix (currently implemented only for the MPIAIJ format).
DA (Distributed Arrays):
- When used with the DA_STENCIL_STAR stencil, type, the routine DAGetGlobalIndices()
returns local-to-global mapping indices that now include the inactive corner ghost nodes.
This is useful, e.g., when using MatSetValuesLocal() to set matrix elements, including
corner boundary nodes.
VEC (Vectors):
- VecSetLocalToGlobalMapping() now takes a ISLocalToGlobalMapping object rather than a
list of indices.
- Added the routine VecCreateMPIWithArray().
- Changed the calling sequence for VecCreateGhost(); added VecCreateGhostWithArray(),
VecGhostUpdate[Begin/End](), and VecGhost[Get/Restore]LocalRepresentations().
IS (Index Sets):
- Added ISGlobalToLocalMappingApply() to allow one to convert lists that are in the global
numbering to a local numbering.
- Added a communicator as the first argument to ISLocalToGlobalMappingCreate().
Draw (Graphics):
- Added routines for drawing simple histograms. See DrawHistCreate().
- Removed the option -draw_x_private_colormap and made a private colormap the default.
- Added the option -draw_x_shared_colormap to indicate not to use a private colormap. If
you use Netscape on your machine and are also doing contour plots, you generally don't
want to use a shared colormap.
- Improved the colors used in the contour plotting.
- Changed some routine names:
- DrawText() to DrawString()
- DrawTextVertical() to DrawStringVertical()
- DrawTextSetSize() to DrawStringSetSize()
- DrawTextGetSize() to DrawStringGetSize()
- DrawSyncClear() to DrawSynchronizedClear()
- DrawSyncFlush() to DrawSynchronizedFlush()
- DrawSyncGetMouseButton() to DrawSynchronizedGetMouseButton().
Viewers:
- Added VIEWER_STDOUT_() and VIEWER_STDERR_().
System Routines:
- Added the routine OptionsClearValue().
- Added the option -get_resident_set_size that causes the program to call
PetscGetResidentSetSize() at the end of the run and print how much physical memory each
process has used.
- Changed OptionsGetProgramName() to PetscGetProgramName() and changed the calling
sequence to match PetscGetHostname(), etc.
- Changed BINARY_INT and BINARY_SCALAR to PETSC_INT and PETSC_SCALAR.
Error Handling:
Event Logging:
Fortran Interface:
NEW FEATURES and CHANGES in PETSc 2.0.17
General:
- Added support for Windows NT/95 using the Microsoft Developers Studio Visual C++. See
the file 'Installation' for details.
- Other new machines on which this release has been tested: Cray T3E, SGI Origin See the
file petsc/Installation for a complete list.
TS (Timestepping Solvers):
- Modified the pseudo-transient continuation updates:
- Changed the default update to dt = current_dt*previous_fnorm/current_fnorm.
- Added the routine TSPseudoIncrementDtFromInitialDt() and the corresponding option
-ts_pseudo_increment_dt_from_initial_dt to indicate use of the alternative update formula
dt = initial_dt*initial_fnorm/current_fnorm.
- Changed the calling sequence of TSRegister().
SNES (Nonlinear Solvers):
- Added support for computing large, sparse Jacobians efficiently via finite differences,
see Section 5.6 (Finite Difference Jacobian Approximations) of the users manual.
- Added the routines SNESGetNumberLinearIterations() and SNESSetConvergenceHistory(). See
man pages for details.
- Activated a counter of function evaluations, which is used in convergence tests to
terminate solver if the number of function evaluations exceeds a given tolerance. Note:
Users of matrix-free Newton-Krylov methods may need to reset the default allowable maximum
(1000), via SNESSetTolerances() or -snes_max_func <maxfunc>.
- Changed the calling sequence of SNESRegister().
SLES (Linear Solvers):
KSP (Krylov Subspace Methods):
- Changed the calling sequence of KSPRegister().
PC (Preconditioners):
- Changed the calling sequence of PCRegister().
- New Additive Schwarz variants (preconditioner type PCASM)
- Added the routine PCASMSetType() (and the corresponding option -pc_asm_type
[basic,restrict,interpolate,none]) for setting the variant of the additive Schwarz method.
See the man page and users manual for details.
- Changed the default variant of PCASM from full restriction and interpolation to full
restriction only, since this version requires less communication and for many problems
converges faster than the basic variant that uses full restriction and interpolation.
Users can still employ the basic ASM by calling PCASMSetType(pc,PC_ASM_BASIC) or by using
the option -pc_asm_type basic.
- Added an interface to the SPAI preconditioner implementation of Steven Bernard; see
src/contrib/spai. This has undergone little testing and optimization; it is intended
mainly for "hackers".
MAT (Matrices):
- Added the matrix option, MatSetOption(mat,MAT_NEW_NONZERO_LOCATION_ERROR), that will
cause an error if a new nonzero is generated in a sparse matrix. (currently implemented
for AIJ and BAIJ matrices only). This is a useful flag when using SAME_NONZERO_PATTERN in
calling SLESSetOperators() to ensure that the nonzero pattern truely does remain
unchanged. For examples, see the programs
petsc/src/snes/examples/tutorials/[ex5.c,ex5f.F].
- Added the routine MatSetUnfactored(), intended primarily for use with in-place ILU(0)
factorization as a preconditioner for matrix-free Krylov methods. See the manual page for
details.
- Added the routines MatConvertRegisterAll() and MatLoadRegisterAll() to allow the
restriction of the matrix routines linked into an application code. This can decrease the
size of your executable and the time it takes to link your program. For details, see the
manual page and petsc/src/snes/examples/tutorials/ex5.c
- Added the routine MatSetValuesBlocked(), for more efficient assembly of block AIJ
formatted matrices (MATSEQBAIJ and MATMPIBAIJ).
- Changed the calling sequence of MatReorderingRegister();
DA (Distributed Arrays):
- Added additional arguments to DACreate1d(), DACreate2d(), and DACreate3d() to allow the
user to set the distribution of nodes on each processor; set these arguments to PETSC_NULL
for the standard default distribution.
- Modified DAGetInfo() to return the type of periodicity.
VEC (Vectors):
- Added the routine VecCreateGhost() to create vectors that have ghost padding at the end
of the local array. This is useful for gathering remote values to perform local
calculations that involve off-processor ghost values. This is often appropriate for codes
using unstructured grids. See petsc/src/vec/examples/tutorials/ex9.c for possible usage.
IS (Index Sets):
Draw (Graphics):
- Application codes should not need to use #include "draw.h" anymore from C/C++,
since this file is now included automatically when "petsc.h" or any other PETSc
include file is included.
Viewers:
- VIEWER_DRAWX_WORLD, VIEWER_DRAWX_SELF, VIEWER_MATLAB_WORLD are now supported from
Fortran.
- Added VIEWER_DRAWX_(MPI_Comm comm) from C. Useful for rapid code prototyping without
having to declare a Viewer.
System Routines:
- Since memory leaks and uninitialized memory can be serious problems for large-scale
application codes, we've added several new tools to assist in their diagnosis. These tools
are all work in conjunction with the PETSc memory allocation (the default for codes that
are compiled in debug mode with BOPT=[g,g_c++,g_complex]).
- Added the runtime option -trmalloc_log, which activates logging of all calls to malloc
via the new routines PetscTrLog() and PetscTrLogDump().
- Added the routine PetscGetResidentSetSize() to determine the total memory used by a
process (this is activated by -trmalloc_log); see the man page for details.
- Added the option -trmalloc_nan for tracking down allocated memory that is used before it
has been initialized. This option calls the new routines PetscInitializeNans() and
PetscInitializeLargeInts(). So far these work on the Sun4 system.
Error Handling:
- The error checking macros SETERRQ() and SETERRA() now have the calling sequence
SETERRQ(int ierr,int pierr,char *message); where pierr is an additional integer error code
passed to the error handler. Currently you should just set pierr=1.
- Also, SETERRQ() and SETERRA() now use the macro __FUNC__ to keep track of routine names.
Users need not worry about this in their application codes, but can take advantage of this
feature if desired by setting this macro before each user-defined routine that may call
SETERRQ(), SETERRA(), CHKERRQ(), or CHKERRA(). __FUNC__ should be set to a string
containing the routine name. For example, #undef __FUNC__ #define __FUNC__
"MyRoutine1" int MyRoutine1() { /* code here */ return 0; } See
petsc/src/snes/examples/tutorials/ex3.c for an example.
- PETSc error handlers now take two additional arguments. Consult the man page for
PetscPushErrorHandler() for more information.
Event Logging:
- Changed PLogPrintSummary(MPI_Comm,FILE *) to PLogPrintSummary(MPI_Comm,char *).
- Now the option -log_summary takes [filename] as an optional argument.
Fortran Interface:
- Added some limited support for direct use of Fortran90 pointers in the routines
Vec[Get,Restore]ArrayF90(), Mat[Get,Restore]ArrayF90(), IS[Get,Restore]IndicesF90(),
ISBlock[Get,Restore]IndicesF90(), VecDuplicateVecsF90(), VecDestroyVecsF90(),
DAGetGlobalIndicesF90(). See the man pages and the section 'Fortran90' in the users manal
for details. Unfortunately, these routines currently work only with the NAG F90 compiler.
We hope to support other compilers as well, but we will need assistance from the vendors
since the Fortran90/C interface is not a defined standard.
- Added the macro PetscDoubleExp(a,b) = a d b (machines where double precision arithmetic
is used) = a e b (machines where single precision arithmetic is used, e.g., Crays) This
macro is intended for use only if you wish to maintain a Fortran code that is portable to
both the Cray T3d/T3e and other Unix machines.
- For mixed Fortran/C users: added the makefile flag FCONF that may be used in place of
the flag CONF. For an example of usage, see src/vec/examples/tutorials/makefile
NEW FEATURES and CHANGES in PETSc 2.0.16
General:
- Added the option -compare option for incremental debugging; see the users manual for
more details.
- Added tags file so that vi users can easily browse PETSc source files (just as emacs
users already can by using etags). See the users manual subsection "VI users"
for details.
- We have stopped distributing the UNIX-style manpages with PETSc. Instead, we now only
distribute the HTML version. You can still access the man pages with the command
$PETSC_DIR/bin/petscman. Alternatively, you can directly view
$PETSC_DIR/docs/www/www.html.
TS (Timestepping Solvers):
SNES (Nonlinear Solvers):
- You can now attach several SNES monitoring routines with SNESSetMonitor() instead of
only one as previously allowed. Similarly, multiple monitors can be used from the options
database (e.g., -snes_monitor and -snes_xmonitor).
SLES (Linear Solvers):
KSP (Krylov Subspace Methods):
- You can now attach several KSP monitoring routines with KSPSetMonitor() instead of only
one as previously allowed. Similarly, multiple monitors can be used from the options
database (e.g., -ksp_monitor and -ksp_xmonitor).
PC (Preconditioners):
MAT (Matrices):
- Added the routines MatSetValuesLocal(), MatZeroRowsLocal() and
MatSetLocalToGlobalMapping() to enable the user to set values in a matrix using a local
numbering of the nodes rather than a global numbering.
- Added the option MAT_IGNORE_OFF_PROC_ENTRIES for MatSetOptions(), which causes all
entries on any processor destined to be stored on a different processor to be dropped
instead. This is useful if you know that the "owning" processor is also always
generating the correct entries, so PETSc need not ship over the duplicate entry generated
on another processor. -
- Added options MAT_COLUMNS_UNSORTED and MAT_ROWS_UNSORTED for MatSetOptions() to enable
switching betwen sorted and unsorted input.
DA (Distributed Arrays):
VEC (Vectors):
- Changed the SCATTER_ALL argument in VecScatterXXX() routines to SCATTER_FORWARD.
- Added the routines VecSetValuesLocal() and VecSetLocalToGlobalMapping() to allow the
user to set values into a vector using a local numbering of the nodes rather than a global
numbering.
- Added the routine VecSetOption(Vec,VEC_IGNORE_OFF_PROCESSOR_ENTRIES), which causes all
entries on any processor destined to be stored on a different processor to be dropped
instead. This is useful if you know that the "owning" processor is also always
generating the correct entries, so PETSc need not transfer the duplicate entries generated
on another processor.
IS (Index Sets):
Draw (Graphics):
- The numbers on the axis plots are much improved.
- You can now pass PETSC_DECIDE as the x and y arguments in DrawOpenX() and
ViewerDrawOpenX() to let PETSc place non-overlapping windows on the display.
Viewers:
System Routines:
- Added routines PetscSynchronizedPrintf(MPI_Comm,format,args) and
PetscSynchronizedFlush(MPI_Comm), which allow groups of processes to print to stdout as
one would expect. I.e., the output from processor 0 is followed by the output from
processor 1, etc. Very useful during code development. This can often be a substitute for
attempting to sequentialize printf() statements via PetscSequentialPhaseBegin() and
PetscSequentialPhaseEnd(). -
- Added the command line option -options_file <file> that causes all options in the
specified file to be treated as if they were typed on the command line.
- Added the option -log_trace [filename] (and the corresponding routine PLogTraceBegin())
that allows tracing of all PETSc calls; useful to see where a program is hanging without
running in the debugger. Can be used in conjunction with the -log_info option.
- Added PetscRandomSetInterval() to enable the user to set an interval over which random
numbers will be uniformly distributed.
Event Logging:
Fortran Interface:
- Added the Fortran interface for VecDuplicateVecs(), VecDestroyVecs(), VecMAXPY(),
VecMDot(), and VecMTDot().
NEW FEATURES and CHANGES in PETSc 2.0.15
Highlights of new features in version 2.0.15, added since the last public release of
PETSc (2.0.Beta.13). See details in the sections below.
- - Added support for shared version of PETSc libraries for several machines to enable
faster linking and smaller executables
- - Added new parallel block row matrix format, improved efficiency for block diagonal
formats -
- Added a suite of routines to help manage the mappings between an application-defined
ordering of variables and the ordering used by PETSc for matrices and vectors
- - Expanded users manual information for performance tuning and profiling
- - The option -log_summary now summarize of message-passing activity as well as flop
rates. -
- Running the test suite now requires much less disk space.
- - Example programs are in the process of being reorganized into tutorials and tests
(see, e.g., petsc/src/sles/examples/tutorials for tutorial-style examples for the linear
solvers). -
- The HTML version of the PETSc man pages now provides indices (organized by both concepts
and routine names) to tutorial examples.
General
- Added support for shared libraries for the machines PETSC_ARCH =
[sun4,solaris,alpha,IRIX,IRIX64,linux] to enable faster linking and smaller executables.
To compile the shared libraries, install PETSc as usual and then execute the command make
BOPT=g shared from the PETSc home directory (or use whatever BOPT you like). You can
remove the shared libraries with the command make BOPT=g deleteshared Note: Shared
libraries can also be used with PETSC_ARCH=freebsd and PETSC_ARCH=hpux if some minor
modifications are made. For detailed instructions, see the files
${PETSC_DIR}/bmake/${PETSC_ARCH}/base. Please write to us at petsc-maint@mcs.anl.gov if
you encounter any problems when using the shared libraries.
- - Users must now ALWAYS set the environmental variable PETSC_DIR to indicate the PETSc
home directory. Previously, PETSC_DIR was set within the various makefiles within the
PETSc installation. However, since this causes problems for shared libraries on some
machines, the environmental variable PETSC_DIR is now used instead.
- - Added global variables for use in debuggers: PetscGlobalRank - processor's rank in
MPI_COMM_WORLD PetscGlobalSize - number of processors in MPI_COMM_WORLD
- - For complex numbers versions (e.g., BOPT=g_complex): Added a global variable defining
the imaginary number "i": PETSC_i
TS (Time Stepping Module)
- - Changed TS_PSEUDO_POSITION_INDEPENDENT_TIMESTEP -> TS_PSEUDO_POSIND -
- Changed TSPseudoSetPositionIndependentTimeStep() -> TSPseudoSetPosIndTimeStep(). Even
Barry couldn't stand names that long :-)
SNES (Nonlinear Solvers):
- - The user can now set parameters used in matrix-free approximations of Jacobian-vector
products, with the options -snes_mf_err : square root of relative error in computing
function -snes_mf_umin : minimum iterate parameter or by calling the routine
SNESSetMatrixFreeParameters().
- - Added the option -snes_mf_operator, which allows the user to apply the default
matrix-free Jacobian but retain the user-provided Jacobian preconditioner matrix.
- - Added the routine SNESGetTolerances() to extract the various parameters used for
convergence testing.
- - Initialized iteration counter to 0 for successive calls to SNES solvers.
- - Changed the names for SNES runtime options associated with particular solvers to the
forms -snes_eq_ls_- nonlinear equations, line search method -snes_eq_tr_ - nonlinear
equations, trust region method -snes_um_ls_- unconstrained minimization, line search
method -snes_um_tr_ - unconstrained minimization, trust region method Run program with
-help for a detailed list of options.
SLES (Linear Solvers): See PC and KSP
- - Changed the default linear solvers from GMRES(30) with Jacobi preconditioning to
uniprocessor: GMRES(30) with ILU(0) preconditioning multiprocessor: GMRES(30) with block
Jacobi preconditioning, where there is 1 block per processor, and each block is solved
with ILU(0) See the users manual for additional options for the block Jacobi method. You
can still employ the old default at runtime with the option -pc_type jacobi
KSP (Krylov subspace methods):
- - Added routines KSPComputeEigenvalues(), KSPComputeEigenvaluesExplicitly() and runtime
options -ksp_compute_eigenvalues, -ksp_plot_eigenvalues,
-ksp_compute_eigenvalues_explictly and -ksp_plot_eigenvalues_explicitly for users
interested in examining the eigenvalues of the preconditioned operator to better
understand the convergence of a chosen iterative method.
- - Changed KSPSetCalculateExtremeSingularValues() ->
KSPSetComputeExtremeSingularValues() - Changed KSPSetCalculateResidual() ->
KSPSetComputeResidual()
PC (Preconditioners):
- - Added the routine PCSetModifySubMatrices(), which allows the user to set an optional
routine for modifying the entries of the submatrices that arise in certain subdomain-based
preconditioners (ASM, block Jacobi, block Gauss-Seidel).
MAT (Matrices):
- Eliminated routine MatGetSubmatrix(); now use MatGetSubMatrices() even when extracting
just 1 submatrix. -
- Added routine MatDestroyMatrices(). -
- Fixed bug in MatGetSubMatrices() for successive calls for matrices having different
nonzero structure.
- - Added routine MatGetBlockSize(). - Changed routine MatGetInfo() so that it returns
more information. See man page for details.
- - Changed usage of MatGetReordering() and MatRegisterOrdering(); see man pages.
- - Changed the prefix used for matrix operation names within MatShellSetOperation() and
MatHasOperation(): MAT_-> MATOP_ For example, MAT_MULT -> MATOP_MULT.
DA (Distributed Arrays):
VEC (Vectors):
IS (Index Sets):
- - Changed ISCreateSeq() to ISCreateGeneral() -
- Changed ISCreateStrideSeq() to ISCreateStride() -
- Added routine ISCreateBlock() to create a blocked index set. See the man page for
details and related routines.
Draw (Graphics):
- Added -draw_x_private_colormap option that causes PETSc to allocate a separate colormap
for PETSc graphics windows. This prevents bad contour plots due to Netscape altering the
default color map.
- - You can now zoom in and out of contour plots using the option -draw_pause -1 and left
and center mouse buttons.
- - The option -draw_contour_grid will display the underlying grid on a contour plot.
VIEWERS:
- - Added routine ViewerGetFormat().
- - Added options -viewer_matlab_machine and -viewer_matlab_port
- - Changed ASCII_FORMAT_xxx to VIEWER_FORMAT_ASCII_xxx and ASCII_FORMAT_INFO_DETAILED to
VIEWER_FORMAT_ASCII_INFO_LONG
- - Changed BINARY_FORMAT_xxx to VIEWER_FORMAT_BINARY_xxx
- - PETSc now provides basic support for VRML viewers. Currently, one can draw surface
contours of vector fields with the routine DFVecDrawTensorSurfaceContour(). Note that the
VRML utilities will be expanded and the interface will change in the near future.
SYSTEM:
EVENT LOGGING:
FORTRAN INTERFACE:
- - Changed PETSC_NULL_CHAR to PETSC_NULL_CHARACTER - Replaced PETSC_DEFAULT with
- - You no longer need MPE to build PETSc.
- - Included petsc/include/options.h within petsc/include/petsc.h -
- Changed distributed array name from RA to DA. Also changed DAGlobalToLocal() to
DAGlobalToLocalBegin() followed by DAGlobalToLocalEnd().
- - Changed usage of KSPBuildSolution() slightly to avoid copying when not needed.
- - Remove first argument (rflag) from ALL options database commands, i.e.,
OptionsGetInt(0,0,"-m",&m) => OptionsGetInt(0,"-m",&m),
etc.
- - Changed the way memory tracing is done. When compiling with BOPT=g it is the default,
but you may turn it off with -notrmalloc. When compiling with BOPT=O it is by default off,
but one may turn it on with -trmalloc or -trdump.