ArepoVTK: The Arepo Visualization ToolKit

ArepoVTK is a visualization library designed to produce high quality, presentation-ready visualizations of hydrodynamic simulations run with the AREPO code. It can render single images as well as frame sequences for movies from cosmological simulations such as IllustrisTNG as well as idealized test problems and other computational fluid dynamics simulations. It is primarily ray-tracing based, casting through scalar and vector fields defined on an unstructured Voronoi tessellation of space. In this case, piecewise constant/nearest-neighbor (i.e. first order) and linear gradient reconstruction (i.e. second order) are both supported, as is the higher-order natural neighbor interpolation (NNI).

Alternatively, ArepoVTK can disregard the Voronoi mesh and perform N-th nearest neighbor interpolation using an oct-tree structure and various support kernels including the modified Shepard's method (inverse distance weighting), Gaussian, and the usual SPH cubic spline. IDW can also be performed on the natural neighbors of each Voronoi site. As a final alternative, using the dual structure of the Delaunay tessellation, barycentric interpolation on the tetrahedra is available with the Delaunay tessellation field estimator (DTFE) method.

Technically, we implement a high level renderering framework in C++, which is dynamically linked with AREPO to use its existing functionality to e.g. load snapshots, initialize fluid and particle data, and construct the Voronoi mesh and its connectivity structures. Transfer function design is the burden of the user and assumes an expert knowledge of the data present in the snapshots. This is specified, along with all other rendering options, in a configuration file read at run time. Camera support includes: orthographic, perspective, and angular fisheye (180 degree full-dome; 360 degree environmental); camera motion can be animated using keyframes.

ArepoVTK is currently designed to explore novel visualization techniques, i.e. it is highly experimental, easily broken, and assuredly beta software. It is multi-threaded using pthreads, but is not yet multi-node parallelized. It is not interactive.

Future goals include: (i) combining the volume rendering approach with coincident point particle sets, i.e. stars and dark matter, (ii) time interpolation between snapshots, (iii) faster Watson-Sambridge and Liang-Hale algorithms for NNI, (iv) splatting and alternatives to ray-tracing, (v) distributed-memory parallelism with MPI, (vi) GPU acceleration.

Installation

First, make sure you have a recent C++ compiler (gcc or intel). On a standard cluster, load a set of required modules by executing e.g. module load intel gsl fftw hdf5-serial impi. If you are on a laptop or otherwise don't have the module command available, you must install these libraries (consult the AREPO user documentation for more details).

Next, download the ArepoVTK source as well as the public AREPO source:

git clone https://github.com/dnelson86/ArepoVTK.git
cd ArepoVTK/
git clone https://github.com/dnelson86/arepo

Install libpng if it is not already available on your system:

git clone git://git.code.sf.net/p/libpng/code libpng
cd libpng
./configure
make

Build the libarepo.a shared library used within ArepoVTK:

cd ../arepo
make libarepo.a -j

Finally, build ArepoVTK itself:

cd ..
mkdir build
make -j

Executing ./ArepoRT with no options should produce the following output:

      ___           ___           ___           ___           ___                    ___           ___
     /\  \         /\  \         /\  \         /\  \         /\  \                  /\  \         /\  \
    /::\  \       /::\  \       /::\  \       /::\  \       /::\  \                /::\  \        \:\  \
   /:/\:\  \     /:/\:\  \     /:/\:\  \     /:/\:\  \     /:/\:\  \              /:/\:\  \        \:\  \
  /::\~\:\  \   /::\~\:\  \   /::\~\:\  \   /::\~\:\  \   /:/  \:\  \            /::\~\:\  \       /::\  \
 /:/\:\ \:\__\ /:/\:\ \:\__\ /:/\:\ \:\__\ /:/\:\ \:\__\ /:/__/ \:\__\          /:/\:\ \:\__\     /:/\:\__\
 \/__\:\/:/  / \/_|::\/:/  / \:\~\:\ \/__/ \/__\:\/:/  / \:\  \ /:/  /          \/_|::\/:/  /    /:/  \/__/
      \::/  /     |:|::/  /   \:\ \:\__\        \::/  /   \:\  /:/  /              |:|::/  /    /:/  /
      /:/  /      |:|\/__/     \:\ \/__/         \/__/     \:\/:/  /               |:|\/__/     \/__/
     /:/  /       |:|  |        \:\__\                      \::/  /                |:|  |
     \/__/         \|__|         \/__/                       \/__/                  \|__|

   v0.44 (Dec 25 2019). Author: Dylan Nelson (dnelson@uni-heidelberg.de)

