Debian Codegraph @

python/demo/documented/periodic/documentation.rst

raw
1 .. Documentation for the Periodic Poisson demo from DOLFIN.
2
3 .. _demo_pde_periodic_python_documentation:
4
5
6 Poisson equation with periodic boundary conditions
7 ==================================================
8
9 This demo is implemented in a single Python file,
10 :download:`demo_periodic.py`, which contains both the variational form
11 and the solver.
12
13 .. include:: ../common.txt
14
15
16 Implementation
17 --------------
18
19 This demo is implemented in a single file,
20 :download:`demo_periodic.py`.
21
22 First, the :py:mod:`dolfin` module is imported
23
24 .. code-block:: python
25
26 from dolfin import *
27
28 A subclass of :py:class:`Expression <dolfin.cpp.function.Expression>`,
29 ``Source``, is created for the source term ``f``. The function
30 :py:meth:`eval() <dolfin.cpp.fem.BasisFunction.eval>` returns values
31 for a function at the given point ``x``.
32
33 .. code-block:: python
34
35 # Source term
36 class Source(Expression):
37 def eval(self, values, x):
38 dx = x[0] - 0.5
39 dy = x[1] - 0.5
40 values[0] = x[0]*sin(5.0*DOLFIN_PI*x[1]) \
41 + 1.0*exp(-(dx*dx + dy*dy)/0.02)
42
43 To define the boundaries, we create subclasses of the class
44 :py:class:`SubDomain <dolfin.cpp.mesh.SubDomain>`. A simple Python
45 function, returning a boolean, can be used to define the subdomain for
46 the Dirichlet boundary condition (:math:`\Gamma_D`). The function
47 should return True for those points inside the subdomain and False for
48 the points outside. In our case, we want to say that the points
49 :math:`(x, y)` such that :math:`y = 0` or :math:`y = 1` are inside of
50 :math:`\Gamma_D`. (Note that because of round-off errors, it is often
51 wise to instead specify :math:`y < \epsilon` or :math:`y > 1 -
52 \epsilon` where :math:`\epsilon` is a small number (such as machine
53 precision).)
54
55 .. code-block:: python
56
57 # Sub domain for Dirichlet boundary condition
58 class DirichletBoundary(SubDomain):
59 def inside(self, x, on_boundary):
60 return bool((x[1] < DOLFIN_EPS or x[1] > (1.0 - DOLFIN_EPS)) \
61 and on_boundary)
62
63 The periodic boundary is defined by PeriodicBoundary and we define
64 what is inside the boundary in the same way as in
65 DirichletBoundary. The function ``map`` maps a coordinate ``x`` in
66 domain ``H`` to a coordinate ``y`` in the domain ``G``, it is used for
67 periodic boundary conditions, so that the right boundary of the domain
68 is mapped to the left boundary. When the class is defined, we create
69 the boundary by making an instance of the class.
70
71 .. code-block:: python
72
73 # Sub domain for Periodic boundary condition
74 class PeriodicBoundary(SubDomain):
75
76 # Left boundary is "target domain" G
77 def inside(self, x, on_boundary):
78 return bool(x[0] < DOLFIN_EPS and x[0] > -DOLFIN_EPS and on_boundary)
79
80 # Map right boundary (H) to left boundary (G)
81 def map(self, x, y):
82 y[0] = x[0] - 1.0
83 y[1] = x[1]
84
85 A 2D mesh is created using the built-in class
86 :py:class:`UnitSquareMesh <dolfin.cpp.mesh.UnitSquareMesh>`, and we
87 define a finite element function space relative to this space. Notice
88 the fourth argument of :py:class:`FunctionSpace
89 <dolfin.cpp.function.FunctionSpace>`. It specifies that all functions
90 in ``V`` have periodic boundaries defined by ``pbc``. Also notice that
91 in order for periodic boundary conditions to work correctly it is necessary
92 that the mesh nodes on the periodic boundaries match up. This is automatically
93 satisfied for :py:class:`UnitSquareMesh <dolfin.cpp.mesh.UnitSquareMesh>`
94 but may require extra care with more general meshes (especially externally
95 generated ones).
96
97 .. code-block:: python
98
99 # Create mesh and finite element
100 mesh = UnitSquareMesh(32, 32)
101 V = FunctionSpace(mesh, "CG", 1, constrained_domain=PeriodicBoundary())
102
103 Now, we create the Dirichlet boundary condition using the class
104 :py:class:`DirichletBC <dolfin.cpp.fem.DirichletBC>`. A
105 :py:class:`DirichletBC <:py:class:`DirichletBC
106 <dolfin.cpp.fem.DirichletBC>` takes three arguments: the function
107 space the boundary condition applies to, the value of the boundary
108 condition, and the part of the boundary on which the condition
109 applies. In our example, the function space is ``V``, the value of the
110 boundary condition (0.0) can be represented using a
111 :py:class:`Constant <dolfin.functions.constant.Constant>` and the
112 Dirichlet boundary is defined by the class DirichletBoundary. The
113 definition of the Dirichlet boundary condition then looks as follows:
114
115 .. code-block:: python
116
117 # Create Dirichlet boundary condition
118 u0 = Constant(0.0)
119 dbc = DirichletBoundary()
120 bc0 = DirichletBC(V, u0, dbc)
121
122 When all boundary conditions are defined and created we can collect
123 them in a list:
124
125 .. code-block:: python
126
127 # Collect boundary conditions
128 bcs = [bc0]
129
130 Here only the Dirichlet boundary condition is put into the list
131 because the periodic boundary condition is already applied in the
132 definition of the function space. Next, we want to express the
133 variational problem. First, we need to specify the trial function u
134 and the test function v, both living in the function space V. We do
135 this by defining a :py:class:`TrialFunction
136 <dolfin.functions.function.TrialFunction>` and a
137 :py:class:`TestFunction <dolfin.functions.function.TestFunction>` on
138 the previously defined :py:class:`FunctionSpace
139 <dolfin.cpp.function.FunctionSpace>` V. The source function f is
140 created by making an instance of Source. With these ingredients, we
141 can write down the bilinear form a and the linear form L (using UFL
142 operators). In summary, this reads
143
144 .. code-block:: python
145
146 # Define variational problem
147 u = TrialFunction(V)
148 v = TestFunction(V)
149 f = Source(degree=1)
150 a = dot(grad(u), grad(v))*dx
151 L = f*v*dx
152
153 Now, we have specified the variational form and can consider the solution of the variational problem. First, we need to define a :py:class:`Function <dolfin.cpp.function.Function>` u to represent the solution. (Upon initialization, it is simply set to the zero function.) A Function represents a function living in a finite element function space. Next, we can call the solve function with the arguments a == L, u and bcs as follows:
154
155 .. code-block:: python
156
157 # Compute solution
158 u = Function(V)
159 solve(a == L, u, bcs)
160
161 The function u will be modified during the call to solve. The default settings for solving a variational problem have been used. However, the solution process can be controlled in much more detail if desired.
162
163 A :py:class:`Function <dolfin.cpp.function.Function>` can be manipulated in various ways, in particular, it can be plotted and saved to file. Here, we output the solution to a VTK file (using the suffix .pvd) for later visualization and also plot it using the plot command:
164
165 .. code-block:: python
166
167 # Save solution to file
168 file = File("periodic.pvd")
169 file << u
170
171 # Plot solution
172 plot(u, interactive=True)
173
174 Complete code
175 -------------
176
177 .. literalinclude:: demo_periodic.py
178 :start-after: # Begin demo