RSS Feed MfixReader User Guide
7. Requesting Data
One or more variables at a single time in any open dataset can be obtained using:
int MfixReaderGetData(int handle,
float dataTime,
int nRequests,
struct MfixReaderDataRequest *requests
)
The time is given in seconds. As described elsewhere, variables not available in the file for the requested time are generated using the interpolation or extrapolation rules and parameters.
The number of variables obtained by a particular call to this routine is set by nRequests. Requests for variables that are not available do not cause errors.
During any particular call to this routine, the requested variable(s) are read from the files in the optimum order, not necessarily in the order in which they are requested. For example, if two requested variables are stored in the same file, the variable found first in the file will be read first. This means that slightly better performance will result if a single call to this routine is used instead of multiple calls, for a given time step.
7.1 Request Structure
The following data structure is used to both make the request and to return the results:
struct MfixReaderDataRequest {char *variableName;
int primaryNum;
int secondaryNum;
int component;
enum MfixReaderFormat format;
char *units;
enum MfixReaderDataType dataType;
enum MfixReaderAttach attach;
int veclen;
int interpolated;
float dataTime[2];
int *dims;
int *dataInt;
float *dataFloat;
}
The first five items in this structure define the data request and are not changed by the routine. The remaining items are information returned by this routine and will be zero when a variable cannot be found.
The units, dataType, and attach parameters returned in the structure are copies of the metadata for the variable.
7.2 Variable Selection
The variable name in the request must be an exact match to an available variable.
The request includes the primary and secondary variant indices, primaryNum and secondaryNum. If the variable has no variants, these are ignored. Otherwise, they should be a zero-based index into the list of variants for the variable. A negative variant index is treated as if it was zero.
If the variable uses primary variants (even if there is only 1), the requested primary variant index must be in range (i.e., it must be no more than one less than the number of variants). Otherwise, the variable is considered to be unavailable.
If the variable also uses secondary variants (even if there is only 1), the requested secondary variant index must be in range; otherwise, the variable is considered to be unavailable.
7.3 Vectors
The requested component is ignored if the variable is a scalar. Otherwise, this value indicates the component index (0, 1 or 2). All components are returned if this value is negative or greater than 2. The length of the vector is returned in veclen.
7.4 Format Selection
The format parameter selects one of three data formats:
- MRF_cell
- cell data defined for the standard grid
- MRF_node_average
- node data defined for the standard grid
- MRF_node_center
- node data defined for the cell-centered grid
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.
Node data for the cell-centered grid is actually the original cell data - only the grid is changed. This data must be used, of course, with the cell-centered coordinates obtained using MfixReaderGetCoordinates.
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, averaging can cause a noticeable change in the result (see Figure 7.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 7.2).
7.5 Time Selection
If the data that is returned was interpolated, the interpolated flag is 1 and the two times used for the interpolation are returned in dataTime.
When interpolation is not used, the flag is 0 and the times returned are both set to the time used.
When a time that is compatible with the requested time and the time rules cannot be found, the variable is considered to be unavailable. This can happen if, for example, the extrapolation rule is set to "never" and the requested time is greater than the greatest time for which the variable is available.
7.6 Order of the Data
The data is stored in the returned arrays in this order:
- vector component varies fastest
- x (or radius) from min to max
- y (or height) from min to max
- z (or angle) varies slowest, from min to max
|
| |
| Figure 7.1 Isosurfaces using averaged node data (left) and cell-centered node data (right). | Figure 7.2 Cell-centered grid stops half a cell from the boundary of the standard grid. |