4-CAIVS-user-guide/4.1-Purpose.md

-x
+
\ No newline at end of file
+
+CAIVS is a converter for NIRVANA snapshot files (`NIR#.#`; cf.
+[NIRVANA: snapshot files](3.3-Output-data#snapshot-files)) into data
+formats that are more suitable for visualization and postprocessing.
+Various output formats are supported for data readers of visualization
+tools like
+[IDL](https://www.l3harrisgeospatial.com/Software-Technology/IDL),
+[VisIt](https://wci.llnl.gov/simulation/computer-codes/visit) or
+[ParaView](https://www.paraview.org/). The CAIVS user interface allows
+to individually select physical variables contained in a NIRVANA
+snapshot for output. A user can also define own variables derived from
+the imported snapshot variables. Different options exist to operate on
+the input mesh before ouput data is produced. For instance, data
+conversion can be restricted to a user-defined subdomain or, to name a
+second example, an adaptive mesh can be transformed onto a unigrid with
+resolution equivalent to some refinement level of the original mesh.
+
+Output files produced by CAIVS get names `#.format` where `#` is a
+user-specified number, and the suffix `format`∈{`nir`,`silo`,`csv`,`h5`}
+stands for one of the possible output formats. If variables are
+requested to be written out in separate files (cf. 
+[Specification of parameters](4.2-User-interfaces#specification-of-parameters)) 
+the output file name reads `#.variable_name.format` where `variable_name`
+represents the name of the selected variable.
+
+CAIVS currently supports the following output formats:
+
+#### CAIVS native format (`#.nir`)
+
+The CAIVS native file format is a proprietary, self-describing data
+format with a textual header containing metadata about the mesh
+structure followed by physical data in binary form.
+
+The NIRVANA software provides an IDL reader for the native data format
+called `readNIR.pro`. The IDL procedure `readNIR.pro` is located in the
+subdirectory `/caivs/idl`. `readNIR.pro` is able to import multi-block
+data resulting from an AMR simulation. However, visualization of AMR
+data in IDL is non-trivial. NIRVANA provides a few prototype procedures
+in `/caivs/idl` to show how AMR data imported by `readNIR.pro` could be
+handled including a wrapper for a multi-block contour plot.
+
+#### Silo (`#.silo`)
+
+The [Silo](https://wci.llnl.gov/simulation/computer-codes/silo) data
+format is a self-describing format developed at the Lawrence Livermore
+National Laboratory. The CAIVS Silo export module was developed on basis
+of version 4.8 of the Silo library using the low-level storage driver
+PDB. Silo is the favorit import format in VisIt.
+
+*Note: The Silo output option requires the installation of the Silo
+library and the configuration of the CAIVS makefile `Makefile_CAIVS`
+located in directory `/caivs/bin` (cf. 
+[Quick tutorial](2-Getting-started#quick-tutorial)).*
+
+#### CSV-like (`#.csv`)
+
+The Comma-Separated-Variables-like format is a text file in form of a
+table. The produced file is not strictly CSV because the first two rows
+do not store datapoints. Also entries are not separated by commas but by
+blanks. The first row contains information in the order: timestep cycle
+number, physical time, problem dimension, coord geometry, geometry of
+vector variables, number of columns and, finally, number of datapoints.
+The second row contains column labels. Physical data actually starts
+with the third row. Data rows are of the form
+
+    x y [z] variable1 variable2 ....
+
+Data from 2D simulations store only the *x*- and *y*-coordinate. The
+number of data rows equals the number of cells (or cell nodes) in the
+output mesh.
+
+The NIRVANA software provides an IDL reader for the CSV-like data format
+called `readCSV.pro`. The IDL procedure `readCSV.pro` is located in the
+subdirectory `/caivs/idl`.
+
+*Note: CSV-like files are usually larger in size and slower to read than
+native format files.*
+
+#### HDF5 (`#.h5`)
+
+Output files of this type are formatted according to the
+[HDF5](https://www.hdfgroup.org/solutions/hdf5/) standard. Like the
+CAIVS native and Silo formats HDF5 is a self-describing file format. In
+contrast to these formats, however, HDF5 does not adhere to a fixed
+layout by definition. This means that CAIVS produces its own flavoured
+HDF5 format. Therefore, the HDF5 data file `#.h5` is accompanied by a
+[XDMF2](https://www.xdmf.org/index.php/Xdmf2\_Model\_and\_Format\_Archive)
+file named `#.h5.xmf`. The XDMF2 file is a XML-like descriptor which
+determines that the output data file is a HDF5 file and deposits the
+applied HDF5 layout. Visualization tools like VisIt or ParaView usually
+provide an XDMF reader in order to import associated HDF5 data.
+
+*Note: The HDF5 output option requires the installation of the HDF5
+library and the configuration of the CAIVS makefile `Makefile_CAIVS`
+located in directory `/caivs/bin` (cf. 
+[Quick tutorial](2-Getting-started#quick-tutorial)).*
\ No newline at end of file