For Mavis 1.4 released June 23, 2004

Pittsburgh Supercomputing Center
4400 Fifth Avenue, Pittsburgh, PA 15213
www.psc.edu -> (SC)² -> (SC)² Projects -> MFIX Support

This is the guide for users of Mavis, an interactive scientific visualization and analysis program. It is used to explore multi-variate structured data sets such as those produced by the MFIX simulation (see www.mfix.org). Please send questions and comments to eschenbe@psc.edu.

Table of Contents

1. Introduction

The User Guide covers the use of the program after it has been installed. A copy of this guide and installation notes can be found at sc-2.psc.edu/mfix.

This Introduction provides information that you may wish to read before getting into the details of the program.

MFIX (Multiphase Flow with Interphase eXchanges) is a simulation of hydrodynamics, heat transfer and chemical reactions in three-dimensional fluid-solids systems. Evaluating the output of MFIX has always been a challenge. The creation of a parallel version supporting larger grids in 2001 increased the need for new tools to augment or replace existing tools developed at the National Energy Technology Laboratory or NETL (www.netl.doe.gov).

Figure 1.1  Main window.

It was decided that the primary usage scenario for the new tool would be as follows: (1) run MFIX; (2) download the results to a workstation; and then (3) run the tool(s) on the workstation ( Figure 1.1).

In addition, we hoped to explore other scenarios. For example, we might wish to work with data at a remote location where some or all of the rendering is also performed. These goals set the overall program design.

From the outset, it was clear that this tool would evolve and grow. There are no easy solutions to the evaluation of data sets that may include dozens of transient variables defined over 3D grids. Therefore, the software was organized as modules so that additional features could be easily added. To help meet this goal, the Python language (www.python.org) was selected for its support of object-oriented programming and user interface design.

Of the several open-source graphics libraries available, OpenDX (www.opendx.org) was selected for its many high-level features. It can generate cut planes, isosurfaces and streamlines as well as perform calculations with the data. For this project, two of OpenDX's designs were heavily modified.

First, the OpenDX user interface was replaced with one created using Python. The native DX interface includes many options that are not needed for this project, and can be awkward to use. The interface created with Python focuses on the options needed, grouped in a manner that makes sense for this project. In addition, because Python is a general-purpose programming language, simple user selections can, when needed, use a complex series of Python calculations and OpenDX modules to carry out the task.

Figure 1.2 The Mavis.

Second, the OpenDX data input and storage method was replaced with one that reads only the data currently needed for the display. This makes it possible to work with data sets much larger than the workstation memory.

The OpenDX input system uses a library of routines, written in the C language, that is named MfixReader. These routines open and read MFIX files and return metadata and simulation data as requested. If you would like to use this library for other applications, please contact Mavis support (eschenbe@psc.edu).

This new tool was developed at the Pittsburgh Supercomputing Center (www.psc.edu) where the name Mavis (MFIX Analysis and Visualization) was selected. The name also refers to the program's mascot, a European song thrush (Figure 1.2).

2. Concepts

This section describes fundamental concepts that are unlikely to change as as the program evolves. This manual is not a programmer's guide; it often idealizes a function so that it is easier to understand and to use.

2.1 Data Flow

No guide, including this one, can explicitly discuss all possible interactions between parts of the software. Understanding the order in which parts are executed can help to explain the interactions.

The flow of information begins when one or more sets of files (A,B,C in Figure 2.1) are read. In reality, the program doesn't read the input files once but instead goes back to them again and again as different time steps and variables are needed.

Next, the data flows to one or more visualization methods such as Boundary Visualization or Isosurface Visualization. Each of these may use several OpenDX modules. The result of a visualization method is a graphical "object" such as the triangles that form an isosurface or the lines that form a streamline.

Finally, the graphical objects flow to one or more views. A "view", as used in this program, means a display area within the main window. You can select from one to six views and display different variables in each.

Each component (reader, visualization, etc.) is controlled through its own graphical user interface (GUI).

Figure 2.1   Idealized data flow.

2.2 Menus and Controls

The graphical user interface consists of menus and controls. The menubar, across the top of the main menu, lists the pulldown menus:

• File:  Menus for input, output and general preferences
• Utilities:  Options that affect how other tasks work
• Visualization:  Direct visualization methods
• Analysis:  Calculation of new variables and fields (future)
• Help:  Useful and interesting support information

Some of the menus have options that are used so often that it becomes awkward to repeatedly display the menu. The most used options have therefore been moved to the bottom of the main window where they are called "controls" (Figures 1.1 and 2.2).

Figure 2.2  Controls for mouse mode (left 4 buttons), printing (printer icon) and time step (right 11 widgets).

2.3 Updates and Parameters

It can be difficult to use an interactive tool like Mavis with very large data sets because it may take many seconds or minutes to redraw or update the display. Understanding how to reduce the number of updates can help.

2.3.1 View Updates

Changes in the view (e.g., rotation) that are requested using the mouse are always made immediately. Indirect viewing changes, such as a change in the size of the main window, also cause an immediate update.

