m2e User Guide

For m2e 3.3 released November 22, 2004

This user guide describes the installation and use of m2e, a program that converts MFIX files into Ensight's native file format ( www.ensight.com). Please forward questions or comments to PSC User Services.

1. Introduction

Complete scientific visualization packages (e.g., AVS, OpenDX, Ensight) usually provide several methods for reading data:

• from files where the data is stored in the package's own, private file format;
  
• from files using the format of one of the popular analysis and simulation programs; and
  
• from other application-specific files using a custom reader.

Although the third approach is elegant, it is the most complex and may require time consuming conversion every time data is read. The m2e program supports the first approach by reading in a MFIX data set and writing out a set of files that are in Ensight's own, private file format. Ensight can read the files produced by m2e directly.

The program has no graphical user interface; instead, an extensive set of command-line options can be used to select a subset of the geometry, a subset of the time steps, and/or a subset of the variables. The -i option can be used to take a quick look at a MFIX dataset without producing any files.

2. Installation

It is recommended that a separate directory be created to hold m2e. The directory can be located anywhere. To download the program, see www.psc.edu/mfix/tools.

Unpack the downloaded file and run make. If problems occur, you may need to edit the file makefile to work on your system. Add the m2e directory to your environmental variable PATH or move the m2e executable to a directory already in your path.

3. Operation

This section discusses the operations controlled by the command-line options.

3.1 Data Flow

The basic idea behind the program is that the data flows through a pipeline consisting of several components:

• reader
• variable filter
• space filter
• time filter
• time interpolation or extrapolation
• conversion to node data
• drawing creation
• writer

If the MFIX input files use cylindrical coordinates, all references in m2e to x/y/z become references to radius/z/angle. Otherwise, the data flow is identical for rectangular and cylindrical coordinate systems.

3.2 Reader

The reader ignores the file extension in the name you provide. Instead, it sets the file extension itself and tries to read all possible MFIX files (i.e., .res, .sp1, .sp2, ...).

It then 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

The record length and endian-type of the input files may be changed on the command line though these options are very seldom needed (see Section 5, Command Line Options).

3.3 Variable Filter

Many MFIX variables are defined for several species (i.e., types of materials) and for several phases (e.g., gas, solid). These are called "variants" of the variable. In m2e, a selection of a variable at the filter always selects all variants of the variable.

The command-line option -v can be used any number of times to select variables. When this option is not used at all, all variables are selected.

3.4 Space Filter

The space or geometry filter will discard a selected number of cells at the ends of the coordinate axes. There are 6 command-line options, one for the filter setting for each of the 2 ends of each of the 3 axes. Note that these options select the number of cells, not vertices, to be discarded.

When the MFIX coordinate system is cylindrical, some border cells must be removed using this filter for sensible results. The first cell in X (radius) as well as the first and last cells along Z (angle) should be removed. This corresponds to the commands -x0 1 -z0 1 -z1 1.

When no command-line option is used for the space filter, the default for each parameter is 0.

3.5 Time Filter

Each variable is given in the data file at its own list of simulation times (ST). These ST may be the same as those for other variables or completely different. Ensight, however, needs a single list of times that will be used for all variables. The command-line option -tm is used to select from 3 methods for creating a single list of times.

A setting of -tm 0 (the default) causes all ST for all variables to be used. If two or more variables use the "same" time, it is entered in the list only once. Two times are considered the same if they are closer than the time threshold set using the -tt option.

A setting of -tm 1 is the same as -tm 0 except that ST before and after the first and last user-specified filter times are removed from the list of ST. The filter times are set using the -t0 and -t1 options, respectively.

A setting of -tm 2 ignores the ST completely. Instead, it calculates a new set of times using the first and last user-specified filter times and the time increment set with the -ti option.

3.6 Time Interpolation or Extrapolation

The program attempts to produce all selected variables at all selected times. 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 a time in the list, it is said to be "missing" at that time.

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:

0 - return no data (not recommended) 1 - use data from the time nearest to the current time 2 - use data from the nearest earlier time 3 - use data from the nearest later time 4 - estimate the value using the two nearest times and linear interpolation

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

0 - return no data (not recommended) 1 - use data from the time nearest to the current time

3.7 Conversion to Node Data

By default, m2e will provide Ensight with data attached to the cells. Ensight will silently convert cell data to node data when needed for, say, an isosurface. This generally works fine.

