1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
|
.. _petsc_python_types:
PETSc Python types
==================
Here we discuss details about Python-aware PETSc types that can be used within the library.
In particular, we discuss matrices, preconditioners, Krylov solvers, nonlinear solvers, ODE integrators and viewers.
The low-level, Cython implementation exposing the Python methods is in `src/petsc4py/PETSc/libpetsc4py.pyx <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/src/petsc4py/PETSc/libpetsc4py.pyx>`_.
The scripts used here can be found at `demo/python_types <https://gitlab.com/petsc/petsc/-/tree/release/src/binding/petsc4py/demo/python_types>`_.
.. _petsc_python_mat:
PETSc Python matrix type
------------------------
PETSc provides a convenient way to compute the action of linear operators coded
in Python through the `petsc4py.PETSc.Mat.Type.PYTHON` type.
In addition to the matrix action, the implementation can expose additional
methods for use within the library. A template class for
the supported methods is given below.
.. literalinclude:: ../../demo/python_types/matpython_protocol.py
In the example below, we create an operator that applies the Laplacian operator
on a two-dimensional grid, and use it to solve the associated linear system.
The default preconditioner in the script is `petsc4py.PETSc.PC.Type.JACOBI`
which needs to access the diagonal of the matrix.
.. literalinclude:: ../../demo/python_types/mat.py
.. _petsc_python_pc:
PETSc Python preconditioner type
--------------------------------
The protocol for the `petsc4py.PETSc.PC.Type.PYTHON` preconditioner is:
.. literalinclude:: ../../demo/python_types/pcpython_protocol.py
In the example below, we create a Jacobi preconditioner, which needs to access
the diagonal of the matrix. The action of the preconditioner consists of the
pointwise multiplication of the inverse diagonal with the input vector.
.. literalinclude:: ../../demo/python_types/pc.py
We can run the script used to test our matrix class and use command line
arguments to specify that our preconditioner should be used:
.. code-block:: console
$ python mat.py -pc_type python -pc_python_type pc.myJacobi -ksp_view
KSP Object: 1 MPI process
type: cg
maximum iterations=10000, initial guess is zero
tolerances: relative=1e-05, absolute=1e-50, divergence=10000.
left preconditioning
using PRECONDITIONED norm type for convergence test
PC Object: 1 MPI process
type: python
Python: pc.myJacobi
linear system matrix = precond matrix:
Mat Object: 1 MPI process
type: python
rows=256, cols=256
Python: __main__.Poisson2D
.. _petsc_python_ksp:
PETSc Python linear solver type
-------------------------------
The protocol for the `petsc4py.PETSc.KSP.Type.PYTHON` Krylov solver is:
.. literalinclude:: ../../demo/python_types/ksppython_protocol.py
.. _petsc_python_snes:
PETSc Python nonlinear solver type (TODO)
-----------------------------------------
.. _petsc_python_ts:
PETSc Python ode-integrator type (TODO)
---------------------------------------
.. _petsc_python_tao:
PETSc Python optimization solver type
-------------------------------------
The protocol for the `petsc4py.PETSc.TAO.Type.PYTHON` TAO optimizer is:
.. literalinclude:: ../../demo/python_types/tao.py
In the example below, we create a simple gradient based (first order)
optimization solver. A `petsc4py.PETSc.TAOLineSearch.Type.UNIT` line search
with step size :math:`0.2` is used. Therefore the update becomes
.. math::
x^{k+1} = x^k + 0.2 \nabla f(x^k).
.. note::
This setup is also well suited for non-linesearch-based quasi-Newton
optimization algorithms. It provides a general interface for using the TAO
provided state and functionality on a custom algorithm.
The optimizer can be used from Python as
.. code-block:: python
PETSc.TAO().createPython(myGradientDescent())
or selected through the PETSc options as
.. code-block:: console
python tao.py -tao_type python -tao_python_type tao.myGradientDescent
.. tip::
The prefix **tao** to **tao_python_type** is dependant on the Python module in
which the optimizer is located. It aligns with the fully qualified Python
module name.
.. _petsc_python_viewer:
PETSc Python viewer
-------------------
The protocol for the `petsc4py.PETSc.Viewer.Type.PYTHON` viewer is:
.. literalinclude:: ../../demo/python_types/petscviewerpython_protocol.py
|
