]> https://gitweb.dealii.org/ - dealii.git/commitdiff
Finish writing.
authorWolfgang Bangerth <bangerth@math.tamu.edu>
Wed, 9 Feb 2011 16:56:39 +0000 (16:56 +0000)
committerWolfgang Bangerth <bangerth@math.tamu.edu>
Wed, 9 Feb 2011 16:56:39 +0000 (16:56 +0000)
git-svn-id: https://svn.dealii.org/trunk@23317 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/examples/step-1/doc/intro.dox

index 133da7689e04427e3666d3993f864bf25ed51989..d50235226ce751865caf1172723a6d84ef6de195 100644 (file)
@@ -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:
+<ol>
+  <li> <b>Introduction:</b> This is a discussion of what the program
+       does, including the mathematical model, and
+       what programming techniques are new compared to previous
+       tutorial programs.
+  <li> <b>The commented program:</b> 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 <i>what</i> the program wants to achieve
+       (a goal discussed in the introduction) before you can
+       understand <i>how</i> it intends to get there.
+  <li> <b>Results:</b> 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.
+  <li> <b>The plain program:</b> 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.
+</ol>
 
+The tutorials are not only meant to be static documentation, but you
+should play with them. To this end, go to the
+<code>examples/step-1</code> 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, <code>make run</code> 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 <code>examples/step-1/step-1.cc</code>
+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.
+
+
+<h3> What this program does </h3>
+
+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.

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.