ETSF_IO library - documentation pages

As NetCDF is shipped with `ncdump` and `ncgen` to handle NetCDF files, ETSF_IO is shipped with its own binary program `etsf_io`. This utility is made to handle some high level actions on ETSF files.

# etsf_io man page

`etsf_io` is called with the mandatory `-a` option (or `--action`) to define what action will be done by the program. Follows the little help returned by `etsf_io --help`:

    Usage: etsf_io [-h | -a action] [[-i file]...] [[-f flag]...]
                   [-o file] [arguments]

       Handle ETSF files, see --action option.
    -h --help             : show this little help.
    -a --action value     : give the action to perform.
                            Possible action may be:
                            * 'merge' to gather several files that
                              have been splitted.
                            * 'content' to get the name of
                              specifications the file matches.
                            * 'check' to check the validity of
                              the file against specifications.
    -o --output-file file : give the path to the output ETSF file.
    -i --input-file file  : give the path for an input file. This
                            option can be used one or several times.
    -l --list             : when action is check, it give the list
                            of available flags.
    -f --flag value       : give a flag name (get valid names from
                            -l option).

       Examples:
    Merge three files, etsf_io -a merge -i file1.nc -i file2.nc
                       -i file3.nc -o output.nc

    Get the contents of file test.nc, etsf_io -a contents test.nc

    Get the list of flags for validity checks, etsf_io -a check -l

    Checks with two flags, etsf_io -a check -f flag1 -f flag2 test.nc

# Action merge

The merge action can read several ETSF files and create a new one, copying all variables that are not splitted and merging those that have a split definition. If there is not enough input file to create a full unsplitted array, the new file will contains some new split informations resulting from the merge. This routine also copy headers and attributes, as for all none-ETSF variables and dimensions.

An example of usage could be:

    $ ./etsf_io -a merge -i output_proc1-etsf.nc -i output_proc2-etsf.nc -o output-etsf.nc

where `output_proc1-etsf.nc` and `output_proc2-etsf.nc` are two files generated by a distributed run on two processors.

# Action content

The file is analised by `etsf_io` and produce a human readable list of matching specifications for the given file. When a specification is not matched, a reason is given.

An example of usage could be:

    $ ./etsf_io -a content output-etsf.nc
    Analyse file 'output-etsf.nc'
     - No - wavefunctions_data.
            given reason, 'primitive_vectors' -> Variable not found
     - No - scalar_field_data.
            given reason, 'primitive_vectors' -> Variable not found
     - No - crystallographic_data.
            given reason, 'primitive_vectors' -> Variable not found

# Action check

Check if the given file match a given specification. It raise an error if there is an error and return 1 (or should since Fortran has no return value). It returns 0 if the file matches (or shouild because of Fortran). These problems make this action unusable at the present time.