Year: 2025
Type: report
Abstract: About This ManualThis 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.1 PETSc/TAO Users Manual, Release 3.24.0 Getting StartedPETSc consists of a collection of classes, which are discussed in detail in later parts of the manual (The Solvers in PETSc/TAO and Additional Information).The important PETSc classes include• index sets (IS), for indexing into vectors, renumbering, permuting, etc;• Vectors and Parallel Data (Vec);• (generally sparse) Matrices (Mat)• KSP: Linear System Solvers (KSP);• preconditioners, including multigrid, block solvers, patch solvers, and sparse direct solvers (PC);• SNES: Nonlinear Solvers (SNES);• TS: Scalable ODE and DAE Solvers for solving time-dependent (nonlinear) PDEs, including support for differential-algebraic-equations, and the computation of adjoints (sensitivities/gradients of the solutions) (TS);• scalable TAO: Optimization Solvers including a rich set of gradient-based optimizers, Newton-based optimizers and optimization with constraints (Tao).• {any}ch_regressor (PetscRegressor)• DM Basics code for managing interactions between mesh data structures and vectors, matrices, and solvers (DM);Each class consists of an abstract interface (simply a set of calling sequences corresponding to an abstract base class in C++) and an implementation for each algorithm and data structure.This design enables easy comparison and use of different algorithms (for example, experimenting with different Krylov subspace methods, preconditioners, or truncated Newton methods).Hence, PETSc provides a rich environment for modeling scientific applications as well as for rapid algorithm design and prototyping.The classes enable easy customization and extension of both algorithms and implementations.This approach promotes code reuse and flexibility.The PETSc infrastructure creates a foundation for building large-scale applications.It is useful to consider the interrelationships among different pieces of PETSc.Numerical Libraries in PETSc is a diagram of some of these pieces.The figure illustrates the library's hierarchical organization, enabling users to employ the most appropriate solvers for a particular problem.PETSc/TAO Users Manual, Release 3.24.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. Running PETSc ProgramsBefore using PETSc, the user must first set the environmental variable PETSC_DIR to indicate the full path of the PETSc home directory.For example, under the Unix bash shell, a command of the formcan be placed in the user's .bashrcor other startup file.In addition, the user may need to set the environment variable $PETSC_ARCH to specify a particular configuration of the PETSc libraries.Note that $PETSC_ARCH is just a name selected by the installer to refer to the libraries compiled for a particular set of compiler options and machine type.Using different values of $PETSC_ARCH allows one to switch between several different sets (say debug and optimized versions) of libraries easily.To determine if you need to set $PETSC_ARCH, look in the directory indicated by $PETSC_DIR, if there are subdirectories beginning with arch then those subdirectories give the possible values for $PETSC_ARCH.See handson to immediately jump in and run PETSc code.All PETSc programs use the MPI (Message Passing Interface) standard for message-passing communication [For94].Thus, to execute PETSc programs, users must know the procedure for beginning MPI jobs on their selected computer system(s).For instance, when using the MPICH implementation of MPI and many others, the following command initiates a program that uses eight processors:PETSc also provides a script that automatically uses the correct mpiexec for your configuration.$ $PETSC_DIR/lib/petsc/bin/petscmpiexec -n 8 ./petsc_program_namepetsc_optionsCertain 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, 4 Chapter 1. Introduction to PETSc PETSc/TAO Users Manual, Release 3.24.0• -malloc_debug -enable memory debugging (by default, this is activated for the debugging version of PETSc), see Detecting Memory Allocation Problems and Memory Usage, • -start_in_debugger [noxterm,gdb,lldb] [-display name] -start all (or a subset of the) processes in a debugger.See Debugging, for more information on debugging PETSc programs.• -on_error_attach_debugger [noxterm,gdb,lldb] [-display name] -start debugger only on encountering an error • -info -print a great deal of information about what the program is doing as it runs • -version -display the version of PETSc being used 1.2.3 Writing PETSc Programs Most PETSc programs begin with a call to PetscInitialize(int *argc,char ***argv,char *file,char *help); which initializes PETSc and MPI.The arguments argc and argv are the usual command line arguments in C and C++ programs.The argument file optionally indicates an alternative name for the PETSc options file, .petscrc,which resides by default in the user's home directory.Runtime Options provides details regarding this file and the PETSc options database, which can be used for runtime customization.The final
DOI: 10.2172/2998643
Authors: S. Balay, S. Abhyankar, M. Adams, J. Brown, P. Brune, K. Buschelman, E. Constantinescu, L. Dalcin, S. Benson, A. Dener, V. Eijkhout, J. Faibussowitsch, W. Gropp, V. Hapla, T. Isaac, P. Jolivet, D. Karpeev, D. Kaushik, M. Knepley, F. Kong, S. Kruger, D. May, L. McInnes, R. Mills, L. Mitchell, T. Munson, Jose Roman, K. Rupp, P. Sanan, J. Sarich, B. Smith, H. Suh, S. Zampini, H. Zhang, J. Zhang
Institutions: Argonne National Laboratory, Pacific Northwest National Laboratory, Lawrence Berkeley National Laboratory, University of Colorado Boulder, King Abdullah University of Science and Technology, The University of Texas at Austin, University of Illinois Urbana-Champaign, ETH Zurich, Georgia Institute of Technology, Centre National de la Recherche Scientifique, Sorbonne Université, University at Buffalo, State University of New York, Idaho National Laboratory, Tech-X Corporation (United States), University of California San Diego, University of Oxford, Durham University, Nvidia (United States), Universitat Politècnica de València, Tsinghua University, Flatiron Institute, Illinois Institute of Technology
Language: English
Topic: Matrix Theory and Algorithms
Subfield: Computational Theory and Mathematics
Field: Computer Science
Domain: Physical Sciences
Open Access status: green
OpenAlex ID: W4415353511