Debian Codegraph @

python/demo/documented/singular-poisson/demo_singular-poisson.py.rst

raw
1 Singular Poisson
2 ================
3
4 This demo is implemented in a single Python file,
5 :download:`demo_singular-poisson.py`, which contains both the
6 variational forms and the solver.
7
8 This demo illustrates how to:
9
10 * Solve a linear partial differential equation
11 * Apply non-zero Neumann boundary conditions
12 * Define Expressions
13 * Define a FunctionSpace
14 * Use the Krylov solver
15 * Solve singular problems
16
17 The solution for :math:`u` in this demo will look as follows:
18
19 .. image:: singular_u.png
20 :scale: 75 %
21
22
23 Equation and problem definition
24 -------------------------------
25
26 The Poisson equation is the canonical elliptic partial differential
27 equation. For a domain :math:`\Omega \in \mathbb{R}^n` with boundary
28 :math:`\Gamma = \partial \Omega`, the Poisson equation with pure
29 Neumann boundary conditions reads:
30
31 .. math::
32 -\nabla^{2} u &= f \quad {\rm in} \ \Omega \\
33 \nabla u \cdot n &= g \quad {\rm on} \ \Gamma \\
34
35 Since only Neumann conditions are applied, :math:`u` is only
36 determined up to a constant by the above equations. An addition
37 constraint is thus required, for instance
38
39 .. math::
40 \int u \, {\rm d} x = 0
41
42 The most standard variational form of the Poisson equation reads: find
43 :math:`u \in V` such that
44
45 .. math::
46 a(u, v) = L(v) \quad \forall \ v \in V,
47
48 where :math:`V` is a suitable function space and
49
50 .. math::
51 a(u, v) &= \int_{\Omega} \nabla u \cdot \nabla v \, {\rm d} x, \\
52 L(v) &= \int_{\Omega} f v \, {\rm d} x
53 + \int_{\Gamma} g v \, {\rm d} s.
54
55 The expression :math:`a(u, v)` is the bilinear form and :math:`L(v)`
56 is the linear form.
57
58 If we make the Ansatz that :math:`u` can be expressed as a linear
59 combination of the basis functions of :math:`V`, and discretize the
60 equation, we can write our problem as a linear system:
61
62 .. math::
63 AU = b,
64
65 where :math:`U` gives the coefficient for the basis functions
66 expressing :math:`u`.
67
68 Since we have pure Neumann boundary conditions, the matrix :math:`A`
69 is singular. There exists a non-trival vector :math:`e` such that
70
71 .. math::
72 Ae=0.
73
74 span :math:`\{ e \}` is the null space of A. Consequently, the matrix
75 :math:`A` is rank deficient and the right-hand side vector :math:`b`
76 may fail to be in the column space of :math:`A`. We therefore need to
77 remove the components of :math:`b` that do not lie in the column space
78 to make the system solvable.
79
80 In this demo, we shall consider the following definitions of the input
81 functions, the domain, and the boundaries:
82
83 * :math:`\Omega = [0,1] \times [0,1]` (a unit square)
84 * :math:`\Gamma = \partial \Omega` (boundary)
85 * :math:`g = -\sin(5x)` (normal derivative)
86 * :math:`f = 10\exp(-((x - 0.5)^2 + (y - 0.5)^2) / 0.02)` (source
87 term)
88
89
90 Implementation
91 --------------
92
93 This description goes through the implementation (in
94 :download:`demo_singular-poisson.py`) of a solver for the above
95 described Poisson equation step-by-step.
96
97 First, the modules :py:mod:`dolfin` and matplotlib are imported: ::
98
99 from dolfin import *
100 import matplotlib.pyplot as plt
101
102 Then, we check that dolfin is configured with the backend called
103 PETSc, since it provides us with a wide range of methods used by
104 :py:class:`KrylovSolver <dolfin.cpp.la.KrylovSolver>`. We set PETSc as
105 our backend for linear algebra::
106
107 # Test for PETSc
108 if not has_linear_algebra_backend("PETSc"):
109 info("DOLFIN has not been configured with PETSc. Exiting.")
110 exit()
111
112 parameters["linear_algebra_backend"] = "PETSc"
113
114 We begin by defining a mesh of the domain and a finite element
115 function space :math:`V` relative to this mesh. We use a built-in mesh
116 provided by the class :py:class:`UnitSquareMesh
117 <dolfin.cpp.mesh.UnitSquareMesh>`. In order to create a mesh
118 consisting of :math:`64 \times 64` squares with each square divided
119 into two triangles, we do as follows: ::
120
121 # Create mesh and define function space
122 mesh = UnitSquareMesh(64, 64)
123 V = FunctionSpace(mesh, "CG", 1)
124
125 Now, we need to specify the trial functions (the unknowns) and the
126 test functions on the space :math:`V`. This can be done using a
127 :py:class:`TrialFunction <dolfin.functions.function.TrialFunction>`
128 and a :py:class:`TestFunction
129 <dolfin.functions.function.TrialFunction>` as follows: ::
130
131 u = TrialFunction(V)
132 v = TestFunction(V)
133
134 Further, the source :math:`f` and the boundary normal derivative
135 :math:`g` are involved in the variational forms, and hence we must
136 specify these. Both :math:`f` and :math:`g` are given by simple
137 mathematical formulas, and can be easily declared using the
138 :py:class:`Expression <dolfin.functions.expression.Expression>`
139 class. Note that the strings defining f and g use C++ syntax since,
140 for efficiency, DOLFIN will generate and compile C++ code for these
141 expressions at run-time. ::
142
143 f = Expression("10*exp(-(pow(x[0] - 0.5, 2) + pow(x[1] - 0.5, 2)) / 0.02)", degree=2)
144 g = Expression("-sin(5*x[0])", degree=2)
145
146 With :math:`u,v,f` and :math:`g`, we can write down the bilinear form
147 :math:`a` and the linear form :math:`L` (using UFL operators). ::
148
149 a = inner(grad(u), grad(v))*dx
150 L = f*v*dx + g*v*ds
151
152 In order to transform our variational problem into a linear system we
153 need to assemble the coefficient matrix ``A`` and the right-side
154 vector ``b``. We do this using the function :py:meth:`assemble
155 <dolfin.cpp.fem.Assembler.assemble>`: ::
156
157 # Assemble system
158 A = assemble(a)
159 b = assemble(L)
160
161 We specify a Vector for storing the result by defining a
162 :py:class:`Function <dolfin.cpp.function.Function>`. ::
163
164 # Solution Function
165 u = Function(V)
166
167 Next, we specify the iterative solver we want to use, in this case a
168 :py:class:`PETScKrylovSolver <dolfin.cpp.la.PETScKrylovSolver>` with
169 the conjugate gradient (CG) method, and attach the matrix operator to
170 the solver. ::
171
172 # Create Krylov solver
173 solver = PETScKrylovSolver("cg")
174 solver.set_operator(A)
175
176 We impose our additional constraint by removing the null space
177 component from the solution vector. In order to do this we need a
178 basis for the null space. This is done by creating a vector that spans
179 the null space, and then defining a basis from it. The basis is then
180 attached to the matrix ``A`` as its null space. ::
181
182 # Create vector that spans the null space and normalize
183 null_vec = Vector(u.vector())
184 V.dofmap().set(null_vec, 1.0)
185 null_vec *= 1.0/null_vec.norm("l2")
186
187 # Create null space basis object and attach to PETSc matrix
188 null_space = VectorSpaceBasis([null_vec])
189 as_backend_type(A).set_nullspace(null_space)
190
191 Orthogonalization of ``b`` with respect to the null space makes sure
192 that it doesn't contain any component in the null space. ::
193
194 null_space.orthogonalize(b);
195
196 Finally we are able to solve our linear system ::
197
198 solver.solve(u.vector(), b)
199
200 and plot the solution ::
201
202 plot(u)
203 plt.show()