Debian Codegraph @

python/demo/documented/subdomains-poisson/documentation.rst

raw
1 .. Documentation for the DOLFIN iterative Stokes demo.
2
3 .. _demo_pde_subdomains_poisson_documentation:
4
5 Poisson equation with multiple subdomains
6 =========================================
7
8 This demo is implemented in a single Python file,
9 :download:`demo_subdomains-poisson.py`, which contains both the
10 variational forms and the solver. We suggest that you familiarize
11 yourself with the :ref:`Poisson demo
12 <demo_pde_poisson_python_documentation>` before studying this example,
13 as some of the more standard steps will be described in less detail.
14
15 .. include:: ../common.txt
16
17 Implementation
18 --------------
19
20 This description goes through the implementation (in
21 :download:`demo_subdomains-poisson.py`) of a solver for the above
22 described equation.
23
24 In this example, different boundary conditions are prescribed on
25 different parts of the boundaries, and different parts of the interior
26 have different material properties. This information must be made
27 available to the solver. One way of doing this, is to tag the
28 different subregions with different (integer) labels, and later
29 integrate over the specified regions. DOLFIN provides a class
30 :py:class:`MeshFunction <dolfin.cpp.MeshFunction>` which is useful for
31 these types of operations: instances of this class represent functions
32 over mesh entities (such as over cells or over facets). Mesh functions
33 can be read from file or, if explicit formulae for the domains are
34 known, they can be constructed by way of instances of the
35 :py:class:`SubDomain <dolfin.cpp.SubDomain>` class. The latter is the
36 case here, so we begin by defining the left, right, top and bottom
37 boundaries, and the interior obstacle domain using the
38 :py:class:`SubDomain <dolfin.cpp.SubDomain>` class and creating
39 instances of these classes.
40
41 .. code-block:: python
42
43 from dolfin import *
44
45 # Create classes for defining parts of the boundaries and the interior
46 # of the domain
47 class Left(SubDomain):
48 def inside(self, x, on_boundary):
49 return near(x[0], 0.0)
50
51 class Right(SubDomain):
52 def inside(self, x, on_boundary):
53 return near(x[0], 1.0)
54
55 class Bottom(SubDomain):
56 def inside(self, x, on_boundary):
57 return near(x[1], 0.0)
58
59 class Top(SubDomain):
60 def inside(self, x, on_boundary):
61 return near(x[1], 1.0)
62
63 class Obstacle(SubDomain):
64 def inside(self, x, on_boundary):
65 return (between(x[1], (0.5, 0.7)) and between(x[0], (0.2, 1.0)))
66
67 # Initialize sub-domain instances
68 left = Left()
69 top = Top()
70 right = Right()
71 bottom = Bottom()
72 obstacle = Obstacle()
73
74 Note that the DOLFIN functions :py:func:`near <dolfin.cpp.near>` and
75 :py:func:`between <dolfin.cpp.between>` provide robust ways of testing
76 whether a coordinate is (to within machine precision) close to a given
77 numerical value and in a range of values, respectively.
78
79 We next define a mesh of the domain:
80
81 .. code-block:: python
82
83 mesh = UnitSquareMesh(64, 64)
84
85 The above subdomains are defined with the sole purpose of populating
86 mesh functions. (For more complicated geometries, the mesh functions
87 would typically be provided by other means.) We define a :py:class:`MeshFunction
88 <dolfin.cpp.MeshFunction>` over the mesh cells to indicate which cells that correspond to
89 the different interior subregions :math:`\Omega_0` and
90 :math:`\Omega_1`. Those in the interior rectangle will be tagged by
91 `1`, while the remainder is tagged by `0`. We can set all the values
92 of a :py:class:`MeshFunction <dolfin.cpp.MeshFunction>` to a given
93 value using the :py:func:`set_all
94 <dolfin.cpp.MeshFunctionInt.set_all>` method. So, in order to
95 accomplish what we want, we can set all values to `0` first, and then
96 we can use the ``obstacle`` instance to mark the cells identified as
97 inside the obstacle region by `1` (thus overwriting the previous
98 value):
99
100 .. code-block:: python
101
102 # Initialize mesh function for interior domains
103 domains = MeshFunction("size_t", mesh, mesh.topology().dim())
104 domains.set_all(0)
105 obstacle.mark(domains, 1)
106
107
108 We can do the same for the boundaries using a :py:class:`MeshFunction
109 <dolfin.cpp.MeshFunction>` defined ove the topological dimension `
110 mesh.topology().dim()-1`. We first tag all the edges by ``0``, then
111 the edges on the left by ``1``, on the top by ``2``, on the right by
112 ``3`` and on the bottom by ``4``:
113
114 .. code-block:: python
115
116 # Initialize mesh function for boundary domains
117 boundaries = MeshFunction("size_t", mesh, mesh.topology().dim()-1)
118 boundaries.set_all(0)
119 left.mark(boundaries, 1)
120 top.mark(boundaries, 2)
121 right.mark(boundaries, 3)
122 bottom.mark(boundaries, 4)
123
124 Now that the geometry is defined and labeled, we can move on to
125 defining the input source functions:
126
127 .. code-block:: python
128
129 # Define input data
130 a0 = Constant(1.0)
131 a1 = Constant(0.01)
132 g_L = Expression("- 10*exp(- pow(x[1] - 0.5, 2))", degree=2)
133 g_R = Constant(1.0)
134 f = Constant(1.0)
135
136 Here, ``a0`` and ``a1`` represent the values of the coefficient
137 :math:`a` in the two regions of the domain, ``g_L`` and ``g_R``
138 represent the values of the Neumann boundary condition on the left and
139 right boundaries respectively, and ``f`` represents the body source.
140
141 We may now move on to define the variational equation. As usual, we
142 start by defining a finite element function space and basis functions
143 on this space:
144
145 .. code-block:: python
146
147 # Define function space and basis functions
148 V = FunctionSpace(mesh, "CG", 2)
149 u = TrialFunction(V)
150 v = TestFunction(V)
151
152 With this function space, we can define the essential (Dirichlet)
153 boundary conditions on the top and bottom boundaries. These boundaries
154 correspond to the facets tagged by ``2`` and ``4``, respectively, in
155 the ``boundaries`` facet function:
156
157 .. code-block:: python
158
159 # Define Dirichlet boundary conditions at top and bottom boundaries
160 bcs = [DirichletBC(V, 5.0, boundaries, 2),
161 DirichletBC(V, 0.0, boundaries, 4)]
162
163 DOLFIN predefines the "measures" ``dx``, ``ds`` and ``dS``
164 representing integration over cells, exterior facets (that is, facets
165 on the boundary) and interior facets, respectively. These measures can
166 take an additional integer argument. In fact, ``dx`` defaults to
167 ``dx(0)``, ``ds`` defaults to ``ds(0)``, and ``dS`` defaults to
168 ``dS(0)``. Integration over subregions can be specified by measures
169 with different integer labels as arguments. However, we also need to
170 map the geometry information stored in the mesh functions to these
171 measures. The easiest way of accomplishing this is to define new
172 measures with the mesh functions as additional input:
173
174 .. code-block:: python
175
176 # Define new measures associated with the interior domains and
177 # exterior boundaries
178 dx = Measure('dx', domain=mesh, subdomain_data=domains)
179 ds = Measure('ds', domain=mesh, subdomain_data=boundaries)
180
181 We can now define the variational forms corresponding to the
182 variational problem above using these measures and the tags for the
183 different subregions. For simplicity, we define the full form first,
184 and then extract the left- and right-hand sides using the UFL
185 functions :py:func:`lhs` and :py:func:`rhs` afterwards. We can then
186 :py:func:`solve <dolfin.fem.solving.solve>` as usual:
187
188 .. code-block:: python
189
190 # Define variational form
191 F = (inner(a0*grad(u), grad(v))*dx(0) + inner(a1*grad(u), grad(v))*dx(1)
192 - g_L*v*ds(1) - g_R*v*ds(3)
193 - f*v*dx(0) - f*v*dx(1))
194
195 # Separate left and right hand sides of equation
196 a, L = lhs(F), rhs(F)
197
198 # Solve problem
199 u = Function(V)
200 solve(a == L, u, bcs)
201
202 Now, we can also evaluate various integrals of the solution or derived
203 quantities of the solution over different regions, here are some
204 examples:
205
206 .. code-block:: python
207
208 # Evaluate integral of normal gradient over top boundary
209 n = FacetNormal(mesh)
210 m1 = dot(grad(u), n)*ds(2)
211 v1 = assemble(m1)
212 print("\int grad(u) * n ds(2) = ", v1)
213
214 # Evaluate integral of u over the obstacle
215 m2 = u*dx(1)
216 v2 = assemble(m2)
217 print("\int u dx(1) = ", v2)
218
219 We also plot the solution and its gradient:
220
221 .. code-block:: python
222
223 # Plot solution and gradient
224 plot(u, title="u")
225 plot(grad(u), title="Projected grad(u)")
226 interactive()
227
228
229 Complete code
230 -------------
231
232 .. literalinclude:: demo_subdomains-poisson.py
233 :start-after: # Begin demo