[MOAB-dev] commit/MOAB: janehu: Added developer's guide for metadata_info.doc.

commits-noreply at bitbucket.org commits-noreply at bitbucket.org
Sun Jun 30 00:10:07 CDT 2013


1 new commit in MOAB:

https://bitbucket.org/fathomteam/moab/commits/d4b3f02b288c/
Changeset:   d4b3f02b288c
Branch:      master
User:        janehu
Date:        2013-06-30 06:57:05
Summary:     Added developer's guide for metadata_info.doc.

Affected #:  1 file

diff --git a/doc/DG/moabDG.h b/doc/DG/moabDG.h
index d2e14f0..1091094 100644
--- a/doc/DG/moabDG.h
+++ b/doc/DG/moabDG.h
@@ -1,10 +1,45 @@
-/*! \page developerguide Developer's Guide (MOAB 4.6)
-=20
-  \subpage dg-contents
-=20
-  \subpage dg-figures
+/*! \page developerguide Developer's Guide (MOAB 4.6)
+=20
+  \subpage dg-contents
+=20
+  \subpage dg-figures
+
+  \subpage dg-tables
+*/
+
+/*!  \page dg-contents Table of Contents
+
+  \subpage sequence-info
+
+  \subpage meta-data-info
+*/
+
+/*!  \page dg-figures List of Figures
+
+    \ref figure1
+
+    \ref figure2
+
+    \ref figure3
+*/
+
+/*!  \page dg-tables List of Tables
+
+    \ref table1
+
+    \ref table2
+
+    \ref table3
+
+    \ref table4
+
+    \ref table5
+
+    \ref table6
+
+*/
=20
-  \page dg-contents Table of Contents
+/*!  \page sequence-info Sequence Info
=20
   \ref sequence
=20
@@ -14,10 +49,9 @@
=20
   \ref sets
=20
-  \section sequence  1. EntitySequence & SequenceData
+  \section sequence  EntitySequence & SequenceData=20
=20
   \subsection figure1 Figure 1: EntitySequences For One SequenceData
-
 The <I>SequenceData</I> class manages as set of arrays of per-entity value=
s. Each
 <I>SequenceData</I> has a start and end handle denoting the block of entit=
ies for which
 the arrays contain data. The arrays managed by a <I>SequenceData</I> insta=
nce are
@@ -77,9 +111,9 @@ a feature. Sequences for which the corresponding data ca=
nnot be used to store
 new entities (e.g. structured mesh discussed in a later section) will retu=
rn -1 or
 some other invalid value.
=20
- \ref dg-contents
+ \ref sequence-info "Top"
=20
-  \section manager 2. TypeSequenceManager & SequenceManager=20
+  \section manager TypeSequenceManager & SequenceManager=20
=20
 The <I>TypeSequenceManager</I> class maintains an organized set of <I>Enti=
tySequence</I>
 instances and corresponding <I>SequenceData</I> instances. It is used to m=
anage
@@ -141,119 +175,920 @@ such as allocating the correct <I>EntitySequence</I=
> subtype for a given <I>Enti
=20
 <sup>2</sup>Given rule four for the data managed by a <I>TypeSequenceManag=
er</I>, any <I>SequenceData</I> for which all handles are allocated will be=
 referenced by exactly one <I>EntitySequence</I>.
=20
-  \ref dg-contents
-
- \section s-mesh 3. Structured Mesh
-
-Structured mesh storage is implemented using subclasses of <I>SequenceData=
</I>:
-<I>ScdElementData</I> and <I>ScdVertexData</I>. The <I>StructuredElementSe=
q</I> class is
-used to access the structured element connectivity. A standard <I>VertexSe=
quence</I>
-instance is used to access the ScdVertexData because the vertex data stora=
ge
-is the same as for unstructured mesh.
-
-  \ref dg-contents
-
-  \section sets 4. Entity Sets
-
-- MeshSetSequence
-
-The <I>MeshSetSequence</I> class is the same as most other subclasses of <=
I>EntitySequence</I>
-in that it utilizes SequenceData to store its data. A single array in the =
<I>SequenceData</I>
-is used to store instances of the MeshSet class, one per allocated <I>Enti=
tyHandle</I>.
-<I>SequenceData</I> allocates all of its managed arrays using malloc and f=
ree as
-simple arrays of bytes. <I>MeshSetSequence</I> does in-place construction =
and de-
-struction of <I>MeshSet</I> instances within that array. This is similar t=
o what is
-done by <I>std::vector</I> and other container classes that may own more s=
torage
-than is required at a given time for contained objects.
-
-- MeshSet
-
-  \subsection figure3 Figure 3: SequenceManager and Related Classes
-
-The <I>MeshSet</I> class is used to represent a single entity set instance=
 in MOAB.
-The class is optimized to minimize storage (further possible improvements =
in
-storage size are discussed later.)
-
-Figure 3 shows the memory layout of an instance of the <I>MeshSet</I> clas=
s.
-The flags member holds the set creation bit flags: <I>MESHSET_TRACK_OWNER<=
/I>,
-<I>MESHSET_SET</I>, and <I>MESHSET_ORDERED</I>. The presence of the <I>MES=
HSET_TRACK_OWNER</I>
-indicates that reverse links from the contained entities back to the ownin=
g set
-should be maintained in the adjacency list of each entity. The <I>MESHSET_=
SET</I>
-and <I>MESHSET_ORDERED</I> bits are mutually exclusive, and as such most c=
ode only
-tests for the <I>MESHSET_ORDERED</I>, meaning that in practice the <I>MESH=
SET_SET</I> bit is
-ignored. <I>MESHSET_ORDERED</I> indicates that the set may contain duplica=
te handles
-and that the order that the handles are added to the set should be preserv=
ed.
-In practice, such sets are stored as a simple list of handles. <I>MESHSET_=
SET</I> (or in
-practice, the lack of <I>MESHSET_ORDERED</I>) indicates that the order of =
the handles
-need not be preserved and that the set may not contain duplicate handles. =
Such
-sets are stored in a sorted range-compacted format similar to that of the =
Range
-class.
-
-The memory for storing contents, parents, and children are each handled in
-the same way. The data in the class is composed of a 2-bit =E2=80=98size=
=E2=80=99 field and two
-values, where the two values may either be two handles or two pointers. Th=
e size
-bit-fields are grouped together to reduce the required amount of memory. I=
f the
-numerical value of the 2-bit size field is 0 then the corresponding list i=
s empty.
-If the 2-bit size field is either 1 or 2, then the contents of the corresp=
onding list
-are stored directly in the corresponding two data fields of the MeshSet ob=
ject.
-If the 2-bit size field has a value of 3 (11 binary), then the correspondi=
ng two
-data fields store the begin and end pointers of an external array of handl=
es.
-The number of handles in the external array can be obtained by taking the
-difference of the start and end pointers. Note that unlike <I>std::vector<=
/I>, we
-do not store both an allocated and used size. We store only the =E2=80=98u=
sed=E2=80=99 size
-and call std::realloc whenever the used size is modified, thus we rely on =
the
-std::malloc implementation in the standard C library to track =E2=80=98all=
ocated=E2=80=99 size
-for us. In practice this performs well but does not return memory to the =
=E2=80=98system=E2=80=99
-when lists shrink (unless they shrink to zero). This overall scheme could =
exhibit
-poor performance if the size of one of the data lists in the set frequentl=
y changes
-between less than two and more than two handles, as this will result in fr=
equent
-releasing and re-allocating of the memory for the corresponding array.
-
-If the <I>MESHSET_ORDERED</I> flag is not present, then the set contents l=
ist (parent
-and child lists are unaffected) is stored in a range-compacted format. In =
this
-format the number of handles stored in the array is always a multiple of t=
wo.
-Each consecutive pair of handles indicate the start and end, inclusive, of=
 a range
-of handles contained in the set. All such handle range pairs are stored in=
 sorted
-order and do not overlap. Nor is the end handle of one range ever one less=
 than
-the start handle of the next. All such =E2=80=98adjacent=E2=80=99 range pa=
irs are merged into a
-single pair. The code for insertion and removal of handles from range-form=
atted
-set content lists is fairly complex. The implementation will guarantee tha=
t a
-given call to insert entities into a range or remove entities from a range=
 is never
-worse than O(ln n) + O(m + n), where =E2=80=98n=E2=80=99 is the number of =
handles to insert
-and =E2=80=98m=E2=80=99 is the number of handles already contained in the =
set. So it is generally
-much more efficient to build Ranges of handles to insert (and remove) and =
call
-MOAB to insert (or remove) the entire list at once rather than making may
-calls to insert (or remove) one or a few handles from the contents of a se=
t.
-The set storage could probably be further minimized by allowing up to six
-handles in one of the lists to be elided. That is, as there are six potent=
ial =E2=80=98slots=E2=80=99
-in the MeshSet object then if two of the lists are empty it should be poss=
ible to store up to six values of the remaining list directly in the MeshSe=
t object.
-However, the additional runtime cost of such complexity could easily outwe=
igh
-any storage advantage. Further investigation into this has not been done b=
ecause
-the primary motivation for the storage optimization was to support binary =
trees.
-
-Another possible optimization of storage would be to remove the <I>MeshSet=
</I>
-object entirely and instead store the data in a =E2=80=98blocked=E2=80=99 =
format. The corre-
-sponding <I>SequenceData</I> would contain four arrays: flags, parents, ch=
ildren, and
-contents instead of a single array of <I>MeshSet</I> objects. If this were=
 done then
-no storage need ever be allocated for parent or child links if none of the=
 sets
-in a <I>SequenceData</I> has parent or child links. The effectiveness of t=
he storage
-reduction would depend greatly on how sets get grouped into <I>SequenceDat=
as</I>.
-This alternate storage scheme might also allow for better cache utilizatio=
n as it
-would group like data together. It is often the case that application code=
 that
-is querying the contents of one set will query the contents of many but ne=
ver
-query the parents or children of any set. Or that an application will quer=
y only
-parent or child links of a set without every querying other set properties=
. The
-downside of this solution is that it makes the implementation a little les=
s mod-
-ular and maintainable because the existing logic contained in the <I>MeshS=
et</I> class
-would need to be spread throughout the <I>MeshSetSequence</I> class.
-
-  \ref dg-contents
-
-  \page dg-figures List of Figures
-
-  \ref figure1
-
-  \ref figure2
-
-  \ref figure3
+  \ref sequence-info "Top"
+
+ \section s-mesh Structured Mesh
+
+Structured mesh storage is implemented using subclasses of <I>SequenceData=
</I>:
+<I>ScdElementData</I> and <I>ScdVertexData</I>. The <I>StructuredElementSe=
q</I> class is
+used to access the structured element connectivity. A standard <I>VertexSe=
quence</I>
+instance is used to access the ScdVertexData because the vertex data stora=
ge
+is the same as for unstructured mesh.
+
+  \ref sequence-info "Top"
+
+  \section sets Entity Sets
+
+- MeshSetSequence
+
+The <I>MeshSetSequence</I> class is the same as most other subclasses of <=
I>EntitySequence</I>
+in that it utilizes SequenceData to store its data. A single array in the =
<I>SequenceData</I>
+is used to store instances of the MeshSet class, one per allocated <I>Enti=
tyHandle</I>.
+<I>SequenceData</I> allocates all of its managed arrays using malloc and f=
ree as
+simple arrays of bytes. <I>MeshSetSequence</I> does in-place construction =
and de-
+struction of <I>MeshSet</I> instances within that array. This is similar t=
o what is
+done by <I>std::vector</I> and other container classes that may own more s=
torage
+than is required at a given time for contained objects.
+
+- MeshSet
+
+  \subsection figure3 Figure 3: SequenceManager and Related Classes
+
+The <I>MeshSet</I> class is used to represent a single entity set instance=
 in MOAB.
+The class is optimized to minimize storage (further possible improvements =
in
+storage size are discussed later.)
+
+Figure 3 shows the memory layout of an instance of the <I>MeshSet</I> clas=
s.
+The flags member holds the set creation bit flags: <I>MESHSET_TRACK_OWNER<=
/I>,
+<I>MESHSET_SET</I>, and <I>MESHSET_ORDERED</I>. The presence of the <I>MES=
HSET_TRACK_OWNER</I>
+indicates that reverse links from the contained entities back to the ownin=
g set
+should be maintained in the adjacency list of each entity. The <I>MESHSET_=
SET</I>
+and <I>MESHSET_ORDERED</I> bits are mutually exclusive, and as such most c=
ode only
+tests for the <I>MESHSET_ORDERED</I>, meaning that in practice the <I>MESH=
SET_SET</I> bit is
+ignored. <I>MESHSET_ORDERED</I> indicates that the set may contain duplica=
te handles
+and that the order that the handles are added to the set should be preserv=
ed.
+In practice, such sets are stored as a simple list of handles. <I>MESHSET_=
SET</I> (or in
+practice, the lack of <I>MESHSET_ORDERED</I>) indicates that the order of =
the handles
+need not be preserved and that the set may not contain duplicate handles. =
Such
+sets are stored in a sorted range-compacted format similar to that of the =
Range
+class.
+
+The memory for storing contents, parents, and children are each handled in
+the same way. The data in the class is composed of a 2-bit =E2=80=98size=
=E2=80=99 field and two
+values, where the two values may either be two handles or two pointers. Th=
e size
+bit-fields are grouped together to reduce the required amount of memory. I=
f the
+numerical value of the 2-bit size field is 0 then the corresponding list i=
s empty.
+If the 2-bit size field is either 1 or 2, then the contents of the corresp=
onding list
+are stored directly in the corresponding two data fields of the MeshSet ob=
ject.
+If the 2-bit size field has a value of 3 (11 binary), then the correspondi=
ng two
+data fields store the begin and end pointers of an external array of handl=
es.
+The number of handles in the external array can be obtained by taking the
+difference of the start and end pointers. Note that unlike <I>std::vector<=
/I>, we
+do not store both an allocated and used size. We store only the =E2=80=98u=
sed=E2=80=99 size
+and call std::realloc whenever the used size is modified, thus we rely on =
the
+std::malloc implementation in the standard C library to track =E2=80=98all=
ocated=E2=80=99 size
+for us. In practice this performs well but does not return memory to the =
=E2=80=98system=E2=80=99
+when lists shrink (unless they shrink to zero). This overall scheme could =
exhibit
+poor performance if the size of one of the data lists in the set frequentl=
y changes
+between less than two and more than two handles, as this will result in fr=
equent
+releasing and re-allocating of the memory for the corresponding array.
+
+If the <I>MESHSET_ORDERED</I> flag is not present, then the set contents l=
ist (parent
+and child lists are unaffected) is stored in a range-compacted format. In =
this
+format the number of handles stored in the array is always a multiple of t=
wo.
+Each consecutive pair of handles indicate the start and end, inclusive, of=
 a range
+of handles contained in the set. All such handle range pairs are stored in=
 sorted
+order and do not overlap. Nor is the end handle of one range ever one less=
 than
+the start handle of the next. All such =E2=80=98adjacent=E2=80=99 range pa=
irs are merged into a
+single pair. The code for insertion and removal of handles from range-form=
atted
+set content lists is fairly complex. The implementation will guarantee tha=
t a
+given call to insert entities into a range or remove entities from a range=
 is never
+worse than O(ln n) + O(m + n), where =E2=80=98n=E2=80=99 is the number of =
handles to insert
+and =E2=80=98m=E2=80=99 is the number of handles already contained in the =
set. So it is generally
+much more efficient to build Ranges of handles to insert (and remove) and =
call
+MOAB to insert (or remove) the entire list at once rather than making may
+calls to insert (or remove) one or a few handles from the contents of a se=
t.
+The set storage could probably be further minimized by allowing up to six
+handles in one of the lists to be elided. That is, as there are six potent=
ial =E2=80=98slots=E2=80=99
+in the MeshSet object then if two of the lists are empty it should be poss=
ible to store up to six values of the remaining list directly in the MeshSe=
t object.
+However, the additional runtime cost of such complexity could easily outwe=
igh
+any storage advantage. Further investigation into this has not been done b=
ecause
+the primary motivation for the storage optimization was to support binary =
trees.
+
+Another possible optimization of storage would be to remove the <I>MeshSet=
</I>
+object entirely and instead store the data in a =E2=80=98blocked=E2=80=99 =
format. The corre-
+sponding <I>SequenceData</I> would contain four arrays: flags, parents, ch=
ildren, and
+contents instead of a single array of <I>MeshSet</I> objects. If this were=
 done then
+no storage need ever be allocated for parent or child links if none of the=
 sets
+in a <I>SequenceData</I> has parent or child links. The effectiveness of t=
he storage
+reduction would depend greatly on how sets get grouped into <I>SequenceDat=
as</I>.
+This alternate storage scheme might also allow for better cache utilizatio=
n as it
+would group like data together. It is often the case that application code=
 that
+is querying the contents of one set will query the contents of many but ne=
ver
+query the parents or children of any set. Or that an application will quer=
y only
+parent or child links of a set without every querying other set properties=
. The
+downside of this solution is that it makes the implementation a little les=
s mod-
+ular and maintainable because the existing logic contained in the <I>MeshS=
et</I> class
+would need to be spread throughout the <I>MeshSetSequence</I> class.
+
+  \ref sequence-info "Top"
 */
