From: wolf Date: Tue, 28 Mar 2006 15:05:37 +0000 (+0000) Subject: More doxygenization X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4c6c27dd8663c766fd9ca30ce732d236b25f1401;p=dealii-svn.git More doxygenization git-svn-id: https://svn.dealii.org/trunk@12719 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/intro.html b/deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/intro.dox similarity index 96% rename from deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/intro.html rename to deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/intro.dox index bb0e891cb2..9770ba1df4 100644 --- a/deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/intro.html +++ b/deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/intro.dox @@ -1,16 +1,16 @@

Introduction

-

-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 ParameterHandler class then reads an input file with all these parameters, and the application program can then get their values back from this class. -

-

+ + In order to perform these three steps, the 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. -

-

+ + Once all parameters have been declared, parameters can be read, using the 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. -

-

+ + A typical input file will look like this: - -

+@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
-
- +@endcode Note that subsections can be nested. -

-

+ + Finally, the application program can get the values of declared parameters back by traversing the subsections of the parameter tree and using the 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. -

-

+ + Using the 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. -

-

+ + 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 ParameterHandler class for more information on specific details of that class. -

+ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/results.html b/deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/results.dox similarity index 94% rename from deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/results.html rename to deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/results.dox index b84ee19071..b13a41c982 100644 --- a/deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/results.html +++ b/deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/results.dox @@ -1,11 +1,10 @@

Results

-

+ With all that above, here is first what we get if we just run the program without any parameters at all: - -

+@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
-
- +@endcode -

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 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. -

-

+ + 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: - -

+@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 let's see what happens if we attempt to merge all these files into a single one: - -

+@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
-
- +@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. -

-

-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 solution-0005.prm that contains only one line: - -

+@code
 set Output format  = gnuplot
-
- +@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
 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 -

We can then visualize this one file with gnuplot, obtaining something like this: -

- -

+@image html step-19.solution-0005.png + That's not particularly exciting, but the file we're looking at has only one 32nd of the entire domain anyway, so we can't expect much. In more complicated situations, we would use parameter files that set more of the values to non-default values. A file for which this is the case could look like this, generating output for the OpenDX visualization program: - -
+@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
-
-
+@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 (#) is considered a comment. -

-

+ + If one runs step-19 with this input file, this is what is going to happen: - -

+@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)]
-
- +@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. -

-

+ + 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. -

+ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/solution-0005.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/step-19.solution-0005.png similarity index 100% rename from deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/solution-0005.png rename to deal.II/doc/tutorial/chapter-2.step-by-step/step-19.data/step-19.solution-0005.png diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/p-random.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/p-random.png deleted file mode 100644 index 39e7be3682..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/p-random.png and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/p.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/p.png deleted file mode 100644 index 6b9bdead3e..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/p.png and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/results.html b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/results.dox similarity index 76% rename from deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/results.html rename to deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/results.dox index adadfc1961..b2ca86bf3a 100644 --- a/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/results.html +++ b/deal.II/doc/tutorial/chapter-2.step-by-step/step-20.data/results.dox @@ -3,9 +3,9 @@

Output of the program and graphical visualization

-

+ 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. -

+

Convergence

-

+ 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: @@ -109,16 +109,16 @@ in the pressure variable: - +
O(h) O(h2) O(h3) O(h) $O(h^2)$ $O(h^3)$
The theoretically expected convergence orders are very nicely reflected by the experimentally observed ones indicated in the last row of the table. -

-

-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: @@ -162,17 +162,17 @@ in the velocity variables: - +
O(h) O(h2) O(h3) O(h) $O(h^2)$ $O(h^3)$
The result concerning the convergence order is the same here. -

+

Possibilities for extensions

-

+ 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