Debian Codegraph @

python/demo/documented/neumann-poisson/demo_neumann-poisson.py.rst

raw
1
2 .. _demo_pde_neumann-poisson_python_documentation:
3
4 Poisson equation with pure Neumann boundary conditions
5 ======================================================
6
7 This demo is implemented in a single Python file,
8 :download:`demo_neumann-poisson.py`, which contains both the
9 variational form and the solver.
10
11 This demo illustrates how to:
12
13 * Solve a linear partial differential equation with Neumann boundary
14 conditions
15 * Use mixed finite element spaces
16
17 The solution for :math:`u` in this demo will look as follows:
18
19 .. image:: neumann-poisson_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 \subset \mathbb{R}^n` with
28 boundary :math:`\partial \Omega`, the Poisson equation with particular
29 boundary conditions reads:
30
31 .. math::
32
33 - \nabla^{2} u &= f \quad {\rm in} \ \Omega, \\
34 \nabla u \cdot n &= g \quad {\rm on} \ \partial \Omega.
35
36 Here, :math:`f` and :math:`g` are input data and :math:`n` denotes the
37 outward directed boundary normal. Since only Neumann conditions are
38 applied, :math:`u` is only determined up to a constant :math:`c` by
39 the above equations. An additional constraint is thus required, for
40 instance:
41
42 .. math::
43
44 \int_{\Omega} u \, {\rm d} x = 0.
45
46 This can be accomplished by introducing the constant :math:`c` as an
47 additional unknown (to be sought in :math:`\mathbb{R}`) and the above
48 constraint expressed via a Lagrange multiplier.
49
50 We further note that a necessary condition for the existence of a
51 solution to the Neumann problem is that the right-hand side :math:`f`
52 satisfies
53
54 .. math::
55
56 \int_{\Omega} f \, {\rm d} x = - \int_{\partial\Omega} g \, {\rm d} s.
57
58 This can be seen by multiplying by :math:`1` and integrating by
59 parts:
60
61 .. math::
62
63 \int_{\Omega} f \, {\rm d} x = - \int_{\Omega} 1 \cdot \nabla^{2} u \, {\rm d} x
64 = - \int_{\partial\Omega} 1 \cdot \partial_n u \, {\rm d} s
65 + \int_{\Omega} \nabla 1 \cdot \nabla u \, {\rm d} x
66 = - \int_{\partial\Omega} g \, {\rm d} s.
67
68 This condition is not satisfied by the specific right-hand side chosen
69 for this test problem, which means that the partial differential
70 equation is not well-posed. However, the variational problem expressed
71 below is well-posed as the Lagrange multiplier introduced to satisfy
72 the condition :math:`\int_{\Omega} u \, {\rm d} x = 0` *effectively
73 redefines the right-hand side such that it safisfies the necessary
74 condition* :math:`\int_{\Omega} f \, {\rm d} x = -
75 \int_{\partial\Omega} g \, {\rm d} s`.
76
77 Our variational form reads: Find :math:`(u, c) \in V \times R` such
78 that
79
80 .. math::
81
82
83 a((u, c), (v, d)) = L((v, d)) \quad \forall \ (v, d) \in V \times R,
84
85
86
87 .. math::
88
89 a((u, c), (v, d)) &= \int_{\Omega} \nabla u \cdot \nabla v \, {\rm d} x
90 + \int_{\Omega} cv \, {\rm d} x
91 + \int_{\Omega} ud \, {\rm d} x, \\
92 L(v) &= \int_{\Omega} f v \, {\rm d} x
93 + \int_{\partial\Omega} g v \, {\rm d} s.
94
95 :math:`V` is a suitable function space containing :math:`u` and `v`,
96 :math:and :math:`R` is the space of real numbers.
97
98 The expression :math:`a(\cdot, \cdot)` is the bilinear form and
99 :math:`L(\cdot)` is the linear form.
100
101 Note that the above variational problem may alternatively be expressed
102 in terms of the modified (and consistent) right-hand side
103 :math:`\tilde{f} = f - c`.
104
105 In this demo we shall consider the following definitions of the domain
106 and input functions:
107
108 * :math:`\Omega = [0, 1] \times [0, 1]` (a unit square)
109 * :math:`g = - \sin(5x)` (normal derivative)
110 * :math:`f = 10\exp(-((x - 0.5)^2 + (y - 0.5)^2) / 0.02)` (source term)
111
112
113 Implementation
114 --------------
115
116 This description goes through the implementation in
117 :download:`demo_neumann-poisson.py` of a solver for the above
118 described Poisson equation step-by-step.
119
120 First, the :py:mod:`dolfin` module is imported: ::
121
122 from dolfin import *
123
124 We proceed by defining a mesh of the domain. We use a built-in mesh
125 provided by the class :py:class:`UnitSquareMesh
126 <dolfin.cpp.UnitSquareMesh>`. In order to create a mesh consisting of
127 :math:`64 \times 64` squares, we do as follows: ::
128
129 # Create mesh
130 mesh = UnitSquareMesh.create(64, 64, CellType.Type.quadrilateral)
131
132 Next, we need to define the function space. ::
133
134 # Build function space with Lagrange multiplier
135 P1 = FiniteElement("Lagrange", mesh.ufl_cell(), 1)
136 R = FiniteElement("Real", mesh.ufl_cell(), 0)
137 W = FunctionSpace(mesh, P1 * R)
138
139 The second argument to :py:class:`FunctionSpace
140 <dolfin.functions.functionspace.FunctionSpace>` specifies underlying
141 finite element, here a mixed element is obtained by ``*`` operator.
142
143 Now, we want to define the variational problem, but first we need to
144 specify the trial functions (the unknowns) and the test functions.
145 This can be done using
146 :py:class:`TrialFunctions<dolfin.functions.function.TrialFunction>`
147 and :py:class:`TestFunctions
148 <dolfin.functions.function.TestFunction>`. It only remains to define
149 the source function :math:`f`, before we define the bilinear and
150 linear forms. It is given by a simple mathematical formula, and can
151 easily be declared using the :py:class:`Expression
152 <dolfin.functions.expression.Expression>` class. Note that the string
153 defining ``f`` uses C++ syntax since, for efficiency, DOLFIN will
154 generate and compile C++ code for these expressions at run-time. The
155 following code shows how this is done and defines the variational
156 problem: ::
157
158 # Define variational problem
159 (u, c) = TrialFunction(W)
160 (v, d) = TestFunctions(W)
161 f = Expression("10*exp(-(pow(x[0] - 0.5, 2) + pow(x[1] - 0.5, 2)) / 0.02)", degree=2)
162 g = Expression("-sin(5*x[0])", degree=2)
163 a = (inner(grad(u), grad(v)) + c*v + u*d)*dx
164 L = f*v*dx + g*v*ds
165
166 Since we have natural (Neumann) boundary conditions in this problem,
167 we do not have to implement boundary conditions. This is because
168 Neumann boundary conditions are default in DOLFIN.
169
170 To compute the solution we use the bilinear form, the linear forms,
171 and the boundary condition, but we also need to create a
172 :py:class:`Function <dolfin.functions.function.Function>` to store the
173 solution(s). The (full) solution will be stored in ``w``, which we
174 initialize using the
175 :py:class:`FunctionSpace<dolfin.functions.functionspace.FunctionSpace>`
176 ``W``. The actual computation is performed by calling
177 :py:func:`solve<dolfin.fem.solving.solve>`. The separate components
178 ``u`` and ``c`` of the solution can be extracted by calling the split
179 function. Finally, we output the solution to a ``VTK`` file to examine the result. ::
180
181 # Compute solution
182 w = Function(W)
183 solve(a == L, w)
184 (u, c) = w.split()
185
186 # Save solution in VTK format
187 file = File("neumann_poisson.pvd")
188 file << u