DATA FILE CONVERSION

The standard MPI-AMRVAC 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), to *.plt format for the commercial package Tecplot, or the *.dx format for the opensource package openDX. We also provide possibilities to convert to a format *.out suitable for Idl, for which some automated macro's can be made in analogy with those used for the Versatile Advection Code , but be forewarned that 3D (and even 2D) AMR data for Idl will require you to program your own macro's. Also, this info will not explain you how to use the mentioned software for visualization, but just explain how to do the conversion. Furthermore, this part of the code is subject to continuous change and improvement, and we welcome extra contributions.

We now give some brief info on how to use the same executable amrvac (which you already compiled and used to obtain output *.dat files with), to convert a single or all *.dat file(s) to one of these formats.

This page: [Converting on a single CPU] [Parallel conversion options] [Autoconvert] [Some notes on extra conversion possibilities] [Endianness]

Converting (on a single CPU)

Note that all the steps below assume you're running on a single CPU. The same steps are to be taken for obtaining any of the other precoded data formats. One important warning is due: when you run a simulation for some reason twice, and you did not erase the previously created *.dat files, these files are overwritten (if the filenameout has not changed). Then, it may be that conversion fails, since the end of the file may contain some leftover data from the previous time, if the filelength has changed due to some other reason. The only remedy to this is that one should always remove old *.dat files, or never forget to change the name for the files accordingly, by setting filenameout in the &filelist.

We will assume that you ran the standard 2D advection problem used for test purposes, i.e. that you did the following steps beforehand:

cd src
setamrvac -d=22 -phi=0 -z=0 -p=rho -u=testrho -g=16,16 -cp=openmpi -s
make clean amrvac
cd ..
ln -s par/testrho/testrho_vac22 amrvac.par
mpirun -np 1 amrvac

We also assume that in the parameter file mentioned above, the namelist &filelist was stating (note that the end of the namelist is indicated as usual by a backslash)

 &filelist
        filenamelog='datamr/testrho/vaclogo'
        filenameout='datamr/testrho/vaclogo'
        primnames='rho'
 /

If all went well, you then have created as many *.dat files as requested through the settings you provided in the combined &savelist and &stoplist namelists from the par-file. For the example, they normally default to asking a full data dump at time zero, as well as every time the time has increased by 0.05, and this till tmax=1.0d0, such that we actually have 21 snapshots in total. You should thus have files like datamr/testrho/vaclogo0000.dat up to datamr/testrho/vaclogo0020.dat. You can now individually convert such *.dat file to a *.vtu file by doing the following. Edit the par-file, to modify the &filelist to something like

 &filelist
        filenamelog='datamr/testrho/vaclogo'
        filenameout='datamr/testrho/vaclogo'
        primnames='rho'
        filenameini='datamr/testrho/vaclogo'
        convert=.true.
        convert_type='vtuCC'
        saveprim=.false.
        snapshotini=0
 /

Assuming that this par-file is still known through the symbolic link amrvac.par as above, you can then convert a single *.dat file (here the datamr/testrho/vaclogo0000.dat file, as we select snapshotini=0) simply running again

mpirun -np 1 amrvac

or, which is actually equivalent (single CPU)

amrvac

Note that this will create a new file, namely datamr/testrho/vaclogo0000.vtu, which can be directly imported in Paraview. It will, under the settings above, just contain the density on the grid hierarchy at time zero. The convert_type='vtuCC' indicates that the data is exactly as the code interprets and updates the values, namely as cell-centered quantities. The saveprim=.false. has for the example here no real meaning, as for advection conservative and primitive variables coincide (just density rho exists).

Realizing that you typically want to convert multiple data files, you can do this by repeating the above as many times as here are *.dat files, by raising/changing the snapshotini identifier. Since you typicallly want to convert all data files between a minimum and maximum number of similarly named files, the script doconvert is added. Typing doconvert will tell you its intended usage, namely

doconvert par/testrho/testrho_vac22 0 20

in the example case at hand, where we created 21 data files from running the advection problem. This doconvert script does assume that you actually edited the par-file manually once as above (such that the needed lines for conversion are in the &filelist namelist), and that the executable amrvac exists in the same directory. It will complain when the parfile does not exist, and obviously requires the existence of all files between the start and stopindex (0 and 20 here). With paraview, you will then be able to immediately import all 21 *.vtu files with the same base filename, and directly make movies or still images from them.

Parallel 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, and for the *.plt format. You should then select one of

convert_type='vtumpi'
convert_type='vtuCCmpi'
convert_type='pvtumpi'
convert_type='pvtuCCmpi'
convert_type='tecplotmpi'
convert_type='tecplotCCmpi'

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.

Also, you can then use the same strategy as explained above for converting on a single CPU: you will always need to edit the par-file once to specify how to do the conversion, and then you may run interactively on e.g. 4 CPU like