+
+/*! \page meta-data-info I/O and Meta-Data Storage Conventions in MOAB
+
+  <Center><H3> Timothy J. Tautges </H3></Center>
+
+    \ref meta-introduction
+
+    \ref meta-conventions
+
+    \ref meta-options
+
+    \ref meta-references
+
+    \ref appendixA
+
+    \ref appendixB
+
+    \ref appendixC
+
+    \ref appendixD
+
+    \ref appendixE
+
+  \section meta-introduction  Introduction
+
+The Mesh-Oriented datABase (MOAB) is a library for representing finite ele=
ment and other types of mesh data [1].  Various types of meta-data are ofte=
n used in conjunction with a mesh.  Examples include boundary condition gro=
upings, material types, and provenance information for the mesh.  Because t=
he data model used in MOAB is so abstract, conventions are useful for descr=
ibing how meta-data is stored into that data model.  This document describe=
s those conventions for several types of data commonly found in meshes stor=
ed 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.
+
+The meshes represented in MOAB originate in a variety of forms, including =
mesh read from files of various formats (e.g. CUBIT =E2=80=9C.cub=E2=80=9D =
file, VTK, etc.) as well as mesh written into MOAB directly by various soft=
ware 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 describe=
s 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.  Alth=
ough 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 proce=
ssed.
+
+Several specific tools are often used in concert with MOAB and bear specia=
l mention here.  The CUBIT toolkit generates finite element meshes, and sav=
es them to a native save file (referred to as a =E2=80=9C.cub=E2=80=9D 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 form=
ats 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 storin=
g meshes into MOAB.  Finally, MOAB includes a CGM reader which can read a g=
eometric model into a faceted representation in MOAB.  Meta-data from all t=
hese tools are stored in MOAB using the conventions described here.=20
+
+The MOAB data model consists of the following basic types:
+- <B>Entity</B>: The basic elements of topology, e.g. vertex, edge, triang=
le, tetrahedron, etc.  MOAB represents all types in the finite element zoo,=
 plus polygons and polyhedra.
+- <B>Entity Set</B>: An arbitrary collection of entities and other sets.  =
Sets can have parent/child relations with other sets, and these relations a=
re distinct from =E2=80=9Ccontains=E2=80=9D relations.
+- <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 =E2=80=9Croot=E2=80=9D set.
+- <B>Tag</B>: A piece of data that can be assigned a distinct value to eac=
h entity and entity set, and to the interface itself.  Tags have a prescrib=
ed name, size in bytes, and data type; allowed data types are integer, doub=
le, entity handle, and byte or opaque.
+.
+
+The following section describes each meta-data tag convention in detail; t=
hese conventions are also summarized in Table 1.
+
+  \ref meta-data-info "Top"
+
+  \section meta-conventions  Meta-Data Conventions
+
+Meta-data is stored in MOAB and iMesh in the form of tags applied to eithe=
r entities or entity sets.  For meta-data represented as entity sets, the c=
ontents of those sets are determined by the convention, with tags on those =
sets identifying them with the convention and adding any other semantic dat=
a.
+
+Each meta-data convention is described in a subsection below.  Each conven=
tion begins with a short description of:
+- Whether tags associated with the convention are assigned to entities or =
entity sets
+- The tag(s) associated with the convention; information for each tag incl=
udes the name, the data type (I=3Dinteger, D=3Ddouble, C=3Dcharacter, H=3Dh=
andle), and the tag length.  Tag lengths are specified after an asterisk (*=
); for example, C*32 implies a tag with character type and length 32.  Unsp=
ecified lengths correspond to length one.
+.
+
+<H3>Name</H3>
+
+(Data: Entity sets, entities; Tag(s): NAME/C*32)
+
+Character strings are used in many different contexts in applications.  MO=
AB uses the =E2=80=9CNAME=E2=80=9D tag to store character strings used to n=
ame entities.  This tag is of byte-type and is of length 32 bytes.  Note th=
at the string stored in this tag may or may not be terminated with a NULL c=
haracter.  It is always prudent account for missing NULL terminator, to avo=
id buffer overflow errors in the application.  Applications are free to def=
ine their own version of the NAME tag with a longer length, though this def=
inition may conflict with other services attempting to use this tag with th=
e conventional size.  Applications needing a string tag with a longer or va=
riable length can also use MOAB=E2=80=99s variable-length tag type, though =
this will not be compatible with iMesh.
+
+<H3>Title </H3>
+
+(Data: Entity sets (file or instance); Tag(s): TITLE/C*strlen)
+
+The title tag is meant to hold the overall identifier of a mesh, written a=
t 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 re=
ad by MOAB).
+
+<H3> Global Identifier </H3>
+
+(Data: Entity sets, entities; Tag(s): GLOBAL_ID/I)
+
+Global identifiers are used in many different contexts in applications.  G=
eometric model entities are identified by dimension and id, e.g. =E2=80=9CV=
olume 1=E2=80=9D.  Mesh vertices and elements are identified similarly in m=
esh generation codes.  Boundary conditions and material types are identifie=
d similarly.  This tag is used to store such information.  This tag is curr=
ently stored in a 32-byte integer, though this may change in the future.
+
+<H3> Geometric Model Information </H3>
+
+(Data: Entity sets; Tag(s): GEOM_DIMENSION/I, GLOBAL_ID/I, NAME/C*32, CATE=
GORY/C*32, GEOM_SENSE_2(EH[2]), GEOM_SENSE_N_ENTS(EH*N), GEOM_SENSE_N_SENSE=
S(I*N))
+
+Mesh generation is often performed starting from a geometric model, repres=
ented in some form of CAD engine.  Many of the meshes used by MOAB are gene=
rated based on the CGM library.  Geometric models contain both topological =
information (the topological entities in the geometric model) and shape inf=
ormation (the geometric shape of those entities), as well as other meta-dat=
a written to the entities in a model.  When a mesh is read from a CUBIT .cu=
b file, meta-data from the geometric model is read and represented in the M=
OAB data model, as described below. <B> Note that although MOAB reads and r=
epresents meta-data associated with the geometric model, it does not repres=
ent 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 r=
etrieved only from the model represented in CGM or another geometric modeli=
ng engine.
+
+The information contained in a geometric model, read into and represented =
in MOAB, consists of:
+- Model entities (vertex, edge, face, volume)
+- Topological relationships between model entities
+- Groups of model entities
+- Model entity/group ids
+- Model entity/group names
+.
+The storage of this information into MOAB's data model is described for ea=
ch type is described below.
+
+- <B>Entities </B>
+
+Entities in the geometric model (VERTEX, EDGE, FACE, VOLUME) are each repr=
esented by an entity set<sup>1</sup>.  These sets are tagged with the =E2=
=80=9CGEOM_DIMENSION=E2=80=9D tag, with integer value equal to the topologi=
cal dimension of the entity (VERTEX =3D 0, EDGE =3D 1, etc.)  These sets co=
ntain the mesh owned by the corresponding entity in the geometric model.  N=
ote this does not include mesh owned by bounding entities; thus, the set fo=
r 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 interm=
ediate dimension, e.g. mesh edges owned by a FACE or faces owned by a VOLUM=
E, 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 entitie=
s in the sets is not significant, except in the case of EDGE sets, where or=
der of the mesh vertices and edges corresponds to the relative order of ver=
tices and edges at the time of mesh generation.  In MOAB, these sets are no=
n-tracking by default, i.e. entities do not have knowledge of which geometr=
y sets they are members of.
+
+<sup>1</sup>Body-type entities from CUBIT are not explicitly represented i=
n MOAB.
+
+- <B> Topological Relationships </B>
+
+In the geometric model, each FACE is bounded by zero or more EDGEs; other =
topological relationships between geometric entities exist in a similar man=
ner.  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 rela=
tive order of sets in those parent/child lists is not significant, thus, =
=E2=80=9Cloops=E2=80=9D bounding a FACE cannot reliably be inferred from th=
is data.
+
+- <B> Groups </B>
+
+Geometric entities are sometimes assigned to application-specific groups. =
 These groups are represented using entity sets, tagged with a =E2=80=9CGRO=
UP=E2=80=9D tag whose value equals the group id.  Group sets are =E2=80=9Cs=
et=E2=80=9D-type, and are not tracking sets.  These sets contain the sets c=
orresponding to geometric entities contained in the groups in the geometric=
 model, as well as any mesh entities assigned to the group.
+
+<H4> Sense </H4>
+
+A geometric face has a natural orientation, indicated by the direction of =
the normal to the face; similarly, edges have a natural orientation determi=
ned by the direction of the tangent.  When faces bound regions, or edges bo=
und faces, they do so with a sense; if a region includes a face with forwar=
d sense, that means the face's natural normal direction points out of the v=
olume.  If a face includes an edge with forward sense, that means that if o=
ne moves along the edge in the direction of its tangent, the material of th=
e face is on the left hand side.  The sense of a face (edge) with respect t=
o a region (face) it bounds is stored using tags on the face (edge).
+
+Most models allow a face to be part of only two regions.  Therefore, to st=
ore the sense of a face with respect to regions including it, a tag with tw=
o values is used.  This tag is named GEOM_SENSE_2, and has 2 EntityHandle v=
alues.  The first value corresponds to the entity set for the region for wh=
ich that face has a forward sense, and the second to the region for which t=
hat face has a reverse sense.
+
+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 f=
ace.  These tags are named GEOM_SENSE_N_ENTS and GEOM_SENSE_N_SENSES, respe=
ctively.  These are stored as variable-length tags; see the MOAB user's gui=
de for information on how to work with tags of this type.=20
+
+The following sense values are used:
+- 0: forward
+- 1: reverse
+- -1: unnknown
+
+<H3> Material Type </H3>
+
+(Data: Entity sets; Tag(s): MATERIAL_SET/I)
+
+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 i=
s used to identify these sets.  The value of this tag is conventionally an =
integer; in most cases this stores a user-assigned identifier associated wi=
th that material.=20
+
+CUBIT assigns material types using what it calls =E2=80=9Celement blocks=
=E2=80=9D, with each element block given a user-assigned id number and opti=
onally a name.  The CUBIT and Exodus file readers in MOAB read element bloc=
ks into MATERIAL_SET sets. =20
+
+In CUBIT, materials are typically assigned by assigning geometric volumes =
to element blocks.  Therefore, material sets often contain entity sets corr=
esponding to those volumes.  Thus, a materrial set in MOAB is unlikely to c=
ontain mesh entities directly; rather, that set contains other sets which c=
ontain mesh entities.  In these cases, mesh entities can be retrieved by pa=
ssing a =E2=80=9Crecursive=E2=80=9D flag to the appropriate function (MOAB)=
, or by calling the getEntitiesRec extension function (iMesh) provided by M=
OAB.
+
+<H3> Boundary Conditions (Dirichlet, Neumann)</H3>
+
+Data: Entity sets; Tag(s): DIRICHLET_SET/I, NEUMANN_SET/I)
+
+Boundary conditions are often specified in terms of geometric model entiti=
es, similar to material types.  MOAB uses entity sets to store this informa=
tion 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 fa=
ces, rather than as sides of elements.  Faces can be ordered =E2=80=9Cforwa=
rd=E2=80=9D or =E2=80=9Creverse=E2=80=9D with respect to one of the boundin=
g elements, depending on whether the right-hand normal points into or out o=
f 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 =3D -1; and that reverse set is added to the Neumman=
n set.
+
+<H3> Parallel Mesh Constructs </H3>
+
+(Data: Entity sets, entities; Tag(s): PARALLEL_PART/I, PARALLEL_PARTITION/=
I, PSTATUS/C*1, PARALLEL_SHARED_PROC/I, PARALLEL/SHARED_HANDLE/H, PARALLEL_=
SHARED_PROCS/I*NP, PARALLEL_SHARED_HANDLES/H*NP)
+
+On a parallel computer, MOAB can represent the mesh on each processor as w=
ell 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 th=
e parallel nature of a mesh.  This information is summarized here; for a mo=
re complete description of MOAB=E2=80=99s parallel mesh representation and =
functionality, see [ref-moabpar].
+
+- <B> Parallel partition, parts </B>
+
+Most parallel mesh applications use a domain decomposition approach, where=
 each processor solves for a subset of the domain.  The set of entities sol=
ved by a given processor is referred to as a part, and the collection of pa=
rts together is called the partition.  MOAB stores each part in an entity s=
et, marked with the PARALLEL_PART tag, whose value is the rank of the proce=
ssor assigned that part; an entity set which contains all part sets is give=
n the PARALLEL_PARTITION tag, whose value is currently meaningless.  The MB=
Zoltan tool included as a tool in MOAB can partition a mesh for parallel so=
lution, and writes the partition to the mesh in the form of parts and parti=
tions.  Both these types of sets can be accessed in a serial mesh, e.g. for=
 visualization.
+
+- <B> Part interfaces </B>
+
+When a partitioned mesh has been loaded on a parallel computer, the part o=
n 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_INT=
ERFACE tag, whose value is currently meaningless.
+
+- <B> Shared processor and handle </B>
+
+For entities shared between processors, it is helpful to know locally whic=
h other processor shares an entity, and what the entity=E2=80=99s handle is=
 on the remote processor.  There are two cases which are useful to distingu=
ish, first where an entity is shared with only one other processor (referre=
d to as shared), and second when a processor is shared by more than one oth=
er 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, r=
espectively.  Multi-shared entities are marked with the PARALLEL_SHARED_PRO=
CS and PARALLEL_SHARED_HANDLES tags; these tags have a length NP assigned a=
t compile time in MOAB, with default values of -1 for processor rank and ze=
ro 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 wou=
ld be [1, 2, -1, -1, =E2=80=A6], with PARALLEL_SHARED_HANDLES values of [m,=
 n, 0, 0, =E2=80=A6], where m and n would be the handles of that entity on =
processors 1 and 2.  The shared versions of these tags are =E2=80=9Cdense=
=E2=80=9D, with default values which denote unshared entities.  The multi-s=
hared tags are sparse tags in MOAB, with no default value.
+
+- <B> Parallel status </B>
+
+In addition to the tags above, MOAB also defines the PSTATUS tag, whose bi=
ts contain information about the parallel status of a given entity.  Starti=
ng 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.  T=
he first bit being set indicates =E2=80=9Cnot owned=E2=80=9D so that the de=
fault value for this tag, of zero, corresponds to an owned, unshared entity=
, which will be the state of most entities on a given processor.
+
+<H3>Structured Mesh Parameters </H3>
+
+MOAB has a structured mesh interface for creating structured mesh (see =E2=
=80=9CScdInterface.hpp=E2=80=9D header file in MOAB source code).  Along wi=
th an internal representation that is more memory-efficient (since it does =
not need to store connectivity), MOAB also creates and tags entity sets wit=
h structured mesh parameters, which can be accessed through the normal tag =
and set interface.  The following tags are used:
+- <B>BOX_DIMS</B>: This tag stores the ijk coordinates of the lower and up=
per corner of the structured mesh box(es).
+- <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 diffe=
rent than the local box dimensions).
+- <B>BOX_PERIODIC</B>: Stores whether the box is periodic in the i (BOX_PE=
RIODIC[0]) and j (BOX_PERIODIC[1]) directions.
+- <B>__BOX_SET</B>: Pointer to the ScdBox instance corresponding to this e=
ntity set.<sup>2</sup>
+.
+Although the structured mesh is not saved as such in HDF5-format files, th=
e entity sets and corresponding tags will be saved and restored.
+
+<sup>2</sup>The double-underscore in the tag name implies that this tag wi=
ll not be saved in a file, in this case because the ScdBox instances are no=
t preserved in a file.
+
+<H3>Spectral Mesh Constructs </H3>
+
+The Spectral Element Method (SEM) is a high-order method, using a polynomi=
al Legendre interpolation basis with Gauss-Lobatto quadrature points, in co=
ntrast to the Lagrange basis used in (linear) finite elements.  A spectral =
mesh with order O contains quadrilateral or hexahedral elements comprised o=
f (O+1)d vertices.  Spectral meshes are usually represented in one of two w=
ays, either as coarse elements which point to an array of higher-order vert=
ices (and with corner vertices represented in the normal manner), or as lin=
ear quads/hexes formed from the higher-order vertices, with each original c=
oarse quad/hex represented by Od fine quads/hexes.  Similarly, the spectral=
 variables, which are normally computed at fine vertex positions, are store=
d either on those vertices, or in lexicographically-ordered arrays on eleme=
nts (with tag values repeated on neighboring elements).  MOAB can read spec=
tral meshes from a variety of formats (at this time, including CAM-SE, HOMM=
E, and Nek5000).  Which of the above two representations are controlled by =
read options and are indicated by certain tags:
+- SPECTRAL_MESH: read option indicating that spectral elements should be r=
epresented as coarse linear quads/hexes and each element containing an arra=
y of lexicographically-ordered vertex handles
+- TAG_SPECTRAL_ELEMENTS: read option; if given, spectral variables are rep=
resented as lexicographically-ordered arrays on elements
+- TAG_SPECTRAL_VERTICES: read option; if given, spectral variables are rep=
resented as tags on vertices
+- CONN=3D<filename>: in CAM-SE, the connectivity of the spectral mesh is s=
tored by default in a file named =E2=80=9CHommeMapping.nc=E2=80=9D; this op=
tion can be given to read the connectivity from a different file
+- SPECTRAL_VERTICES: tag name for array of vertex handles
+- 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
+.
+
+  \ref meta-data-info "Top"
+
+  \section meta-options Reader/Writer Options
+
+All mesh file readers and writers in MOAB take an option string as an argu=
ment.  By default, the semicolon (=E2=80=9C;=E2=80=9D) delimits individual =
options in the option string.  Options used in multiple readers are describ=
ed in this section; the options enabled in specific readers/writers are des=
cribed in the corresponding appendix at the end of this document.
+
+<H3>variable=3D<var_name>[,...]</H3>
+
+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 specifi=
c variables that should be read along with the mesh (note also the =E2=80=
=9Cnomesh=E2=80=9D option, described elsewhere in this document).  The vari=
able name listed will be read into a tag with the same name.  For time-depe=
ndent variables, the time step number will be appended to the variable name=
 to form the tag name.  If no =E2=80=9Ctimestep=E2=80=9D or =E2=80=9Ctimeva=
l=E2=80=9D option is given, all time steps will be read, resulting in sever=
al tags being created.  If the =E2=80=9Cnomesh=E2=80=9D option is given, th=
e application must pass the entity set resulting from the original mesh rea=
d in to the function, that this set must contain the mesh read only from th=
at file.  The mesh in the file is checked against the mesh in the set to ve=
rify that the two correspond.  The special name =E2=80=9CMOAB_ALL_VARIABLES=
=E2=80=9D can be used to indicate that all variables should be read.  Multi=
ple variable names can be specified, separated from each other by commas.
+
+<H3>nomesh </H3>
+
+Indicates that no mesh should be read from the file.  This option is used =
in conjunction with the =E2=80=9Cvariable=3D=E2=80=9D option, to read varia=
bles 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 sh=
ould contain the mesh previously read from the file.
+
+<H3>timestep=3D<step_number>[, ...] </H3>
+
+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 va=
riable(s) will be formed by appending the time step number to the variable =
name.  Multiple time step values can be specified, separated from each othe=
r by commas.
+
+  \ref meta-data-info "Top"
+
+  \section meta-references References
+
+[1]	T.J. Tautges, R. Meyers, K. Merkley, C. Stimpson, and C. Ernst, MOAB: =
A Mesh-Oriented Database, Sandia National Laboratories, 2004.
+
+[2]	L. Diachin, A. Bauer, B. Fix, J. Kraftcheck, K. Jansen, X. Luo, M. Mil=
ler, C. Ollivier-Gooch, M.S. Shephard, T. Tautges, and H. Trease, =E2=80=9C=
Interoperable mesh and geometry tools for advanced petascale simulations,=
=E2=80=9D Journal of Physics: Conference Series,  vol. 78, 2007, p. 012015.
+
+\ref meta-data-info "Top"
+
+  \section appendixA Appendix A: Summary
+
+  \subsection table1 Table 1: Summary of MOAB meta-data conventions.
+
+<table border=3D"1">
+<tr>
+<th>Convention</th>
+<th>Applies to (E=3Dent, S=3Dset)</th>
+<th>Tag(s) (type/length)</th>
+<th>Description</th>
+</tr>
+<tr>
+<td>Name</td>
+<td>E, S</td>
+<td>NAME/C*32</td>
+<td></td>
+</tr>
+<tr>
+<td>Title</td>
+<td>S</td>
+<td>TITLE/C*strlen</td>
+<td>Title of mesh</td>
+</tr>
+<tr>
+<td>Global identifier</td>
+<td>E, S</td>
+<td>GLOBAL_ID/I</td>
+<td></td>
+</tr>
+<tr>
+<td>Geometric topology</td>
+<td>S</td>
+<td>GEOM_DIMENSION/I, GLOBAL_ID/I,
+NAME/C*32,
+CATEGORY/C*32.
+GEOM_SENSE_2/EH[2],
+GEOM_SENSE_N_ENTS/EH*N,
+GEOM_SENSE_N_SENSES/I*N</td>
+<td>Sets contain mesh owned by that entity; parent/child links to bounded/=
bounding entities in geometric model</td>
+</tr>
+<tr>
+<td>Material type</td>
+<td>S</td>
+<td>MATERIAL_SET/I</td>
+<td>Set contains entities or sets assigned a common material type</td>
+</tr>
+<tr>
+<td>Boundary condition</td>
+<td>S</td>
+<td>DIRICHLET_SET/I, NEUMANN_SET/I</td>
+<td>Set contains entities or sets assigned a particular boundary condition=
; neumann sets usually contain edges (2D) or faces (3D)</td>
+</tr>
+<tr>
+<td>Parallel mesh constructs</td>
+<td>E, S</td>
+<td>PARALLEL_PART/I, PARALLEL_PARTITION/I, PSTATUS/C*1, PARALLEL_SHARED_PR=
OC/I, PARALLEL/SHARED_HANDLE/H, PARALLEL_SHARED_PROCS/I*NP, PARALLEL_SHARED=
_HANDLES/H*NP</td>
+<td> Data which describes parallel mesh</td>
+</tr>
+<tr>
+<td>Structured mesh constructs</td>
+<td>S</td>
+<td>BOX_DIMS/I*6, GLOBAL_BOX_DIMS/I*6, BOX_PERIODIC/2*I, __BOX_SET/O</td>
+<td>Data describing structured mesh </td>
+</tr>
+<tr>
+<td>Spectral mesh constructs </td>
+<td>E, S</td>
+<td>SPECTRAL_ORDER/I, SPECTRAL_VERTICES/I*(O+1)^2</td>
+<td>Data marking spectral mesh constructs</td>
+</tr>
+</table>
+=20
+  \ref meta-introduction "Back to Introduction"
+
+  \subsection table2 Table 2: Summary of MOAB conventional tag names, type=
s, and purposes.  Data types are I=3Dinteger, D=3Ddouble, C=3Dcharacter, H=
=3Dentity handle,O=3Dopaque.  Data type with *x denote length of x elements=
 of that data type.
+
+<Table border=3D"1">
+<tr>
+<th>Tag name</th>
+<th>Data type</th>
+<th>Applies to (E=3Dentity, S=3Dset)</th>
+<th>Purpose</th>
+</tr>
+<tr>
+<td>BOX_DIMS</td>
+<td>I*6</td>
+<td>S</td>
+<td>Lower and upper ijk dimensions of box, ordered (ilo, jlo, klo, ihi, jh=
i, khi)</td>
+</tr>
+<tr>
+<td>BOX_PERIODIC</td>
+<td>I*2</td>
+<td>S</td>
+<td>Indicates whether box is periodic in i (BOX_PERIODIC[0]) or j (BOX_PER=
IODIC[1])</td>
+</tr>
+<tr>
+<td>__BOX_SET</td>
+<td>O</td>
+<td>S</td>
+<td>Pointer to corresponding ScdBox instance</td>
+</tr>
+<tr>
+<td>CATEGORY</td>
+<td>C*32</td>
+<td>S</td>
+<td>String describing purpose of set; examples include =E2=80=9Cgroup=E2=
=80=9D, =E2=80=9Cvertex=E2=80=9D, =E2=80=9Cedge=E2=80=9D, =E2=80=9Csurface=
=E2=80=9D, =E2=80=9Cvolume=E2=80=9D</td>
+</tr>
+<tr>
+<td>DIRICHLET_SET </td>
+<td>I</td>
+<td>SO</td>
+<td>Entities or sets with common boundary condition</td>
+</tr>
+<tr>
+<td>GEOM_DIMENSION</td>
+<td>I</td>
+<td>S</td>
+<td>Identifies mesh entities resolving a given geometric model entity</td>
+</tr>
+<tr>
+<td>GEOM_SENSE_2</td>
+<td>EH*2</td>
+<td>S</td>
+<td> Stored on face-type geometric topology sets, values store regions hav=
ing forward and reverse sense</td>
+</tr>
+<tr>
+<td>GEOM_SENSE_N_ENTS</td>
+<td>EH*N</td>
+<td>S</td>
+<td>Stored on edge-type geometric topology sets, values store faces whose =
senses are stored in GEOM_SENSE_N_SENSES.</td>
+</tr>
+<tr>
+<td>GEOM_SENSE_N_SENSES</td>
+<td>I*N</td>
+<td>S</td>
+<td>Stored on edge-type geometric topology sets, values store senses of th=
e edge with respect to faces stored in GEOM_SENSE_N_ENTS.</td>
+</tr>
+<tr>
+<td>GLOBAL_ID</td>
+<td>I</td>
+<td>E,S</td>
+<td>Application-specific entity id</td>
+</tr>
+<tr>
+<td>MATERIAL_SET</td>
+<td>I</td>
+<td>S</td>
+<td>Entities or sets grouped by material type</td>
+</tr>
+<tr>
+<td>NAME</td>
+<td>C*32</td>
+<td>E, S</td>
+<td>User-assigned entity name(s); multiple names delimited with ?</td>
+</tr>
+<tr>
+<td>NEUMANN_SET</td>
+<td>I</td>
+<td>S</td>
+<td>Entities or sets with common boundary condition </td>
+</tr>
+<tr>
+<td>PARALLEL_PART </td>
+<td>I</td>
+<td>S</td>
+<td>Represent a part in a partition</td>
+</tr>
+<tr>
+<td>PARALLEL_PARTITION</td>
+<td>I</td>
+<td>S</td>
+<td>Represents a partition of the mesh for parallel solution, which is a c=
ollection of parts</td>
+</tr>
+<tr>
+<td>__PARALLEL_SHARED_HANDLEd</td>
+<td>H</td>
+<td>E, S</td>
+<td> Handle of this entity/set on sharing processor</td>
+</tr>
+<tr>
+<td>__PARALLEL_SHARED_PROC</td>
+<td>I</td>
+<td>E,S</td>
+<td>Rank of other processor sharing this entity/set </td>
+</tr>
+</table>
+
+\ref meta-data-info "Top"
+
+  \section appendixB Appendix B: CCMIO (Star-CD, Star-CCM+) Reader/Writer =
Conventions
+
+  \subsection table3 Table 3: Translation between CCMIO options and MOAB t=
ags.
+<Table border=3D"1">
+<tr>
+<th> Set Type</th>
+<th>CCMIO Construct</th>
+<th>MOAB Tag Name, Type</th>
+</tr>
+<tr>
+<td rowspan=3D"2">File set / Interface</td>
+<td>Title (option)</td>
+<td>=E2=80=9CTitle=E2=80=9D (C*32)</td>
+</tr>
+<tr>
+<td>CreatingProgram</td>
+<td>=E2=80=9CCreatingProgram=E2=80=9D (C*32)</td>
+</tr>
+<tr>
+<td rowspan=3D"13">Material sets</td>
+<td>Index</td>
+<td>MATERIAL_SET</td>
+</tr>
+<tr>
+<td>Label<sup>1</sup></td>
+<td>NAME</td>
+</tr>
+<tr>
+<td>MaterialId</td>
+<td>=E2=80=9CMaterialId=E2=80=9D (I)</td>
+</tr>
+<tr>
+<td>Radiation</td>
+<td>=E2=80=9CRadiation=E2=80=9D (I)</td>
+</tr>
+<tr>
+<td>PorosityId</td>
+<td>=E2=80=9CPorosityId=E2=80=9D (I)</td>
+</tr>
+<tr>
+<td>SpinId</td>
+<td>=E2=80=9CSpinId=E2=80=9D (I)</td>
+</tr>
+<tr>
+<td>GroupId</td>
+<td>=E2=80=9CGroupId=E2=80=9D (I)</td>
+</tr>
+<tr>
+<td>ColorIdx</td>
+<td>=E2=80=9CColorIdx=E2=80=9D (I)</td>
+</tr>
+<tr>
+<td>ProcessorId</td>
+<td>=E2=80=9CProcessorId=E2=80=9D (I)</td>
+</tr>
+<tr>
+<td>LightMaterial</td>
+<td>=E2=80=9CLightMaterial=E2=80=9D (I)</td>
+</tr>
+<tr>
+<td>FreeSurfaceMaterial</td>
+<td>=E2=80=9CThickness=E2=80=9D (F)</td>
+</tr>
+<tr>
+<td>Thickness</td>
+<td>=E2=80=9CThickness=E2=80=9D (F)</td>
+</tr>
+<tr>
+<td>MaterialType</td>
+<td>=E2=80=9CMaterialType=E2=80=9D (C*32)</td>
+</tr>
+<tr>
+<td rowspan=3D"5">Neumann sets</td>
+<td>Index</td>
+<td>NEUMANN_SET</td>
+</tr>
+<tr>
+<td>Label</td>
+<td>NEUMANN_SET</td>
+</tr>
+<tr>
+<td>BoundaryName</td>
+<td>NAME</td>
+</tr>
+<tr>
+<td>BoundaryType</td>
+<td>=E2=80=9CBoundaryType=E2=80=9D (C*32)</td>
+</tr>
+<tr>
+<td>ProstarRegionNumber</td>
+<td>=E2=80=9CProstarRegionNumber=E2=80=9D (I)</td>
+</tr>
+</table>
+
+Notes:
+1. If no name is present, labels the material group with =E2=80=9CMaterial=
X=E2=80=9D, where X is the index of that group.
+
+\ref meta-data-info "Top"
+
+  \section appendixC Appendix C: ExodusII Reader/Writer Conventions=20
+
+  \subsection table4 Table 4: Translation between ExodusII constructs and =
MOAB tags.
+<Table border=3D"1">
+<tr>
+<th> Data Type</th>
+<th>ExodusII Construct</th>
+<th>MOAB Tag Name, Type</th>
+</tr>
+<tr>
+<td></td>
+<td>QA records</td>
+<td>=E2=80=9CqaRecord=E2=80=9D (C*(v))<sup>2</sup></td>
+</tr>
+<tr>
+<td rowspan=3D"2">Material sets</td>
+<td>Block number</td>
+<td>MATERIAL_SET</td>
+</tr>
+<tr>
+<td>Block element type</td>
+<td>Entity type, # vertices per entity</td>
+</tr>
+<tr>
+<td rowspan=3D"2">Dirichlet sets<sup>3</sup></td>
+<td>Nodeset number</td>
+<td>DIRICHLET_SET</td>
+</tr>
+<tr>
+<td>Distribution factors</td>
+<td>=E2=80=9CdistFactor=E2=80=9D (D*(v))<sup>1</sup></td>
+</tr>
+<tr>
+<td>Neumann sets</td>
+<td>Sideset number</td>
+<td>NEUMANN_SET</td>
+</tr>
+<tr>
+<td rowspan=3D"2">Neumann sets, reverse faces3<sup>3</sup></td>
+<td>Distribution factors</td>
+<td>=E2=80=9CdistFactor=E2=80=9D (D*(v))<sup>1</sup></td>
+</tr>
+<tr>
+<td>Sides</td>
+<td>SENSE</td>
+</tr>
+<tr>
+<td>Nodes, elements</td>
+<td>node_num_map, elem_map</td>
+<td>GLOBAL_ID on nodes/elements</td>
+</tr>
+</table>
+
+Notes:
+-# Variable-length tag used for distribution factors; length for each set =
is the number of entities in
+each set, such that there is one distribution factor for each entity in th=
e set.
+-# QA records are stored as variable-length tags on file set specified on =
read. Tag is a
+concatenation of QA record strings into a single string, with '\0' used to=
 delimit lines.
+-# MOAB represents sidesets as sets of faces, rather than as sides of elem=
ents. Faces can be
+ordered =E2=80=9Cforward=E2=80=9D or =E2=80=9Creverse=E2=80=9D with respec=
t to one of the bounding elements, depending on
+whether the right-hand normal points into or out of the element. Forward-s=
ense faces are added
+to the Neumann set. Reverse-sense faces are put into a separate set; that =
set is tagged with the SENSE tag, with value =3D -1; and that reverse set i=
s added to the Neummann set.
+.
+
+  \ref meta-data-info "Top"
+
+  \section appendixD Appendix D: NC (Climate Data) Reader/Writer Conventio=
ns
+
+The climate data reader in MOAB reads files with the '.nc' filename extens=
ion. By default, this reader
+reads the whole mesh in the file and creates it as structured mesh in MOAB=
, with the mesh accessible
+through MOAB's structured mesh interface. By default, all variables and ti=
mesteps are read from the
+file, and written as tags on the mesh vertices from that file. This behavi=
or is controlled by the
+=E2=80=9Cvariable=E2=80=9D, =E2=80=9Cnomesh=E2=80=9D, =E2=80=9Ctimestep=E2=
=80=9D, and =E2=80=9Ctimeval=E2=80=9D options described earlier in this doc=
ument. If MOAB
+is compiled for parallel execution and configured with a pnetcdf reader, t=
he mesh is read in parallel,
+with a 1D or 2D decomposition designed to balance read performance and com=
munication interface
+size (for details on the partitioning method used, see the src/io/ReadNC.c=
pp source file).
+
+Mesh is put into the entity set provided to the load_file function. This e=
ntity set is also annotated with
+various tags representing information read from the file. These tags are d=
escribed in Table 5.
+
+Several other things to note about reading climate data files into MOAB:
+- Time-dependent variables: MOAB currently has no mechanism for time-depen=
dent tags. Therefore, time-dependent variables are represented using one ta=
g per timestep, with the tag name set as the variable name plus the timeste=
p index. Thus, the first few timesteps for the variable TEMPERATURE would b=
e represented in tags named TEMPERATURE0, TEMPERATURE1, etc.
+- Cell- and face-centered variables: The climate data reader currently doe=
s not do cell- and face-
+centered variables correctly.
+.
+  \subsection table5 Table 5: Summary of MOAB conventional tag names, type=
s, and purposes. Data types are I=3Dinteger, D=3Ddouble, C=3Dcharacter, H=
=3Dentity handle. Data type with *x denote length of x elements of that dat=
a type; data type with *var denote variable-length tag. Tag names with two =
underscores prepended (=E2=80=9C__=E2=80=9D) denote tags not written to a f=
ile by MOAB.
+
+<Table border=3D"1">
+<tr>
+<th> Tag name </th>
+<th>Data type </th>
+<th> Applies to (E=3Dentity, S=3Dset) </th>
+<th>Purpose </th>
+</tr>
+<tr>
+<td>__NUM_DIMS </td>
+<td>I</td>
+<td>S</td>
+<td>The number of dimensions in the netcdf file.</td>
+</tr>
+<tr>
+<td>__NUM_VARS</td>=20
+<td>I</td>
+<td>S</td>
+<td>The number of variables in the netcdf file.</td>
+</tr>
+<tr>
+<td>__DIM_NAMES </td>
+<td>C*var </td>
+<td>S </td>
+<td>The dimension names, concatenated into a
+character string, with '\0' terminating each name.
+ </td>
+</tr>
+<tr>
+<td>__DIM_NAMES=20
+</td>
+<td>C*var</td>
+<td>S</td>
+<td>The variable names, concatenated into a character
+string, with '\0' terminating each name.
+</td>
+</tr>
+<tr>
+<td><dim_name>=20
+</td>
+<td>(I or=20
+D)*va=20
+</td>
+<td>S</td>
+<td>For each dimension, the values for the dimension.
+The data type for this tag corresponds to that in the
+netcdf file. The length of this tag is the number of
+values stored for the dimension in the netcdf file.</td>
+</tr>
+<tr>
+<td>__<dim_name>_LOC_MIN MAX</td>=20
+<td>2*(I or D)</td>
+<td>S</td>
+<td>The indices (0-based) of the local min and max
+values of dimension stored locally. For spatial
+dimensions like lon or lat, this will store the
+minimum and maximum indices in the loca</td>
+</tr>
+<tr>
+<td >__<dim_name>_LOC_VAL </td>=20
+<td>(I or D)*var </td>
+<td>S</td>
+<td>The indices (0-based) of the dimension stored
+locally. This tag only makes sense for dimensions
+that can be read in multiple pieces, such as time.
+Only one of __<dim_name>_LOC_VALS and
+_LOC_MIN_MAX can be used for a given
+dimension.
+</tr>
+<tr>
+<td>__<var_name>_DIMS=20
+</td>
+<td>C*n=20
+</td>
+<td>S</td>
+<td>For each variable, the tag handles for the
+dimensions defining this variable, in netcdf
+ordering (last dimension varying fastest). The
+length of this tag, n, is # dimensions for the
+variable * sizeof(TagHandle).
+</td>
+</tr>
+<tr>
+<td><var_name><timestep_ind>=20
+</td>
+<td>(data type)</td>
+<td>E</td>
+<td>Values of the variable for timestep <timestep_ind>
+for vertices. The data type of this tag corresponds
+to that of the variable from the netcdf file.
+Timestep index is 0-based.
+</td>
+</tr>
+<tr>
+<td>__GLOBAL_ATTRIBS=20
+</td>
+<td>C*Var=20
+</td>
+<td>S</td>
+<td>The global attributes, concatenated into a character
+string, with =E2=80=98\0=E2=80=99 terminating each attribute name, =E2=80=
=98;=E2=80=99
+       separating the data type and value, and =E2=80=98;=E2=80=99
+          separating one name/data type/value from the next.
+</td>
+</tr>
+<tr>
+<td>__GLOBAL_ATTRIBS_LEN=20
+</td>
+<td>I*Var=20
+</td>
+<td>S</td>
+<td>A vector of integers, marking the end position of
+each attribute (name/data type/value) in __GLOBAL_ATTRIBS tag.
+</td>
+</tr>
+<tr>
+<td>__<var_name>_ATTRIBS=20
+</td>
+<td>C*Var
+</td>
+<td>S</td>
+<td>The variable attributes, concatenated into a
+character string, with =E2=80=98\0=E2=80=99 terminating each attribute
+   name, =E2=80=98;=E2=80=99 separating the data type and value, and =E2=
=80=98;=E2=80=99
+          separating one name/data type/value from the next.
+</td>
+</tr>
+<tr>
+<td>__<var_name>_ATTRIBS_LEN=20
+</td>
+<td>I*Var
+</td>
+<td>S</td>
+<td>A vector of integers, marking the end position of
+each attribute (name/data type/value) in
+__<var_name>_ATTRIBS tags
+</td>
+</tr>
+</table>
+
+  \ref meta-data-info "Top"
+
+  \section appendixE Appendix E: Nek5000 Reader/Writer Conventions
+
+Nek5000, or Nek, is a code that uses the spectral element method to model =
fluid, heat transfer,
+electromagnetics, and other physics. Nek uses unstructured hexahedral mesh=
es, with each hex element
+resolved by a structured grid of =E2=80=9CGauss Lebato Legendre=E2=80=9D (=
GLL) points. Nek can read meshes through
+MOAB, and can output physics variables and GLL points through MOAB as well.
+
+Since fluid is a single material in Nek, no material sets are needed. Boun=
dary conditions are mapped to
+Nek's cbc array using Neumann sets and a user-provided =E2=80=9Cusr_moab2n=
ek=E2=80=9D subroutine (for an example
+of this subroutine, see examples/moab/pipe.usr in the Nek source code). GL=
L point locations and fluid
+variables on those points are stored in tags on the hex elements. All hex =
elements have the same
+number of GLL points. The number of GLL points in each direction is stored=
 in a tag on the mesh
+instance. These tags are described in Table 6.
+
+GLL point locations and fluid variables are stored in lexicographic order,=
 similar to their storage order
+inside the Nek code.
+
+  \subsection table6 Table 6: Summary of MOAB conventional tag names, type=
s, and purposes for Nek. Data types are I=3Dinteger, D=3Ddouble, C=3Dcharac=
ter, H=3Dentity handle. Data type with *x denote length of x elements of th=
at data type; data type with *var denote variable-length tag. Tag names wit=
h two underscores prepended (=E2=80=9C__=E2=80=9D) denote tags not written =
to a file by MOAB.
+<Table border=3D"1">
+<tr>
+<th> Tag name </th>
+<th> Data Type</th>
+<th>Applies to (E=3Dentity, S=3Dset)</th>
+<th>Purpose</th>
+</tr>
+<tr>
+<td>SEM_DIMS</td>
+<td>I*3</td>
+<td>S</td>
+<td>The dimensions of the GLL mesh in each hex
+element.
+</td>
+</tr>
+<tr>
+<td>SEM_X</td>
+<td>D*nx*ny*nz</td>
+<td>E</td>
+<td>X position of GLL points (having nx*ny*nz
+values)
+</td>
+</tr>
+<tr>
+<td>SEM_Y</td>
+<td>D*nx*ny*nz</td>
+<td>E</td>
+<td>Y position of GLL points (having nx*ny*nz values)</td>
+</tr>
+<tr>
+<td>SEM_Z</td>
+<td>D*nx*ny*nz</td>
+<td>E</td>
+<td>Z position of GLL points (having nx*ny*nz values)</td>
+</tr>
+<tr>
+<td>VEL_X</td>
+<td>D*nx*ny*nz</td>
+<td>E</td>
+<td>Fluid velocities in the x direction for GLL point
+array (having nx*ny*nz values)</td>
+</tr>
+<tr>
+<td>VEL_Y</td>
+<td>D*nx*ny*nz</td>
+<td>E</td>
+<td>Fluid velocities in the y direction for GLL point
+array (having nx*ny*nz values)</td>
+</tr>
+<tr>
+<td>VEL_Z</td>
+<td>D*nx*ny*nz</td>
+<td>E</td>
+<td>Fluid velocities in the z direction for GLL point
+array (having nx*ny*nz values)</td>
+</tr>
+<tr>
+<td>TEMP</td>
+<td>D*nx*ny*nz</td>
+<td>E</td>
+<td>Fluid temperature for GLL point array (having
+nx*ny*nz values)
+</td>
+</tr>
+<tr>
+<td>PRESS</td>
+<td>D*nx*ny*nz</td>
+<td>E</td>
+<td>Fluid pressure for GLL point array (having
+nx*ny*nz values)
+</td>
+</tr>
+</table>
+  \ref meta-data-info "Top"
+	*/

Repository URL: https://bitbucket.org/fathomteam/moab/

--

This is a commit notification from bitbucket.org. You are receiving
this because you have the service enabled, addressing the recipient of
this email.


More information about the moab-dev mailing list