MOAB: Mesh Oriented datABase  (version 5.2.1)
Go to the documentation of this file.
00001 /*! \page metadata I/O and Meta-Data Storage Conventions in MOAB
00003     <Center> <H3>   Timothy J. Tautges </H3> </Center>
00005     \subpage  md-contents
00007     \subpage  md-tables
00008 */
00010 /*!  \page md-contents Table of Contents
00012   \ref meta-introduction
00014   \ref meta-conventions
00016   \ref meta-options
00018   \ref meta-references
00020   \ref appendixA
00022   \ref appendixB
00024   \ref appendixC
00026   \ref appendixD
00028   \ref appendixE
00030   \section meta-introduction  Introduction
00032 The Mesh-Oriented datABase (MOAB) is a library for representing finite element and other types of mesh data [1].  Various types of meta-data are often used in conjunction with a mesh.  Examples include boundary condition groupings, material types, and provenance information for the mesh.  Because the data model used in MOAB is so abstract, conventions are useful for describing how meta-data is stored into that data model.  This document describes those conventions for several types of data commonly found in meshes stored in MOAB.  Because the data models used by MOAB and iMesh, the ITAPS mesh interface [2], are so similar, the conventions described here apply almost unmodified to iMesh as well as to MOAB.
00034 The meshes represented in MOAB originate in a variety of forms, including mesh read from files of various formats (e.g. CUBIT “.cub” file, VTK, etc.) as well as mesh written into MOAB directly by various software libraries (e.g. MeshKit).  Although there is no standard for naming or storing meta-data with a mesh, there is a great deal of commonality in the types of meta-data typically found with mesh data.  This document describes conventions that have been established for commonly encountered meta-data.  Various mesh readers implemented in MOAB attempt to read meta-data from a file and write it into the MOAB data model using these conventions.  Although there is no requirement to store a given type of meta-data in the form described here, a number of services have been written to handle meta-data using these conventions, no matter the source of the meta-data being processed.
00036 Several specific tools are often used in concert with MOAB and bear special mention here.  The CUBIT toolkit generates finite element meshes, and saves them to a native save file (referred to as a “.cub” file) which MOAB is able to read.  Reading CUBIT meshes into MOAB through the .cub file format is preferred over other formats, since most other mesh formats written by CUBIT do not save most meta-data.  The MeshKit library also generates mesh using CGM and MOAB, and uses the same conventions for storing meshes into MOAB.  Finally, MOAB includes a CGM reader which can read a geometric model into a faceted representation in MOAB.  Meta-data from all these tools are stored in MOAB using the conventions described here.
00038 The MOAB data model consists of the following basic types:
00039 - <B>Entity</B>: The basic elements of topology, e.g. vertex, edge, triangle, tetrahedron, etc.  MOAB represents all types in the finite element zoo, plus polygons and polyhedra.
00040 - <B>Entity %Set</B>: An arbitrary collection of entities and other sets.  Sets can have parent/child relations with other sets, and these relations are distinct from “contains” relations.
00041 - <B>Interface</B>: The interface object through which other entities are accessed, in the sense of object-oriented-programming.  iMesh refers to the interface as the “root” set.
00042 - <B>Tag</B>: A piece of data that can be assigned a distinct value to each entity and entity set, and to the interface itself.  Tags have a prescribed name, size in bytes, and data type; allowed data types are integer, double, entity handle, and byte or opaque.
00043 .
00045 The following section describes each meta-data tag convention in detail; these conventions are also summarized in Table 1.
00047 \ref md-contents "Top"
00049   \section meta-conventions  Meta-Data Conventions
00051 Meta-data is stored in MOAB and iMesh in the form of tags applied to either entities or entity sets.  For meta-data represented as entity sets, the contents of those sets are determined by the convention, with tags on those sets identifying them with the convention and adding any other semantic data.
00053 Each meta-data convention is described in a subsection below.  Each convention begins with a short description of:
00055 - Whether tags associated with the convention are assigned to entities or entity sets
00056 - The tag(s) associated with the convention; information for each tag includes the name, the data type (I=integer, D=double, C=character, H=handle), and the tag length.  Tag lengths are specified after an asterisk (*); for example, C*32 implies a tag with character type and length 32.  Unspecified lengths correspond to length one.
00057 .
00059 <H3>Name</H3>
00060 (Data: Entity sets, entities; Tag(s): NAME/C*32)
00062 Character strings are used in many different contexts in applications.  MOAB uses the “NAME” tag to store character strings used to name entities.  This tag is of byte-type and is of length 32 bytes.  Note that the string stored in this tag may or may not be terminated with a NULL character.  It is always prudent account for missing NULL terminator, to avoid buffer overflow errors in the application.  Applications are free to define their own version of the NAME tag with a longer length, though this definition may conflict with other services attempting to use this tag with the conventional size.  Applications needing a string tag with a longer or variable length can also use MOAB’s variable-length tag type, though this will not be compatible with iMesh.
00064 <H3>Title </H3>
00065 (Data: Entity sets (file or instance); Tag(s): TITLE/C*strlen)
00067 The title tag is meant to hold the overall identifier of a mesh, written at generation time or read from a file generated with a non-MOAB tool.  The tag length is variable, and is set by the application directly (by calling the tag_create function) or indirectly (by embedding the title in a file read by MOAB).
00069 <H3> Global Identifier </H3>
00070 (Data: Entity sets, entities; Tag(s): GLOBAL_ID/I)
00072 Global identifiers are used in many different contexts in applications.  Geometric model entities are identified by dimension and id, e.g. “Volume 1”.  Mesh vertices and elements are identified similarly in mesh generation codes.  Boundary conditions and material types are identified similarly.  This tag is used to store such information.  This tag is currently stored in a 32-byte integer, though this may change in the future.
00074 <H3> Geometric Model Information </H3>
00077 Mesh generation is often performed starting from a geometric model, represented in some form of CAD engine.  Many of the meshes used by MOAB are generated based on the CGM library.  Geometric models contain both topological information (the topological entities in the geometric model) and shape information (the geometric shape of those entities), as well as other meta-data written to the entities in a model.  When a mesh is read from a CUBIT .cub file, meta-data from the geometric model is read and represented in the MOAB data model, as described below. <B> Note that although MOAB reads and represents meta-data associated with the geometric model, it does not represent the geometric model itself.</B>  Therefore, shape-related information, e.g. the arc length of an edge or surface normal at a given point, can be retrieved only from the model represented in CGM or another geometric modeling engine.
00079 The information contained in a geometric model, read into and represented in MOAB, consists of:
00080 - Model entities (vertex, edge, face, volume)
00081 - Topological relationships between model entities
00082 - Groups of model entities
00083 - Model entity/group ids
00084 - Model entity/group names
00085 .
00087 The storage of this information into MOAB's data model is described for each type is described below.
00089 - <B>Entities </B>
00091  in the geometric model (VERTEX, EDGE, FACE, VOLUME) are each represented by an entity set<sup>1</sup>.  These sets are tagged with the “GEOM_DIMENSION” tag, with integer value equal to the topological dimension of the entity (VERTEX = 0, EDGE = 1, etc.)  These sets contain the mesh owned by the corresponding entity in the geometric model.  Note this does not include mesh owned by bounding entities; thus, the set for a FACE will not contain the mesh vertices owned by bounding EDGEs in the geometric model.  These sets may or may not contain mesh entities of intermediate dimension, e.g. mesh edges owned by a FACE or faces owned by a VOLUME, depending on the application generating the mesh or the file from which the mesh was read.  These sets are all set-types, i.e. the order of entities in the sets is not significant, except in the case of EDGE sets, where order of the mesh vertices and edges corresponds to the relative order of vertices and edges at the time of mesh generation.  In MOAB, these sets are non-tracking by default, i.e. entities do not have knowledge of which geometry sets they are members of.
00093 <sup>1</sup>Body-type entities from CUBIT are not explicitly represented in MOAB.
00095 - <B> Topological Relationships </B>
00097 In the geometric model, each FACE is bounded by zero or more EDGEs; other topological relationships between geometric entities exist in a similar manner.  These relationships are embedded in the data model using parent/child relations between entity sets.  For example, the entity set corresponding to a FACE will have child sets, each corresponding to a bounding EDGE, and parent sets, each corresponding to a VOLUME bounded by that FACE.  The relative order of sets in those parent/child lists is not significant, thus, “loops” bounding a FACE cannot reliably be inferred from this data.
00099 - <B> Groups </B>
00101 Geometric entities are sometimes assigned to application-specific groups.  These groups are represented using entity sets, tagged with a “GROUP” tag whose value equals the group id.  Group sets are “set”-type, and are not tracking sets.  These sets contain the sets corresponding to geometric entities contained in the groups in the geometric model, as well as any mesh entities assigned to the group.
00103 - <B> Sense </B>
00105 A geometric face has a natural orientation, indicated by the direction of the normal to the face; similarly, edges have a natural orientation determined by the direction of the tangent.  When faces bound regions, or edges bound faces, they do so with a sense; if a region includes a face with forward sense, that means the face's natural normal direction points out of the volume.  If a face includes an edge with forward sense, that means that if one moves along the edge in the direction of its tangent, the material of the face is on the left hand side.  The sense of a face (edge) with respect to a region (face) it bounds is stored using tags on the face (edge).
00107 Most models allow a face to be part of only two regions.  Therefore, to store the sense of a face with respect to regions including it, a tag with two values is used.  This tag is named GEOM_SENSE_2, and has 2 EntityHandle values.  The first value corresponds to the entity set for the region for which that face has a forward sense, and the second to the region for which that face has a reverse sense.
00109 Edges can bound more than two faces.  Therefore, two variable-length tags are used, one to store the EntityHandles of the faces the edge bounds, and the other to store the sense with which the edge bounds the corresponding face.  These tags are named GEOM_SENSE_N_ENTS and GEOM_SENSE_N_SENSES, respectively.  These are stored as variable-length tags; see the MOAB user's guide for information on how to work with tags of this type.
00111 The following sense values are used:
00112 - 0: forward
00113 - 1: reverse
00114 - -1: unnknown
00115 .
00117 <H3> Material Type </H3>
00118 (Data: Entity sets; Tag(s): MATERIAL_SET/I)
00120 Most finite element and other PDE-based analysis codes require a material type for each cell or element in the simulation.  MOAB uses entity sets to store this information, in the form of entity sets.  The MATERIAL_SET tag is used to identify these sets.  The value of this tag is conventionally an integer; in most cases this stores a user-assigned identifier associated with that material.
00122 CUBIT assigns material types using what it calls “element blocks”, with each element block given a user-assigned id number and optionally a name.  The CUBIT and Exodus file readers in MOAB read element blocks into MATERIAL_SET sets.
00124 In CUBIT, materials are typically assigned by assigning geometric volumes to element blocks.  Therefore, material sets often contain entity sets corresponding to those volumes.  Thus, a materrial set in MOAB is unlikely to contain mesh entities directly; rather, that set contains other sets which contain mesh entities.  In these cases, mesh entities can be retrieved by passing a “recursive” flag to the appropriate function (MOAB), or by calling the getEntitiesRec extension function (iMesh) provided by MOAB.
00126 <H3> Boundary Conditions (Dirichlet, Neumann)</H3>
00127 Data: Entity sets; Tag(s): DIRICHLET_SET/I, NEUMANN_SET/I)
00129 Boundary conditions are often specified in terms of geometric model entities, similar to material types.  MOAB uses entity sets to store this information as well.  The DIRICHLET_SET and NEUMANN_SET tags are used to represent Dirichlet- and Neumann-type boundary condition sets, resp.  By convention, Neumann sets usually contain (indirectly) intermediate-dimension entities like edges in a 2D mesh or faces in a 3D mesh, while Dirichlet sets usually contain vertices.  In addition, Neumann sets are represented as sets of faces, rather than as sides of elements.  Faces can be ordered “forward” or “reverse” with respect to one of the bounding elements, depending on whether the right-hand normal points into or out of the element.  Forward-sense faces are added to the Neumann set.  Reverse-sense faces are put into a separate set; that set is tagged with the NEUSET_SENSE tag, with value = -1; and that reverse set is added to the Neummann set.
00131 <H3> Parallel Mesh Constructs </H3>
00134 On a parallel computer, MOAB can represent the mesh on each processor as well as information about entities shared with neighboring processors.  Some of this information is also relevant even when the mesh is represented on a serial machine.  MOAB uses several tag and set conventions to describe the parallel nature of a mesh.  This information is summarized here; for a more complete description of MOAB’s parallel mesh representation and functionality, see [3].
00136 - <B> Parallel partition, parts </B>
00138 Most parallel mesh applications use a domain decomposition approach, where each processor solves for a subset of the domain.  The set of entities solved by a given processor is referred to as a part, and the collection of parts together is called the partition.  MOAB stores each part in an entity set, marked with the PARALLEL_PARTITION tag, whose value is the rank of the processor assigned that part; an entity set which contains all part sets is given the PARALLEL_PARTITIONING_TAG_NAME tag, whose value is currently meaningless.  The MBZoltan tool included as a tool in MOAB can partition a mesh for parallel solution, and writes the partition to the mesh in the form of parts and partitions.  Both these types of sets can be accessed in a serial mesh, e.g. for visualization.
00140 - <B> Part interfaces </B>
00142 When a partitioned mesh has been loaded on a parallel computer, the part on a given processor may share portions of its boundary with parts on other processors.  These shared regions are called part interfaces, and are also represented using entity sets.  These sets are marked with the PARALLEL_INTERFACE tag, whose value is currently meaningless.
00144 - <B> Shared processor and handle </B>
00146 For entities shared between processors, it is helpful to know locally which other processor shares an entity, and what the entity’s handle is on the remote processor.  There are two cases which are useful to distinguish, first where an entity is shared with only one other processor (referred to as shared), and second when a processor is shared by more than one other processor (referred to as multi-shared).   Shared entities are given the PARALLEL_SHARED_PROC and PARALLEL_SHARED_HANDLE tags, which store the rank of the sharing processor and the handle of the entity on that processor, respectively.  Multi-shared entities are marked with the PARALLEL_SHARED_PROCS and PARALLEL_SHARED_HANDLES tags; these tags have a length NP assigned at compile time in MOAB, with default values of -1 for processor rank and zero for handle (which are each invalid values for the corresponding data).  The processors/handles sharing a given entity are then written on the front of the arrays.  So, for example, an entity on processor rank 0, shared by processors 1 and 2, would have a PARALLEL_SHARED_PROCS tag whose values would be [1, 2, -1, -1, …], with PARALLEL_SHARED_HANDLES values of [m, n, 0, 0, …], where m and n would be the handles of that entity on processors 1 and 2.  The shared versions of these tags are “dense”, with default values which denote unshared entities.  The multi-shared tags are sparse tags in MOAB, with no default value.
00148 - <B> Parallel status </B>
00150 In addition to the tags above, MOAB also defines the PSTATUS tag, whose bits contain information about the parallel status of a given entity.  Starting with least significant bit, these bits represent whether an entity is 1) not owned, 2) shared, 3) multi-shared, 4) interface, 5) a ghost entity.  The first bit being set indicates “not owned” so that the default value for this tag, of zero, corresponds to an owned, unshared entity, which will be the state of most entities on a given processor.
00152 <H3>Structured Mesh Parameters </H3>
00154 MOAB has a structured mesh interface for creating structured mesh (see “ScdInterface.hpp” header file in MOAB source code).  Along with an internal representation that is more memory-efficient (since it does not need to store connectivity), MOAB also creates and tags entity sets with structured mesh parameters, which can be accessed through the normal tag and set interface.  The following tags are used:
00156 - <B>BOX_DIMS</B>: This tag stores the ijk coordinates of the lower and upper corner of the structured mesh box(es).
00157 - <B>GLOBAL_BOX_DIMS</B>: If specified when the structured mesh is created, a tag with this name stores the global box dimensions (which may be different than the local box dimensions).
00158 - <B>BOX_PERIODIC</B>: Stores whether the box is periodic in the i (BOX_PERIODIC[0]) and j (BOX_PERIODIC[1]) directions.
00159 - <B>__BOX_SET</B>: Pointer to the ScdBox instance corresponding to this entity set.<sup>2</sup>
00160 .
00161 Although the structured mesh is not saved as such in HDF5-format files, the entity sets and corresponding tags will be saved and restored.
00163 <sup>2</sup>The double-underscore in the tag name implies that this tag will not be saved in a file, in this case because the ScdBox instances are not preserved in a file.
00165 <H3>Spectral Mesh Constructs </H3>
00167 The Spectral Element Method (SEM) is a high-order method, using a polynomial Legendre interpolation basis with Gauss-Lobatto quadrature points, in contrast to the Lagrange basis used in (linear) finite elements.  A spectral mesh with order O contains quadrilateral or hexahedral elements comprised of (O+1)d vertices.  Spectral meshes are usually represented in one of two ways, either as coarse elements which point to an array of higher-order vertices (and with corner vertices represented in the normal manner), or as linear quads/hexes formed from the higher-order vertices, with each original coarse quad/hex represented by Od fine quads/hexes.  Similarly, the spectral variables, which are normally computed at fine vertex positions, are stored either on those vertices, or in lexicographically-ordered arrays on elements (with tag values repeated on neighboring elements).  MOAB can read spectral meshes from a variety of formats (at this time, including CAM-SE, HOMME, and Nek5000).  Which of the above two representations are controlled by read options and are indicated by certain tags:
00169 - SPECTRAL_MESH: read option indicating that spectral elements should be represented as coarse linear quads/hexes and each element containing an array of lexicographically-ordered vertex handles
00171 - TAG_SPECTRAL_ELEMENTS: read option; if given, spectral variables are represented as lexicographically-ordered arrays on elements
00173 - TAG_SPECTRAL_VERTICES: read option; if given, spectral variables are represented as tags on vertices
00175 - CONN=<filename>: in CAM-SE, the connectivity of the spectral mesh is stored by default in a file named “”; this option can be given to read the connectivity from a different file
00177 - SPECTRAL_VERTICES: tag name for array of vertex handles
00179 - SPECTRAL_ORDER: tag name for spectral order, written to file set or (if no file set given) to interface after a spectral mesh is read
00181 .
00183 \ref md-contents "Top"
00185   \section meta-options Reader/Writer Options
00187 All mesh file readers and writers in MOAB take an option string as an argument.  By default, the semicolon (“;”) delimits individual options in the option string.  Options used in multiple readers are described in this section; the options enabled in specific readers/writers are described in the corresponding appendix at the end of this document.
00189 <H3>variable=<var_name>[,...]</H3>
00191 By default, all field data stored with the mesh is read with the mesh, and stored as tags on the associated mesh entities.  This option lists specific variables that should be read along with the mesh (note also the “nomesh” option, described elsewhere in this document).  The variable name listed will be read into a tag with the same name.  For time-dependent variables, the time step number will be appended to the variable name to form the tag name.  If no “timestep” or “timeval” option is given, all time steps will be read, resulting in several tags being created.  If the “nomesh” option is given, the application must pass the entity set resulting from the original mesh read in to the function, that this set must contain the mesh read only from that file.  The mesh in the file is checked against the mesh in the set to verify that the two correspond.  The special name “MOAB_ALL_VARIABLES” can be used to indicate that all variables should be read.  Multiple variable names can be specified, separated from each other by commas.
00193 <H3>nomesh </H3>
00195 Indicates that no mesh should be read from the file.  This option is used in conjunction with the “variable=” option, to read variables and assign them as tags to a previously-read mesh.  If this option is used, applications should pass an entity set to the read function, which should contain the mesh previously read from the file.
00197 <H3>timestep=<step_number>[, ...] </H3>
00199 Read the time step number whose time value is equal to or greater than the specified time value, for the specified variable(s).  Tag names for the variable(s) will be formed by appending the time step number to the variable name.  Multiple time step values can be specified, separated from each other by commas.
00201 <H3>timeval=<time_value>[, ...]</H3>
00203 Read the time step number whose time value is equal to or greater than the specified time value, for the
00204 specified variable(s). Tag names for the variable(s) will be formed by appending the time step number
00205 to the variable name. Multiple time step values can be specified, separated from each other by commas.
00207 <H3>gather_set[=<rank>] </H3>
00209 Create a gather set (associated with tag GATHER_SET) on one processor with the specified rank, to duplicate entities on other processors. If the rank is not specified, it will be rank 0 by default. If an invalid rank is passed, no gather set will be created. Gather set is specially used by HOMME, MPAS, and any other unstructured grid.
00211 <H3>no_mixed_elements </H3>
00213 Indicates that no mixed elements (e.g. pentagons and hexagons) should be created by the MPAS reader. If this option is used, a common parameter maxEdgesPerCell will be computed to be used across all processors (instead of the one reported in the MPAS file header, which is usually 10), and each cell is created with maxEdgesPerCell edges. Any cell that has less actual edges will be padded by duplicating the last vertex in the connectivity array. As a result, all created cells will be in one contiguous chunk.
00215 <H3>no_edges </H3>
00217 Indicates that no edges should be created and no edge variables will be read. This option can be used when there is no need to read variables on edges. For a huge MPAS file with 65M cells, it can save more than 3GB MOAB internal storage for edge connectivity.
00219 \ref md-contents "Top"
00221   \section meta-references References
00223 [1]     T.J. Tautges, R. Meyers, K. Merkley, C. Stimpson, and C. Ernst, MOAB: A Mesh-Oriented Database, Sandia National Laboratories, 2004.
00225 [2]     L. Diachin, A. Bauer, B. Fix, J. Kraftcheck, K. Jansen, X. Luo, M. Miller, C. Ollivier-Gooch, M.S. Shephard, T. Tautges, and H. Trease, “Interoperable mesh and geometry tools for advanced petascale simulations,” Journal of Physics: Conference Series,  vol. 78, 2007, p. 012015.
00226 [3]     T.J. Tautges, J.A. Kraftcheck, N. Bertram, V. Sachdeva, and J. Magerlein,  "Mesh Interface Resolution and Ghost Exchange in a Parallel Mesh Representation", In Proceedings of the 2012 IEEE 26th International Parallel and Distributed Processing Symposium Workshops & PhD Forum (IPDPSW '12), 2012.
00228 \ref md-contents "Top"
00230   \section appendixA Appendix A: Summary
00232 \subsection table1 Table 1: Summary of MOAB meta-data conventions.
00234 <table border="1">
00235 <tr>
00236 <th>Convention</th>
00237 <th>Applies to (E=ent, S=set)</th>
00238 <th>Tag(s) (type/length)</th>
00239 <th>Description</th>
00240 </tr>
00241 <tr>
00242 <td>Name</td>
00243 <td>E, S</td>
00244 <td>NAME/C*32</td>
00245 <td></td>
00246 </tr>
00247 <tr>
00248 <td>Title</td>
00249 <td>S</td>
00250 <td>TITLE/C*strlen</td>
00251 <td>Title of mesh</td>
00252 </tr>
00253 <tr>
00254 <td>Global identifier</td>
00255 <td>E, S</td>
00256 <td>GLOBAL_ID/I</td>
00257 <td></td>
00258 </tr>
00259 <tr>
00260 <td>Geometric topology</td>
00261 <td>S</td>
00263 NAME/C*32,
00264 CATEGORY/C*32.
00265 GEOM_SENSE_2/EH[2],
00268 <td>%Sets contain mesh owned by that entity; parent/child links to bounded/bounding entities in geometric model</td>
00269 </tr>
00270 <tr>
00271 <td>Material type</td>
00272 <td>S</td>
00273 <td>MATERIAL_SET/I</td>
00274 <td>%Set contains entities or sets assigned a common material type</td>
00275 </tr>
00276 <tr>
00277 <td>Boundary condition</td>
00278 <td>S</td>
00280 <td>%Set contains entities or sets assigned a particular boundary condition; neumann sets usually contain edges (2D) or faces (3D)</td>
00281 </tr>
00282 <tr>
00283 <td>Parallel mesh constructs</td>
00284 <td>E, S</td>
00286 <td> Data which describes parallel mesh</td>
00287 </tr>
00288 <tr>
00289 <td>Structured mesh constructs</td>
00290 <td>S</td>
00292 <td>Data describing structured mesh </td>
00293 </tr>
00294 <tr>
00295 <td>Spectral mesh constructs </td>
00296 <td>E, S</td>
00298 <td>Data marking spectral mesh constructs</td>
00299 </tr>
00300 </table>
00302   \ref meta-introduction "Back to Introduction"
00304   \subsection table2 Table 2: Summary of MOAB conventional tag names, types, and purposes.  Data types are I=integer, D=double, C=character, H=entity handle,O=opaque.  Data type with *x denote length of x elements of that data type.
00306 <Table border="1">
00307 <tr>
00308 <th>Tag name</th>
00309 <th>Data type</th>
00310 <th>Applies to (E=entity, S=set)</th>
00311 <th>Purpose</th>
00312 </tr>
00313 <tr>
00314 <td>BOX_DIMS</td>
00315 <td>I*6</td>
00316 <td>S</td>
00317 <td>Lower and upper ijk dimensions of box, ordered (ilo, jlo, klo, ihi, jhi, khi)</td>
00318 </tr>
00319 <tr>
00320 <td>BOX_PERIODIC</td>
00321 <td>I*2</td>
00322 <td>S</td>
00323 <td>Indicates whether box is periodic in i (BOX_PERIODIC[0]) or j (BOX_PERIODIC[1])</td>
00324 </tr>
00325 <tr>
00326 <td>__BOX_SET</td>
00327 <td>O</td>
00328 <td>S</td>
00329 <td>Pointer to corresponding ScdBox instance</td>
00330 </tr>
00331 <tr>
00332 <td>CATEGORY</td>
00333 <td>C*32</td>
00334 <td>S</td>
00335 <td>String describing purpose of set; examples include “group”, “vertex”, “edge”, “surface”, “volume”</td>
00336 </tr>
00337 <tr>
00338 <td>DIRICHLET_SET </td>
00339 <td>I</td>
00340 <td>SO</td>
00341 <td>Entities or sets with common boundary condition</td>
00342 </tr>
00343 <tr>
00344 <td>GEOM_DIMENSION</td>
00345 <td>I</td>
00346 <td>S</td>
00347 <td>Identifies mesh entities resolving a given geometric model entity</td>
00348 </tr>
00349 <tr>
00350 <td>GEOM_SENSE_2</td>
00351 <td>EH*2</td>
00352 <td>S</td>
00353 <td> Stored on face-type geometric topology sets, values store regions having forward and reverse sense</td>
00354 </tr>
00355 <tr>
00356 <td>GEOM_SENSE_N_ENTS</td>
00357 <td>EH*N</td>
00358 <td>S</td>
00359 <td>Stored on edge-type geometric topology sets, values store faces whose senses are stored in GEOM_SENSE_N_SENSES.</td>
00360 </tr>
00361 <tr>
00362 <td>GEOM_SENSE_N_SENSES</td>
00363 <td>I*N</td>
00364 <td>S</td>
00365 <td>Stored on edge-type geometric topology sets, values store senses of the edge with respect to faces stored in GEOM_SENSE_N_ENTS.</td>
00366 </tr>
00367 <tr>
00368 <td>GLOBAL_ID</td>
00369 <td>I</td>
00370 <td>E,S</td>
00371 <td>Application-specific entity id</td>
00372 </tr>
00373 <tr>
00374 <td>MATERIAL_SET</td>
00375 <td>I</td>
00376 <td>S</td>
00377 <td>Entities or sets grouped by material type</td>
00378 </tr>
00379 <tr>
00380 <td>NAME</td>
00381 <td>C*32</td>
00382 <td>E, S</td>
00383 <td>User-assigned entity name(s); multiple names delimited with ?</td>
00384 </tr>
00385 <tr>
00386 <td>NEUMANN_SET</td>
00387 <td>I</td>
00388 <td>S</td>
00389 <td>Entities or sets with common boundary condition </td>
00390 </tr>
00391 <tr>
00392 <td>PARALLEL_PARTITION </td>
00393 <td>I</td>
00394 <td>S</td>
00395 <td>Represent a part in a partition</td>
00396 </tr>
00397 <tr>
00399 <td>I</td>
00400 <td>S</td>
00401 <td>Represents a partition of the mesh for parallel solution, which is a collection of parts</td>
00402 </tr>
00403 <tr>
00405 <td>H</td>
00406 <td>E, S</td>
00407 <td> Handle of this entity/set on sharing processor</td>
00408 </tr>
00409 <tr>
00410 <td>__PARALLEL_SHARED_PROC</td>
00411 <td>I</td>
00412 <td>E,S</td>
00413 <td>Rank of other processor sharing this entity/set </td>
00414 </tr>
00415 <tr>
00417 <td>H*NP</td>
00418 <td>E,S</td>
00419 <td>Handles of this entity/set on sharing processors </td>
00420 </tr>
00421 <tr>
00422 <td>__PARALLEL_SHARED_PROCS</td>
00423 <td>I*NP</td>
00424 <td>E,S</td>
00425 <td>Ranks of other processors sharing this entity/set </td>
00426 </tr>
00427 <tr>
00428 <td>__PARALLEL_STATUS</td>
00429 <td>C*1</td>
00430 <td>E,S</td>
00431 <td>Bit-field indicating various parallel information </td>
00432 </tr>
00433 <tr>
00434 <td>SPECTRAL_ORDER</td>
00435 <td>I</td>
00436 <td>S</td>
00437 <td> Order of a spectral mesh </td>
00438 </tr>
00439 <tr>
00440 <td>SPECTRAL_VERTICES</td>
00441 <td>H*(O+1)^d</td>
00442 <td>E</td>
00443 <td> Vertices comprising a spectral element, ordered lexicographically; here, O=value of SPECTRAL_ORDER tag. </td>
00444 </tr>
00445 </table>
00447 \ref md-contents "Top"
00449   \section appendixB Appendix B: CCMIO (Star-CD, Star-CCM+) Reader/Writer Conventions
00451   \subsection table3 Table 3: Translation between CCMIO options and MOAB tags.
00452 <Table border="1">
00453 <tr>
00454 <th> %Set Type</th>
00455 <th>CCMIO Construct</th>
00456 <th>MOAB Tag Name, Type</th>
00457 </tr>
00458 <tr>
00459 <td rowspan="2">File set / Interface</td>
00460 <td>Title (option)</td>
00461 <td>“Title” (C*32)</td>
00462 </tr>
00463 <tr>
00464 <td>CreatingProgram</td>
00465 <td>“CreatingProgram” (C*32)</td>
00466 </tr>
00467 <tr>
00468 <td rowspan="13">Material sets</td>
00469 <td>Index</td>
00470 <td>MATERIAL_SET</td>
00471 </tr>
00472 <tr>
00473 <td>Label<sup>1</sup></td>
00474 <td>NAME</td>
00475 </tr>
00476 <tr>
00477 <td>MaterialId</td>
00478 <td>“MaterialId” (I)</td>
00479 </tr>
00480 <tr>
00481 <td>Radiation</td>
00482 <td>“Radiation” (I)</td>
00483 </tr>
00484 <tr>
00485 <td>PorosityId</td>
00486 <td>“PorosityId” (I)</td>
00487 </tr>
00488 <tr>
00489 <td>SpinId</td>
00490 <td>“SpinId” (I)</td>
00491 </tr>
00492 <tr>
00493 <td>GroupId</td>
00494 <td>“GroupId” (I)</td>
00495 </tr>
00496 <tr>
00497 <td>ColorIdx</td>
00498 <td>“ColorIdx” (I)</td>
00499 </tr>
00500 <tr>
00501 <td>ProcessorId</td>
00502 <td>“ProcessorId” (I)</td>
00503 </tr>
00504 <tr>
00505 <td>LightMaterial</td>
00506 <td>“LightMaterial” (I)</td>
00507 </tr>
00508 <tr>
00509 <td>FreeSurfaceMaterial</td>
00510 <td>“Thickness” (F)</td>
00511 </tr>
00512 <tr>
00513 <td>Thickness</td>
00514 <td>“Thickness” (F)</td>
00515 </tr>
00516 <tr>
00517 <td>MaterialType</td>
00518 <td>“MaterialType” (C*32)</td>
00519 </tr>
00520 <tr>
00521 <td rowspan="5">Neumann sets</td>
00522 <td>Index</td>
00523 <td>NEUMANN_SET</td>
00524 </tr>
00525 <tr>
00526 <td>Label</td>
00527 <td>NEUMANN_SET</td>
00528 </tr>
00529 <tr>
00530 <td>BoundaryName</td>
00531 <td>NAME</td>
00532 </tr>
00533 <tr>
00534 <td>BoundaryType</td>
00535 <td>“BoundaryType” (C*32)</td>
00536 </tr>
00537 <tr>
00538 <td>ProstarRegionNumber</td>
00539 <td>“ProstarRegionNumber” (I)</td>
00540 </tr>
00541 </table>
00543 Notes:
00544 1. If no name is present, labels the material group with “MaterialX”, where X is the index of that group.
00546 \ref md-contents "Top"
00548   \section appendixC Appendix C: ExodusII Reader/Writer Conventions 
00550   \subsection table4 Table 4: Translation between ExodusII constructs and MOAB tags.
00551 <Table border="1">
00552 <tr>
00553 <th> Data Type</th>
00554 <th>ExodusII Construct</th>
00555 <th>MOAB Tag Name, Type</th>
00556 </tr>
00557 <tr>
00558 <td></td>
00559 <td>QA records</td>
00560 <td>“qaRecord” (C*(v))<sup>2</sup></td>
00561 </tr>
00562 <tr>
00563 <td rowspan="2">Material sets</td>
00564 <td>Block number</td>
00565 <td>MATERIAL_SET</td>
00566 </tr>
00567 <tr>
00568 <td>Block element type</td>
00569 <td>Entity type, # vertices per entity</td>
00570 </tr>
00571 <tr>
00572 <td rowspan="2">Dirichlet sets<sup>3</sup></td>
00573 <td>Nodeset number</td>
00574 <td>DIRICHLET_SET</td>
00575 </tr>
00576 <tr>
00577 <td>Distribution factors</td>
00578 <td>“distFactor” (D*(v))<sup>1</sup></td>
00579 </tr>
00580 <tr>
00581 <td>Neumann sets</td>
00582 <td>Sideset number</td>
00583 <td>NEUMANN_SET</td>
00584 </tr>
00585 <tr>
00586 <td rowspan="2">Neumann sets, reverse faces3<sup>3</sup></td>
00587 <td>Distribution factors</td>
00588 <td>“distFactor” (D*(v))<sup>1</sup></td>
00589 </tr>
00590 <tr>
00591 <td>Sides</td>
00592 <td>SENSE</td>
00593 </tr>
00594 <tr>
00595 <td>Nodes, elements</td>
00596 <td>node_num_map, elem_map</td>
00597 <td>GLOBAL_ID on nodes/elements</td>
00598 </tr>
00599 </table>
00601 Notes:
00602 -# Variable-length tag used for distribution factors; length for each set is the number of entities in
00603 each set, such that there is one distribution factor for each entity in the set.
00604 -# QA records are stored as variable-length tags on file set specified on read. Tag is a
00605 concatenation of QA record strings into a single string, with '\0' used to delimit lines.
00606 -# MOAB represents sidesets as sets of faces, rather than as sides of elements. Faces can be
00607 ordered “forward” or “reverse” with respect to one of the bounding elements, depending on
00608 whether the right-hand normal points into or out of the element. Forward-sense faces are added
00609 to the Neumann set. Reverse-sense faces are put into a separate set; that set is tagged with the SENSE tag, with value = -1; and that reverse set is added to the Neummann set.
00610 .
00612   \ref md-contents "Top"
00614   \section appendixD Appendix D: NC (Climate Data) Reader/Writer Conventions
00616 The climate data reader in MOAB reads files with the '.nc' filename extension. By default, this reader
00617 reads the whole mesh in the file and creates it as structured mesh in MOAB, with the mesh accessible
00618 through MOAB's structured mesh interface. By default, all variables and timesteps are read from the
00619 file, and written as tags on the mesh vertices from that file. This behavior is controlled by the
00620 “variable”, “nomesh”, “timestep”, and “timeval” options described earlier in this document. If MOAB
00621 is compiled for parallel execution and configured with a pnetcdf reader, the mesh is read in parallel,
00622 with a 1D or 2D decomposition designed to balance read performance and communication interface
00623 size (for details on the partitioning method used, see the src/io/ReadNC.cpp source file).
00625 Mesh is put into the entity set provided to the load_file function. This entity set is also annotated with
00626 various tags representing information read from the file. These tags are described in Table 5.
00628 Reading unstructured NC files in the HOMME format is also supported. Currently a trivial
00629 element-based partition is the only option for parallel reading. As the data is unstructured, it is necessary to have a connectivity file to define the vertex adjacencies. The default convention is to have a file called in the same directory as the the variable data file. If this convention is not followed, the connectivity file can be specified with the option -O CONN=”/path/to/”. An example of mbconvert using the parallel read capability is shown below:
00631 <B>  mpiexec -np 2 tools/mbconvert -O TRIVIAL -O DEBUG_IO=1 -o DEBUG_IO=9 -o PARALLEL=WRITE_PART /nfs2/hayes6/meshlab/homme_data/ output.h5m </B>
00633 Several other things to note about reading climate data files into MOAB:
00634 - Time-dependent variables: MOAB currently has no mechanism for time-dependent tags. Therefore, time-dependent variables are represented using one tag per timestep, with the tag name set as the variable name plus the timestep index. Thus, the first few timesteps for the variable TEMPERATURE would be represented in tags named TEMPERATURE0, TEMPERATURE1, etc.
00635 - Cell- and face-centered variables: The climate data reader currently does not do cell- and face-
00636 centered variables correctly.
00637 .
00638   \subsection table5 Table 5: Summary of MOAB conventional tag names, types, and purposes. Data types are I=integer, D=double, C=character, H=entity handle. Data type with *x denote length of x elements of that data type; data type with *var denote variable-length tag. Tag names with two underscores prepended (“__”) denote tags not written to a file by MOAB.
00640 <Table border="1">
00641 <tr>
00642 <th> Tag name </th>
00643 <th>Data type </th>
00644 <th> Applies to (E=entity, S=set) </th>
00645 <th>Purpose </th>
00646 </tr>
00647 <tr>
00648 <td>__NUM_DIMS </td>
00649 <td>I</td>
00650 <td>S</td>
00651 <td>The number of dimensions in the netcdf file.</td>
00652 </tr>
00653 <tr>
00654 <td>__NUM_VARS</td> 
00655 <td>I</td>
00656 <td>S</td>
00657 <td>The number of variables in the netcdf file.</td>
00658 </tr>
00659 <tr>
00660 <td>__DIM_NAMES </td>
00661 <td>C*var</td>
00662 <td>S</td>
00663 <td>The dimension names, concatenated into a
00664 character string, with '\0' terminating each name.
00665 </td>
00666 </tr>
00667 <tr>
00668 <td>__DIM_LENS </td>
00669 <td>I*var</td>
00670 <td>S</td>
00671 <td>A vector of integers, storing the length of
00672 each dimension.
00673 </td>
00674 </tr>
00675 <tr>
00676 <td>__VAR_NAMES
00677 </td>
00678 <td>C*var</td>
00679 <td>S</td>
00680 <td>The variable names, concatenated into a
00681 character string, with '\0' terminating each name.
00682 </td>
00683 </tr>
00684 <tr>
00685 <td><dim_name> 
00686 </td>
00687 <td>(I or D)*var</td>
00688 <td>S</td>
00689 <td>For each dimension, the values for the dimension.
00690 The data type for this tag corresponds to that in the
00691 netcdf file. The length of this tag is the number of
00692 values stored for the dimension in the netcdf file.</td>
00693 </tr>
00694 <tr>
00695 <td>__<dim_name>_LOC_MIN_MAX</td>
00696 <td>(I or D)*2</td>
00697 <td>S</td>
00698 <td>The indices (0-based) of the local min and max
00699 values of dimension stored locally. For spatial
00700 dimensions like lon or lat, this will store the
00701 minimum and maximum indices in the local partition
00702 of the grid. For dimensions like time, where each
00703 processor represents the entire dimension, this will
00704 likely store 0 and the number of values for that
00705 dimension. Only one of __<dim_name>_LOC_VALS and
00706 __<dim_name>_LOC_MIN_MAX can be used for a given
00707 dimension.</td>
00708 </tr>
00709 <tr>
00710 <td>__<dim_name>_LOC_VAL </td>
00711 <td>(I or D)*var</td>
00712 <td>S</td>
00713 <td>The indices (0-based) of the dimension stored
00714 locally. This tag only makes sense for dimensions
00715 that can be read in multiple pieces, such as time.
00716 Only one of __<dim_name>_LOC_VALS and
00717 __<dim_name>_LOC_MIN_MAX can be used for a given
00718 dimension.</td>
00719 </tr>
00720 <tr>
00721 <td>__<dim_name>_GLOBAL_MIN_MAX</td>
00722 <td>(I or D)*2</td>
00723 <td>S</td>
00724 <td>The indices (0-based) of the global min and max
00725 values of dimension.</td>
00726 </tr>
00727 <tr>
00728 <td>__<var_name>_DIMS 
00729 </td>
00730 <td>H*n 
00731 </td>
00732 <td>S</td>
00733 <td>For each variable, this tag stores the tag
00734 handles for the n dimensions defining this variable,
00735 in netcdf ordering (last dimension varying fastest).
00736 The size of this tag is n * sizeof(TagHandle).
00737 </td>
00738 </tr>
00739 <tr>
00740 <td><var_name><timestep_ind> 
00741 </td>
00742 <td>(data type)</td>
00743 <td>E</td>
00744 <td>Values of the variable for timestep <timestep_ind>
00745 for vertices. The data type of this tag corresponds
00746 to that of the variable from the netcdf file.
00747 Timestep index is 0-based.
00748 </td>
00749 </tr>
00750 <tr>
00751 <td>__GLOBAL_ATTRIBS 
00752 </td>
00753 <td>C*var
00754 </td>
00755 <td>S</td>
00756 <td>The global attributes, concatenated into a character
00757 string, with ‘\0’ terminating each attribute name, ‘;’
00758        separating the data type and value, and ‘;’
00759           separating one name/data type/value from the next.
00760 </td>
00761 </tr>
00762 <tr>
00764 </td>
00765 <td>I*var
00766 </td>
00767 <td>S</td>
00768 <td>A vector of integers, marking the end position of
00769 each attribute (name/data type/value) in __GLOBAL_ATTRIBS tag.
00770 </td>
00771 </tr>
00772 <tr>
00773 <td>__<var_name>_ATTRIBS 
00774 </td>
00775 <td>C*var
00776 </td>
00777 <td>S</td>
00778 <td>The variable attributes, concatenated into a
00779 character string, with ‘\0’ terminating each attribute
00780    name, ‘;’ separating the data type and value, and ‘;’
00781           separating one name/data type/value from the next.
00782 </td>
00783 </tr>
00784 <tr>
00785 <td>__<var_name>_ATTRIBS_LEN 
00786 </td>
00787 <td>I*var
00788 </td>
00789 <td>S</td>
00790 <td>A vector of integers, marking the end position of
00791 each attribute (name/data type/value) in
00792 __<var_name>_ATTRIBS tags
00793 </td>
00794 </tr>
00795 </table>
00797   \ref md-contents "Top"
00799   \section appendixE Appendix E: Nek5000 Reader/Writer Conventions
00801 Nek5000, or Nek, is a code that uses the spectral element method to model fluid, heat transfer,
00802 electromagnetics, and other physics. Nek uses unstructured hexahedral meshes, with each hex element
00803 resolved by a structured grid of “Gauss Lebato Legendre” (GLL) points. Nek can read meshes through
00804 MOAB, and can output physics variables and GLL points through MOAB as well.
00806 Since fluid is a single material in Nek, no material sets are needed. Boundary conditions are mapped to
00807 Nek's cbc array using Neumann sets and a user-provided “usr_moab2nek” subroutine (for an example
00808 of this subroutine, see examples/moab/pipe.usr in the Nek source code). GLL point locations and fluid
00809 variables on those points are stored in tags on the hex elements. All hex elements have the same
00810 number of GLL points. The number of GLL points in each direction is stored in a tag on the mesh
00811 instance. These tags are described in Table 6.
00813 GLL point locations and fluid variables are stored in lexicographic order, similar to their storage order
00814 inside the Nek code.
00816   \subsection table6 Table 6: Summary of MOAB conventional tag names, types, and purposes for Nek. Data types are I=integer, D=double, C=character, H=entity handle. Data type with *x denote length of x elements of that data type; data type with *var denote variable-length tag. Tag names with two underscores prepended (“__”) denote tags not written to a file by MOAB.
00817 <Table border="1">
00818 <tr>
00819 <th> Tag name </th>
00820 <th> Data Type</th>
00821 <th>Applies to (E=entity, S=set)</th>
00822 <th>Purpose</th>
00823 </tr>
00824 <tr>
00825 <td>SEM_DIMS</td>
00826 <td>I*3</td>
00827 <td>S</td>
00828 <td>The dimensions of the GLL mesh in each hex
00829 element.
00830 </td>
00831 </tr>
00832 <tr>
00833 <td>SEM_X</td>
00834 <td>D*nx*ny*nz</td>
00835 <td>E</td>
00836 <td>X position of GLL points (having nx*ny*nz
00837 values)
00838 </td>
00839 </tr>
00840 <tr>
00841 <td>SEM_Y</td>
00842 <td>D*nx*ny*nz</td>
00843 <td>E</td>
00844 <td>Y position of GLL points (having nx*ny*nz values)</td>
00845 </tr>
00846 <tr>
00847 <td>SEM_Z</td>
00848 <td>D*nx*ny*nz</td>
00849 <td>E</td>
00850 <td>Z position of GLL points (having nx*ny*nz values)</td>
00851 </tr>
00852 <tr>
00853 <td>VEL_X</td>
00854 <td>D*nx*ny*nz</td>
00855 <td>E</td>
00856 <td>Fluid velocities in the x direction for GLL point
00857 array (having nx*ny*nz values)</td>
00858 </tr>
00859 <tr>
00860 <td>VEL_Y</td>
00861 <td>D*nx*ny*nz</td>
00862 <td>E</td>
00863 <td>Fluid velocities in the y direction for GLL point
00864 array (having nx*ny*nz values)</td>
00865 </tr>
00866 <tr>
00867 <td>VEL_Z</td>
00868 <td>D*nx*ny*nz</td>
00869 <td>E</td>
00870 <td>Fluid velocities in the z direction for GLL point
00871 array (having nx*ny*nz values)</td>
00872 </tr>
00873 <tr>
00874 <td>TEMP</td>
00875 <td>D*nx*ny*nz</td>
00876 <td>E</td>
00877 <td>Fluid temperature for GLL point array (having
00878 nx*ny*nz values)
00879 </td>
00880 </tr>
00881 <tr>
00882 <td>PRESS</td>
00883 <td>D*nx*ny*nz</td>
00884 <td>E</td>
00885 <td>Fluid pressure for GLL point array (having
00886 nx*ny*nz values)
00887 </td>
00888 </tr>
00889 </table>
00890   \ref md-contents "Top"
00891         */
00893 /*!  \page md-tables List of Tables
00894     \ref table1
00896     \ref table2
00898     \ref table3
00900     \ref table4
00902     \ref table5
00904     \ref table6
00906 */
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines