PETSc/TAO Users Manual V.3.21

This manual describes the use of the Portable, Extensible Toolkit for Scientific Computation (PETSc) and the Toolkit for Advanced Optimization (TAO) for the numerical solution of partial differential equations (PDEs) and related problems on high-performance computers.PETSc/TAO is a suite of data structures and routines that provide the building blocks for implementing large-scale application codes on parallel (and serial) computers.PETSc uses the MPI standard for all distributed memory communication.PETSc/TAO includes a large suite of parallel linear solvers, nonlinear solvers, time integrators, and optimizers that may be used in application codes written in Fortran, C, C++, and Python (via petsc4py; see Getting Started ).The library is organized hierarchically, enabling users to employ the abstraction level most appropriate for a particular problem.By using techniques of object-oriented programming, PETSc provides enormous flexibility for users.PETSc is a sophisticated set of software tools; it initially has a steeper learning curve than packages such as MATLAB or a simple subroutine library.In particular, for individuals without some experience programming in C, C++, Python, or Fortran and experience using a debugger such as gdb or lldb, it may require a significant amount of time to take full advantage of the features that enable efficient software use.However, the power of the PETSc design and the algorithms it incorporates makes the efficient implementation of many application codes simpler than "rolling them" yourself.• For many tasks, a package such as MATLAB is often the best tool; PETSc is not intended for the classes of problems for which effective MATLAB code can be written.• Several packages (listed on https://petsc.org/),built on PETSc, may satisfy your needs without requiring directly using PETSc.We recommend reviewing these packages' functionality before starting to code directly with PETSc.• PETSc can be used to provide a "MPI parallel linear solver" in an otherwise sequential or OpenMP parallel code.This approach can provide modest improvements in the application time by utilizing modest numbers of MPI processes.See PCMPI for details on how to utilize the PETSc MPI linear solver server.Since PETSc is under continued development, small changes in usage and calling sequences of routines will occur.PETSc has been supported for twenty-five years; see mailing list information on our website for information on contacting support.PETSc/TAO Users Manual, Release 3.21.0DM: Interfacing Between Solvers and Models/Discretizations details how a user's models and discretizations can easily be interfaced with the solvers by using the DM construct.Additional Information describes a variety of useful information, including profiling, the options database, viewers, error handling, and some details of PETSc design.Visual Studio Code, Eclipse, Emacs, and Vim users may find their development environment's options for searching in the source code are useful for exploring the PETSc source code.Details of this feature are provided in Developer Environments.Note to Fortran Programmers: In most of the manual, the examples and calling sequences are given for the C/C++ family of programming languages.However, Fortran programmers can use all of the functionality of PETSc from Fortran, with only minor differences in the user interface.PETSc for Fortran Users provides a discussion of the differences between using PETSc from Fortran and C, as well as several complete Fortran examples. Note to Python Programmers:To program with PETSc in Python, you need to enable Python bindings (i.e.petsc4py) with the configure option --with-petsc4py=1.See the PETSc installation guide for more details.$ mpiexec -n 8 ./petsc_program_namepetsc_optionsPETSc also provides a script that automatically uses the correct mpiexec for your configuration.$ $PETSC_DIR/lib/petsc/bin/petscmpiexec -n 8 ./petsc_program_namepetsc_options Certain options are supported by all PETSc programs.We list a few particularly useful ones below; a complete list can be obtained by running any PETSc program with the option -help.• -log_view -summarize the program's performance (see Profiling)• -fp_trap -stop on floating-point exceptions; for example divide by zero • -malloc_dump -enable memory tracing; dump list of unfreed memory at conclusion of the run, see Detecting Memory Allocation Problems and Memory Usage, MatCreate(MPI_Comm comm,Mat *A); VecCreate(MPI_Comm comm,Vec *x); KSPCreate(MPI_Comm comm,KSP *ksp); Chapter 2. The Solvers in PETSc/TAO PETSc/TAO Users Manual, Release 3.21.0 DMNETWORK -Creating vectors for networksSee Networks for discussion of creating vectors with DMNETWORK. Common vector functions and operationsOne can examine (print out) a vector with the command VecView(Vec x,PetscViewer v);To print the vector to the screen, one can use the viewer PETSC_VIEWER_STDOUT_WORLD, which ensures that parallel vectors are printed correctly to stdout.To display the vector in an X-window, one can use the default X-windows viewer PETSC_VIEWER_DRAW_WORLD, or one can create a viewer with the routine PetscViewerDrawOpen().A variety of viewers are discussed further in Viewers: Looking at PETSc Objects.To create a new vector of the same format and parallel layout as an existing vector, useVecDuplicate(Vec old,Vec *new);To create several new vectors of the same format as an existing vector, useVecDuplicateVecs(Vec old,PetscInt n,Vec **new);This routine creates an array of pointers to vectors.The two routines are useful because they allow one to write library code that does not depend on the particular format of the vectors being used.Instead, the subroutines can automatically create work vectors based on the specified existing vector.As discussed in Duplicating Multiple Vectors, the Fortran interface for VecDuplicateVecs() differs slightly.When a vector is no longer needed, it should be destroyed with the command VecDestroy(Vec *x);To destroy an array of vectors, use the command VecDestroyVecs(PetscInt n,Vec **vecs);Note that the Fortran interface for VecDestroyVecs() differs slightly, as described in Duplicating Multiple Vectors.It is also possible to create vectors that use an array the user provides rather than having PETSc internally allocate the array space.Such vectors can be created with the routines such as