<h1>Results</h1>


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.

Usage:
    ./\step-19 [-p parameter_file] list_of_input_files
              [-x output_format] [-o output_file]

Parameter sequences in brackets can be omitted if a parameter file is
specified on the command line and if it provides values for these
missing parameters.

The parameter file has the following format and allows the following
values (you can cut and paste this and use it for your own parameter
file):

# Listing of Parameters
# ---------------------
# A dummy parameter asking for an integer
set Dummy iterations = 42

# The name of the output file to be generated
set Output file      =

# A name for the output format to be used
set Output format    = gnuplot


subsection DX output parameters
  # A Boolean field indicating whether neighborship information between cells
  # is to be written to the OpenDX output file
  set Write neighbors = true
end


subsection Dummy subsection
  # A dummy parameter that shows how one can define a parameter that can be
  # assigned values from a finite set of values
  set Dummy color of output = red

  # A dummy parameter that can be fed with either 'true' or 'false'
  set Dummy generate output = true
end


subsection Eps output parameters
  # Angle of the viewing position against the vertical axis
  set Azimut angle                        = 60

  # Name of a color function used to colorize mesh lines and/or cell
  # interiors
  set Color function                      = default

  # Whether the interior of cells shall be shaded
  set Color shading of interior of cells  = true

  # Whether the mesh lines, or only the surface should be drawn
  set Draw mesh lines                     = true

  # Whether only the mesh lines, or also the interior of cells should be
  # plotted. If this flag is false, then one can see through the mesh
  set Fill interior of cells              = true

  # Number of the input vector that is to be used to generate color
  # information
  set Index of vector for color           = 0

  # Number of the input vector that is to be used to generate height
  # information
  set Index of vector for height          = 0

  # The width in which the postscript renderer is to plot lines
  set Line widths in eps units            = 0.5

  # Whether width or height should be scaled to match the given size
  set Scale to width or height            = width

  # Scaling for the z-direction relative to the scaling used in x- and
  # y-directions
  set Scaling for z-axis                  = 1

  # The size (width or height) to which the eps output file is to be scaled
  set Size (width or height) in eps units = 300

  # Angle of the viewing direction against the y-axis
  set Turn angle                          = 30
end

subsection Povray output parameters
  # Whether camera and lighting information should be put into an external
  # file "data.inc" or into the POVRAY input file
  set Include external file = true

  # Whether POVRAY should use bicubic patches
  set Use bicubic patches   = false

  # A flag indicating whether POVRAY should use smoothed triangles instead of
  # the usual ones
  set Use smooth triangles  = false
end


subsection UCD output parameters
  # A flag indicating whether a comment should be written to the beginning of
  # the output file indicating date and time of creation as well as the
  # 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
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.



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, 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
-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
@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
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
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
<code>solution-0005.prm</code> 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:
<img src="http://www.dealii.org/images/steps/developer/step-19.solution-0005.png" alt="">

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

set Dummy iterations = -13

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 (<code>#</code>) 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
        -13
    for the entry named
        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 <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.

