Zoltan Developer's Guide: Visualization of Geometric Partitions

Zoltan Developer's Guide | Next | Previous

Appendix: Visualization of Geometric Partitions

Graphical images of partitioned meshes can help you to understand the geometric partitioning algorithms of Zoltan and to debug new or existing algorithms. The following sections describe methods for visualizing the partitions computed by the test drivers.

2D problems with gnuplot

To view the result of a 2D decomposition performed by the test driver, use the "gnuplot output" option of the test driver input file, as described in zdrive.inp. The test driver will write a file that can be loaded into gnuplot. The result for the test mesh in directory ch_hammond, partitioned into four regions with RCB, is show below. The first picture is obtained from the input file zdrive.inp.gnuplot1 with gnuplot output = 1. The second picture is obtained from the input file zdrive.inp.gnuplot2 with gnuplot output = 2. Both pictures have been zoomed so that the xrange is [-0.2,1.2] and the yrange is [-0.3,0.35].

[gnuplot 2D view]

3D problems with vtk_view

3D visualization requires downloading and compiling the Visualization Toolkit (VTK) library (version 5.0 or later). You can then use the Zoltan top level makefile to build the vtk_view application found in the util directory of Zoltan. Build details can be found in the Config.generic file in Utilities/Config. Note that you will have to download and build CMake, the makefile generator used by VTK, before you can build VTK.

vtk_view is a parallel MPI program. It does not need to be run with the same number of processes with which you ran zdrive. You can choose the number of processes based on the size of the input mesh you will be visualizing, and the computational load of rendering it to an image at interactive rates.

If you run vtk_view in the directory in which you ran the test driver, the following will happen:

vtk_view will read zdrive.inp, or another input parameter file if you specify a different file on the command line.
It will read in the same input Chaco or Exodus II mesh that the test driver read in.
It will read in the file_name.out.p.n files that the test driver wrote listing the part assigned to every global ID.
It will open a window on your display, showing the input mesh. For Chaco files, the mesh vertices will be colored by the part into which Zoltan placed them. For Exodus II files, the mesh elements will be so colored. A scalar bar in the window indicates the mapping from colors to part numbers. A caption describes the input file name, the decomposition method, the Zoltan parameter settings, and so on. You can use your mouse to rotate the volume, pan and zoom in and out.

The example below shows how vtk_view displays the mesh in the test directory ch_brack2_3 after it has been partitioned with HSFC across 5 processes.

[vtk_view 3D view]

If no test driver output files are found, vtk_view will display the mesh without part IDs.

There are a few additional options that can be added to the test driver input file, that are specifically for vtk_view.

zdrive count = <number> the number of file_name.out.p.n files, also the value of p
image height = <number> number of pixels in height of image (default is 300)
image width = <number> number of pixels in width of image (300)
omit caption = <1 or 0> do not print default caption in window if "1" (0)
omit scalar bar = <1 or 0> do not print scalar bar in window if "1" (0)
add caption = <text of caption> display indicated text in the window (no caption)

The zdrive count option may be required if you have more than one set of test driver output files in the directory. Otherwise, vtk_view will look for files of the form file_name.out.p.n for any value p. Note that since the window may be resized with the mouse, you may not need image height and image width unless you must have a very specific window size. Also note that if you ran the Fortan test driver zfdrive, you will need to rename the output files from file_name.fout.p.n to file_name.out.p.n.

Off-screen rendering with vtk_write

In some situations it is not possible or not convenient to open a window on a display. In that case, you can compile util/vtk_view.cpp with the flag OUTPUT_TO_FILE and it will create a program that renders the image to a file instead of opening a window on a display. (The Zoltan top level makefile does exactly this when you use the vtk_write target.)

Note that while vtk_view is built with OpenGL and VTK, vtk_write must be built with Mesa GL and a version of the VTK libraries that you have compiled with special Mesa flags and with the Mesa header files. This is because OpenGL implementations are not in general capable of off-screen rendering, and Mesa GL is. The Config.generic file in Utilities/Config describes in detail how to build Mesa and then VTK for off-screen rendering.

vtk_write goes through the same steps that vtk_view does, except at the end it writes one or more image files instead of opening a window on your display. The images begin with a camera focused on the mesh, pointing in the direction of the negative Z-axis. The positive Y-axis is the "up" direction, and we use a right-handed coordinate system. (So the X-axis is pointing to the right.) The camera can revolve around the mesh in 1 degree increments.

The zdrive count, image width, and image height options listed above also apply to vtk_write. In addition, you can use these options to govern the output images.

output format = <format name> choices are tiff, png, jpeg, ps and bmp (default is tiff)
output name = <file name> base name of image file or files (outfile)
output frame start = <number> first frame, between 0 and 360 (0)
output frame stop = <number> last frame, between 0 and 360 (0)
output frame stride = <number> the difference in degrees from one frame to the next (1)
output view up = <x y z> the direction of "up" as camera points at mesh (0 1 0)

Other file formats

vtk_view was written to post-process zdrive runs, so it only reads Chaco or Exodus II/Nemesis meshes. If you are working with a different mesh-based file format, it is still possible that you could use vtk_view or vtk_write to view the parts assigned to your mesh by some application using the Zoltan library. VTK at this point in time has readers for many different file formats. If VTK has a reader for your format, then modify the read_mesh function in util/vtk_view.cpp to use that reader.

You can then hard-code vtk_view to read your file, or you can modify read_cmd_file in driver/dr_input.c to accept a specification of your file type in addition to Chaco and Nemesis. If you do the latter you can create a zdrive-style input file in which to specify your file name and other visualization parameters.

Finally, you need to create text files listing each global ID you supplied to Zoltan, followed by the part ID assigned by Zoltan, with only one global ID/part ID pair per line. Name this file or files using the conventions used by the test drivers.

[Table of Contents | Next: Using the Test Script | Previous: Using the Test Drivers | Privacy and Security]

zdrive count = <number>	the number of file_name.out.p.n files, also the value of p
image height = <number>	number of pixels in height of image (default is 300)
image width = <number>	number of pixels in width of image (300)
omit caption = <1 or 0>	do not print default caption in window if "1" (0)
omit scalar bar = <1 or 0>	do not print scalar bar in window if "1" (0)
add caption = <text of caption>	display indicated text in the window (no caption)

output format = <format name>	choices are tiff, png, jpeg, ps and bmp (default is tiff)
output name = <file name>	base name of image file or files (outfile)
output frame start = <number>	first frame, between 0 and 360 (0)
output frame stop = <number>	last frame, between 0 and 360 (0)
output frame stride = <number>	the difference in degrees from one frame to the next (1)
output view up = <x y z>	the direction of "up" as camera points at mesh (0 1 0)