Debian Codegraph @

python/demo/documented/poisson/demo_poisson.py.rst

raw
1
2 .. _demo_poisson_equation:
3
4 Poisson equation
5 ================
6
7 This demo is implemented in a single Python file,
8 :download:`demo_poisson.py`, which contains both the variational forms
9 and the solver.
10
11 This demo illustrates how to:
12
13 * Solve a linear partial differential equation
14 * Create and apply Dirichlet boundary conditions
15 * Define Expressions
16 * Define a FunctionSpace
17 * Create a SubDomain
18
19 The solution for :math:`u` in this demo will look as follows:
20
21 .. image:: poisson_u.png
22 :scale: 75 %
23
24
25 Equation and problem definition
26 -------------------------------
27
28 The Poisson equation is the canonical elliptic partial differential
29 equation. For a domain :math:`\Omega \subset \mathbb{R}^n` with
30 boundary :math:`\partial \Omega = \Gamma_{D} \cup \Gamma_{N}`, the
31 Poisson equation with particular boundary conditions reads:
32
33 .. math::
34 - \nabla^{2} u &= f \quad {\rm in} \ \Omega, \\
35 u &= 0 \quad {\rm on} \ \Gamma_{D}, \\
36 \nabla u \cdot n &= g \quad {\rm on} \ \Gamma_{N}. \\
37
38 Here, :math:`f` and :math:`g` are input data and :math:`n` denotes the
39 outward directed boundary normal. The most standard variational form
40 of Poisson equation reads: find :math:`u \in V` such that
41
42 .. math::
43 a(u, v) = L(v) \quad \forall \ v \in V,
44
45 where :math:`V` is a suitable function space and
46
47 .. math::
48 a(u, v) &= \int_{\Omega} \nabla u \cdot \nabla v \, {\rm d} x, \\
49 L(v) &= \int_{\Omega} f v \, {\rm d} x
50 + \int_{\Gamma_{N}} g v \, {\rm d} s.
51
52 The expression :math:`a(u, v)` is the bilinear form and :math:`L(v)`
53 is the linear form. It is assumed that all functions in :math:`V`
54 satisfy the Dirichlet boundary conditions (:math:`u = 0 \ {\rm on} \
55 \Gamma_{D}`).
56
57 In this demo, we shall consider the following definitions of the input
58 functions, the domain, and the boundaries:
59
60 * :math:`\Omega = [0,1] \times [0,1]` (a unit square)
61 * :math:`\Gamma_{D} = \{(0, y) \cup (1, y) \subset \partial \Omega\}`
62 (Dirichlet boundary)
63 * :math:`\Gamma_{N} = \{(x, 0) \cup (x, 1) \subset \partial \Omega\}`
64 (Neumann boundary)
65 * :math:`g = \sin(5x)` (normal derivative)
66 * :math:`f = 10\exp(-((x - 0.5)^2 + (y - 0.5)^2) / 0.02)` (source
67 term)
68
69
70 Implementation
71 --------------
72
73 This description goes through the implementation (in
74 :download:`demo_poisson.py`) of a solver for the above described
75 Poisson equation step-by-step.
76
77 First, the :py:mod:`dolfin` module is imported: ::
78
79 from dolfin import *
80
81 We begin by defining a mesh of the domain and a finite element
82 function space :math:`V` relative to this mesh. As the unit square is
83 a very standard domain, we can use a built-in mesh provided by the
84 class :py:class:`UnitSquareMesh <dolfin.cpp.UnitSquareMesh>`. In order
85 to create a mesh consisting of 32 x 32 squares with each square
86 divided into two triangles, we do as follows ::
87
88 # Create mesh and define function space
89 mesh = UnitSquareMesh(32, 32)
90 V = FunctionSpace(mesh, "Lagrange", 1)
91
92 The second argument to :py:class:`FunctionSpace
93 <dolfin.functions.functionspace.FunctionSpace>` is the finite element
94 family, while the third argument specifies the polynomial
95 degree. Thus, in this case, our space ``V`` consists of first-order,
96 continuous Lagrange finite element functions (or in order words,
97 continuous piecewise linear polynomials).
98
99 Next, we want to consider the Dirichlet boundary condition. A simple
100 Python function, returning a boolean, can be used to define the
101 subdomain for the Dirichlet boundary condition (:math:`\Gamma_D`). The
102 function should return ``True`` for those points inside the subdomain
103 and ``False`` for the points outside. In our case, we want to say that
104 the points :math:`(x, y)` such that :math:`x = 0` or :math:`x = 1` are
105 inside on the inside of :math:`\Gamma_D`. (Note that because of
106 rounding-off errors, it is often wise to instead specify :math:`x <
107 \epsilon` or :math:`x > 1 - \epsilon` where :math:`\epsilon` is a
108 small number (such as machine precision).) ::
109
110 # Define Dirichlet boundary (x = 0 or x = 1)
111 def boundary(x):
112 return x[0] < DOLFIN_EPS or x[0] > 1.0 - DOLFIN_EPS
113
114 Now, the Dirichlet boundary condition can be created using the class
115 :py:class:`DirichletBC <dolfin.fem.bcs.DirichletBC>`. A
116 :py:class:`DirichletBC <dolfin.fem.bcs.DirichletBC>` takes three
117 arguments: the function space the boundary condition applies to, the
118 value of the boundary condition, and the part of the boundary on which
119 the condition applies. In our example, the function space is ``V``,
120 the value of the boundary condition (0.0) can represented using a
121 :py:class:`Constant <dolfin.functions.constant.Constant>` and the
122 Dirichlet boundary is defined immediately above. The definition of the
123 Dirichlet boundary condition then looks as follows: ::
124
125 # Define boundary condition
126 u0 = Constant(0.0)
127 bc = DirichletBC(V, u0, boundary)
128
129 Next, we want to express the variational problem. First, we need to
130 specify the trial function :math:`u` and the test function :math:`v`,
131 both living in the function space :math:`V`. We do this by defining a
132 :py:class:`TrialFunction <dolfin.functions.function.TrialFunction>`
133 and a :py:class:`TestFunction
134 <dolfin.functions.function.TrialFunction>` on the previously defined
135 :py:class:`FunctionSpace
136 <dolfin.functions.functionspace.FunctionSpace>` ``V``.
137
138 Further, the source :math:`f` and the boundary normal derivative
139 :math:`g` are involved in the variational forms, and hence we must
140 specify these. Both :math:`f` and :math:`g` are given by simple
141 mathematical formulas, and can be easily declared using the
142 :py:class:`Expression <dolfin.functions.expression.Expression>` class.
143 Note that the strings defining ``f`` and ``g`` use C++ syntax since,
144 for efficiency, DOLFIN will generate and compile C++ code for these
145 expressions at run-time.
146
147 With these ingredients, we can write down the bilinear form ``a`` and
148 the linear form ``L`` (using UFL operators). In summary, this reads ::
149
150 # Define variational problem
151 u = TrialFunction(V)
152 v = TestFunction(V)
153 f = Expression("10*exp(-(pow(x[0] - 0.5, 2) + pow(x[1] - 0.5, 2)) / 0.02)", degree=2)
154 g = Expression("sin(5*x[0])", degree=2)
155 a = inner(grad(u), grad(v))*dx
156 L = f*v*dx + g*v*ds
157
158 Now, we have specified the variational forms and can consider the
159 solution of the variational problem. First, we need to define a
160 :py:class:`Function <dolfin.functions.function.Function>` ``u`` to
161 represent the solution. (Upon initialization, it is simply set to the
162 zero function.) A :py:class:`Function
163 <dolfin.functions.function.Function>` represents a function living in
164 a finite element function space. Next, we can call the :py:func:`solve
165 <dolfin.fem.solving.solve>` function with the arguments ``a == L``,
166 ``u`` and ``bc`` as follows: ::
167
168 # Compute solution
169 u = Function(V)
170 solve(a == L, u, bc)
171
172 The function ``u`` will be modified during the call to solve. The
173 default settings for solving a variational problem have been
174 used. However, the solution process can be controlled in much more
175 detail if desired.
176
177 A :py:class:`Function <dolfin.functions.function.Function>` can be
178 manipulated in various ways, in particular, it can be plotted and
179 saved to file. Here, we output the solution to a ``VTK`` file (using
180 the suffix ``.pvd``) for later visualization and also plot it using
181 the :py:func:`plot <dolfin.common.plot.plot>` command: ::
182
183 # Save solution in VTK format
184 file = File("poisson.pvd")
185 file << u
186
187 # Plot solution
188 import matplotlib.pyplot as plt
189 plot(u)
190 plt.show()