<a name="Intro"></a>
<h1>Introduction</h1>


In step-18, we saw a need to write
output files in an intermediate format: in a %parallel program, it doesn't scale
well if all processors participate in computing a result, and then only a
single processor generates the graphical output. Rather, each of them should
generate output for its share of the domain, and later on merge all these
output files into a single one.



Thus was the beginning of step-19: it is the program that reads a number of
files written in intermediate format, and merges and converts them into the
final format that one would like to use for visualization. It can also be used
for the following purpose: if you are unsure at the time of a computation what
graphics program you would like to use, write your results in intermediate
format; it can later be converted, using the present program, to any other
format you may want.



While this in itself was not interesting enough to make a tutorial program, we
have used the opportunity to introduce one class that has proven to be
extremely help- and useful in real application programs, but had not been
covered by any of the previous tutorial programs: the
<code>ParameterHandler</code> class. This class is used in applications that
want to have some of their behavior determined at run time, using input
files. For example, one may want to specify the geometry, or specifics of the
equation to be solved, at run time. Other typical parameters are the number of
nonlinear iterations, the name of output files, or the names of input files
specifying material properties or boundary conditions.



Working with such parameter files is not rocket science. However, it is rather
tedious to write the parsers for such files, in particular if they should be
extensible, be able to group parameters into subsections, perform some error
checks such as that parameters can have only certain kinds of values (for
example, it should only be allowed to have integer values in an input file for
parameters that denote a number of iteration), and similar requirements. The
<code>ParameterHandler</code> class allows for all this: an application program
will declare the parameters it expects (or call a function in the library that
declares a number of parameters for you), the <code>ParameterHandler</code>
class then reads an input file with all these parameters, and the application
program can then get their values back from this class.



In order to perform these three steps, the <code>ParameterHandler</code> offers
three sets of functions: first, the
<code>ParameterHandler::declare_entry</code> function is used to declare the
existence of a named parameter in the present section of the input file (one
can enter and leave subsections in a parameter file just like you would
navigate through a directory tree in a file system, with the functions
<code>ParameterHandler::enter_subsection</code> and
<code>ParameterHandler::leave_subsection</code> taking on the roles of the
commands <code>cd dir</code> and <code>cd ..</code>; the only difference being
that if you enter a subsection that has never been visited before, it is
created: it isn't necessary to "create" subsections explicitly). When declaring
a parameter, one has to specify its name and default value, in case the
parameter isn't later listed explicitly in the parameter file. In addition to
that, there are optional arguments indicating a pattern that a parameter has to
satisfy, such as being an integer (see the discussion above), and a help text
that might later give an explanation of what the parameter stands for.



Once all parameters have been declared, parameters can be read, using the
<code>ParameterHandler::parse_input</code> family of functions. There are
versions of this function that can read from a file stream, that take a file
name, or that simply take a string and parse it. When reading parameters, the
class makes sure that only parameters are listed in the input that have been
declared before, and that the values of parameters satisfy the pattern that has
been given to describe the kind of values a parameter can have. Input that uses
undeclared parameters or values for parameters that do not conform to the
pattern are rejected by raising an exception.



A typical input file will look like this:
@code
set Output format  = dx
set Output file    = my_output_file.dx

set Maximal number of iterations = 13

subsection Application
  set Color of output = blue
  set Generate output = false
end
@endcode
Note that subsections can be nested.



Finally, the application program can get the values of declared parameters back
by traversing the subsections of the parameter tree and using the
<code>ParameterHandler::get</code> and related functions. The
<code>ParameterHandler::get</code> simply returns the value of a parameter as a
string, whereas <code>ParameterHandler::get_integer</code>,
<code>ParameterHandler::get_double</code>, and
<code>ParameterHandler::get_bool</code> already convert them to the indicated
type.



Using the <code>ParameterHandler</code> class therefore provides for a pretty
flexible mechanism to handle all sorts of moderately complex input files without
much effort on the side of the application programmer. We will use this to
provide all sorts of options to the step-19 program in order to convert from
intermediate file format to any other graphical file format.



The rest of the story is probably best told by looking at the source of step-19
itself. Let us, however, end this introduction by pointing the reader at the
extensive class documentation of the <code>ParameterHandler</code> class for
more information on specific details of that class.