mpirun -np 4 amrvac

or do this in batch (use a batch job script for that), to do multiple data file conversions. We also provide a small script, called doconvertpar, which works similar to the doconvert explained above, but takes one extra parameter: the number of CPUs. Its usage is described by

doconvertpar parfilename startindex stopindex nprocessor

Autoconvert

In addition to the conversion after the run, AMRVAC now offers also to 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 parallel conversion). To enable this capability, simply set the switch autoconvert=.true.. The example above would then read

&filelist
        filenamelog='datamr/testrho/vaclogo'
        filenameout='datamr/testrho/vaclogo'
        primnames='rho'
        saveprim=.false.
        autoconvert=.true.
        convert_type='pvtuCCmpi'
 /

and when the code is run via

mpirun -np 2 amrvac

three new output files (vaclogoXXXX.pvtu, vaclogoXXXXp0000.vtu, vaclogoXXXXp0001.vtu) will appear simultaneous to the vaclogoXXXX.dat files, stored at given intervals. All functionality of the usual convert is conserved, e.g. derived quantities and primitive variables (using the saveprim=.true. option) can be stored in the output files.

Notes on conversion possibilities

Cell center versus cell corner values

In all cases mentioned 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 MPI-AMRVAC does this nterpolation, and the way it happens internally to paraview, so we provide both options as output *.vtu files. Similar observations hold for the Tecplot format.

Conservative/primitive storage and adding derived quantities

The saveprim logical allows you to select whether the conservative or primitive variables need to be stored in the resulting output file. The names for the conservative variables are taken from the wnames string, and those for the primitive need to be set in primnames.

Another very useful option is to specify which variables actually need to be converted: by default all conservative 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 typcial 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 MPI-AMRVAC.

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 MPI-AMRVAC 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='tecplot' or convert_type='tecplotCC'

This realizes conversion to *.plt files, which can be read in directly by Tecplot. Note that the output is in ASCII format, which may mean huge data sets, but Tecplot has its own preplot command that will allow you to operate on such a file, and thereby make a binary version for it. The above is for single CPU execution, allows to add user-defined variables with nwauxio, and renormalization using the normt and normvar array.

convert_type='tecplotmpi' or convert_type='tecplotCCmpi'

Same as above, but allows to perform the conversion in parallel. One can add user -defined variables with nwauxio, and renormalize using the normt and normvar array. The current implementation is such that tecplotmpi and tecplotCCmpi will create different length output ASCII files when used on 1 versus multiple CPUs. In fact, on 1 CPU, there will be as many (tecplot) zones as there are levels, while on on multiple CPUs, there will be a number of zones up to the number of levels times the number of CPUs (or less, when some level does not exist on a certain CPU).

convert_type='idl' or convert_type='idlCC'

This will do the conversion to *.out files, which are a generalization of the Versatile Advection Code output files. For those VAC-style files, extensive macro's are provided with the VAC code itself, allowing for fairly interactive visualization of quantities, or computation of derived quantities etc. The Idl macro's that allow to read *.out files converted with MPI-AMRVAC, and that use similar commands as for VAC files, are downloadable here as a single gzipped tar file. It contains the hidden, to be adjusted file .idlrc, and the directories Idl and Idl_amr, with macro's inside. However, they only allow a very limited visualization, with some (possibly incomplete and inaccurate) description here, fine for 1D and little for 2D runs, but with no support for 3D data analysis. This would mean you need to write your own Idl macro's, after you fully understand what dataformat is actually stored in a *.out file. For that, just study the source code in convert.t.

The Idl conversion does not work in parallel, it can handle the addition of extra IO variables (nwauxio), and allows to renormalize the data using the normt and normvar array, in case you directly want to have dimensional quantities available. An additional script provided is the doidlcat script, which basically concatenates all requested *.out files in a single file, that can be used with the (few) Idl macro's above. Its intended use for the 2D advection example would be

doconvert par/testrho/testrho_vac22 0 20
doidlcat datamr/testrho/vaclogo 0 20 1

The first line creates the 21 files datamr/testrho/vaclogo0000.out till datamr/testrho/vaclogo0020.out (assuming you edited the par-file and indicated the proper convert_type for idl), while the next line then gathers them all in a single datamr/testrho/vaclogoall.out file, ready for Idl visualization with VAC-like macro's, like .r getpict, .r plotfunc or .r animate. The 3 integer parameters to doidlcat indicate the first and last snapshot number, and a skiprate. If the latter is different from 1, you include every so many files in the concatenation.

convert_type='dx'

This (heritage) output format is suited for openDX conversion.

onegrid(mpi), oneblock(B), ...

Extra possibilities to allow creation of a single uniform grid level output. Please inspect the workings in convert.t.

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.

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.