2.3.2 Time Updates

Changes to the time can be made using the controls at the bottom of the main window. These updates are carried out immediately.

There are, however, several methods for jumping directly to a desired time thus avoiding updates at the intermediate times. See 8.4, Time Utility.

2.3.3 General Parameter Updates

Parameters are set using the menus. Usually, changing a parameter has no effect until that menu's "Apply" button is clicked. This button carries out all pending changes in a menu. In this guide, parameters that require that you use the "Apply" button will be tagged "A" (e.g. 3.4, Reader Messages Menu ).

Until "Apply" is clicked, you can undo changes made since the previous use of "Apply" with the "Reset" button.

The "Apply" button is enabled only when one or more parameters have changed. After changing a value in a type-in field, the "Enter" or "Return" key can be pressed to enable "Apply". However, this is not necessary - the new typed-in value will always be used at the next "Apply".

When "Apply" is clicked, parameters are checked for validity; numeric parameters must be in range and must have no non-numeric characters. A warning message is displayed describing any problems.

2.3.4 Parameter Updates with AutoApply

Some menus include an "AA" or AutoApply button. When on, changing certain parameters also clicks "Apply", internally. As a general rule, the AutoApply feature is connected to:

• the left and right arrows used to step parameters up and down
• pressing "Enter" or "Return" in a type-in field

In this guide, parameters that are part of the AutoApply feature will be tagged "AA".

Visualization parameters that are out of range and part of the AutoApply feature are usually silently "corrected" if they are invalid. For example, the Section visualization method silently corrects start and thickness parameters to prevent attempts to plot outside the dataset. In this guide, these parameters are tagged "AA-C".

2.3.5 Special Parameter Updates

Some menus include "special" parameters that only indirectly affect the visualization. For example, the isosurface visualization menu includes three such special parameters:

• the level step size (a type-in field)
• the loop speed (a type-in field with up/down buttons)
• the number of steps in a loop (a type-in field with up/down buttons)

Since these parameters have only an indirect effect, they are always applied immediately and never require the "Apply" button. However, you must still press "Enter" or "Return" after using the keyboard to enter a new value in a type-in field.

In this guide, special parameters will be tagged "S".

2.4 Multiview

It can be difficult to visually examine multiple variables because the graphical objects representing the variables can obscure one another. One solution developed at NETL is to display multiple viewports, a "multiview", where different variables are depicted in different views (Figure 2.3).

Figure 2.3   Four views using a variety of visualization methods.

Figure 2.4  A portion of the Viewing Utility used to select views.

2.4.1 Selecting the Views

The notes at 8.3, Viewing Utility, describe how to select from one to six views (Figure 2.4). The following paragraphs will describe how the vis methods and cameras from the different views interact.

2.4.2 Selecting the Plots for Each View

All views display data from the same time step. However, each view can show different variables from different datasets using different visualization methods, in any combination.

Figure 2.5  View tabs provided in each visualization menu

Each visualization method includes, at the top of its menu, a tab for each view (Figure 2.5). The parameters under each tab control the visualization for the corresponding view.

2.4.3 Cameras

The concept of a "camera" represents the direction and location from which one looks at the graphical objects. The camera is moved using the mouse.

Cameras for views 2 through 6 are kept in sync with the camera for view 1. For example, after moving the camera in view 1 and releasing the mouse button, all other view's camera will be updated to be the same as view 1's camera.

Cameras for views 2 through 6 can be temporarily changed just by moving them. When you release the mouse button, the camera for these views will be updated so that they are again synchronized with the camera of view 1.

2.4.4 Attachments

In some situations, you many want to display the same variable in several views. This can be done, of course, by setting the view parameters to have the same values in each view. This, however, would be a bit of a waste of the user's time. It is definitely a waste of CPU time and memory since the graphical object will be created again for each view.

Figure 2.6  The attach buttons provided in most vis menus.

The Attach option avoids this waste by providing a way to use a visualization (e.g, an isosurface) from one view in one or more other views.

Any visualization method that supports Attachments will provide a set of buttons similar to Figure 2.6 under the tab for each view. The buttons for views 1, 2, ..., 6 will have an "S" (for "Self") in button positions 1, 2, ..., 6. When "S" is selected, the visualization for that view is connected to "itself" and so is independent.

However, if a numbered button is selected in one view, that view will instead show a copy of the visualization defined for the numbered view. When a visualization in one view is changed (e.g., the isosurface level is changed), any attached views are also changed.

2.5 Cell Data

Some of the MFIX data cannot be used with some visualization methods. For example, using an isosurface to examine MFIX variables is a problem because the MFIX data is given at cells while the isosurface algorithm requires data given at nodes.

Although OpenDX includes a conversion routine that can work around the problem in some cases, it alters the data at best and produces incorrect results at worse. Mavis includes two options for converting cell data to node data so that the user can select the best compromise.

2.5.1 Review of Data Set Organization

