From 88c0abc26405378bbbfc3d7a2aba0a0d5563bd52 Mon Sep 17 00:00:00 2001 From: Wolfgang Bangerth Date: Wed, 9 Feb 2011 16:56:39 +0000 Subject: [PATCH] Finish writing. git-svn-id: https://svn.dealii.org/trunk@23317 0785d39b-7218-0410-832d-ea1e28bc413d --- deal.II/examples/step-1/doc/intro.dox | 78 +++++++++++++++++++++++---- 1 file changed, 69 insertions(+), 9 deletions(-) diff --git a/deal.II/examples/step-1/doc/intro.dox b/deal.II/examples/step-1/doc/intro.dox index 133da7689e..d50235226c 100644 --- a/deal.II/examples/step-1/doc/intro.dox +++ b/deal.II/examples/step-1/doc/intro.dox @@ -35,20 +35,80 @@ different levels: sparsity patterns of matrices. This is documentation at an intermediate level: they give you an overview of what's there in a particular area. For example when you wonder what finite element - classes exist, you would take a look at the @ref fe module. + classes exist, you would take a look at the @ref fe module. The + modules are, of course, also cross-linked to the manual (and, at + times, to the tutorial); if you click on a class name, say on + Triangulation, would will also at the very top right under the class + name get a link to the modules this class is a member of if you want + to learn more about its context. +Let's come back to the tutorial, since this is the first step of +it. Each tutorial program is subdivided into the following sections: +
    +
  1. Introduction: This is a discussion of what the program + does, including the mathematical model, and + what programming techniques are new compared to previous + tutorial programs. +
  2. The commented program: An extensively documented listing of the + source code. Here, we often document individual lines, or + blocks of code, and discuss what they do, how they do it, and + why. The comments frequently reference the introduction, + i.e. you have to understand what the program wants to achieve + (a goal discussed in the introduction) before you can + understand how it intends to get there. +
  3. Results: The output of the program, with comments and + interpretation. This section also frequently has a subsection + that gives suggestions on how to extend the program in various + direction; in the earlier programs, this is intended to give + you directions for little experiments designed to make your + familiar with deal.II, while in later programs it is more about + how to use more advanced numerical techniques. +
  4. The plain program: The source code stripped of + all comments. This is useful if you want to see the "big + picture" of the code, since the commented version of the + program has so much text in between that it is often difficult + to see the entire code of a single function on the screen at + once. +
+The tutorials are not only meant to be static documentation, but you +should play with them. To this end, go to the +examples/step-1 directory (or whatever the number of the +tutorial is that you're interested in) and type +@code + make + make run +@endcode +The first command compiles the sources into an executable, while the +second executes it (strictly speaking, make run will also +compile the code if the executable doesn't exist yet, so you could +have skipped the first command if you wanted). This is all that's +needed to run the code and produce the output that is discussed in the +"Results" section of the tutorial programs. +When learning the library, you need to play with it and see what +happens. To this end, open the examples/step-1/step-1.cc +source file with your favorite editor and modify it in some way (see, +for example, the suggestions at the end of the results section of this +program), save it and run it as above. + + +

What this program does

+ +Let's come back to step-1, the current program. In this first example, we don't actually do 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 which is a regularly refined square (not very exciting, but a common starting grid for some problems), and one more geometric attempt: a -ring-shaped domain, which is refined towards the inner edge. The -latter is certainly not very useful and is probably only rarely used -in numerical analysis for PDEs (although, to everyone's surprise, it -has actually found its way into the literature, see the paper by M. Mu -titled "PDE.MART: A network-based problem-solving environment", ACM -Trans. Math. Software, vol. 31, pp. 508-531, 2005 :-), but looks nice -and illustrates how loops over cells are written and some of the -things you can do with cells. +ring-shaped domain, which is refined towards the inner edge. Through +this, you will get to know three things every finite element program +will have to have somewhere: An object of type Triangulation for the +mesh; a call to the GridGenerator functions to generate a mesh; and +loops over all cells that involve iterators (iterators are a +generalization of pointers and are frequently used in the C++ standard +library; in the context of deal.II, the @ref Iterators module talks +about them). + +The program is otherwise small enough that it doesn't need a whole lot +of introduction. Let us just continue with its commented source. -- 2.39.5