From: wolf Date: Tue, 28 Mar 2006 14:45:58 +0000 (+0000) Subject: Doxygenize X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=189acbc78d0754deef3b1817f69fd05aaf9d060a;p=dealii-svn.git Doxygenize git-svn-id: https://svn.dealii.org/trunk@12716 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/error.gif b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/error.gif deleted file mode 100644 index 8bcae42c72..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/error.gif and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/intro.html b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/intro.dox similarity index 95% rename from deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/intro.html rename to deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/intro.dox index cd167e2b26..7362602221 100644 --- a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/intro.html +++ b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/intro.dox @@ -3,7 +3,7 @@

Background and purpose

-

+ In this example program, we will not so much be concerned with describing new ways how to use deal.II and its facilities, but rather with presenting methods of writing modular and extensible finite @@ -21,13 +21,13 @@ program:

  • a wave equation solver: 21,020 lines of code. (The library proper - without example programs and -test suite - has slightly more than 150,000 lines of code.) In -the opinion of the author of this example program, the sizes of these +test suite - has slightly more than 150,000 lines of code as of spring 2002.) +In the opinion of the author of this example program, the sizes of these applications are at the edge of what one person, even an experienced programmer, can manage. -

    -

    + + The numbers above make one thing rather clear: monolithic programs that are not broken up into smaller, mostly independent pieces have no way of surviving, since even the author will quickly lose the overview of @@ -39,9 +39,9 @@ absolute prerequisite if more than one person is developing a program, since otherwise confusion will quickly prevail as one developer would need to know if another changed something about the internals of a different module if they were not cleanly separated. -

    -

    + + In previous examples, you have seen how the library itself is broken up into several complexes each building atop the underying ones, but relatively independent of the other ones: @@ -60,10 +60,10 @@ course the following ``tool'' modules:

  • output in various graphical formats;
  • linear algebra classes. -

    -

    + + The goal of this program is now to give an example of how a relatively simple finite element program could be structured such that we end up with a set of modules that are as independent of each other as @@ -71,9 +71,9 @@ possible. This allows to change the program at one end, without having to worry that it might break at the other, as long as we do not touch the interface through which the two ends communicate. The interface in C++, of course, is the declaration of abstract base classes. -

    -

    + + Here, we will implement (again) a Laplace solver, although with a number of differences compared to previous example programs:

      @@ -106,9 +106,9 @@ number of differences compared to previous example programs:
    1. Separate the description of the test case with which we will present the program, from the rest of the program.
    -

    -

    + + The things the program does are not new. In fact, this is more like a melange of previous programs, cannibalizing various parts and functions from earlier examples. It is the way they are arranged in @@ -123,9 +123,9 @@ practice, and is not necessarily a style that you have to adopt in order to write successful numerical software if you feel uncomfortable with the chosen ways. It should serve as a case study, however, inspiring the reader with ideas to the desired end. -

    -

    + + Once you have worked through the program, you will remark that it is already somewhat complex in its structure. Nevertheless, it only has about 850 lines of code, without comments. In real @@ -136,9 +136,9 @@ the applications listed above, this is still small, as they are 20 to the start is thus indispensible. Otherwise, it will have to be redesigned at one point in its life, once it becomes too large to be manageable. -

    -

    + + Despite of this, all three programs listed above have undergone major revisions, or even rewrites. The wave program, for example, was once entirely teared to parts when it was still significantly smaller, just @@ -154,34 +154,34 @@ without flaws in its design, and in particular might not be suited for an application where the objective is different. It should serve as an inspiration for writing your own application in a modular way, to avoid the pitfalls of too closely coupled codes. -

    +

    What the program does

    -

    + What the program actually does is not even the main point of this program, the structure of the program is more important. However, in a few words, a description would be: solve the Laplace equation for a given right hand side such that the solution is the function - u(x,t)=exp(x+sin(10y+5x2)) . The goal of the +$u(x,t)=\exp(x+\sin(10y+5x^2))$. The goal of the computation is to get the value of the solution at the point -x0=(0.5,0.5), and to compare the accuracy with +$x_0=(0.5,0.5)$, and to compare the accuracy with which we resolve this value for two refinement criteria, namely global refinement and refinement by the error indicator by Kelly et al. which we have already used in previous examples. -

    -

    + + The results will, as usual, be discussed in the respective section of this document. In doing so, we will find a slightly irritating observation about the relative performance of the two refinement criteria. In a later example program, building atop this one, we will devise a different method that should hopefully perform better than the techniques discussed here. -

    -

    + + So much now for all the theoretical and anecdotal background. The best way of learning about a program is to look at it, so here it is: -

    + diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/grid-kelly-8.gif b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/grid-kelly-8.gif deleted file mode 100644 index 23a6a526d2..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/grid-kelly-8.gif and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-0.jpg b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-0.jpg deleted file mode 100644 index e5ebc3ceb5..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-0.jpg and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-1.jpg b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-1.jpg deleted file mode 100644 index 46ddb2dd5d..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-1.jpg and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-2.jpg b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-2.jpg deleted file mode 100644 index 11a2f8b585..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-2.jpg and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-3.jpg b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-3.jpg deleted file mode 100644 index 33d72a153f..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-3.jpg and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-4.jpg b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-4.jpg deleted file mode 100644 index c32d227561..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-4.jpg and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-5.jpg b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-5.jpg deleted file mode 100644 index 022f4fe14e..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-5.jpg and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-6.jpg b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-6.jpg deleted file mode 100644 index c766a80160..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-6.jpg and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-7.jpg b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-7.jpg deleted file mode 100644 index 7c890215ac..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-7.jpg and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-8.jpg b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-8.jpg deleted file mode 100644 index 1213d67bcc..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-8.jpg and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-9.jpg b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-9.jpg deleted file mode 100644 index b894e94439..0000000000 Binary files a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/pix-kelly/solution-kelly-9.jpg and /dev/null differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/results.html b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/results.dox similarity index 76% rename from deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/results.html rename to deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/results.dox index 66b921aab8..c45718de00 100644 --- a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/results.html +++ b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/results.dox @@ -2,22 +2,21 @@

    Results

    -

    + The results of this program are not that interesting - after all its purpose was not to demonstrate some new mathematical idea, and also not how to program with deal.II, but rather to use the material which we have developed in the previous examples to form something which demonstrates a way to build modern finite element software in a modular and extensible way. -

    -

    + + Nevertheless, we of course show the results of the program. Of foremost interest is the point value computation, for which we had implemented the corresponding evaluation class. The results (i.e. the output) of the program looks as follows: - -

    +@code
         Running tests with "global" refinement criterion:
         -------------------------------------------------
         Refinement cycle: 0 1 2 3 4 5 6
    @@ -46,124 +45,107 @@ output) of the program looks as follows:
          7100 1.5876
         13059 1.5942
         24749 1.5933
    -
    - -

    +@endcode + -

    What surprises here is that the the exact value is 1.59491554..., and that it is obviously suprisingly complicated to compute the solution even to only one per cent accuracy, although the solution is smooth (in fact infinite often differentiable). This smoothness is shown in the graphical output generated by the program, here coarse grid and the first 9 refinement steps of the Kelly refinement indicator: -

    +
    - Solution Kelly, coarse grid + @image html step-13.solution-kelly-0.png - Solution Kelly, 1 refinement steps + @image html step-13.solution-kelly-1.png
    - Solution Kelly, 2 refinement steps + @image html step-13.solution-kelly-2.png - Solution Kelly, 3 refinement steps + @image html step-13.solution-kelly-3.png
    - Solution Kelly, 4 refinement steps + @image html step-13.solution-kelly-4.png - Solution Kelly, 5 refinement steps + @image html step-13.solution-kelly-5.png
    - Solution Kelly, 6 refinement steps + @image html step-13.solution-kelly-6.png - Solution Kelly, 7 refinement steps + @image html step-13.solution-kelly-7.png
    - Solution Kelly, 8 refinement steps + @image html step-13.solution-kelly-8.png - Solution Kelly, 9 refinement steps + @image html step-13.solution-kelly-9.png
    -

    + While we're already at watching pictures, this is the eighth grid, as viewed from top: -

    -

    - Kelly, grid 8 -

    +@image html step-13.kelly-grid-8.png -

    However, we are not yet finished with evaluation the point value computation. In fact, plotting the error -e=|u(xh)-uh(x0)| for the two +$e=|u(x_0)-u_h(x_0)|$ for the two refinement criteria yields the following picture: -

    -

    - error -

    + +@image html step-13.error.png + + -

    What is disturbing about this picture is that not only is the adaptive mesh refinement not better than global refinement as one would usually expect, it is even significantly worse since its convergence is irregular, preventing all extrapolation techniques when using the values of subsequent meshes! On the other hand, global -refinement provides a perfect 1/N or h-2 +refinement provides a perfect $1/N$ or $h^{-2}$ convergence history and provides every opportunity to even improve on the point values by extrapolation. Global mesh refinement must therefore be considered superior in this example! This is even more surprising as the evaluation point is not somewhere in the left part where the mesh is coarse, but rather to the right and the adaptive refinement should refine the mesh around the evaluation point as well. -

    -

    + + We thus close the discussion of this example program with a question: -

    +

    What is wrong with adaptivity if it is not better than global refinement? -

    -

    + + Exercise at the end of this example: There is a simple reason for the bad and irregular behavior of the adapted mesh solutions. It is simple to find out by looking at the mesh around the evaluation @@ -174,15 +156,15 @@ avoided. The second exercise is to check whether the results are then better than global refinement, and if so if even a better order of convergence (in terms of the number of degrees of freedom) is achieved, or only by a better constant. -

    -

    + + (Very brief answers for the impatient: at steps with larger errors, the mesh is not regular at the point of evaluation, i.e. some of the adjacent cells have hanging nodes; this destroys some superapproximation effects of which the globally refined mesh can profit. Answer 2: this quick hack -

    +@code
         bool refinement_indicated = false;
         typename Triangulation::active_cell_iterator cell;
         for (cell=triangulation->begin_active();
    @@ -199,10 +181,10 @@ profit. Answer 2: this quick hack
     	for (unsigned int v=0; v::vertices_per_cell; ++v)
     	  if (cell->vertex(v) == Point(.5,.5))
     	    cell->set_refine_flag ();
    -
    +@endcode in the refinement function of the Kelly refinement class right before executing refinement would improve the results (exercise: what does the code do?), making them consistently better than global refinement. Behavior is still irregular, though, so no results about an order of convergence are possible.) -

    + diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.error.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.error.png new file mode 100644 index 0000000000..3752c0da30 Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.error.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.grid-kelly-8.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.grid-kelly-8.png new file mode 100644 index 0000000000..0e36185e16 Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.grid-kelly-8.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-0.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-0.png new file mode 100644 index 0000000000..f993cb7461 Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-0.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-1.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-1.png new file mode 100644 index 0000000000..f657aca3f3 Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-1.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-2.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-2.png new file mode 100644 index 0000000000..18c5e740dd Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-2.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-3.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-3.png new file mode 100644 index 0000000000..241a58d711 Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-3.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-4.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-4.png new file mode 100644 index 0000000000..9c7b797a8e Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-4.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-5.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-5.png new file mode 100644 index 0000000000..ad841b8134 Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-5.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-6.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-6.png new file mode 100644 index 0000000000..fc0d2cd493 Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-6.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-7.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-7.png new file mode 100644 index 0000000000..1701b06236 Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-7.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-8.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-8.png new file mode 100644 index 0000000000..22ec43eda9 Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-8.png differ diff --git a/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-9.png b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-9.png new file mode 100644 index 0000000000..d5ac791572 Binary files /dev/null and b/deal.II/doc/tutorial/chapter-2.step-by-step/step-13.data/step-13.solution-kelly-9.png differ