A data set consists of a grid plus parameters given at locations on the grid. An MFIX data set is structured because it uses a regular grid, i.e., one where, along each axis, there are the same number of vertices.

Structured grids can have three types of coordinates. With uniform coordinates, six numbers define all vertices: the start and increment for each of the three coordinate axes.

With rectilinear coordinates, three lists define all coordinates: each list gives the values along one coordinate axis. This arrangement is used by MFIX.

Finally, with irregular coordinates, each vertex can be anywhere. The shape of the grid could be a sphere, a cylinder, or no regular shape at all.

When MFIX uses the cylindrical coordinate system, the three lists contain the radius, angle and height instead of X, Y and Z. However, few if any graphics packages can directly use such coordinates. Therefore, Mavis calculates the location in a cartesian system for each vertex, thus forming irregular coordinates. For simplicity, both cartesian and cylindrical MFIX grids are converted to irregular coordinates.

Parameters given at the vertices are called node data while those given at the cells between the vertices are called cell data. Most MFIX data is cell data. Vector data in an MFIX file is defined on the sides of a cell but is treated in Mavis as if it was defined at the center of a cell.

2.5.2 Average Method

One algorithm for converting cell data to node data is the averaging method: the data at each node is the average of the data at the surrounding cells.

When MFIX is using cylindrical coordintes, Mavis correctly uses the cells which are adjacent along the central axis, and those cells that are adjacent at 0 degrees.

Cells whose types are not "fluid" are skipped in the averaging.

Like all averaging methods, this algorithm may cause significant changes to extremes in the data. For example, a node at the juncture of 8 cells where 7 have a value of 0.0 and one has a value of 1.0 will be given the value of 0.125. The "maxima" of 1.0 will not appear at all.

2.5.3 Cell-Center Method

To avoid the problem with extrema described above, Mavis offers the cell-center method: a new grid is created with nodes at the cell centers of the original grid. The original data is assigned to the new nodes without change.

Since no averaging is performed, the data values are the actual ones produced by the simulation. In some cases (Figure 2.7), the difference between the cell-centered and averaging methods might be critical to the correct understanding of the physical process.

The main disadvantage in using a cell-centered grid is that it stops half a cell from the boundary of the standard grid (Figure 2.8).

Figure 2.7   Isosurfaces using averaged node data (left) and cell-centered node data (right).

Figure 2.8   Cell-centered grid stops half a cell from the boundary of the standard grid.

3. Reading

This section describes the 3 menus used to tell Mavis and OpenDX how to obtain information from sets of data files:

Open Menu (File->Open)

opens and closes datasets, and provides details about the dataset as a whole (required)

Open Options Menu (File->Open Options)

used before a dataset is opened to set parameters used by the reader (optional)

Reader Messages Menu (File->Reader Messages)

displays messages, if any, from the reader (optional)

3.1 Usage

Most users can get started quickly:

• go to the Open Menu
• select a file type
• use "File" to select a file

There is one special case: when reading an MFIX dataset that uses the cylindrical coordinate system, you must first use the Open Options Menu to clip the boundary cells (more on this below).

Actually, the above steps alone will cause little or no data to be read. Mavis uses a "data manager" and a custom OpenDX reader module that work together to provide data "on demand". Only when a variable is actually displayed is that variable, at the current simulation time, moved from a file into memory.

For example, view 6 may be displaying 3 different variables using the Section, Isosurface and Arrow methods. If you then turn off view 6, the change is first passed to the data manager. If no other methods and views are using those variables, the data manager then instructs the reader that those variables are no longer needed.

Opening a dataset merely causes the reader to find all the files, gather metadata, and calculate how to quickly jump to the various variables and times. This "metadata" occupies very little memory; having many open datasets is quite reasonable. However, opening a dataset may take a few seconds because the reader must examine each MFIX file to form a list of the times it contains.

3.2 Open Menu

This menu displays a list of the datasets that have already been opened, opens additional datasets, and displays dataset details (Figure 3.1 ).

The "dataset names" that are shown are created by using the file name (without paths or extensions) plus a unique integer. This same name is used in other parts of Mavis to compactly reference the dataset.

Figure 3.1   Open Menu showing 3 open MFIX datasets plus 1 open TEST dataset.

3.2.1 Dataset Type

The pulldown menu labeled "Type to Open Next" lists the types of files and datasets currently understood by the custom OpenDX reader. The value currently shown is passed to the reader when a file is selected using the "File" button.

The "TEST" file type causes the reader to create a very simple dataset without reading anything. However, you must still pick a file which will be used only to give the test dataset its name. The grid for this dataset includes (4,5,6) nodes along the (X,Y,Z) axes with a spacing of (3,2,1). The same data is returned for all times. For more details on test data, please see the file readTest.c in the directory Modules in the Mavis installation directory.

3.2.2 Opening the Files

Clicking the "File" button will display a file browser. When you have found the file you wish to open, click the name once and then "Ok", or double-click the file name. You can also type in the file name and then click "Ok."

Mavis ignores the file extension in the name you selected. Instead, it sets the file extension itself and tries to read all possible MFIX files. In other words, you can select the RES or SP1 or any other file in the set.