When detailed and exact visualizations are needed, better results can be attained by performing the conversion to node data in m2e. Two types of conversion are available.

3.7.1 Averaged Node Data

Node data for the standard grid is calculated by taking the average of the cell values around the node. Cells are included in the average only if they are of type 1 (fluid).

When the MFIX coordinate system is cylindrical, the average correctly uses cells on both sides of the cut plane (at the zero angle) and around the central axis. Often, general graphics libraries fail to convert cylindrical MFIX cell data to the node data required for, say, isosurfaces.

3.7.2 Cell-Centered Node Data

This approach begins by defining a new cell-centered grid where each node is at the center of a cell in the standard grid. This grid will be correct for both the MFIX cartesian and cylindrical coordinate systems.

Node data for the cell-centered grid is actually the original cell data - only the grid is changed.

The greatest advantage of the cell-centered option will occur when the visualization method requires node data (e.g., an isosurface) and the variable changes significantly from position to position. In this case, the difference between the cell-centered and averaging methods (whether by m2e or Ensight) can be quite noticeable (see Figure 3.1).

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

Figure 3.1   Isosurfaces using averaged node data (left) and cell-centered node data (right)		Figure 3.2   Cell-centered grid stops half a cell from the boundary of the standard grid

3.8 Drawing Creation

A small number of drawings will be generated to show the location of certain cell types. Each will consist of an unstructured grid where all of the cells are 4-node quads. The quads will represent the outer boundary of each group of like cells; no interior cell boundaries will be shown. No data will be attached to a drawing.

The following list is used in m2e to look for drawings. If no cells of a given type are found in the MFIX data, the corresponding drawing will not be created. This list can be easily extended (please contact PSC to extend the list). Many of the cell types in this list will be found only at the edges of the grid; therefore, if these cells are removed by the Space Filter they will not be drawn.

• obstruction (types 100 to 100) (see note)
• velocity_inlet (types 10 to 10)
• mass_inlet (types 20 to 20)
• velocity_outlet (types 11 to 11)
• mass_outlet (types 21 to 21)

Note: the drawing of the obstructions includes an extra step that attempts to remove cells from the drawing that are part of the outer wall, or that fill in the corners to form a cylindrical chamber.

In Ensight, each drawing will be listed as a separate part in its Part Loader with the name given in the above list. You must direct Ensight to load these parts. Once loaded, the part's color and rendering can be set using the same options used for visualization objects.

3.9 Writer

The general idea of the Writer is to take the output of the pipeline and write it to files that can be read by Ensight. However, there are options that instead write internally-generated test data or which print a short summary of the data.

3.9.1 Summary

When the -i option is entered, the output consists of a summary of the dataset including a description (from the restart file), date, time, version and the size of the coordinate grid. No files are created. When this option is not used, the same summary is placed at the start of the case file.

3.9.2 Files

The Writer component creates a series of files in the Ensight Gold format in the current directory using the single-file method for transient data. These files will include the case file, the geometry file, and one file for each variable and variant of a variable. For example, an MFIX dataset that includes 4 variables, one of which is defined for 3 species, will result in 8 files (case, geometry and 6 variable files).

By default, m2e will not overwrite existing files - it will stop with an error message. The option -o will tell m2e to overwrite existing files.

The Ensight case file will begin with a long list of "comments" that include a summary of the dataset, the options used by m2e, and a list of the drawings that were generated by m2e.

The names of the output files are constructed using part of the input file name and other information. The input file name, with the directory (if any) and extension (if any) removed, is called [base]. Output file names are:

[base].cas

The Ensight case file

[base].geo

The Ensight geometry file

[base]_[var]_[p**][s**][node].[tuple]

The Ensight data files

In all cases, the ** are replaced with sufficient leading zeroes to ensure that the number of characters are the same for all files for a given variable.

The names for the data files include several parts so that each variable, variant and time has a unique name:

[var]

Variable name such as EP_g.

[p**]

Primary variant numbered from 0; not used if not needed. The letter is the first letter of the name of the primary variant. For example, if the primary variant is "phase" the letter is "p".

[s**]

Secondary variant numbered from 0; not used if not needed. The letter is the first letter of the name of the secondary variant. For example, if the secondary variant is "species" the letter is "s".

[node]

This field indicates whether the data is cell data (nothing), averaged node data (_na) or cell-centered node data (_nc).

