petsc-3.15.0 2021-03-30
Report Typos and Errors

# PETSc Users Manual

Argonne National Laboratory

Mathematics and Computer Science Division

Highly recommended resource: Ed Bueler, PETSc for Partial Differential Equations: Numerical Solutions in C and Python or as a Google Play E-book.

Prepared by

S. Balay 1, S. Abhyankar 2, M. Adams 3, J. Brown 10, P. Brune 1, K. Buschelman 1, L. Dalcin 4, A. Dener 1, V. Eijkhout 6, W. Gropp 11, D. Karpeyev 1, D. Kaushik 12, M. Knepley 9, D. May 7, L. Curfman McInnes 1, R. Mills 1, T. Munson 1, K. Rupp 1, P. Sanan 8, B. Smith 1, S. Zampini 4, H. Zhang 5, and H. Zhang 1

1Mathematics and Computer Science Division, Argonne National Laboratory
2Electricity Infrastructure and Buildings Division, Pacific Northwest National Laboratory
3Computational Research, Lawrence Berkeley National Laboratory
4Extreme Computing Research Center, King Abdullah University of Science and Technology
5Department of Computer Science, Illinois Institute of Technology
6Texas Advanced Computing Center, University of Texas at Austin
7Department of Earth Sciences, University of Oxford
8Institute of Geophysics, ETH Zurich
9Department of Computer Science and Engineering, University at Buffalo
10Department of Computer Science, University of Colorado, Boulder
11Department of Computer Science, University of Illinois, Urbana-Champaign
12Qatar Foundation

This work was supported by the Office of Advanced Scientific Computing Research, Office of Science, U.S. Department of Energy, under Contract DE-AC02-06CH11357.

- Introduction to PETSc
  - About This Manual
  - Getting Started
    - Suggested Reading
    - Running PETSc Programs
    - Writing PETSc Programs
    - Simple PETSc Examples
    - Profiling Programs
    - Writing Application Codes with PETSc
    - Citing PETSc
    - Directory Structure
- Programming with PETSc
  - Vectors and Parallel Data
    - Creating and Assembling Vectors
    - Basic Vector Operations
    - Indexing and Ordering
    - Structured Grids Using Distributed Arrays
    - Vectors Related to Unstructured Grids
  - Matrices
    - Creating and Assembling Matrices
    - Basic Matrix Operations
    - Matrix-Free Matrices
    - Other Matrix Operations
    - Partitioning
  - KSP: Linear System Solvers
    - Using KSP
    - Solving Successive Linear Systems
    - Krylov Methods
    - Preconditioners
    - Solving Block Matrices
    - Solving Singular Systems
    - Using External Linear Solvers
  - SNES: Nonlinear Solvers
    - Basic SNES Usage
    - The Nonlinear Solvers
    - General Options
    - Inexact Newton-like Methods
    - Matrix-Free Methods
    - Finite Difference Jacobian Approximations
    - Variational Inequalities
    - Nonlinear Preconditioning
  - TS: Scalable ODE and DAE Solvers
    - Basic TS Options
    - DAE Formulations
    - Using Implicit-Explicit (IMEX) Methods
    - GLEE methods
    - Using fully implicit methods
    - Using the Explicit Runge-Kutta timestepper with variable timesteps
    - Special Cases
    - Monitoring and visualizing solutions
    - Error control via variable time-stepping
    - Handling of discontinuities
    - Using TChem from PETSc
    - Using Sundials from PETSc
  - Performing sensitivity analysis
    - Using the discrete adjoint methods
    - Checkpointing
  - Solving Steady-State Problems with Pseudo-Timestepping
  - High Level Support for Multigrid with KSPSetDM() and SNESSetDM()
    - Adaptive Interpolation
  - DMPlex: Unstructured Grids in PETSc
    - Representing Unstructured Grids
    - Data on Unstructured Grids
    - Evaluating Residuals
    - Networks
- Additional Information
  - PETSc for Fortran Users
    - C vs. Fortran Interfaces
    - Sample Fortran Programs
  - Using MATLAB with PETSc
    - Dumping Data for MATLAB
    - Sending Data to an Interactive MATLAB Session
    - Using the MATLAB Compute Engine
    - Licensing the MATLAB Compute Engine on a cluster
  - Profiling
    - Basic Profiling Information
    - Profiling Application Codes
    - Profiling Multiple Sections of Code
    - Restricting Event Logging
    - Interpreting `-log_info` Output: Informative Messages
    - Time
    - Saving Output to a File
    - Accurate Profiling and Paging Overheads
  - Hints for Performance Tuning
    - Maximizing Memory Bandwidth
    - Performance Pitfalls and Advice
  - The Use of BLAS and LAPACK in PETSc and external libraries
    - 32 or 64 bit BLAS/LAPACK integers
    - Shared memory BLAS/LAPACK parallelism
    - Available BLAS/LAPACK libraries
  - Other PETSc Features
    - PETSc on a process subset
    - Runtime Options
    - Viewers: Looking at PETSc Objects
    - Using SAWs with PETSc
    - Debugging
    - Error Handling
    - Numbers
    - Parallel Communication
    - Graphics
    - Emacs Users
    - VS Code Users
    - Vi and Vim Users
    - Eclipse Users
    - Qt Creator Users
    - Visual Studio Users
    - XCode Users (The Apple GUI Development System)
  - Unimportant and Advanced Features of Matrices and Solvers
    - Extracting Submatrices
    - Matrix Factorization
    - Unimportant Details of KSP
    - Unimportant Details of PC
  - Running PETSc Tests
    - Quick start with the tests
    - Understanding test output and more information
  - Acknowledgments

Frequently Asked Questions (FAQ) Introduction to PETSc