Mavis tries to find the files using different combinations of uppercase and lowercase. For example, if you entered a file name of myData.Res, it will work through the following list until a file is found:

• myData.RES
• myData.res
• mydata.RES
• mydata.res
• MYDATA.RES
• MYDATA.res

3.2.3 Dataset Details

Clicking "Details" will display information about the dataset currently highlighted in the list of opened datasets. This information includes items from the MFIX restart file; options used when the file was opened; and a few calculated parameters.

Of special note is the number of non-fluid cells - such cells are marked as "invalid" and are skipped by most visualization methods.

3.2.4 Closing A Dataset

Clicking "Close" will close the dataset currently highlighted in the list of opened datasets, after confirmation. Visualization methods that are using one or more variables from a closed dataset will turn themselves off, i.e., they will select "None" as the variable.

3.3 Open Options Menu

The options in this menu (Figure 3.2) must be set before opening a dataset. Each dataset may use different values for these options. In most cases, the default values will be best and this menu will not be needed.

Figure 3.2   Open Options Menu

3.3.1 Format (A)

These options describe how to read the files. Most MFIX files can be read with the default values for the record length (512 bytes) and byte order (big endian).

When MFIX uses longer record lengths, it does not store data beyond the first 512 bytes. Mavis correctly skips the unused portion of the record.

When a simulation is restarted, the first new time step that is calculated may be a little earlier than the last time calculated before the restart. Setting the Time Order Tolerance to a larger value (say, 1 second) tells Mavis that this is not an error.

3.3.2 Clipping (A)

These parameters are the number of cells eliminated at each end of each axis. Clip values of 1, for example, will eliminates the boundary cells.

The "Zeroes" and "Ones" buttons may be used to quickly set all the clip parameters. However, the "Apply" button must still be used to cause changes to take effect.

If cylindrical coordinates are used, X becomes the radius, Y becomes the height, and Z becomes the angle. The boundary cell at X min, if not clipped, will become a negative radius and may cause Mavis to crash. Furthermore, the boundary cells at min and max Z will overlap if not clipped. Therefore, it is strongly recommended that these boundaries be clipped if the MFIX dataset uses the cylindrical coordinate system.

3.3.3 Missing Times (A)

Mavis attempts to display all selected variables at the currently selected time. Some variables, however, may not be given in the data file at a time "equal" to the selected time. Two times are considered equal if they are closer than the Time Threshold. When a variable is not in the data file at the current time it is said to be "missing".

Two rules control the action taken when a variable is missing. The Interpolation Rule is applied when the missing time falls between two other times for that variable. Otherwise, the Extrapolation Rule is applied.

The Interpolation rule can be set to one of these values:

• Near:  Use data from the time nearest to the current time
• Prev:  Like Near but limited to times before the current time
• Next:  Like Near but limited to times after the current time
• Linear:  Estimate the value using the two nearest times and linear interpolation
• Never:  Return no data (may cause strange plots or failure)

The Extrapolation rule can be set to one of these values:

• Nearest:  Use data from the time nearest to the current time
• Never:  Return no data (may cause strange plots or failure)

3.4 Reader Messages Menu (A)

This menu displays error and diagnostic messages from the custom OpenDX reader module. They may be helpful when a problem is encountered.

Figure 3.3   Reader Messages Menu

The main Mavis code and OpenDX operate in different processes; therefore, explicit internal commands must be used to transfer messages between the processes. This transfer is executed to obtain all available messages when the "Update" button is clicked and after a new dataset is opened.

The "Clear" button should be clicked when viewing a large number of messages because of the limited memory reserved for these messages. Currently, messages in the buffer after the first 200 are lost.

The "Message Detail" parameter controls the amount of detail produced as the reader operates. It does not affect error messages. A value of 0 requests no messages while a value of 10 requests the most.

4. Boundary Visualization

Use Visualization->Boundary to show the Boundary Menu (Figure 4.1) which provides several methods for showing the outer boundary of the data grid. A variable must be selected but the variable's values are not actually used - just the grid associated with that variable.

4.1 Usage

Select a view using the tabs at the top of the menu, select a variable, and then click "Apply" to add the default boundary (a bounding box) to that view. For other representations of the boundary, select other options and then click "Apply." Note that the "Attach" option is not available for boundaries.

Figure 4.1   Boundary Menu.

4.2 Grid Selection (A)

Two grids are generally available. The one based on "Nodes" uses the original nodes and is typically the one that best reflects the original data.

The grid based on "Cell Centers" may be more useful when viewing cell-center node data with another visualization method. This grid is formed by putting a node at the center of the cells of the original grid. See 2.5, Cell Data, for more on the cell-center method.

When the Data switch is set to "Valid Only", the "Edges" and "Full" styles will skip invalid cells (i.e., non-fluid cells). Otherwise, all cells are used. The "Box" style ignores this switch and always uses all cells.

4.3 Style (A)