[tuple]

"sca" or "vec" for scalars/vectors (all vectors have 3 elements).

3.9.3 Data Structure

By default, m2e converts the MFIX structured grid to an unstructured grid consisting of 8-node hexagonal cells. This is called the standard grid. When node data is created using the cell-center method, a similar cell-centered grid is also written.

3.9.4 Inactive Cells

Any MFIX cell that is not flagged as being fluid is considered an inactive cell and is not written. This rule is used for both the standard and the cell-centered grids. Ensight will correctly leave "holes" in its visualization at inactive cell areas as small as one cell.

4. Calculated Variables

The user can edit the code in the file calc.c (distributed as a part of m2e) to define one or more new calculated variables using any combination of standard MFIX variables. In the following, the file calc.c will be referred to as CF while the calculated variables will be referred to as CV.

The program m2e will calculate a new variable only if it is explicitly requested on the command line using the -v option. In other words, a user may have definitions for dozens of CV in CF but can request them individually.

After CF has been changed, make must be run to update the program. Only this modified version of the program will support the new CV.

As distributed, CF includes two examples. Experienced C programmers may find it easier to understand how CF works by reading the code than by reading these explanations.

4.1 The Interface Routine

Each time a CV is needed, the interface routine calc (in CF) is called. If the user has requested more than one CV, calc is called once for each. The interface routine is passed several arguments:

• the name of the CV (from the command line)
• the format (from the command line; see 5.2)
• a pointer to the create flag (must be set to 1/0 in CF)
• a pointer to the vector length (must be set to 1/3 in CF)
• a pointer to the time flag (must be set to 1/0 in CF)

If calc does not recognize the new variable, it signals that the variable is unknown and returns. Otherwise, calc calls a worker routine (also in CF) to create the variable.

4.2 The Worker Routines

The program is distributed with two example worker routines: calcVar1 and calcVar2. Any number of worker routines can be used. A worker is responsible for creating the new variable at all time steps and writing it to a file.

Each worker routine must first use getVariableInfo to check for the presence of the MFIX variable(s) that are needed to calculate the new variable. If not available, the worker routine should signal this and return.

int getVariableInfo(
char *varName,		/* MFIX variable */
enum MfixReaderFormat format,		/* Data format */
int *available,		/* Return: 0=no, 1=yes */
int *nX,		/* Return: num values in X */
int *nY,		/* Return: num values in Y */
int *nZ		/* Return: num values in Z */
)

The size of the array (nX, nY, nZ) is the number of cells or the number of nodes, as indicated by format, after the space filter.

If the variable(s) are present, the worker then opens the output file with openCalcFile; loops over time; closes the output; and then signals that the new variable has been created.

int openCalcFile(
char *varName,		/* New variable */
enum MfixReaderFormat format,		/* Data format */
int veclen,		/* Vector length (1 or 3) */
FILE **file		/* Return: file pointer */
)

4.3 The Worker Time Loop

Many methods could be used to calculate a new variable. Here and in the examples, the most straight-forward method is used where, at each time step, the new variable is calculated using one or more MFIX variables at the same time step. For each time step, the worker routine

• gets one or more MFIX variables at that time using getVariable
• calculates the new variable
• writes the new variable using writeVariable

Data is obtained from the input MFIX files using this routine:

int getVariable(
char *name,		/* MFIX variable */
int indexPrimary,
int indexSecondary,
enum MfixReaderFormat format,		/* Data format */
int iTime,		/* Time index (0,1,...) */
int **dataInt,		/* Return: int data */
float **dataFloat		/* Return: float data */
)

The primary and secondary indices select the species and/or phase of the MFIX variable. Zeroes can always be supplied. All information about a MFIX variable is available using the C variable choices which is an array of data structures of type MfixReaderDataChoice.

A pointer to the data is returned in either dataInt or dataFloat but never in both. Only the cell types are integer.

The new variable for one time step is written to the Ensight file using this routine:

int writeVariable(
FILE *file,		/* File pointer */
char *description,		/* Any short string */
int veclen,		/* Vector length */
enum MfixReaderFormat format,		/* Data format */
float *dataF		/* Data */
)

4.4 Managing Errors and Flags

An error can occur at any point. Some are caused by events outside of m2e (e.g., a full disk) while some are simple incompatibilities (e.g., a MFIX data set not containing a requested variable). Protocols and flags are provided throughout this package that allow an intelligent response to problems.

