- bookworm 3.18.5-1

PETSC4PY(1) | PETSc for Python | PETSC4PY(1) |

# NAME¶

petsc4py - PETSc for Python

**Author**- Lisandro Dalcin
**Contact***dalcinl@gmail.com***Web Site***https://gitlab.com/petsc/petsc***Date**- Jun 20, 2023

## Abstract¶

This document describes *petsc4py*, a *Python* port to
the *PETSc* libraries.

*PETSc* (the Portable, Extensible Toolkit for Scientific
Computation) is a suite of data structures and routines for the scalable
(parallel) solution of scientific applications modeled by partial
differential equations. It employs the *MPI* standard for all
message-passing communication.

This package provides an important subset of PETSc functionalities
and uses *NumPy* to efficiently manage input and output of array
data.

A *good friend* of petsc4py is:

- •
*mpi4py*: Python bindings for*MPI*, the*Message Passing Interface*.

Other projects depends on petsc4py:

- •
*slepc4py*: Python bindings for*SLEPc*, the*Scalable Library for Eigenvalue Problem Computations*.

# CONTENTS¶

## Overview¶

*PETSc* is a suite of data structures and routines for the
scalable (parallel) solution of scientific applications modeled by partial
differential equations. It employs the *MPI* standard for all
message-passing communication.

PETSc is intended for use in large-scale application projects
*[petsc-efficient]*, and several ongoing computational science projects
are built around the PETSc libraries. With strict attention to component
interoperability, PETSc facilitates the integration of independently
developed application modules, which often most naturally employ different
coding styles and data structures.

PETSc is easy to use for beginners *[petsc-user-ref]*.
Moreover, its careful design allows advanced users to have detailed control
over the solution process. PETSc includes an expanding suite of parallel
linear and nonlinear equation solvers that are easily used in application
codes written in C, C++, and Fortran. PETSc provides many of the mechanisms
needed within parallel application codes, such as simple parallel matrix and
vector assembly routines that allow the overlap of communication and
computation.

- [petsc-user-ref]
- S. Balay, S. Abhyankar, M. Adams, S. Benson, J. Brown, P. Brune, K.
Buschelman, E. Constantinescu, L. Dalcin, A. Dener, V. Eijkhout, J.
Faibussowitsch, W. Gropp, V. Hapla, T. Isaac, P. Jolivet, D. Karpeyev, D.
Kaushik, M. Knepley, F. Kong, S. Kruger, D. May, L. Curfman McInnes, R.
Mills, L. Mitchell, T. Munson, J. Roman, K. Rupp, P. Sanan, J Sarich, B.
Smith, S. Zampini, H. Zhang, and H. Zhang, J. Zhang,
*PETSc/TAO Users Manual*, ANL-21/39 - Revision 3.19, 2023.*https://petsc.org/release/docs/manual/manual.pdf* - [petsc-efficient]
- Satish Balay, Victor Eijkhout, William D. Gropp, Lois Curfman McInnes and Barry F. Smith. Efficient Management of Parallelism in Object Oriented Numerical Software Libraries. Modern Software Tools in Scientific Computing. E. Arge, A. M. Bruaset and H. P. Langtangen, editors. 163--202. Birkhauser Press. 1997.

## Components¶

PETSc is designed with an object-oriented style. Almost all user-visible types are abstract interfaces with implementations that may be chosen at runtime. Those objects are managed through handles to opaque data structures which are created, accessed and destroyed by calling appropriate library routines.

PETSc consists of a variety of components. Each component manipulates a particular family of objects and the operations one would like to perform on these objects. These components provide the functionality required for many parallel solutions of PDEs.