A boundary type of "Box" uses lines to depict the bounding box for the selected grid. The color and width of the lines can be selected.

Boundary types of "Edges" and "Full" draw the outer surface of the selected grid, using the selected color. The "Full" type will retain the facets of this surface (typically rectangles) while the "Edges" type will use lines to show only the connections of this surface (typically the borders of the rectanges).

The "Render" switch selects how the "Edges" and "Full" type are shown. When the boundary type is "Edges", the "Wire" and "Solid" rendering are the same since the drawing consists only of lines. When the boundary type is "Full", a "Wire" rendering will draw the edges of the display elements (two triangles per rectangle).

Setting the rendering switch to "Box", when using a boundary type of "Edges" or "Full", yields the same drawing as the boundary type "Box" but is slower.

Note: A change in the line width will typically not take effect immediately when the type is "Edges" or "Full". In this case, you will need to change to type to "Box", click "Apply", change back to the desired type, and then click "Apply" again.

Figure 4.2   Light Tab in the Boundary Menu.

4.4 Lighting (S)

The Light tab (Figure 4.2) is used to set the levels for the three light components (ambient, diffuse and specular) along with the exponent in the equation for specular light ("shininess") and the opacity (the inverse of transparency).

Boundaries drawn with lines may not be affected by all parameters.

Note: A bug in OpenDX causes the brightest diffuse light to be produced at a value of around 0.5 or lower, and dimmer diffuse light at higher values.

5. Section Visualization

Use Visualization->Sections to display the Sections Menu (Figure 5.1). This method selects a subset of the grid and then colors it using a scalar variable. The subset can be, for example, a single slice of cells in the XZ, XY or YZ planes.

Figure 5.1   Section Menu.

5.1 Usage

Select a view using the tabs at the top of the menu, select a variable, and then click "Apply" to add the default section to that view. The default may be hard to see - it is a single cell at the origin. Use the options under the "Vertices" tab to change the location and size of the section.

For other views, either repeat these steps or use the options under the Att tab to show a copy of a section visualization from another view.

Note that invalid data (non-fluid MFIX cells) may be black or deleted. If the subset consists entirely of invalid cells, there may be nothing visible.

5.2 Data Selection (A)

When a new variable is selected, the "Start" and "Thickness" parameters under the "Vertices" tab may be changed so that the section does not extend beyond the new variable's grid.

Invalid cells (i.e., non-fluid cells) can either have their data values set to zero or be flagged as "invalid". If so flagged, the cell will not be drawn, leaving a hole or gap.

5.3 Vertices (AA-C)

The "Vertices" tab (Figure 5.1) is used to define the section by selecting vertices (not cells) along each axis. The "Start" parameter sets the index of the first vertex along each axis while the "Thickness" parameter sets the number of vertices. The thickness must always be at least 2 so that only whole cells are shown.

When you click Apply, or if AA is on, these parameters are checked to ensure that they are within the range of available vertices for the variable currently selected.

Figure 5.2   Options Tab.

5.4 Options

The "Opt" tab (Figure 5.2) controls the display of cell boundaries and the color.

5.4.1 Shrink (AA-C)

The Shrink parameter reduces the size of each cell by moving the vertices towards the center of the cell, leaving gaps between cells.

The parameter sets the size of the cell as a percent. When the value is 100, the internal OpenDX shrink module is entirely bypassed. Otherwise, the internal shrink module duplicates the vertices at the cell corners, modifies the vertex locations, and creates new facets so that every side of the cell is drawn.

A Shrink value of less than 100 means there may be a very large increase in the number of vertices and facets being rendered. It is therefore wise to use Shrink only after a suitably small subset of the grid has been selected unless you have a very fast workstation.

5.4.2 Color Mapping (A)

The max to min data values are represented by a range of colors from blue to red, respectively. Data values outside of the range are represented by black.

Figure 5.3   Lighting Tab.

5.5 Lighting (AA)

The Light tab (Figure 5.3) is used to set the levels for the three light components (ambient, diffuse and specular) along with the exponent in the equation for specular light ("shininess") and the opacity (the inverse of transparency).

Note: A bug in OpenDX causes the brightest diffuse light to be produced at a value of around 0.5 or lower, and dimmer diffuse light at higher values.

5.6 Looping (S)

A loop will continuously change the Start, Thickness and Shrink parameters between a minimum and a maximum setting, updating the display after each change. For example, a slice parallel to the XZ plane can be made to move along the Y axis.

Before starting a loop, be sure to set the loop's parameters: first adjust the Start, Thickness and Shrink parameters to the desired values; then, click the loop "Min" or "Max" buttons to set the corresponding limits.

Figure 5.1   Loop Tab.

When the loop mode is "Cycle", the loop repeats after reaching the end. If it is instead set to "Bounce", the loop will change direction after reaching each end.

The "Speed" parameter is the delay between one update and the next, providing some control over the speed. However, if your data set is large or your workstation is slow, the actual speed may be slower.

The loop controls consist of 7 buttons: a Stop button in the center, and 3 buttons for each direction. The actions take by the 3 "forward" directions are, left to right:

• Step (make one update)
• Run (continuously)
• Jump to the end

The "range" for a parameter in a loop is the difference between that parameter's minimum and maximum value. Each parameter may have a different range; therefore, one parameter may reach the end of its range before the others. When that happens, that parameter will keep the same value until the end of that iteration of the loop.

All loop controls are special parameters (S) that are used immediately; they do not require the use of the "Apply" button.

5.7 Attachment (A)

The section drawing for any view can be independent (the "S" button is selected) or can be the drawing from another view (a numbered button is selected). See 2.4.4, Attachments, for more.

6. Isosurface Visualization

Use Visualization->Isosurfaces to display the Isosurfaces Menu (Figure 6.1). This method creates, for each view, an isosurface for one scalar variable at one isovalue.

Figure 6.1   Isosurface Menu.

6.1 Usage

Select a view using the tabs at the top of the menu, select a variable, and then click "Apply" to add an isosurface to that view. You may not see anything new until you adjust the isosurface level to a value between the variable's minimum and maximum.

For other views, either repeat these steps or use the options under the Att tab to show a copy of an isosurface visualization from another view.

6.2 Data Selection (A)

The OpenDX isosurface algorithm cannot use cell data; therefore, any cell data read from a file must first be converted to node data as explained in 2.5, Cell Data. A switch in the Isosurface Menu selects the conversion method.

Invalid cells (i.e., non-fluid cells) can either have their data values set to zero or be flagged as "invalid". If so flagged, the cell will not be drawn, leaving a hole or gap.

Currently, an OpenDX bug produces invalid isosurfaces when invalid flags are used. Invalid data should therefore be set to zero.

6.3 Level (AA)

The isosurface level can be typed in, or stepped up or down using the arrow buttons. The size of the step (S) used by the arrow buttons can also be set.

Figure 6.2   Lighting Tab.

Light will reflect better from the "front" side of an isosurface as identified by the surface normal. However, with isosurfaces, the normal is somewhat arbitrary. Try "Reversed" normals if the surface seems too dim.

Set the color and line width to help make the isosurface stand out from other items in the view. The line width will apply only when the data is two-dimensional, and isosurfaces are replaced with isolines.

6.4 Lighting (AA)

The Light Tab (Figure 6.2) is used to set the levels for the three light components (ambient, diffuse and specular) along with the exponent in the equation for specular light ("shininess") and the opacity (the inverse of transparency).

Note: A bug in OpenDX causes the brightest diffuse light to be produced at a value of around 0.5 or lower, and dimmer diffuse light at higher values.

Figure 6.3   Loop Tab.

6.5 Looping (S)

The options on the Loop Tab (Figure 6.3) can continuously change the isovalue between a selected minimum and maximum.

Before starting a loop, set the iso value to its minimum then click "Min", repeating for the maximum value.

When the loop mode is "Cycle", the loop repeats after reaching the end. If it is instead set to "Bounce", the loop will change direction after reaching each end.

The speed at which changes are made is controlled somewhat by the "Speed" parameter. This is the delay between one update and the next. However, if your data set is large or your workstation is slow, the actual speed may be slower.

Each cycle of the loop will use "Num Steps" instances of the isovalue, arranged so that the first is the "Min" and the last is the "Max".

The loop controls consist of 7 buttons: a Stop button in the center, and 3 buttons for each direction. The actions take by the 3 "forward" directions are, left to right:

• Step (make one update)
• Run (continuously)
• Jump to the end

6.6 Attachment (A)

The isosurface drawing for any view can be independent (the "S" button is selected) or can be the drawing from another view (a numbered button is selected). See 2.4.4, Attachments, for more.

7. Arrow Visualization

Use Visualization->Arrows to display the Arrows Menu (Figure 7.1). This method uses small drawings or glyphs to represent a vector variable.

Figure 7.1   Arrow Menu.

7.1 Usage

Select a view using the tabs at the top of the menu, select a variable, and then click "Apply" to add arrows to that view. You may not see anything new until you adjust the scale and cutoff.

For other views, either repeat these steps or use the options under the Att tab to show a copy of an arrow visualization from another view.

7.2 Data Selection (A)

The Arrow visualization always uses the vector data from the selected variable as if it was defined at the center of a cell. In MFIX, the three components of the vector are calculated for the positive coordinate side of each cell. The user should remember this approximation.

7.3 Size and Cutoff

The Sizes Tab includes a widget (AA) for setting a scale factor that is applied to each vector component. The scale can be stepped up and down with the small arrows in the widget, and the size of the step can be set with a type-in widget (S).

After the scale has been applied, all vectors whose length is smaller than the value of the cutoff widget (AA) are removed. Getting the cutoff right is important to avoid drawing so many vectors that refreshes are slow and the image is confusing. The step size for the cutoff can also be set (S).

Figure 7.2   Glyph Tab.

7.4 Glyph (AA)

