Debian Codegraph @

demo/documented/navier-stokes/cpp/documentation.rst

raw
1 .. Documentation for the incompressible Navier-Stokes demo from DOLFIN.
2
3 .. _demo_pde_navier_stokes_cpp_documentation:
4
5 Incompressible Navier-Stokes equations
6 ======================================
7
8 .. include:: ../common.txt
9
10 Implementation
11 --------------
12
13 The implementation is split in four files: three form files containing the
14 definition of the variational forms expressed in UFL and a C++ file
15 containing the actual solver.
16
17 Running this demo requires the files: :download:`main.cpp`,
18 :download:`TentativeVelocity.ufl`, :download:`VelocityUpdate.ufl`,
19 :download:`PressureUpdate.ufl` and :download:`CMakeLists.txt`.
20
21 UFL form files
22 ^^^^^^^^^^^^^^
23
24 The variational forms for the three steps of Chorin's method are
25 implemented in three separate UFL form files.
26
27 The variational problem for the tentative velocity is implemented as
28 follows:
29
30 .. code-block:: python
31
32 # Define function spaces (P2-P1)
33 V = VectorElement("Lagrange", triangle, 2)
34 Q = FiniteElement("Lagrange", triangle, 1)
35
36 # Define trial and test functions
37 u = TrialFunction(V)
38 v = TestFunction(V)
39
40 # Define coefficients
41 k = Constant(triangle)
42 u0 = Coefficient(V)
43 f = Coefficient(V)
44 nu = 0.01
45
46 # Define bilinear and linear forms
47 eq = (1/k)*inner(u - u0, v)*dx + inner(grad(u0)*u0, v)*dx + \
48 nu*inner(grad(u), grad(v))*dx - inner(f, v)*dx
49 a = lhs(eq)
50 L = rhs(eq)
51
52 The variational problem for the pressure update is implemented as
53 follows:
54
55 .. code-block:: python
56
57 # Define function spaces (P2-P1)
58 V = VectorElement("Lagrange", triangle, 2)
59 Q = FiniteElement("Lagrange", triangle, 1)
60
61 # Define trial and test functions
62 p = TrialFunction(Q)
63 q = TestFunction(Q)
64
65 # Define coefficients
66 k = Constant(triangle)
67 u1 = Coefficient(V)
68
69 # Define bilinear and linear forms
70 a = inner(grad(p), grad(q))*dx
71 L = -(1/k)*div(u1)*q*dx
72
73 The variational problem for the velocity update is implemented as
74 follows:
75
76 .. code-block:: python
77
78 # Define function spaces (P2-P1)
79 V = VectorElement("Lagrange", triangle, 2)
80 Q = FiniteElement("Lagrange", triangle, 1)
81
82 # Define trial and test functions
83 u = TrialFunction(V)
84 v = TestFunction(V)
85
86 # Define coefficients
87 k = Constant(triangle)
88 u1 = Coefficient(V)
89 p1 = Coefficient(Q)
90
91 # Define bilinear and linear forms
92 a = inner(u, v)*dx
93 L = inner(u1, v)*dx - k*inner(grad(p1), v)*dx
94
95 Before the form files can be used in the C++ program, they must be
96 compiled using FFC:
97
98 .. code-block:: sh
99
100 ffc -l dolfin TentativeVelocity.ufl
101 ffc -l dolfin VelocityUpdate.ufl
102 ffc -l dolfin PressureUpdate.ufl
103
104 Note the flag ``-l dolfin`` which tells FFC to generate
105 DOLFIN-specific wrappers that make it easy to access the generated
106 code from within DOLFIN.
107
108 C++ program
109 ^^^^^^^^^^^
110
111 In the C++ program, :download:`main.cpp`, we start by including
112 ``dolfin.h`` and the generated header files:
113
114 .. code-block:: c++
115
116 #include <dolfin.h>
117 #include "TentativeVelocity.h"
118 #include "PressureUpdate.h"
119 #include "VelocityUpdate.h"
120
121 To be able to use classes and functions from the DOLFIN namespace
122 directly, we write
123
124 .. code-block:: c++
125
126 using namespace dolfin;
127
128 Next, we define the subdomains that we will use to specify boundary
129 conditions. We do this by defining subclasses of
130 :cpp:class:`SubDomain` and overloading the function ``inside``:
131
132 .. code-block:: c++
133
134 // Define noslip domain
135 class NoslipDomain : public SubDomain
136 {
137 bool inside(const Array<double>& x, bool on_boundary) const
138 {
139 return (on_boundary &&
140 (x[0] < DOLFIN_EPS || x[1] < DOLFIN_EPS ||
141 (x[0] > 0.5 - DOLFIN_EPS && x[1] > 0.5 - DOLFIN_EPS)));
142 }
143 };
144
145 // Define inflow domain
146 class InflowDomain : public SubDomain
147 {
148 bool inside(const Array<double>& x, bool on_boundary) const
149 { return x[1] > 1.0 - DOLFIN_EPS; }
150 };
151
152 // Define inflow domain
153 class OutflowDomain : public SubDomain
154 {
155 bool inside(const Array<double>& x, bool on_boundary) const
156 { return x[0] > 1.0 - DOLFIN_EPS; }
157 };
158
159 We also define a subclass of :cpp:class:`Expression` which we will use
160 to specify the time-dependent boundary value for the pressure at the
161 inflow.
162
163 .. code-block:: c++
164
165 // Define pressure boundary value at inflow
166 class InflowPressure : public Expression
167 {
168 public:
169
170 // Constructor
171 InflowPressure() : t(0) {}
172
173 // Evaluate pressure at inflow
174 void eval(Array<double>& values, const Array<double>& x) const
175 { values[0] = sin(3.0*t); }
176
177 // Current time
178 double t;
179
180 };
181
182 Note that the member variable ``t`` is not automatically updated
183 during time-stepping, so we must remember to manually update the value
184 of the current time in each time step.
185
186 Once we have defined all classes we will use to write our program, we
187 start our C++ program by writing
188
189 .. code-block:: c++
190
191 int main()
192 {
193
194 For the parallel case, we turn off log messages from processes other than
195 the the root process to avoid excessive output:
196
197 .. code-block:: c++
198
199 // Print log messages only from the root process in parallel
200 parameters["std_out_all_processes"] = false;
201
202 We then load the mesh for the L-shaped domain from file:
203
204 .. code-block:: c++
205
206 // Load mesh from file
207 auto mesh = std::make_shared<Mesh>("../lshape.xml.gz");
208
209 We next define a pair of function spaces :math:`V` and :math:`Q` for
210 the velocity and pressure, and test and trial functions on these
211 spaces:
212
213 .. code-block:: c++
214
215 // Create function spaces
216 auto V = std::make_shared<VelocityUpdate::FunctionSpace>(mesh);
217 auto Q = std::make_shared<PressureUpdate::FunctionSpace>(mesh);
218
219 The time step and the length of the interval are defined by:
220
221 .. code-block:: c++
222
223 // Set parameter values
224 double dt = 0.01;
225 double T = 3;
226
227 We next define the time-dependent pressure boundary value, and zero
228 scalar and vector constants that will be used for boundary conditions
229 below.
230
231 .. code-block:: c++
232
233 // Define values for boundary conditions
234 auto p_in = std::make_shared<InflowPressure>();
235 auto zero = std::make_shared<Constant>(0.0);
236 auto zero_vector = std::make_shared<Constant>(0.0, 0.0);
237
238 Before we can define our boundary conditions, we also need to
239 instantiate the classes we defined above for the boundary subdomains:
240
241 .. code-block:: c++
242
243 // Define subdomains for boundary conditions
244 auto noslip_domain = std::make_shared<NoslipDomain>();
245 auto inflow_domain = std::make_shared<InflowDomain>();
246 auto outflow_domain = std::make_shared<OutflowDomain>() ;
247
248 We may now define the boundary conditions for the velocity and
249 pressure. We define one no-slip boundary condition for the velocity
250 and a pair of boundary conditions for the pressure at the inflow and
251 outflow boundaries:
252
253 .. code-block:: c++
254
255 // Define boundary conditions
256 DirichletBC noslip(V, zero_vector, noslip_domain);
257 DirichletBC inflow(Q, p_in, inflow_domain);
258 DirichletBC outflow(Q, zero, outflow_domain);
259 std::vector<DirichletBC*> bcu = {&noslip};
260 std::vector<DirichletBC*> bcp = {{&inflow, &outflow}};
261
262 We collect the boundary conditions in the two arrays ``bcu`` and
263 ``bcp`` so that we may easily iterate over them below when we apply
264 the boundary conditions. This makes it easy to add new boundary
265 conditions or use this demo program to solve the Navier-Stokes
266 equations on other geometries.
267
268 We next define the functions and the coefficients that will be used
269 below:
270
271 .. code-block:: c++
272
273 // Create functions
274 auto u0 = std::make_shared<Function>(V);
275 auto u1 = std::make_shared<Function>(V);
276 auto p1 = std::make_shared<Function>(Q);
277
278 // Create coefficients
279 auto k = std::make_shared<Constant>(dt);
280 auto f = std::make_shared<Constant>(0, 0);
281
282 The next step is now to define the variational problems for the three
283 steps of Chorin's method. We do this by instantiating the classes
284 generated from our UFL form files:
285
286 .. code-block:: c++
287
288 // Create forms
289 TentativeVelocity::BilinearForm a1(V, V);
290 TentativeVelocity::LinearForm L1(V);
291 PressureUpdate::BilinearForm a2(Q, Q);
292 PressureUpdate::LinearForm L2(Q);
293 VelocityUpdate::BilinearForm a3(V, V);
294 VelocityUpdate::LinearForm L3(V);
295
296 Since the forms depend on coefficients, we have to attach the
297 coefficients defined above to the appropriate forms:
298
299 .. code-block:: c++
300
301 // Set coefficients
302 a1.k = k; L1.k = k; L1.u0 = u0; L1.f = f;
303 L2.k = k; L2.u1 = u1;
304 L3.k = k; L3.u1 = u1; L3.p1 = p1;
305
306 Since the bilinear forms do not depend on any coefficients that change
307 during time-stepping, the corresponding matrices remain constant. We
308 may therefore assemble these before the time-stepping begins:
309
310 .. code-block:: c++
311
312 // Assemble matrices
313 Matrix A1, A2, A3;
314 assemble(A1, a1);
315 assemble(A2, a2);
316 assemble(A3, a3);
317
318 // Create vectors
319 Vector b1, b2, b3;
320
321 // Use amg preconditioner if available
322 const std::string prec(has_krylov_solver_preconditioner("amg") ? "amg" : "default");
323
324 We also created the vectors that will be used below to assemble
325 right-hand sides.
326
327 During time-stepping, we will store the solution in VTK format
328 (readable by MayaVi and Paraview). We therefore create a pair of files
329 that can be used to store the solution. Specifying the ``.pvd`` suffix
330 signals that the solution should be stored in VTK format:
331
332 .. code-block:: c++
333
334 // Create files for storing solution
335 File ufile("results/velocity.pvd");
336 File pfile("results/pressure.pvd");
337
338 The time-stepping loop is now implemented as follows:
339
340 .. code-block:: c++
341
342 // Time-stepping
343 double t = dt;
344 while (t < T + DOLFIN_EPS)
345 {
346 // Update pressure boundary condition
347 p_in->t = t;
348
349 We remember to update the current time for the time-dependent pressure
350 boundary value.
351
352 For each of the three steps of Chorin's method, we assemble the
353 right-hand side, apply boundary conditions, and solve a linear
354 system. Note the different use of preconditioners. Incomplete LU
355 factorization is used for the computation of the tentative velocity
356 and the velocity update, while algebraic multigrid is used for the
357 pressure equation if available:
358
359 .. code-block:: c++
360
361 // Compute tentative velocity step
362 begin("Computing tentative velocity");
363 assemble(b1, L1);
364 for (std::size_t i = 0; i < bcu.size(); i++)
365 bcu[i]->apply(A1, b1);
366 solve(A1, *u1->vector(), b1, "gmres", "default");
367 end();
368
369 // Pressure correction
370 begin("Computing pressure correction");
371 assemble(b2, L2);
372 for (std::size_t i = 0; i < bcp.size(); i++)
373 {
374 bcp[i]->apply(A2, b2);
375 bcp[i]->apply(*p1->vector());
376 }
377 solve(A2, *p1->vector(), b2, "bicgstab", prec);
378 end();
379
380 // Velocity correction
381 begin("Computing velocity correction");
382 assemble(b3, L3);
383 for (std::size_t i = 0; i < bcu.size(); i++)
384 bcu[i]->apply(A3, b3);
385 solve(A3, *u1->vector(), b3, "gmres", "default");
386 end();
387
388 Note the use of ``begin`` and ``end``; these improve the readability
389 of the output from the program by adding indentation to diagnostic
390 messages.
391
392 At the end of the time-stepping loop, we store the solution to file
393 and update values for the next time step:
394
395 .. code-block:: c++
396
397 // Save to file
398 ufile << *u1;
399 pfile << *p1;
400
401 // Move to next time step
402 *u0 = *u1;
403 t += dt;
404
405 return 0;
406 }
407
408
409
410 Complete code
411 -------------
412
413 Complete UFL files
414 ^^^^^^^^^^^^^^^^^^
415
416 .. literalinclude:: TentativeVelocity.ufl
417 :start-after: # Compile
418 :language: python
419
420
421 .. literalinclude:: VelocityUpdate.ufl
422 :start-after: # Compile
423 :language: python
424
425
426 .. literalinclude:: PressureUpdate.ufl
427 :start-after: # Compile
428 :language: python
429
430 Complete main file
431 ^^^^^^^^^^^^^^^^^^
432
433 .. literalinclude:: main.cpp
434 :start-after: // Begin demo
435 :language: c++