**Vec**- Provides the vector operations required for setting up and solving large-scale linear and nonlinear problems. Includes easy-to-use parallel scatter and gather operations, as well as special-purpose code for handling ghost points for regular data structures.
**Mat**- A large suite of data structures and code for the manipulation of parallel sparse matrices. Includes four different parallel matrix data structures, each appropriate for a different class of problems.
**PC**- A collection of sequential and parallel preconditioners, including (sequential) ILU(k), LU, and (both sequential and parallel) block Jacobi, overlapping additive Schwarz methods and (through BlockSolve95) ILU(0) and ICC(0).
**KSP**- Parallel implementations of many popular Krylov subspace iterative methods, including GMRES, CG, CGS, Bi-CG-Stab, two variants of TFQMR, CR, and LSQR. All are coded so that they are immediately usable with any preconditioners and any matrix data structures, including matrix-free methods.
**SNES**- Data-structure-neutral implementations of Newton-like methods for nonlinear systems. Includes both line search and trust region techniques with a single interface. Employs by default the above data structures and linear solvers. Users can set custom monitoring routines, convergence criteria, etc.
**TS**- Code for the time evolution of solutions of PDEs. In addition, provides pseudo-transient continuation techniques for computing steady-state solutions.

## Installation¶

## Using pip¶

You can use **pip** to install **petsc4py** and its
dependencies (**mpi4py** is optional but highly recommended):

$ python -m pip install [--user] numpy mpi4py (or pip install [--user] numpy mpi4py) $ python -m pip install [--user] petsc petsc4py (or pip install [--user] petsc petsc4py)

## Using setuptools¶

You can also install dependencies manually and then invoke
setuptools from the *petsc4py* source directory:

You may use the *--install-lib* argument to the
*install* command to alter the *site-packages* directory where the
package is to be installed.

If you are cross-compiling, and the *numpy* module cannot be
loaded on your build host, then before invoking *setup.py*, set
*NUMPY_INCLUDE* environment variable to the path that would be returned
by *import numpy;* *numpy.get_include()*:

## From PETSc source¶

If you already have downloaded PETSc source and have installed the
dependencies of *petsc4py*, then to build the *petsc4py* module
along with PETSc, add the *--with-petsc4py=1* argument to the configure
command when building PETSc:

This will install PETSc and the *petsc4py* module into the
PETSc directory under the prefix specified to the PETSc configure
command.

If you wish to make the module importable without having to set
the *PYTHONPATH* environment variable, you may add a shortcut to the
system-wide *site-packages* directory creating a special *.pth*
file with exactly one line of Python code. This can be done by the following
command, where the system-wide path is assumed to be
*/usr/lib/pythonX/site-packages* (replace *X* with your python
version):

**$ echo**- "import sys, os;" "p = os.getenv('PETSC_DIR');" "a = os.getenv('PETSC_ARCH') or '';" "p = p and os.path.join(p, a, 'lib');" "p and (p in sys.path or sys.path.append(p))" > /usr/lib/pythonX/site-packages/petsc4py.pth

If you are cross-compiling, and *numpy* cannot be loaded on
your build host, then pass *--have-numpy=1 --with-numpy-include=PATH*,
where *PATH* is the path that would be returned by *import numpy;
print(numpy.get_include())*. This will suppress autodetection of the
include path on the build host.

## Tutorial¶

XXX To be written ... Any contribution welcome!

## Citations¶

If PETSc for Python been significant to a project that leads to an academic publication, please acknowledge that fact by citing the project.

- L. Dalcin, P. Kler, R. Paz, and A. Cosimo,
*Parallel Distributed Computing using Python*, Advances in Water Resources, 34(9):1124-1139, 2011.*http://dx.doi.org/10.1016/j.advwatres.2011.04.013* - S. Balay, S. Abhyankar, M. Adams, S. Benson, J. Brown, P. Brune, K.
Buschelman, E. Constantinescu, L. Dalcin, A. Dener, V. Eijkhout, J.
Faibussowitsch, W. Gropp, V. Hapla, T. Isaac, P. Jolivet, D. Karpeyev, D.
Kaushik, M. Knepley, F. Kong, S. Kruger, D. May, L. Curfman McInnes, R.
Mills, L. Mitchell, T. Munson, J. Roman, K. Rupp, P. Sanan, J Sarich, B.
Smith, S. Zampini, H. Zhang, and H. Zhang, J. Zhang,
*PETSc/TAO Users Manual*, ANL-21/39 - Revision 3.19, 2023.*https://petsc.org/release/docs/manual/manual.pdf*

# AUTHOR¶

Lisandro Dalcin

# COPYRIGHT¶

2023, Lisandro Dalcin

June 20, 2023 | 3.1 |