Write rest of documentation.

git-svn-id: https://svn.dealii.org/trunk@11388 0785d39b-7218-0410-832d-ea1e28bc413d

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.html
index f0abefd89d523a7c6a465fa8bfcaab2a2e95b6c5..9eb2b5c92d7b85ab09b98b846be55345ecd74f6e 100644 (file)
--- 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.html
@@ -121,8 +121,157 @@ end
 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
-sorted list of subsections. Within these are the dummy entries and sections we
-have added in the <code>declare_parameters()</code> function, along with their
-default values and documentations.
+sorted list of subsections. Most of the parameters have been declared by the
+<code>DataOutBase</code> class, but there are also the dummy entries and
+sections we have added in the <code>declare_parameters()</code> function, along
+with their default values and documentations.
 </p>
 
+<p>
+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
+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, totalling some 245MB of data:
+<code>
+<pre>
+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
+-rw-r--r--  1 bangerth wheeler 7715984 Aug 12 10:09 solution-0005.0000-002.d2
+-rw-r--r--  1 bangerth wheeler 7887648 Aug 12 10:06 solution-0005.0000-003.d2
+-rw-r--r--  1 bangerth wheeler 7833291 Aug 12 10:09 solution-0005.0000-004.d2
+-rw-r--r--  1 bangerth wheeler 7536394 Aug 12 10:07 solution-0005.0000-005.d2
+-rw-r--r--  1 bangerth wheeler 7817551 Aug 12 10:06 solution-0005.0000-006.d2
+-rw-r--r--  1 bangerth wheeler 7996660 Aug 12 10:07 solution-0005.0000-007.d2
+-rw-r--r--  1 bangerth wheeler 7761545 Aug 12 10:06 solution-0005.0000-008.d2
+-rw-r--r--  1 bangerth wheeler 7754027 Aug 12 10:07 solution-0005.0000-009.d2
+-rw-r--r--  1 bangerth wheeler 7607545 Aug 12 10:11 solution-0005.0000-010.d2
+-rw-r--r--  1 bangerth wheeler 7728039 Aug 12 10:07 solution-0005.0000-011.d2
+-rw-r--r--  1 bangerth wheeler 7577293 Aug 12 10:14 solution-0005.0000-012.d2
+-rw-r--r--  1 bangerth wheeler 7735626 Aug 12 10:10 solution-0005.0000-013.d2
+-rw-r--r--  1 bangerth wheeler 7629075 Aug 12 10:10 solution-0005.0000-014.d2
+-rw-r--r--  1 bangerth wheeler 7314459 Aug 12 10:09 solution-0005.0000-015.d2
+-rw-r--r--  1 bangerth wheeler 7414738 Aug 12 10:10 solution-0005.0000-016.d2
+-rw-r--r--  1 bangerth wheeler 7330518 Aug 12 10:05 solution-0005.0000-017.d2
+-rw-r--r--  1 bangerth wheeler 7418213 Aug 12 10:11 solution-0005.0000-018.d2
+-rw-r--r--  1 bangerth wheeler 7508715 Aug 12 10:08 solution-0005.0000-019.d2
+-rw-r--r--  1 bangerth wheeler 7747143 Aug 12 10:06 solution-0005.0000-020.d2
+-rw-r--r--  1 bangerth wheeler 7563548 Aug 12 10:05 solution-0005.0000-021.d2
+-rw-r--r--  1 bangerth wheeler 7846767 Aug 12 10:12 solution-0005.0000-022.d2
+-rw-r--r--  1 bangerth wheeler 7479576 Aug 12 10:12 solution-0005.0000-023.d2
+-rw-r--r--  1 bangerth wheeler 7925060 Aug 12 10:12 solution-0005.0000-024.d2
+-rw-r--r--  1 bangerth wheeler 7842034 Aug 12 10:13 solution-0005.0000-025.d2
+-rw-r--r--  1 bangerth wheeler 7585448 Aug 12 10:13 solution-0005.0000-026.d2
+-rw-r--r--  1 bangerth wheeler 7609698 Aug 12 10:10 solution-0005.0000-027.d2
+-rw-r--r--  1 bangerth wheeler 7576053 Aug 12 10:08 solution-0005.0000-028.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
+</pre>
+</code>
+
+<p>
+So let's see what happens if we attempt to merge all these files into a single
+one: 
+<code>
+<pre>
+examples/step-19> time ./step-19 solution-0005.0000-*.d2 -x gmv -o solution-0005.gmv  
+real    2m08.35s
+user    1m26.61s
+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
+</pre>
+</code>
+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.
+</p>
+
+<p>
+If visualized, the output looks very much like that shown for <a
+href="step-18.html" target="body">step-18</a>. 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.
+</p>
+
+<p>
+For example, let us use a simple parameter file named
+<code>solution-0005.prm</code> that contains only one line:
+<code>
+<pre>
+set Output format  = gnuplot
+</pre>
+</code>
+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>
+<pre>
+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
+</pre>
+</code>
+
+<p>
+We can then visualize this one file with gnuplot, obtaining something like
+this:
+<p align="center">
+<img src="step-19.data/solution-0005.png" width="80%"></img>
+</p>
+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>
+<pre>
+set Output format  = dx
+set Output file    = my_output_file.dx
+
+set Dummy iterations = -13
+
+subsection Dummy subsection
+  set Dummy color of output = blue
+  set Dummy generate output = false
+end
+</pre>
+</code>
+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 pound
+sign is considered a comment.
+</p>
+
+<p>
+If one runs step-19 with this input file, this is what is going to happen:
+<code>
+<pre>
+examples/step-19> ./step-19 solution-0005.0000-012.d2 -p solution-0005.prm
+Line 4:
+    The entry value
+        -13
+    for the entry named
+        Dummy iterations
+    does not match the given pattern
+        [Integer range 1...1000 (inclusive)]
+</pre>
+</code>
+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.
+</p>
+
+<p>
+This program should have given some insight into the input parameter file
+handling that deal.II provides. The <code>ParameterHandler</code> 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.
+</p>