example-directories = $(shell echo $D/deal.II/examples/step-by-step/step-*)
example-names = $(notdir $(example-directories))
example-htmls = $(addsuffix .html,$(example-names))
+example-sgmls = $(addsuffix .sgml,$(example-names))
all: $(example-htmls)
@cat step-by-step.foot >> $@
+# Note: SGML support is very preliminary and not very functional at present!
+$(example-sgmls):
+ @echo ================== Assembling $@
+ @cat $(@:.sgml=.intro) >> $@
+ @echo "</sect2>" >> $@
+ @cat ../../../deal.II/examples/step-by-step/$(@:.sgml=)/$(@:.sgml=.cc) \
+ | $(PERL) program2html \
+ >> $@
+ @echo "</sect2>" >> $@
+ @cat $(@:.sgml=.results) >> $@
+ @echo "</sect2>" >> $@
+ @cat $D/deal.II/examples/step-by-step/$(@:.sgml=)/$(@:.sgml=.cc) \
+ | $(PERL) program2plain \
+ | $(PERL) -e '$$path="$D/deal.II/examples/step-by-step/$(@:.sgml=)/$(@:.sgml=.cc)"; \
+ $$path =~ s!/! /!g; \
+ while (<>) { s!PROGRAMPATH!$$path!g; print; };' \
+ >> $@
+ @echo "</sect2>" >> $@
+ @$(PERL) -pi -e 's!<a .*</a>!!gi; \
+ s!<h1>(.*)</h1>!<sect2><title>$$1</title>!gi; \
+ s!<p>!\n<para>!gi; \
+ s!</p>!</para>!gi; \
+ s!<pre><code>!<programlisting>!gi; \
+ s!</code></pre>!</programlisting>!gi; ' $@
+
+step-by-step.sgml: $(example-sgmls)
+ @echo ================== Concating $@
+ @cat step-by-step.header.sgml \
+ | perl -pi -e 's/TODAY/$(shell date)/;' \
+ > $@
+ @for step in $(example-names) ; do \
+ echo "<sect1><title>$$step</title>" >> $@ ; \
+ cat $$step.sgml >> $@ ; \
+ echo "</sect1>" >> $@ ; \
+ done
+ @echo "</chapter>" >> $@
+ @echo "</book>" >> $@
+ @rm $(example-sgmls)
+
+
clean:
-rm $(example-htmls)
<p>
<strong>Table of contents</strong>
</p>
- <ol>
+ <ul>
<li>
<p>
<a href="toc.html" target="body">Step-by-Step overview</a>
<a href="step-5.html" target="body">Step 5</a>
</p>
</li>
- </ol>
+
+ <li>
+ <p>
+ <a href="step-6.html" target="body">Step 6</a>
+ </p>
+ </li>
+ </ul>
<p>
<a href="../index.html" target="_top">Back to the tutorial index</a>
</p>
+
+ <p>
+ <a href="../../index.html" target="_top">Back to the deal.II homepage</a>
+ </p>
+
+
<hr>
+
<p>
<a href="mailto:deal@iwr.uni-heidelberg.de">Comments on the tutorial</a>
</p>
$comment_mode = 0;
$program_mode = 1;
$state = $comment_mode;
+
+print "<p>\n";
+
while (<>) {
# ignore cvs tag
next if m!/\*\s*\$Id:!;
# substitute special characters
+ s/&/&/g;
s/</</g;
s/>/>/g;
s/\t/ /g;
{
$state = $comment_mode;
print "</code></pre>\n";
+ print "\n";
+ print "<p>\n";
}
# if in comment mode and no comment line: toggle state.
# don't do so, if only a blank line
elsif (($state == $comment_mode) && !m!^\s*//! && !m!^\s*$!)
{
$state = $program_mode;
+ print "</p>\n";
+ print "\n";
print "<pre><code>\n";
}
{
m!\s*//\s*(.*)!;
print $1, "\n";
- print "<p>" if $1 =~ m!^\s*$!;
+ print "</p>\n\n<p>" if $1 =~ m!^\s*$!;
}
else
{
$_ = <>;
}
-print "<a name=\"PlainProg\"></a>\n";
-print "<h1> The plain program</h1>\n";
+print <<END;
+<a name=\"PlainProg\"></a>
+<h1> The plain program</h1>
-print "(The program can be found at <i>PROGRAMPATH</i>.)\n <p>\n";
+<p>
+(The program can be found at <i>PROGRAMPATH</i>.)
+</p>
-print "<pre><code>\n";
+<p>
+<pre><code>
+END
while (<>) {
next if m!^\s*//!;
# substitute special characters
+ s/&/&/g;
s/</</g;
s/>/>/g;
s/\t/ /g;
print " $_";
}
-print "</code></pre>";
+print "</code></pre>\n</p>\n\n";
<a name="Intro"></a>
<h1>Introduction</h1>
+<p>
In this first example, we do not so very much, but show two
techniques: what is the syntax to generate triangulation objects, and
some elements of simple loops over all cells. We create two grids, one
latter is certainly not very useful and is certainly only rarely used
in numerical analysis, but looks nice and illustrates how loops over
cells are written and some of the things you can do with cells.
+</p>
<a name="Results"></a>
<h1>Results</h1>
+<p>
The program has, after having been run, produced two grids, which look
like this:
-<p>
+
<TABLE WIDTH="60%">
<tr>
<td>
</td>
</tr>
</table>
-<p>
+
The left one, well, is not very exciting. The right one is - at least
- unconventional.
+</p>
<a name="Intro"></a>
<h1>Introduction</h1>
+<p>
After we have created a grid in the previous example, we now show how
we can associate a degree of freedom with each vertex of the
triangulation. This is a rather simple task, since the library does
in a certain sense, and we will use the algorithm of Cuthill and McKee
to do so. The results are written to a file and visualized using
GNUPLOT.
+</p>
<a name="Results"></a>
<h1>Results</h1>
+<p>
The program has, after having been run, produced two sparsity
patterns. We can visualize them using GNUPLOT:
-<pre>
-<code>
+<pre><code>
set data style points
plot "sparsity_pattern.1"
-</code>
-</pre>
+</code></pre>
+</p>
<p>
The results then look like this (every cross denotes an entry which
indicated positions in the matrix tell us which shape functions can
and which can't couple, if the equation is a local, i.e. differential
one):
-<p>
<TABLE WIDTH="60%">
<tr>
<td>
</td>
</tr>
</table>
-<p>
+</p>
+<p>
The different regions in the left picture represent the degrees of
freedom on the different refinement levels of the triangulation. As
can be seen in the right picture, the sparsity pattern is much better
clustered around the main diagonal of the matrix after
renumbering. Although this might not be apparent, the number of
nonzero entries is the same in both pictures, of course.
+</p>
<p>
-
A common observation is that the more refined the grid is, the better
the clustering around the diagonal will get.
+</p>
+
<a name="Intro"></a>
<h1>Introduction</h1>
+<p>
This is the first example where we actually use finite elements. We
will solve a simple version of Laplace's equation witht zero boundary
values, but a nonzero right hand side. This example is still quite
<li> solving the linear system of equations;
<li> writing results to disk.
</ul>
+</p>
<a name="Results"></a>
<h1>Results</h1>
+<p>
The output of the program looks as follows:
-<pre>
-<code>
+<pre><code>
Number of active cells: 1024
Total number of cells: 1365
Number of degrees of freedom: 1089
DEAL:cg::Starting value 0.121094
DEAL:cg::Starting value 0.323075
DEAL:cg::Convergence step 47 value 5.33692e-13
-</code>
-</pre>
+</code></pre>
The first three lines is what we wrote to <code>cout</code>. The last
three lines were generated without our interaction by the CG
show in the next program how to suppress this output, which is
sometimes useful for debugging purposes, but often clutters up the
screen display.
+</p>
<p>
-
Apart from the output shown above, the program generated the file
<code>solution.gpl</code>, which is in GNUPLOT format. It can be
viewed as follows: invoke GNUPLOT and enter the following sequence of
commands at its prompt:
-<pre>
-<code>
+<pre><code>
gnuplot> set data style lines
gnuplot> splot "solution.gpl"
-</code>
-</pre>
+</code></pre>
This produces the picture of the solution below left. Alternatively,
you can order GNUPLOT to do some hidden line removal by the command
-<pre>
-<code>
+<pre><code>
gnuplot> set hidden3d
-</code>
-</pre>
+</code></pre>
to get the result at the right:
+</p>
+
<p>
<TABLE WIDTH="100%">
<tr>
</td>
</tr>
</table>
-<p>
+</p>
+
<a name="Intro"></a>
<h1>Introduction</h1>
+<p>
<acronym>deal.II</acronym> has a unique feature which we call
``dimension independent programming''. You may have noticed in the
previous examples that many classes had a number in angle brackets
programming and leads to a nuisance to keep the two function in synch
(at best) or difficult to find errors if the two versions get out of
synch (at worst; this would probably the more common case).
+</p>
-<p>
+<p>
Such obstacles can be circumvented by using some template magic as
provided by the C++ language: templatized classes and functions are
not really classes or functions but only a pattern depending on an
GridGenerator::hyper_cube (triangulation, -1, 1);
};
</code></pre>
+</p>
+<p>
At the point where the compiler sees this function, it does not know
anything about the value of ``dim'', by now there is a whole zoo of
functions make_grid, one for every possible valueof ``dim''. But since
the compiler can't know which might be used, it can not compile the
function.
+</p>
<p>
-
However, if later down a function would use the following sequence,
<pre><code>
Triangulation<2> triangulation;
GridGenerator::hyper_cube (triangulation, -1, 1);
};
</code></pre>
+</p>
<p>
-
However, it is worth to note that the function
<code>GridGenerator::hyper_cube</code> depends on the dimension as
well, so in this case, the compiler will call the function
<code>GridGenerator::hyper_cube<2></code> while if dim were 3,
it would call <code>GridGenerator::hyper_cube<3></code> which
might be (and actually is) a totally unrelated function.
-
+</p>
<p>
-
The same can be made with member variables. Consider the following
function, which might in turn call the above one:
<pre><code>
...
};
</code></pre>
-
This function has a member variable of type
<code>DoFHandler<dim></code> the size of which may (and does)
depend on the dimension we are working in. Again, the compiler can't
times for different dimensions, it will compile it several times, each
time calling the right ``make_grid'' function and reserving the right
amount of memory for the member variable.
+</p>
<p>
-
The <acronym>deal.II</acronym> library is build around this concept
and that allows you to program in way that will not need to
distinguish between the space dimensions. It should be noted that in
it knows the value of ``dim'' at the time of compilation and will
therefore be able to optimize the ``if'' statement along with the
unused branch.
+</p>
<p>
-
In this example program, we will show how to program dimension
independently (which in fact is even simpler than if you had to take
care about the dimension) and we will extend the Laplace problem of
the last example to a program that runs in two and three space
dimensions at the same time. Other extensions are the use of a
non-constant right hand side function and of non-zero boundary values.
+</p>
<a name="Results"></a>
<h1>Results</h1>
+<p>
The output of the program looks as follows (the number of iterations
may vary by one or two, depending on your computer, since this is
often dependent on the round-off accuracy of floating point
operations, which differs between micro-processors):
-<pre>
-<code>
+<pre><code>
Solving problem in 2 space dimensions.
Number of active cells: 256
Total number of cells: 341
Total number of cells: 4681
Number of degrees of freedom: 4913
29 CG iterations needed to obtain convergence.
-</code>
-</pre>
+</code></pre>
It is obvious that in three spatial dimensions the number of cells and
therefore also the number of degrees of freedom is
much higher. What cannot be seen here, is that besides this higher
dimensions. Together, this leads to a much higher numerical effort for
solving the system of equation, which you can feel when you actually
run the program.
+</p>
<p>
-
The program produces two files: <code>solution-2d.gmv</code> and
<code>solution-3d.gmv</code>, which can be viewed using the program
GMV (in case you do not have that program, you can easily change the
output format in the program to something which you can view more
easily). From the two-dimensional output, we have produced the
following two pictures:
+</p>
<p>
<TABLE WIDTH="100%">
</td>
</tr>
</table>
-<p>
+</p>
+<p>
The left one shows the solution of the problem under consideration as
a 3D plot. As can be seen, the solution is almost flat in the interior
of the domain and has a higher curvature near the boundary. This, of
rising sharply when approaching the boundaries of the domain; the
maximal values of the right hand side function are at the corners of
the domain, where also the solution is moving most rapidly.
-
It is also nice to see that the solution follows the desired quadratic
boundary values along the boundaries of the domain.
+</p>
<p>
-
The right picture shows the two dimensional grid, colorized by the
values of the solution function. This is not very exciting, but the
colors are nice.
-
-<p>
+</p>
+<p>
In three spatial dimensions, visualization is a bit more difficult. To
the left, you can see the solution at three of the six outer faces of
the cube in which we solved the equation, and on a plane through the
origin. On some of the planes, the cut through the grid is also shown.
+</p>
<p>
<TABLE WIDTH="100%">
</td>
</tr>
</table>
-<p>
+</p>
+<p>
The right picture shows the three dimensional grid, colorized by the
solutions values. 3D grids are difficult to visualize, which can be
seen here already, even though the grid is not locally refined.
-
+</p>
<a name="Intro"></a>
<h1>Introduction</h1>
+<p>
This example does not show revolutionary new things, but it shows many
small improvements over the previous examples, and also many small
things that can usually be found in finite element programs. Among
preconditioned iterative solvers for the linear systems of
equations.
</ul>
+</p>
<a name="Results"></a>
<h1>Results</h1>
-
+<p>
The output of the program looks as follows:
-<pre>
-<code>
+<pre><code>
Cycle 0:
Number of active cells: 20
Total number of cells: 20
Number of degrees of freedom: 20609
200 CG iterations needed to obtain convergence.
--------------------------------------------------------
-An error occurred in line <206> of file <step-5.cc> in function
- void Coefficient<2>::value_list<2>(const class vector<Point<2>,__default_alloc_template<false,0> > &, class vector<double,__default_alloc_template<false,0> > &, unsigned int = 0) const
+An error occurred in line <206> of file <step-5.cc> in function
+ void Coefficient<2>::value_list<2>(const class vector<Point<2>,__default_alloc_template<false,0> > &, class vector<double,__default_alloc_template<false,0> > &, unsigned int = 0) const
The violated condition was:
values.size() == n_points
The name and call sequence of the exception was:
Additional Information:
The vector has size 1 but should have 2 elements.
--------------------------------------------------------
-</code>
-</pre>
+</code></pre>
+</p>
+<p>
In each cycle, the number of cells quadruples and the number of CG
iterations roughly doubles. The exception is only raised if the
respective lines at the end of the programs are un-commented.
+</p>
<p>
-
In each cycle, the program writes one output graphic file in EPS
format. They are depicted in the following:
+</p>
<p>
<TABLE WIDTH="100%">
<IMG SRC="step-5.data/solution-5.jpg" ALT="solution-5" WIDTH="300">
</td>
</tr>
-
</table>
-<p>
+</p>
+<p>
Due to the variable coefficient (the curvature there is reduced by the
same factor by which the coefficient is increased), the top region of
the solution is flattened. The gradient of the solution is
discontinuous there, although this is not very clearly visible in the
pictures above. We will look at this in more detail in the next
example.
+</p>
+
+
--- /dev/null
+<a name="Intro"></a>
+<h1>Introduction</h1>
+
+<p>
+</p>
--- /dev/null
+<a name="Results"></a>
+<h1>Results</h1>
+
+<p>
+The output of the program looks as follows:
+<pre><code>
+Cycle 0:
+ Number of active cells: 20
+Cycle 1:
+ Number of active cells: 44
+Cycle 2:
+ Number of active cells: 86
+Cycle 3:
+ Number of active cells: 164
+Cycle 4:
+ Number of active cells: 344
+Cycle 5:
+ Number of active cells: 656
+Cycle 6:
+ Number of active cells: 1364
+Cycle 7:
+ Number of active cells: 2684
+</code></pre>
+</p>
+
+<p>
+As intended, the number of cells roughly doubles in each cycle. The
+final solution, as written by the program, looks as follows:
+</p>
+
+<p>
+<IMG SRC="step-6.data/final-solution.jpg" ALT="final-solution" WIDTH="300">
+</p>
+
+<p>
+In each cycle, the program furthermore writes the grid in EPS
+format. These are depicted in the following:
+</p>
+
+<p>
+<TABLE WIDTH="100%">
+<tr>
+<td>
+<IMG SRC="step-6.data/grid-0.jpg" ALT="grid-0" WIDTH="300">
+</td>
+<td>
+<IMG SRC="step-6.data/grid-1.jpg" ALT="grid-1" WIDTH="300">
+</td>
+</tr>
+
+<tr>
+<td>
+<IMG SRC="step-6.data/grid-2.jpg" ALT="grid-2" WIDTH="300">
+</td>
+<td>
+<IMG SRC="step-6.data/grid-3.jpg" ALT="grid-3" WIDTH="300">
+</td>
+</tr>
+
+<tr>
+<td>
+<IMG SRC="step-6.data/grid-4.jpg" ALT="grid-4" WIDTH="300">
+</td>
+<td>
+<IMG SRC="step-6.data/grid-5.jpg" ALT="grid-5" WIDTH="300">
+</td>
+</tr>
+</table>
+</p>
+
+<tr>
+<td>
+<IMG SRC="step-6.data/grid-6.jpg" ALT="grid-6" WIDTH="300">
+</td>
+<td>
+<IMG SRC="step-6.data/grid-7.jpg" ALT="grid-7" WIDTH="300">
+</td>
+</tr>
+</table>
+</p>
+
+<p>
+It is clearly visible that the region where the solution has a kink,
+i.e. the circle at radial distance 0.5 from the center, is
+refined most. Furthermore, the central region where the solution is
+very smooth and almost flat, is almost not refined at all, but this
+results from the fact that we did not take into account that the
+coefficient is large there. The region outside is refined rather
+randomly, since the second derivative is constant there and refinement
+is therefore mostly based on the size of the cells and their deviation
+from the optimal square.
+</p>
+
+
+
<h1>Step-by-Step Examples</h1>
<p>
-In this chapter, we present a collecting of small programs, each more
+In this chapter, we present a collection of small programs, each more
or less built atop of the previous one, which demonstrate various
aspects of the library. The general layout of each such example is as
follows:
<ol>
<li> A brief description of what the program does and what is new
- compared to the previous programs.
+ compared to the previous programs.
<li> The program, in commented form.
<li> The output of the program, with some comments.
<li> Since the program itself usually is a little bit unreadable
- with all the comments intertwingled, we present the program again,
- with all comments stripped off, to allow getting an overview of it.
+ with all the comments intertwingled, we present the program again,
+ with all comments stripped off, to allow getting an overview of it.
</ol>
</p>
+
+<p>
+The programs themselves can be found at a path which is indicated at
+the beginning of the last section of each example. You can compile
+them by typing ``make'' in the respective directory, and run them
+using ``make run''. The latter command also compiles the program if
+that has not already been done.
+</p>
+
+
<p>
At present, the following programs exist:
</p>
the elliptic operator. Preconditioning of the CG solver for the
linear system of equations.
</dd>
+
+ <dt><a href="step-6.html">Step 6</a></dt>
+ <dd><strong>What's new:</strong> Adaptive local
+ refinement. Handling of hanging nodes.
+ </dd>
</dl>
<!-- Page Foot -->