MfixReader User Guide

4. Setting Parameters

Most of these routines must be called after a reader instance has been created but before the dataset has been opened. The one exception is MfixReaderSetTimeRules which can be called repeatedly at any time.

4.1 Set Filename

int MfixReaderSetFileName( int handle, char *name )

Sets the name of a file in the dataset. May include path information. The file extension in this name is ignored; instead, the program tries all file extensions (.res, .sp1, .sp2, ...).

For each extension, the program also tries various combinations of upper and lower case.

For example, let's say that the filename was set to be myData.sp1. The program then begins with the restart file, trying each file on the following list until one is found:

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

MYDATA.res

The same process is applied to all the other file extensions.

4.2 Set Record Length

int MfixReaderSetRecordLength( int handle, int length )

Sets the record length of the MFIX files, in bytes. The default is 512.

4.3 Set Endian Type

int MfixReaderSetInputEndian( int handle, int endian )

Sets the endian type of the binary data in the MFIX files where the choices are 0 (small endian) or 1 (big endian, the default).

4.4 Set Space Filter

int MfixReaderSetLocationFilter( int handle, int skip[6] )

Sets the number of cells at the ends of the coordinate axes that will be discarded. There are 6 parameters, one for the 2 ends of each of the 3 axes. Note that this option selects 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 a skip array of [1,0,0,0,1,1].

When this parameter is not set, the default for each value is 0. In other words, by default, no cells are eliminated.

4.5 Set Data Time Tolerance

int MfixReaderSetDataTimeTolerance( int handle, float tol )

Sets the data time tolerance. The default is 0.000001.

The times in each MFIX data file should be monotonically increasing, i.e., each time in the file time2 should be greater than or equal to the previous time in the file time1. The actual test is

time1 - tolerance <= time2

If this test fails, the reader will issue an error message and quit.

However, when an MFIX simulation is restarted, the times in a data file after the restart may repeat one or more times already stored in the file. For such a data file to be accepted, the tolerance should be set to a larger number. A value equal to 3 times the internal MFIX time step, for example, will often be sufficent.

4.6 Set Time Rules

int MfixReaderSetTimeRules( int handle, float tolerance, enum MfixReaderExtrapolation extrapRule, enum MfixReaderInterpolation interpRule )

Sets the rules used for missing times. The defaults are 0.000001, MRE_nearest_any and MRI_linear, in that order.

The program attempts to provide requested variables at the requested time. Some variables, however, may not be given in the data file at a time "equal" to the requested time. Two times are considered equal if they are closer than the time tolerance set by this routine.

When a variable is not in the data file at the requested time, 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 defined in the reader's header file:

MRI_never: return no data (not recommended)
MRI_nearest_any: use data from the time nearest to the current time
MRI_nearest_prev: like MRI_nearest_any but limited to times before the current time
MRI_nearest_next: like MRI_nearest_any but limited to times after the current time
MRI_linear: estimate the value using the two nearest times and linear interpolation

The extrapolation rule can be set to one of these values defined in the reader's header file:

MRE_never: return no data (not recommended)
MRE_nearest_any: use data from the time nearest to the current time