m2t User Guide

For m2t 1.4 released September 18, 2003

This user guide describes the installation and use of m2t, a program that reads MFIX datasets and prints a text version of the data and metadata. Please send questions and comments to PSC User Services.

1. Introduction

It can be useful to convert parts of the information in a scientific dataset to plain text. Of course, printing megabytes of data is pointless. The program m2t prints MFIX data with an extensive set of command-line options 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 printing data.

The current version of m2t does not process data from the *.sp9 file.

2. Installation

It is recommended that a separate directory be created to hold m2t. The directory can be located anywhere. To download the program, see http://sc-2.psc.edu/mfix.

Unpack the downloaded file, edit the makefile if needed, then run make. Add the m2t directory to your environmental variable PATH or move the m2t executable to a directory already in your path.

3. Operation

This section discusses the operation of the program. All options are set using the command-line options (Section 4).

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
writer

If the MFIX input files use cylindrical coordinates, all references in m2t 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 though that is seldom needed.

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 m2t, 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, 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 no command-line option is used for the space filter, the default for each parameter is 1. In other words, by default, the boundary cells are eliminated.

3.5 Time Filter

Each variable is given in the data file at its own list of times. These times may be the same as those for other variables, or completely different.

The first and last times that are printed are set using the -t0 and -t1 options, respectively.

3.6 Writer

The output always begins with a summary of the dataset that includes a description (from the restart file), date, time, version and the size of the coordinate grid. When the -i option is entered, output stops after the summary.

Otherwise, the information shown by the summary is followed by the coordinates and a list of the selected variables. For each variable, a description of the variable (e.g., units, type) is followed by the variable's data for each selected time step.

When the option -method 0 is selected (the default), only the minimum, average and maximum for the variable is shown. When -method 1 is selected, all of the values for the variable are printed.

4. Command-Line Options

m2t [options] filename

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

4.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)

4.2 Variable Filter Options

-v string

Variable to convert where the choices are:

If the -v option is not given, all variables are used.

4.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)

4.4 Time Filter Options

-t0 float: First time (0.0 seconds)
-t1 float: Last time (1000000.0 seconds)

4.5 Writer Options

-i

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

-method integer

Select output method where the choices are (0):

4.6 Other Options

-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)
-h: Only show a summary of the command-line options (don't show)