Usage: ArepoRT <configfile.txt> [-s snapNum] [-j jobNum] [-e expandedJobNum]

If you see an error message about "error while loading shared libraries", you need to make sure that the paths to the external libraries are specified in the LD_LIBRARY_PATH environment variable, e.g.

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HDF5_HOME/lib:$GSL_HOME/lib:$FFTW_HOME/lib

If you see an error message about "Fatal error in PMPI_Init" or any other strange MPI initialization errors, you may need to unset the following two environment variables (for interactive/shell usage of MPI compiled codes):

unset I_MPI_HYDRA_BOOTSTRAP
unset I_MPI_PMI_LIBRARY

Getting Started

After compilation succeeds, run the first basic test:

./ArepoRT tests/config_2.txt

this should produce a 600x600 pixel image test_frame2.png which is identical to the following:

This is a result of a simple ray-tracing through a small test setup of a uniform grid of 2^3 (i.e. eight) cells within a box [0,1], each with uniform mass. A ninth, central point at [0.5, 0.5, 0.5] is inserted with higher mass. As a result, the gas density field peaks in the center and falls off radially, modulo the imprint of the tessellation geometry. You can get a sense of the geometry with the interactive WebGL Voronoi mesh visualizer.

The transfer function is defined in the configuration file: in this case, there is only one TF added and it is given by the string constant_table Density idl_33_blue-red 0.5 20. The 'constant' means that we will add light to a ray in linear proportion to the 'Density' field it samples. The color of the light is sampled from a 'table', which is specified by its name 'idl_33_blue-red'. This colormap is stretched between a minimum Density value of '0.5' and a maximum of '20' (code units), and outside of this range gas will not contribute to a ray.

---

Next, let's run a permutation of this test on the same "simulation snapshot":

./ArepoRT tests/config_2b.txt

which should produce the image frame2b.png as shown below:

Several configuration choices were changed from the first image. First, the camera was moved such that it views the simulation domain from an oblique angle, rather than directly 'face-on'. The geometry of the bounding box and the single octagonal Voronoi cell in the center of the domain is clear. Second, we have changed the transfer function to constant Density 1.0 0.2 0.0 which is even simpler than above: a fixed color specified by the RGB triplet {R=1, G=0.2, B=0} (i.e. orange) is added to a ray each time it samples gas 'Density', weighted by the value of that density. Finally, we have changed the viStepSize parameter from zero to 0.05. If viStepSize = 0, then ArepoVTK samples each Voronoi cell exactly once, at the midpoint of the line segment defined by the two intersection points of a ray as it enters and exits that cell. On the other hand, if viStepSize > 0 as in the second example, we take strictly step along each ray and take equally spaced samples 0.05 (world space, i.e. code units) apart.

Note that the lines of the bounding box, Delaunay tetrahedra, and Voronoi polyhedra (if drawn) are added in a final pass, rasterization phase. Thus they are not (yet) ray-traced, i.e. cannot be occluded by density along the line of sight.

---

Moving on to a cosmologically interesting use case, we will run and analyze the output of the AREPO example cosmo_box_star_formation_3d. This is a 32^3 gravity + hydrodynamics simulation (i.e. about 32,000 total gas cells) of a small, 7.5 Mpc/h cosmological volume. You can execute this yourself by

cd arepo/examples/
./test.py --print-all-output --no-cleanup cosmo_box_star_formation_3d

this takes about 20-30 minutes to run (on 16 cores). It will produce, among other outputs, the z=0 snapshot: arepo/run/examples/cosmo_box_star_formation_3d/output/snap_005.hdf5. If you don't want to wait that long, you can skip running this test and download the HDF5 snapshot file directly:

mkdir -p arepo/run/examples/cosmo_box_star_formation_3d/output
wget -P !$ https://www.tng-project.org/files/arepo_tests/cosmo_box_star_formation_3d/snap_005.hdf5

Now, we will execute a render to highlight the temperature structure of the evolved intergalactic medium:

./ArepoRT tests/config_cosmo_box.txt

which should produce the image `frame_cosmo_box.p