MfixReader User Guide

5. Requesting Metadata

An application should obtain metadata rather than making assumptions about the nature of an MFIX dataset. With proper use of the metadata, an application will continue to work correctly even as the MFIX datasets develop and change.

5.1 Overall Metadata

Once a dataset has been opened, metadata that applies to the entire dataset can be obtained using

int MfixReaderGetInfo(
 int handle,
 int *nInfo,
 struct MfixReaderInfo **info
)

The information is returned as an array of data structures where the array is of length nInfo.

5.1.1 Dataset Metadata Structure

Each item of metadata is returned using a structure designed to accomodate a wide range of information:

struct MfixReaderInfo {
 char *keyword;
 enum MfixReaderDataType dataType;
 int nValues;
 int *iValue;
 float *fValue;
 char **cValue;
}

Each item contains one type of data indicated by the parameter dataType which can be

  • MRD_integer
  • MRD_float
  • MRD_string

One of the three data pointers will point to an array of the appropriate type. The other pointers will be zero.

Each metadata item is returned in an array of length nValues. Currently, all arrays are of length 1, 2 or 3 but that may change in the future. Note that items that are one value are still returned as an array (of length 1).

5.1.2 Keywords

The current version of the MFIX reader library returns information for the following keywords. Future versions of the library may extend this list.

dims
An array of 3 integers giving the size of the data arrays after the space filter, i.e., the size of the arrays returned when data is requested. These integers will always be at least one.
dimsoriginal
An array of 3 integers giving the size of the data arrays before the space filter.
ntimes
An integer giving the number of time steps. Equal to the maximum of the number of time steps for each variable.
timespan
An array of 2 floats giving the first and last time, in seconds. Calculated using all variables.
date
An array of 3 integers giving the month, day and year when the dataset was created.
time
An array of 3 integers giving the hour, minute and seconds when the dataset was created.
version
An array of 2 integers giving the major and minor MFIX dataset version.
name
An array containing pointers to two strings containing the two run names provided in the restart file.
type
A string giving the type of MFIX run.
description
A string describing the MFIX run.
units
A string giving the units (example: CGS).
coord
An integer indicating the coordinate system: MRC_cartesian (1) or MRC_cylindrical (2).
ngasspecies
An integer giving the number of gas species.
nsolidphases
An integer giving the number of solid phases.
nsolidspecies
An integer array of length nsolidphases where each element of the array gives the number of solid species for one solid phase.
nscalars
An integer giving the number of scalars.
nreactionrates
An integer giving the number of reaction rates.

5.2 Metadata for Variables

Metadata for every variable in any open dataset can be obtained using

int MfixReaderGetDataChoices(
 int handle,
 int *nChoices,
 struct MfixReaderDataChoice **choices
)

The information is returned as an array of data structures where the array is of length nChoices.

The metadata for each variable is returned using a structure :

struct struct MfixReaderDataChoice {
 char *variableName;
 char *variableDesc;
 char *primaryName;
 int primaryCount;
 char *secondaryName;
 int *secondaryCount;
 char *units;
 enum MfixReaderDataType dataType;
 enum MfixReaderAttach attach;
 int veclen;
 int nTimes;
 float *times;
 int available;
}

The current variable names for an MFIX dataset, along with their variants (if any), are:

  • celltype
  • EP_g
  • P_g
  • P_star
  • Vel_g
  • Vel_s (phase)
  • ROP_s (phase)
  • T_g
  • T_s (phase)
  • X_g (species)
  • X_s (phase,species)
  • THETA_m (phase)
  • scalar
  • r-rate
  • K_Turb_G
  • E_Turb_G

Note that the exact name of a variable must be used when making a request for data.

The descriptions are 1 to 4 word phrases such as "void fraction" and "solid species mass fraction."

The primary and secondary variant names are "species" and/or "phase". A variable may have no variants; only primary variants; or both. A variable will never have only secondary variants.

When a variant is not used, the pointer to the variant name will be null and the associated count will be zero. Otherwise, the count is the number of variants. Note that secondaryCount is an array of integers where each element of the array is the number of secondary variants for the corresponding primary variant.

The data type can be

  • MRD_integer
  • MRD_float
  • MRD_string

All MFIX data is cell-based; however, for generality, the type of data attachment can be

  • MRA_cell for cell-based data
  • MRA_node for node-based data

The vector length, veclen, for MFIX data is always 1 or 3.

The number of times, nTimes, applies to that specific variable and excludes time steps where the full data array is not found in the file (i.e., where the program exited prematurely).

The available flag is somewhat redundant but can be used to quickly determine whether a particular variable (and its associated file) was found when the dataset was opened. When set to 0 (not available), certain other data (e.g., the number of time steps) are, of course, meaningless.



| Table of Contents |   | prev: Setting Parameters |   | next: Requesting Coordinates |