The flag created is provided to calc and passed on to the worker routines. It should be set to 1 if and only if the requested CV was successfully created and written to a file. For example, in calcVar1, created is set to 1 only after all time steps have been successfully written to the output file.

In addition, when the creation of a new variable is successful, the worker routine should set veclen to the number of components in the new variable (1 or 3); and, it should set useTime to 0 (only one time step) or 1 (all time steps defined).

These three routines, used to read and write data, all signal an error in two ways: by setting the global flag kStatus to zero; and by returning kStatus as the routine's value.

• openCalcFile
• getVariable
• writeVariable

Worker routines should always check the kStatus flag. For example, the status after a call to openCalcFile could be tested two ways:

• if( !openCalcFile( ... ) ) goto error;
• openCalcFile( ... ); if( !kStatus ) goto error;

These routines will print a description of any problem to standard output. In other cases where a CV cannot be created, it is nice to print a message to standard output telling the user what has happened.

5. Command-Line Options

m2e [options] filename

In the following, the default value is shown in parenthesis.

5.1 Reader Options

filename

The name of any input file in the MFIX data set (required, no default)

-endian integer

Input file binary form where 0 means little endian and 1 means big endian (1)

-recl integer

Input file record length in bytes (512)

5.2 Variable Filter and Node Conversion Options

-na

Request node data using the averaging method

-nc

Request node data using the cell-center method

-v string

Request one variable (all). Can be used multiple times. The string must be one of the standard MFIX variables (listed below) or one of the calculated variables defined in the file calc.c.

celltype
EP_g
P_g
P_star
Vel_g
Vel_s
ROP_s
T_g
T_s
X_g
X_s
THETA_m
scalar
r-rate
K_Turb_G
E_Turb_G

When no standard MFIX variables are requested with the -v option, all standard MFIX variables that are available will be used. Otherwise, only the requested standard MFIX variables are used. This rule is unaffected by requests for calculated variables.

Each variable that is selected for processing can be sent to Ensight in up to 3 formats: cell data, averaged node data, and/or cell-centered node data. Format(s) for a variable are used if the format was in effect when the variable was implicitly or explicitly requested. Some examples:

m2e file

All standard MFIX variables will be sent to Ensight using the cell data format.

m2e -na file

All standard MFIX variables will be sent to Ensight using the averaged node data format.

m2e -na -v XYZ file

All standard MFIX variables plus the calculated variable XYZ will be sent to Ensight using the averaged node data format.

m2e -v EP_g -na file

Only EP_g will be sent to Ensight using the cell data format. The -na option has no effect.

m2e -v EP_g -na -v EP_g -nc -v EP_g file

Only EP_g will be sent to Ensight using all three formats.

Any variable converted to node data by the averaging or cell-center method will have _na or _nc appended to its name, respectively.

5.3 Space Filter Options

-x0 integer

Cells skipped at start of X axis (1)

-x1 integer

Cells skipped at end of X axis (1)

-y0 integer

Cells skipped at start of Y axis (1)

-y1 integer

Cells skipped at end of Y axis (1)

-z0 integer

Cells skipped at start of Z axis (1)

-z1 integer

Cells skipped at end of Z axis (1)

5.4 Time Filter Options

-tm integer

Method for setting times (0)

0 - use all times
1 - use all times from t0 to t1, inclusive
2 - calculate new times using t0, t1 and ti

-tt float

Threshold for equating times (0.001)

-t0 float

First time (0.0 seconds)

-t1 float

Last time (1000000.0 seconds)

-ti float

Time increment (0.001 seconds)

5.5 Time Interpolation and Extrapolation Options

-tp integer

Time interpolation mode (4)

0 - never
1 - use the nearest time
2 - use the nearest previous time
3 - use the nearest following time
4 - use linear interpolation

-te integer

Time extrapolation mode (1)

0 - never
1 - nearest

5.6 Writer Options

-i

Only show a summary of the dataset (don't show)

-o

Overwrite existing files (don't overwrite)

-s

Write the data as a structured block (unstructured cells)

5.7 Other Options

-h

Only show a summary of the command-line options (don't show)

-bug integer

Debug level. An integer from 0 to 10, inclusive, where 0 produces no debug messages and 10 produces a great many messages (0)