DATA FILE CONVERSION

The standard BHAC dataformat, i.e. the *.dat files usable for restart, contain all the conservative variables in all gridblocks, and hence suffice for visualization, in principle. However, in many instances, one would like to use data formats that are directly readable by some of the more widespread visualization software packages. Therefore, we created the convert.t module, which ensures that this post-process data file conversion can be done with the same executable (but possibly even on a different platform). The many possibilities include conversion to *.vtu (VTK unformatted data format) directly readable by Paraview (or ViSiT).

Of all the options, we currently actively support only the *.vtu and postrad options.

This page: [Setup in par file] [Conversion options] [Autoconvert] [Some notes on extra conversion possibilities] [Endianness]

Setup in par file

To convert an existing *.dat snapshot file, one option is to make a copy of your parameter file, named e.g. convert.par. This should contain the following lines in the filelist:

&filelist
        ...  
        convert             = .true.
        convert_type        = 'vtuBCCmpi'
        saveprim            = .true.
        snapshotini         = 0
        ...
 /

which activates the convert mode (convert = .true.), sets the file-type to binary cell-centered vtu files (convert_type = 'vtuBCCmpi'), makes sure primitive variables are stored (saveprim = .true.) and sets the indices for the snapshot file (snapshotini = 0). To convert with the above settings, simply run BHAC with this parameter-file:

  mpirun -np 8 ./bhac -i convert.par

It is however more convenient to control the conversion simply from the command-line, e.g.

  mpirun -np 8 ./bhac -restart 0 -convert

which uses the default parameter file amrvac.par, sets the snapshot file (-restart 0) and activates the convert option (-convert).
To run over multiple files in bash:

for i in {0..10}; do mpirun -np 8 ./bhac -restart $i -convert; done

Conversion options

For very large simulations (typically 3D, and/or runs achieving high effective resolutions), even the data conversion may need to be done in parallel (and ultimately, the visualization itself too). The convert.t allows to perform some of the *.dat conversions in parallel, in particular, this is true for the *.vtu format. You should then select one of

convert_type='vtumpi'
convert_type='vtuCCmpi'
convert_type='vtuBmpi'
convert_type='vtuBCCmpi'
convert_type='vtimpi'
convert_type='vtiCCmpi'
convert_type='pvtumpi'
convert_type='pvtuCCmpi'
convert_type='pvtuBmpi'
convert_type='pvtuBCCmpi'
convert_type='hdf5'

in the filelist of the parameter-file.

Here, the prefix p stands for the parallel file format, where each process is allowed to dump its data into a single (e.g. *.vtu) file and a master file (e.g. *.pvtu) is stored by rank zero. This has the advantage that the write operation on suitable file systems is sped up significantly. In a visualization software, only the *.pvtu files need to be imported and also the reading process is sped up in case of parallel visualization. See further instructions on hdf5.

The following formats are available on single processor conversion:

'oneblock' | 'oneblockB' | 'postrad' | 'postradB' | 'postradBdp' | 'postradBsp'

the postrad formats (B for binary, dp and sp refer to double- or single- precision) can be read in with GRRT codes, e.g. BHOSS or RAPTOR. oneblock is simlar to postrad, you obtain a fully uniformly re-gridded version of your simulation.

Autoconvert

In addition to the conversion after the run, BHAC can also directly output files ready to use for visualization along with the simulation. A parallel run will however only be capable to provide the file-types ready for parallel conversion (see above). To enable this capability, simply set the switch autoconvert=.true. in the filelist.

Notes on conversion possibilities

Cell center versus cell corner values

In the cases below, the difference between convert-types with or without CC relates to the difference between cell center (`CC') versus cell corner values. For the cell center case, no interpolation of the computed data is needed, since the (conservative) variables actually represent volume averages stored at cell centers. For the other cases (without 'CC'), the convert.t tries to interpolate from cell center to the cell corners, and then the data will be known at the grid nodes. This will be noticable on reading in the data in paraview, which reports whether data is cell data (cell centered) or point data (nodes or corners). In principle, the conversion from cell centered (or cell data) to cell corner (or point data) types can also be achieved in paraview itself, with the filter Cell data to Point data. There may be subtle differences between the way BHAC does this nterpolation, and the way it happens internally to paraview, so we provide both options as output *.vtu files.

Another very useful option is to specify which variables actually need to be converted: by default all primitive variables available in the *.dat file will be included, but then again filesizes may become restrictive. For that purpose, the logical array writew allows to select which variable(s) to store (and this in combination with saveprim, possibly). You can then create different files for selected variables, knowing that the output filename will start with filenameout, while the actual data file converted is known from the combination filenameini and snapshotini.

We allow the possibility to compute derived variables from the *.dat file in the userfile, by setting how many you add beyond the nw variables typical for the physics module at hand, in the integer nwauxio. Correspondingly that many variables, you should then compute and store in the w(*,nw+1) ... w(*,nw+nwauxio) entries, in the user-written subroutine specialvar_output (as defined in amrvacnul/speciallog.t). The names for these variables then need to be provided in the corresponding specialvarnames_output subroutine, which simply then extends the strings wnames and primnames. This feature is very useful, for the same reason as above: you can let the code compute gradients of scalar fields, divergence of vector quantities, curls of vectors, etc, using the precoded subroutines for that purpose found in geometry.t. You then do not rely on visualization software to do interpolations or discretizations, which may not reflect those actually taken in BHAC.

Another useful feature is the possibility to select the output AMR level. You can let the code compute from the *.dat file an output residing on a specified level level_io. This then uses the BHAC internal means to perform restriction and prolongations, and you can then make sure to have a single uniform grid output too.

convert_type='vtu' or convert_type='vtuCC'

Does the conversion to *.vtu data files. This option works on 1 CPU. The resulting *.vtu files contain data in ASCII format.

convert_type='vtuB' or convert_type='vtuBCC'

Does the conversion to *.vtu data files. This option works on 1 CPU. The resulting *.vtu files are in binary format.

convert_type='vtumpi' or convert_type='vtuCCmpi'

Does the conversion to *.vtu data files. This option works on multiple CPUs. The resulting *.vtu files contain data in ASCII format.

convert_type='vtuBmpi' or convert_type='vtuBCCmpi'

Does the conversion to *.vtu data files. This option works on multiple CPUs. The resulting *.vtu files contain data in binary format. (recommended)

Endianness

Our *.dat files contain the data in binary format. This is in principle exchangeable between different platforms, with the possible exception for big endian or little endian type machines (these differ in the ordering of bytes for integers and reals). E.g. IBM SP platforms have different endianness than the VIC3 cluster at K.U.Leuven. In that sense, you may need to do conversion on the same (type) platform than you used for running the code.

For the binary .vtu files, the endianness can be provided in the xml header and vtu readers like paraview will then interprete the data correctly. The default endianness of .vtu files is little endian. To switch to big endian, simply add the line

#define BIGENDIAN

to the definitions.h file.

There can be solutions on the machine at hand, using the assign command (whose syntax you will need to get info on). We would also like to hear if anyone knows about a way to specify the endianness of the output in MPI/Fortran itself, independent of the platform. Using Fortran compilers like gfortran and intel fortran, it is now possible to output .dat data files in the other endian, e. g. big endian, with a parameter endian_swap=.true. in the filelist section of the parameter file.