The Glyph Tab (Figure 7.2) includes widgets that set the appearance of the glyph. These options affect those aspects of the glyph that are not directly controlled by the data.

The Style switch can select a fast, simple representation using one line (needle); an arrow with arrowhead drawn with lines; or a 3D arrow (rocket) drawn with polygons. The last is the slowest but makes it easier to see the 3D orientation.

The Thickness parameter makes the arrow and rocket representations wider, relative to the vector length, as the parameter becomes larger.

The Line Width parameter sets the width of the lines used in the needle and arrow representations.

The Color pulldown menu sets the color used in all representations. It is currently not possible to color the arrows based on their size.

Figure 7.3   Lighting Tab.

7.5 Lighting (AA)

The Light Tab (Figure 7.3) is used to set the levels for the three light components (ambient, diffuse and specular) along with the exponent in the equation for specular light ("shininess") and the opacity (the inverse of transparency).

Note: A bug in OpenDX causes the brightest diffuse light to be produced at a value of around 0.5 or lower, and dimmer diffuse light at higher values.

7.6 Attachment (A)

The arrow drawing for any view can be independent (the "S" button is selected) or can be the drawing from another view (a numbered button is selected). See 2.4.4, Attachments, for more.

8. Utilities

Utility menus control services that are used indirectly. A few, such as the Time Utility, have some of their most useful widgets moved to the main window control area for quick access. Most utilities are found on the Utilities pull-down menu; however, some are found at other locations as noted below.

8.1 Help

Selecting Help on the menu bar shows a list of topics arranged in two groups: local help and browser help.

Local help provides brief discussions of some basic topics using only files on the local workstation.

Browser help provides more extensive discussions, including figures and images, using a web browser and the web pages stored at PSC.

Browser help is extremely flexible and can be adapted within Mavis to work with almost any web browser using the options in the Preferences menu.

Figure 8.1   Init File Tab from the Preferences Menu.

8.2 Preferences

Selecting File->Preferences displays the Preferences menu (Figure 8.1). Selections made here affect all parts of the program.

8.2.1 Init Files Tab

An initialization file or init file records almost every selection that can be made in Mavis. It also records the location of the popup menus and whether they are displayed. It does not currently store the camera location.

These files use the XML protocol and so can be viewed in most web browsers and changed in any text editor. However, it is easier to ensure a valid file if Mavis is used to create them.

Initialization files are read in a way that allows them to be incomplete. In other words, when Mavis reads an init file and cannot find a particular parameter, the parameter in Mavis is left unchanged. Future versions of Mavis, with additional parameters, will therefore be able to read old init files.

A parameter read from an init file will always be forced to the limits of the current data. For example, an init file may specify that the variable Vel_g be used to create an isosurface; if not available, no variable will be used.

File .mavisrc.xml is the default initialization file and is read automatically whenever Mavis starts. To create it, click "Save" under "Automatic Initialization File". You may create and use as many other initialization files as you wish using the Init Files tab in the Preferences menu (Figure 8.1).

Figure 8.2   Help Tab from the Preferences Menu.

8.2.2 Help Tab

All the parameters used with browser help are set using the options at this tab. In addition, popup help can be enabled or disabled.

Browser

The path to the browser executable. The default is /usr/local/netscape/netscape.

Argument Format

The command to the browser. It must include "%s" to indicate where the URL is to be placed. The default works with Netscape, Mozilla and Mozilla Firebird: -remote "openurl(%s)". Please note that these Netscape-related browsers must be running before Mavis' browser help will work.

Page Location

A URL that points to the directory holding the web pages. The default is http://sc-2.psc.edu/mfix.

Page Extension

The final part of a page name. The default is php.

Document Type

A flag that can be "Normal" or "Simplified". The later choice is best for older browsers that do not display standard HTML correctly.

Figure 8.3   Debugging Tab from the Preferences Menu.

8.2.3 Debugging Tab

Use these options (Figure 8.2) only when problems arise and you, or a support person, are familiar with OpenDX and the internal Python programming of Mavis. The messages can be obscure.

Show OpenDX errors

Enable the display of serious OpenDX errors. These errors are seldom synchronized with Mavis actions and include events that really should be classified as warnings.

Enable OpenDX debugging

List each OpenDX internal action. As with error messages, these are seldom synchronized with Mavis actions.

Force OpenDX synchronization

Halts execution of Python commands until requests sent to OpenDX are acknowledged (but not necessarily executed).

Enable Mavis debugging

Prints each command as it is sent to OpenDX.

Figure 8.4   Viewing Utility with views 1,2,4 and 6 enabled

8.3 Viewing Utility

The menu for the Viewing Utility (Figure 8.4) sets parameters that affect all views.

The buttons in the Views group enable a view when depressed. As shown in Figure 2.3, the Mavis display area is divided horizontally into equal-width view areas. The width of the red border around the views can be from 0 to 100 pixels. Wider borders take space away from the plots but can make it easier to separate the views.

The Background pulldown is used to select an appropriate background color. A dark gray is best for video while white is best for images that will be included in a document.

