From: wolf
-In step-18, we saw a need to write
+
+In @ref step_18 "step-18", we saw a need to write
output files in an intermediate format: in a parallel program, it doesn't scale
well if all processors participate in computing a result, and then only a
single processor generates the graphical output. Rather, each of them should
generate output for its share of the domain, and later on merge all these
output files into a single one.
-
+
+
Thus was the beginning of step-19: it is the program that reads a number of
files written in intermediate format, and merges and converts them into the
final format that one would like to use for visualization. It can also be used
@@ -18,9 +18,9 @@ for the following purpose: if you are unsure at the time of a computation what
graphics program you would like to use, write your results in intermediate
format; it can later be converted, using the present program, to any other
format you may want.
-
+
+
While this in itself was not interesting enough to make a tutorial program, we
have used the opportunity to introduce one class that has proven to be
extremely help- and useful in real application programs, but had not been
@@ -31,9 +31,9 @@ files. For example, one may want to specify the geometry, or specifics of the
equation to be solved, at run time. Other typical parameters are the number of
nonlinear iterations, the name of output files, or the names of input files
specifying material properties or boundary conditions.
-
+
+
Working with such parameter files is not rocket science. However, it is rather
tedious to write the parsers for such files, in particular if they should be
extensible, be able to group parameters into subsections, perform some error
@@ -45,9 +45,9 @@ will declare the parameters it expects (or call a function in the library that
declares a number of parameters for you), the
+
+
In order to perform these three steps, the
+
+
Once all parameters have been declared, parameters can be read, using the
+
+
A typical input file will look like this:
-
+
+
Finally, the application program can get the values of declared parameters back
by traversing the subsections of the parameter tree and using the
+
+
Using the
+
+
The rest of the story is probably best told by looking at the source of step-19
itself. Let us, however, end this introduction by pointing the reader at the
extensive class documentation of the
+
With all that above, here is first what we get if we just run the program
without any parameters at all:
-
That's a lot of output for such a little program, but then that's also a lot of
output formats that deal.II supports. You will realize that the output consists
of first entries in the top-level section (sorted alphabetically), then a
@@ -125,17 +122,16 @@ sorted list of subsections. Most of the parameters have been declared by the
+
+
Let us try to run this program on a set of input files generated by a modified
- step-18 run on 32 nodes of a
- cluster. The computation was rather big, with more
+@ref step_18 "step-18" run on 32 nodes of a
+cluster. The computation was rather big, with more
than 350,000 cells and some 1.2M unknowns. That makes for 32 rather big
intermediate files that we will try to merge using the present program. Here is
the list of files, totaling some 245MB of data:
-
So let's see what happens if we attempt to merge all these files into a single
one:
-
-If visualized, the output looks very much like that shown for step-18. But that's not quite as
+
+
+If visualized, the output looks very much like that shown for
+@ref step_18 "step-18". But that's not quite as
important for the moment, rather we are interested in showing how to use the
parameter file. To this end, remember that if no parameter file is given, or if
it is empty, all the default values listed above are used. However, whatever we
specify in the parameter file is used, unless overridden again by
parameters found later on the command line.
-
+
+
For example, let us use a simple parameter file named
We can then visualize this one file with gnuplot, obtaining something like
this:
-
-
-Introduction
-ParameterHandler
class then reads an input file with all these parameters, and the application
program can then get their values back from this class.
-ParameterHandler
offers
three sets of functions: first, the
ParameterHandler::declare_entry
function is used to declare the
@@ -64,9 +64,9 @@ parameter isn't later listed explicitly in the parameter file. In addition to
that, there are optional arguments indicating a pattern that a parameter has to
satisfy, such as being an integer (see the discussion above), and a help text
that might later give an explanation of what the parameter stands for.
-ParameterHandler::read_input
family of functions. There are
versions of this function that can read from a file stream, that take a file
@@ -76,12 +76,11 @@ declared before, and that the values of parameters satisfy the pattern that has
been given to describe the kind of values a parameter can have. Input that uses
undeclared parameters or values for parameters that do not conform to the
pattern are rejected by raising an exception.
-
-
+@endcode
Note that subsections can be nested.
-
+@code
set Output format = dx
set Output file = my_output_file.dx
@@ -91,12 +90,11 @@ subsection Application
set Color of output = blue
set Generate output = false
end
-
-ParameterHandler::get
and related functions. The
@@ -105,19 +103,19 @@ string, whereas ParameterHandler::get_integer
,
ParameterHandler::get_double
, and
ParameterHandler::get_bool
already convert them to the indicated
type.
-ParameterHandler
class therefore provides for a pretty
flexible mechanism to handle all sorts of moderately complex input files without
much effort on the side of the application programmer. We will use this to
provide all sorts of options to the step-19 program in order to convert from
intermediate file format to any other graphical file format.
-ParameterHandler
class for
more information on specific details of that class.
-Results
-
-
+@endcode
-
+@code
examples/step-19> ./step-19
Converter from deal.II intermediate format to other graphics formats.
@@ -114,10 +113,8 @@ subsection UCD output parameters
# creating program
set Write preamble = true
end
-
-DataOutBase
class, but there are also the dummy entries and
sections we have added in the declare_parameters()
function, along
with their default values and documentations.
-
-
+@endcode
-
+@code
examples/step-19> ls -l *d2
-rw-r--r-- 1 bangerth wheeler 7982085 Aug 12 10:11 solution-0005.0000-000.d2
-rw-r--r-- 1 bangerth wheeler 7888316 Aug 12 10:13 solution-0005.0000-001.d2
@@ -169,14 +165,11 @@ examples/step-19> ls -l *d2
-rw-r--r-- 1 bangerth wheeler 7682418 Aug 12 10:08 solution-0005.0000-029.d2
-rw-r--r-- 1 bangerth wheeler 7544141 Aug 12 10:05 solution-0005.0000-030.d2
-rw-r--r-- 1 bangerth wheeler 7348899 Aug 12 10:04 solution-0005.0000-031.d2
-
-
-
+@endcode
So in roughly two minutes we have merged 240MB of data. Counting reading and
writing, that averages a throughput of 3.8MB per second, not so bad.
-
+@code
examples/step-19> time ./step-19 solution-0005.0000-*.d2 -x gmv -o solution-0005.gmv
real 2m08.35s
user 1m26.61s
@@ -184,56 +177,48 @@ system 0m05.74s
examples/step-19> ls -l solution-0005.gmv
-rw-r--r-- 1 bangerth wheeler 240680494 Sep 9 11:53 solution-0005.gmv
-
-solution-0005.prm
that contains only one line:
-
-
+@endcode
If we run step-19 with it again, we obtain this (for simplicity, and because we
don't want to visualize 240MB of data anyway, we only convert the one, the
twelfth, intermediate file to gnuplot format):
-
+@code
set Output format = gnuplot
-
-
-
+@endcode
-
+@code
examples/step-19> ./step-19 solution-0005.0000-012.d2 -p solution-0005.prm -o solution-0005.gnuplot
examples/step-19> ls -l solution-0005.gnuplot
-rw-r--r-- 1 bangerth wheeler 20281669 Sep 9 12:15 solution-0005.gnuplot
-
-
-
+@endcode
If one wanted to, one could write comments into the file using the
same format as used above in the help text, i.e. everything on a line
following a hashmark (
+@code
set Output format = dx
set Output file = my_output_file.dx
@@ -243,17 +228,15 @@ subsection Dummy subsection
set Dummy color of output = blue
set Dummy generate output = false
end
-
-#
) is considered a comment.
-
+
+
If one runs step-19 with this input file, this is what is going to happen:
-
-
+@endcode
Ah, right: valid values for the iteration parameter needed to be within the
range [1...1000]. We would fix that, then go back to run the program with
correct parameters.
-
+@code
examples/step-19> ./step-19 solution-0005.0000-012.d2 -p solution-0005.prm
Line 4:
The entry value
@@ -262,17 +245,16 @@ Line 4:
Dummy iterations
does not match the given pattern
[Integer range 1...1000 (inclusive)]
-
-
+
+
This program should have given some insight into the input parameter file
handling that deal.II provides. The ParameterHandler
class has a
few more goodies beyond what has been shown in this program, for those who want
to use this class, it would be useful to read the documentation of that class
to get the full picture.
-
+ If we run the program as is, we get this output: -
+@code
examples/step-20> make run
============================ Remaking Makefile.dep
==============debug========= step-20.cc
@@ -16,20 +16,20 @@ Total number of cells: 85
Number of degrees of freedom: 208 (144+64)
10 CG Schur complement iterations to obtain convergence.
Errors: ||e_p||_L2 = 0.178055, ||e_u||_L2 = 0.0433435
-
+@endcode
+
The fact that the number of iterations is so small, of course, is due to good
(but expensive!) preconditioner we have developed. To get confidence in the
solution, let us take a look at it. The following three images show (from left
to right) the x-velocity, the y-velocity, and the pressure (click on the images
for larger versions):
-
+@image html step-20.u.png
+@image html step-20.v.png
+@image html step-20.p.png
+
+
-Let us start with the pressure: it is highest at the left and lowest at the right, so flow will be from left to right. In addition, though hardly visible in the graph, we have chosen the pressure field such that the flow left-right @@ -38,23 +38,23 @@ the x-velocity has to increase to get the flow through the narrow part, something that can easily be seen in the left image. The middle image represents inward flow in y-direction at the left end of the domain, and outward flow in y-directino at the right end of the domain. -
-
+
+
As an additional remark, note how the x-velocity in the left image is only
continuous in x-direction, whereas the y-velocity is continuous in
y-direction. The flow fields are discontinuous in the other directions. This
very obviously reflects the continuity properties of the Raviart-Thomas
elements, which are, in fact, only in the space H(div) and not in the space
-H1. Finally, the pressure field is completely discontinuous, but
+$H^1$. Finally, the pressure field is completely discontinuous, but
that should not surprise given that we have chosen FE_DGQ(0)
as
the finite element for that solution component.
-
+
The program offers two obvious places where playing and observing convergence
is in order: the degree of the finite elements used (passed to the constructor
of the MixedLaplaceProblem
class from main()
), and
@@ -62,10 +62,10 @@ the refinement level (determined in
MixedLaplaceProblem::make_grid_and_dofs
). What one can do is to
change these values and observe the errors computed later on in the course of
the program run.
-
-If one does this, one finds the following pattern for the L2 error + + +If one does this, one finds the following pattern for the $L_2$ error in the pressure variable:
O(h) | O(h2) | O(h3) | +O(h) | $O(h^2)$ | $O(h^3)$ |
-One can make the same experiment with the L2 error + + +One can make the same experiment with the $L_2$ error in the velocity variables:
O(h) | O(h2) | O(h3) | +O(h) | $O(h^2)$ | $O(h^3)$ |
+ Realistic flow computations for ground water or oil reservoir simulations will not use a constant permeability. Here's a first, rather simple way to change this situation: we use a permeability that decays very rapidly away from a @@ -182,16 +182,16 @@ homogenous and, while permeably to fluids, not overly so; on the other stone, the stone has cracked, or faulted, along one line, and the fluids flow much easier along this large crask. Here is how we could implement something like this: -
-template <int dim>
+@code
+template
void
-KInverse<dim>::value_list (const std::vector<Point<dim> > &points,
- std::vector<Tensor<2,dim> > &values) const
+KInverse::value_list (const std::vector > &points,
+ std::vector > &values) const
{
Assert (points.size() == values.size(),
ExcDimensionMismatch (points.size(), values.size()));
- for (unsigned int p=0; p<points.size(); ++p)
+ for (unsigned int p=0; p
+@endcode
Remember that the function returns the inverse of the permeability tensor.
-
-+ + With a significantly higher mesh resolution, we can visualize this, here with x- and y-velocity: -
- + +@image html step-20.u-wiggle.png +@image html step-20.v-wiggle.png + It is obvious how fluids flow essentially only along the middle line, and not anywhere else. - -+ + Another possibility would be to use a random permeability field. A simple way to achieve this would be to scatter a number of centers around the domain and then use a permeability field that is the sum of (negative) exponentials for @@ -233,64 +232,63 @@ each of these centers. Flow would then try to hop from one center of high permeability to the next one. This is an entirely unscientific attempt at describing a random medium, but one possibility to implement this behavior would look like this: -
-template <int dim>
-class KInverse : public TensorFunction<2,dim>
+@code
+template
+class KInverse : public TensorFunction<2,dim>
{
public:
KInverse ();
- virtual void value_list (const std::vector<Point<dim> > &points,
- std::vector<Tensor<2,dim> > &values) const;
+ virtual void value_list (const std::vector > &points,
+ std::vector > &values) const;
private:
- std::vector<Point<dim> > centers;
+ std::vector > centers;
};
-template <int dim>
-KInverse<dim>::KInverse ()
+template
+KInverse::KInverse ()
{
const unsigned int N = 40;
centers.resize (N);
- for (unsigned int i=0; i<N; ++i)
- for (unsigned int d=0; d<dim; ++d)
+ for (unsigned int i=0; i
void
-KInverse<dim>::value_list (const std::vector<Point<dim> > &points,
- std::vector<Tensor<2,dim> > &values) const
+KInverse::value_list (const std::vector > &points,
+ std::vector > &values) const
{
Assert (points.size() == values.size(),
ExcDimensionMismatch (points.size(), values.size()));
- for (unsigned int p=0; p<points.size(); ++p)
+ for (unsigned int p=0; p
+@endcode
+
-With a permeability field like this, we would get x-velocities and pressures as follows: -
- + +@image html step-20.u-random.png +@image html step-20.p-random.png + diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.p-random.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.p-random.png new file mode 100644 index 0000000000..af0677e009 Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.p-random.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.p.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.p.png new file mode 100644 index 0000000000..d6802ed739 Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.p.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.u-random.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.u-random.png new file mode 100644 index 0000000000..0492c4070a Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.u-random.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.u-wiggle.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.u-wiggle.png new file mode 100644 index 0000000000..e1b5bf19f6 Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.u-wiggle.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.u.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.u.png new file mode 100644 index 0000000000..5549c25bd0 Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.u.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.v-wiggle.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.v-wiggle.png new file mode 100644 index 0000000000..815483aa18 Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.v-wiggle.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.v.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.v.png new file mode 100644 index 0000000000..d3a23d305c Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/step-20.v.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/u-random.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/u-random.png deleted file mode 100644 index db18db9a05..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/u-random.png and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/u-wiggle.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/u-wiggle.png deleted file mode 100644 index 467f19d69a..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/u-wiggle.png and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/u.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/u.png deleted file mode 100644 index b4c112cb44..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/u.png and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/v-wiggle.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/v-wiggle.png deleted file mode 100644 index ead4ada5e4..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/v-wiggle.png and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/v.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/v.png deleted file mode 100644 index 6e6d395ab9..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/v.png and /dev/null differ