Debian Codegraph @

python/demo/documented/stokes-mini/documentation.rst

raw
1 .. Documentation for the Stokes mini demo from DOLFIN.
2
3 .. _demo_pde_stokes-mini_python_documentation:
4
5 Stokes equations with Mini elements
6 ===================================
7
8 This demo is implemented in a single Python file,
9 :download:`demo_stokes-mini.py`, which contains both the variational
10 form and the solver.
11
12 .. include:: ../common.txt
13
14 Implementation
15 --------------
16
17 This description goes through the implementation (in
18 :download:`demo_stokes-mini.py`) of a solver for the Stokes equation
19 step-by-step.
20
21 First, the :py:mod:`dolfin` module is imported:
22
23 .. code-block:: python
24
25 from dolfin import *
26
27 In this example, different boundary conditions are prescribed on
28 different parts of the boundaries. This information must be made
29 available to the solver. One way of doing this, is to tag the
30 different sub-regions with different (integer) labels. DOLFIN provides
31 a class :py:class:`MeshFunction <dolfin.cpp.mesh.MeshFunction>` which
32 is useful for these types of operations: instances of this class
33 represent a functions over mesh entities (such as over cells or over
34 facets). Mesh and mesh functions can be read from file in the
35 following way:
36
37 .. code-block:: python
38
39 # Load mesh and subdomains
40 mesh = Mesh("../dolfin_fine.xml.gz")
41 sub_domains = MeshFunction("size_t", mesh, "../dolfin_fine_subdomains.xml.gz")
42
43 Next, we define a :py:class:`FunctionSpace
44 <dolfin.functions.functionspace.FunctionSpace>` on Mini element
45 ``V * Q``. UFL object ``V = VectorElement(NodalEnrichedElement(P1, B))`` stands for
46 the vectorial Lagrange element of degree 1 enriched with the cubic
47 Bubble. ``V * Q`` defines the mixed element for velocity and pressure.
48
49 .. code-block:: python
50
51 # Build function spaces on Mini element
52 P1 = FiniteElement("Lagrange", mesh.ufl_cell(), 1)
53 B = FiniteElement("Bubble", mesh.ufl_cell(), mesh.topology().dim() + 1)
54 V = VectorElement(NodalEnrichedElement(P1, B))
55 Q = P1
56 W = FunctionSpace(mesh, V * Q)
57
58 Now that we have our mixed function space and marked subdomains
59 defining the boundaries, we define boundary conditions:
60
61 .. code-block:: python
62
63 # No-slip boundary condition for velocity
64 bc0 = DirichletBC(W.sub(0), (0, 0), sub_domains, 0)
65
66 # Inflow boundary condition for velocity
67 inflow = Expression(("-sin(x[1]*pi)", "0.0"), degree=2)
68 bc1 = DirichletBC(W.sub(0), inflow, sub_domains, 1)
69
70 # Collect boundary conditions
71 bcs = [bc0, bc1]
72
73 Here, we have given four arguments in the call of
74 :py:class:`DirichletBC <dolfin.cpp.fem.DirichletBC>`. The first
75 specifies the :py:class:`FunctionSpace
76 <dolfin.cpp.function.FunctionSpace>`. Since we have a
77 mixed function space, we write
78 ``W.sub(0)`` for the velocity componenet of the space,
79 and ``W.sub(1)`` for the pressure component of the space. The second
80 argument specifies the value on the Dirichlet boundary. The two last
81 arguments specify the marking of the subdomains; ``sub_domains`` contains
82 the subdomain markers and the number given as the last argument is the
83 subdomain index.
84
85 The bilinear and linear forms corresponding to the weak mixed
86 formulation of the Stokes equations are defined as follows:
87
88 .. code-block:: python
89
90 # Define variational problem
91 u, p = TrialFunctions(W)
92 v, q = TestFunctions(W)
93 f = Constant((0, 0))
94 a = (inner(grad(u), grad(v)) - div(v)*p - q*div(u))*dx
95 L = inner(f, v)*dx
96
97 To compute the solution we use the bilinear and linear forms, and the
98 boundary condition, but we also need to create a :py:class:`Function
99 <dolfin.cpp.function.Function>` to store the solution(s). The (full)
100 solution will be stored in ``w``, which we initialize using the mixed
101 function space ``W``. The actual
102 computation is performed by calling solve with the arguments ``a``,
103 ``L``, ``w`` and ``bcs``. The separate components ``u`` and ``p`` of
104 the solution can be extracted by calling the :py:meth:`split
105 <dolfin.functions.function.Function.split>` function. Here we use an
106 optional argument True in the split function to specify that we want a
107 deep copy. If no argument is given we will get a shallow copy. We want
108 a deep copy for further computations on the coefficient vectors.
109
110 .. code-block:: python
111
112 # Compute solution
113 w = Function(W)
114 solve(a == L, w, bcs)
115
116 # Split the mixed solution using deepcopy
117 # (needed for further computation on coefficient vector)
118 u, p = w.split(True)
119
120 We may be interested in the :math:`l^2` norms of u and p, they can be
121 calculated and printed by writing
122
123 .. code-block:: python
124
125 print("Norm of velocity coefficient vector: %.15g" % u.vector().norm("l2"))
126 print("Norm of pressure coefficient vector: %.15g" % p.vector().norm("l2"))
127
128 One can also split functions using shallow copies (which is enough
129 when we just plot the result) by writing
130
131 .. code-block:: python
132
133 # Split the mixed solution using a shallow copy
134 u, p = w.split()
135
136 Finally, we can store to file and plot the solutions.
137
138 .. code-block:: python
139
140 # Save solution in VTK format
141 ufile_pvd = File("velocity.pvd")
142 ufile_pvd << u
143 pfile_pvd = File("pressure.pvd")
144 pfile_pvd << p
145
146 # Plot solution
147 plot(u)
148 plot(p)
149 interactive()
150
151 Complete code
152 -------------
153
154 .. literalinclude:: demo_stokes-mini.py
155 :start-after: # Begin demo