The Projection buttons select an orthogonal projection ("Ortho") where objects are the same size no matter their distance; or, a perspective projection ("Persp") where distant objects are smaller.

Figure 8.5   Mouse controls in main window.

If perspective projection is used, the field of view (FOV) controls how quickly objects become smaller as they move further away. Large values (around 90) cause objects to become smaller more quickly. Very large values (around 179) may cause you to be sucked into the screen.

The XZ scale factor changes the scale of an object in its X and Z dimensions while leaving its scale in Y unchanged. For example, it may be useful to use an XZ scale of, say, 10 for an object that is 10 times larger in Y than in X and Z. Note: the global scaling set using the mouse or caused by perspective is added to whatever scaling is set by this parameter.

Figure 8.6   Time Utility.

The Viewing Utility also manages interactive transformations using the mouse and the controls located at the bottom left of the main window (Figure 8.5). From left to right, these controls set the mouse to:

• Rotate (hold down mouse buttons 1 or 3)
• Pan side to side (hold down mouse button 1)
• Scale in three dimensions (hold down mouse button 1)
• Reset (click with mouse button 1)

8.4 Time Utility

The Time Utility works with a list of simulation times formed by combining all of the times from all of the variables in all of the open data sets. The menu for the Time Utility (Figure 8.6) sets parameters that affect the time in all views.

The "Available Times" area shows the list of times. Double clicking on a time will jump to that time.

The "Playback Limits" area shows the first and last times used when looping over time. To set new values, select a time in the "Available Times" area and then click the appropriate "Set" button. Click "Use All Times" to reset the first and last loop times to show all times.

The "Playback Speed" parameters control the speed of time loops. The two speed settings, in milliseconds, set the delay between one update and the next. The actual speed may be slower if the data set is large or the workstation is slow. When the fast speed has been selected (see below), the effective speed can be increased even further by skipping some times. A Fast step size of 1 shows all time steps while, say, a step size of 3 shows only 1 of 3 time steps.

Figure 8.7   Controls for time utility in main window.

The Time Utility displays some of its controls in the main window (Figure 8.7). The center widget displays the current time. You can type a new time into this widget and press Enter to jump directly to a new time. The value will be automatically changed to the one closest to an actual time.

There are 5 buttons on either side of the current time that control loops over time. "Run" and "Fast" loops continue indefinitely. The 5 forward buttons, to the right of the current time, perform these functions (listed left to right):

• Stop
• Step (go 1 time step)
• Run (uses Run speed and a step size of 1)
• Fast (uses Fast speed and Fast step size)
• End (jumps to last time)

9. Printing

Use File->Print to display the Printing Menu (Figure 9.1). This facility does not actually print anything but instead creates files that you can display or print with other applications.

Figure 9.1   Printing Menu.

9.1 Usage

Use the menu to first set parameters as needed. Then, generate a print file by clicking on the print button (an icon that looks like a printer) at the bottom of the main window (S).

Changes made in the Print Menu are used only when printing starts; changes made while printing is in progress have no immediate effect.

Two types of print files can be created: a single image or a movie. If an image format has been selected, the print button will reset automatically after the print has completed. If a movie format has been selected, recording will continue until you click the print button again or exit the program.

9.2 File Parameters (A)

The "Select" button displays the menu used to enter a file name or select the name of an existing file. Warning: recording an image to an existing image file overwrites the previous image.

The "Format" pulldown menu selects from these file formats.

• MIFF Movie
• RGB Movie
• YUV Movie
• GIF
• TIFF
• Color Postscript
• Color Encapsulated Postscript
• Grayscale Postscript
• Grayscale Encapsulated Postscript

The three movie formats will add a copy of the Mavis graphics display to a file whenever the image changes. These changes could include changes in parameters or in time. It is unwise to change the size of the main Mavis window while recording a movie. Files in the MIFF format can be edited and converted to other formats, such as MPEG, by the application ImageMagick (www.imagemagick.org).

The 6 image formats will record one copy of the Mavis graphics display in a file. If you wish to record several images, you will need to change the file name between recordings. Applications such as ImageMagick can be used to work with the recorded images.

The 2 encapsulated Postscript formats produce files that can be inserted into other documents. The 2 non-encapsulated Postscript formats can often be sent directly to a printer. OpenDX creates Postscript files that contain fixed-resolution pixmaps.

All formats copy the Mavis display from the screen. Therefore, the recorded image will have more pixels and detail if the Mavis main window is made larger before recording.

The current version of OpenDX seems to work best using the TIFF and MIFF formats.

9.3 Size Parameters (A)

These parameters are used only when recording Postscript images. Please see the OpenDX documentation for details.

9.4 Miscellaneous Parameters (A)

The Gamma Correction will change the brightness of mid-range colors while leaving very dark and very light colors unchanged. Setting Gamma greater than one causes the colors to be brighter.

The "View that will be printed" switch selects which view will be printed. Only one view can be printed at any given moment.

© Pittsburgh Supercomputing Center (PSC), SuperComputing Science Consortium