[MOAB-dev] commit/MOAB: janehu: Added the figures for developer's guide.
commits-noreply at bitbucket.org
commits-noreply at bitbucket.org
Wed Jul 17 11:17:34 CDT 2013
1 new commit in MOAB:
https://bitbucket.org/fathomteam/moab/commits/99aa30a5c8d8/
Changeset: 99aa30a5c8d8
Branch: master
User: janehu
Date: 2013-07-17 18:16:40
Summary: Added the figures for developer's guide.
Affected #: 4 files
diff --git a/doc/DG/figure1.jpg b/doc/DG/figure1.jpg
new file mode 100644
index 0000000..e102a97
Binary files /dev/null and b/doc/DG/figure1.jpg differ
diff --git a/doc/DG/figure2.jpg b/doc/DG/figure2.jpg
new file mode 100644
index 0000000..7e8b199
Binary files /dev/null and b/doc/DG/figure2.jpg differ
diff --git a/doc/DG/figure3.jpg b/doc/DG/figure3.jpg
new file mode 100644
index 0000000..8810bfc
Binary files /dev/null and b/doc/DG/figure3.jpg differ
diff --git a/doc/DG/moabDG.h b/doc/DG/moabDG.h
index 1724436..51281b1 100644
--- a/doc/DG/moabDG.h
+++ b/doc/DG/moabDG.h
@@ -1,20 +1,20 @@
-/*! \page developerguide Developer's Guide (MOAB 4.6)
-
- \subpage dg-contents
-
- \subpage dg-figures
-
+/*! \page developerguide Developer's Guide (MOAB 4.6)
+
+ \subpage dg-contents
+
+ \subpage dg-figures
+
*/
-
-/*! \page dg-figures List of Figures
-
- \ref figure1
-
- \ref figure2
-
- \ref figure3
+
+/*! \page dg-figures List of Figures
+
+ \ref figure1
+
+ \ref figure2
+
+ \ref figure3
*/
-
+
/*! \page dg-contents Table of Contents
@@ -29,6 +29,10 @@
\section sequence EntitySequence & SequenceData
\subsection figure1 Figure 1: EntitySequences For One SequenceData
+ <img src="../../DG/figure1.jpg">
+
+ \ref dg-figures "List of Figures"
+
The <I>SequenceData</I> class manages as set of arrays of per-entity values. Each
<I>SequenceData</I> has a start and end handle denoting the block of entities for which
the arrays contain data. The arrays managed by a <I>SequenceData</I> instance are
@@ -104,6 +108,9 @@ enforces the following four rules on its contained data:
.
\subsection figure2 Figure 2: SequenceManager and Related Classes
+ <img src="../../DG/figure2.jpg">
+
+ \ref dg-figures "List of Figures"
The first three rules are required for the validity of the data model. The
fourth rule avoids unnecessary inefficiency. It is implemented by merging such
@@ -153,111 +160,114 @@ such as allocating the correct <I>EntitySequence</I> subtype for a given <I>Enti
<sup>2</sup>Given rule four for the data managed by a <I>TypeSequenceManager</I>, any <I>SequenceData</I> for which all handles are allocated will be referenced by exactly one <I>EntitySequence</I>.
\ref dg-contents "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>StructuredElementSeq</I> class is
-used to access the structured element connectivity. A standard <I>VertexSequence</I>
-instance is used to access the ScdVertexData because the vertex data storage
-is the same as for unstructured mesh.
-
- \ref dg-contents "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>EntityHandle</I>.
-<I>SequenceData</I> allocates all of its managed arrays using malloc and free 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 to what is
-done by <I>std::vector</I> and other container classes that may own more storage
-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> class.
-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>MESHSET_TRACK_OWNER</I>
-indicates that reverse links from the contained entities back to the owning 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 code only
-tests for the <I>MESHSET_ORDERED</I>, meaning that in practice the <I>MESHSET_SET</I> bit is
-ignored. <I>MESHSET_ORDERED</I> indicates that the set may contain duplicate handles
-and that the order that the handles are added to the set should be preserved.
-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 ‘size’ field and two
-values, where the two values may either be two handles or two pointers. The size
-bit-fields are grouped together to reduce the required amount of memory. If the
-numerical value of the 2-bit size field is 0 then the corresponding list is empty.
-If the 2-bit size field is either 1 or 2, then the contents of the corresponding list
-are stored directly in the corresponding two data fields of the MeshSet object.
-If the 2-bit size field has a value of 3 (11 binary), then the corresponding two
-data fields store the begin and end pointers of an external array of handles.
-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 ‘used’ 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 ‘allocated’ size
-for us. In practice this performs well but does not return memory to the ‘system’
-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 frequently changes
-between less than two and more than two handles, as this will result in frequent
-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 list (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 two.
-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 ‘adjacent’ range pairs are merged into a
-single pair. The code for insertion and removal of handles from range-formatted
-set content lists is fairly complex. The implementation will guarantee that 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 ‘n’ is the number of handles to insert
-and ‘m’ 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 set.
-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 potential ‘slots’
-in the MeshSet object then if two of the lists are empty it should be possible to store up to six values of the remaining list directly in the MeshSet object.
-However, the additional runtime cost of such complexity could easily outweigh
-any storage advantage. Further investigation into this has not been done because
-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 ‘blocked’ format. The corre-
-sponding <I>SequenceData</I> would contain four arrays: flags, parents, children, 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 the storage
-reduction would depend greatly on how sets get grouped into <I>SequenceDatas</I>.
-This alternate storage scheme might also allow for better cache utilization 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 never
-query the parents or children of any set. Or that an application will query 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 less mod-
-ular and maintainable because the existing logic contained in the <I>MeshSet</I> class
-would need to be spread throughout the <I>MeshSetSequence</I> class.
-
- \ref dg-contents "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>StructuredElementSeq</I> class is
+used to access the structured element connectivity. A standard <I>VertexSequence</I>
+instance is used to access the ScdVertexData because the vertex data storage
+is the same as for unstructured mesh.
+
+ \ref dg-contents "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>EntityHandle</I>.
+<I>SequenceData</I> allocates all of its managed arrays using malloc and free 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 to what is
+done by <I>std::vector</I> and other container classes that may own more storage
+than is required at a given time for contained objects.
+
+- MeshSet
+
+ \subsection figure3 Figure 3: SequenceManager and Related Classes
+ <img src="../../DG/figure3.jpg">
+
+ \ref dg-figures "List of Figures"
+
+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> class.
+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>MESHSET_TRACK_OWNER</I>
+indicates that reverse links from the contained entities back to the owning 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 code only
+tests for the <I>MESHSET_ORDERED</I>, meaning that in practice the <I>MESHSET_SET</I> bit is
+ignored. <I>MESHSET_ORDERED</I> indicates that the set may contain duplicate handles
+and that the order that the handles are added to the set should be preserved.
+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 ‘size’ field and two
+values, where the two values may either be two handles or two pointers. The size
+bit-fields are grouped together to reduce the required amount of memory. If the
+numerical value of the 2-bit size field is 0 then the corresponding list is empty.
+If the 2-bit size field is either 1 or 2, then the contents of the corresponding list
+are stored directly in the corresponding two data fields of the MeshSet object.
+If the 2-bit size field has a value of 3 (11 binary), then the corresponding two
+data fields store the begin and end pointers of an external array of handles.
+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 ‘used’ 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 ‘allocated’ size
+for us. In practice this performs well but does not return memory to the ‘system’
+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 frequently changes
+between less than two and more than two handles, as this will result in frequent
+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 list (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 two.
+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 ‘adjacent’ range pairs are merged into a
+single pair. The code for insertion and removal of handles from range-formatted
+set content lists is fairly complex. The implementation will guarantee that 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 ‘n’ is the number of handles to insert
+and ‘m’ 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 set.
+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 potential ‘slots’
+in the MeshSet object then if two of the lists are empty it should be possible to store up to six values of the remaining list directly in the MeshSet object.
+However, the additional runtime cost of such complexity could easily outweigh
+any storage advantage. Further investigation into this has not been done because
+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 ‘blocked’ format. The corre-
+sponding <I>SequenceData</I> would contain four arrays: flags, parents, children, 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 the storage
+reduction would depend greatly on how sets get grouped into <I>SequenceDatas</I>.
+This alternate storage scheme might also allow for better cache utilization 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 never
+query the parents or children of any set. Or that an application will query 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 less mod-
+ular and maintainable because the existing logic contained in the <I>MeshSet</I> class
+would need to be spread throughout the <I>MeshSetSequence</I> class.
+
+ \ref dg-contents "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