Advanced Scientific Computing Research (ASCR) under the U.S. Department of Energy Office of Science (Office of Science)

Project Team Members:

Northwestern University

The HDF Group

Argonne National Laboratory

North Carolina State University

Northwestern University - EECS Dept.


This page describes the data model for Damsel. This data model describes the language used to communicate with Damsel. Much of the inspiration for this data model comes from MOAB and ITAPS, though in some specific ways it is not identical to those.

1. Dimension

  1. Def: An independent variable with specified name and fixed or unlimited length.
  2. Specification: Each dimension has a name, either a non-negative or unlimited (specified with "-1") length, and an optional associated tag (see "Tags" below) with the same name.
  3. Length, Values, Range: The length of a dimension, denoted L(dimname), is fixed (for the entire file), or unlimited. If fixed, there are L(dimname) values, with range denoted R(dimname). Values of dimension can be any type supported by tags (see "Tags" below). For unlimited length dimensions, the number of values is implied by the number of values for tags appearing in the file.
  4. Association with a tag: A dimension can be uniquely associated with a single tag; by convention, the tag name is the same as the dimension name, and the tag data type determines the data type of the values for that dimension.
  5. Discretization: Dimensions come with a built-in discretization, which may be at odds with the notion of a mesh. So, for example, a tag associated with the X, Y, and Z dimensions, assigned to mesh vertices, implies a value for a given vertex at each of the discrete values associated with the X, Y, and Z dimensions. On the other hand, a tag associated with the TIME dimension assigned to mesh vertices implies a distinct value at a vertex for each discrete time value, which fits with the notion of a time-dependent solution variable.

2. Space

  1. Def: A space is a named grouping of one or more dimensions, and implies a product space of those dimensions.
  2. Tag associated with a space: A tag can be associated with a space, implying that each value of the tag has a number of entries equal to the product of the lengths of the dimensions in the space.
  3. Usage: Grouping dimensions into a space implies some semantics of tags associated with the space. The length and values for the dimensions in a space may partition the space according to some discretization scheme. For example, an angular space may be defined as a grouping of two dimensions, theta and phi, whose ranges are (0, 2*PI) and (0, PI), respectively. A value for a tag associated with the angular space would have a number of values equal to L(theta)*L(phi).

3. Units

  1. Def: A characterization of the metric used for a given dimension or quantity.
  2. Specification: Units have:
    • a name
    • an abbreviation
    • zero or more tuples of (base unit/numerator exponent/denominator exponent/offset/multiple); units with zero tuples are dimensionless, and represent a cardinality or number of something.
    • an optional quantity name
    • a handle
  3. Base units: Damsel defines seven base units, corresponding to the SI system's seven base quantities expressed in SI's seven base units[NIST]. The base units, and the quantities they measure, are shown in the following table:
    =========== =======================================
    Name        Abbrev        Base quantity
    =========== ============  =========================
     Kilogram   kg            Mass 
     Meter      m             Length 
     Second     s             Time 
     Kelvin     K             Thermodynamic temperature 
     Ampere     A             Electric current 
     Candella   cd            Luminous intensity 
     Mole       mol           Amount of substance 
    =========== ============  =========================
  4. Derived units: Derived units are specified in terms of the tuples described above, i.e. zero or more tuples (unit/numerator exponent/denominator exponent/offset/multiple). For example, density, specified in terms of kg/m3, is composed from the tuples (kg/1/0/0/1) and (m/0/3/0/1).
  5. Conversion: Given two values of a quantity in two unit systems, conversion between those can be computed using the specification of the units in one of those systems in terms of the other. For example, if (cm/1/0/0/1) in system 1 is equivalent to (m/1/0/0/.01), the conversion from cm to m is given by ((m/cm)/1/0/0/.01) or 0.01 m/cm. More interestingly, for (kg/1/0/0/1), (m/0/3/0/1) and (2.2lb/1/0/0/1), (39.4in/0/3/0/1), conversion from kg/m3 to lb/in3 is (2.2)/(39.43) = 3.61e-5. Note, there's some sort of algebra here in these tuples that I'm not capturing...

4. Entity

  1. Def: Topological entity of prescribed or non-prescribed topological type.
  2. Entity type: An enumeration of the entities treated by Damsel.
  3. Prescribed-topology entity types: {Vertex, Edge, Triangle, Quadrilateral, Tetrahedron, Pyramid, Prism, Septahedron, Hexahedron)
  4. Non-prescribed topology entities: {Polygon, Polyhedron}
  5. Corner vertices: The minimum set of vertices required to describe a prescribed-topology entity.
  6. Connectivity (1) and canonical ordering: Each prescribed-topology entity has a prescribed number, arrangement, and local (within-entity) numbering of corner vertices to form the entity. Damsel will use a 0-based numbering system, where vertices are numbered from 0..N-1, N being the number of corner vertices in the entity. The relative placement of vertices defining an entity is described by the entity's canonical numbering. The canonical numbering for the prescribed- topology entity types above is described in [Tau09] (for all but Septahedrons) and by [iMesh] (for Septahedrons).
  7. Topological dimension: The number of independent directions in the local space of an entity. Each entity type in Damsel has a topological dimension:
    ========== ================================================================
    Dimension  Entity type(s)                                   
    ========== ================================================================
    0          Vertex                                           
    1          Edge                                             
    2          Triangle, Quadrilateral, Polygon                               
    3          Tetrahedron, Pyramid, Prism, Septahedron, Hexahedron, Polyhedron
    ========== ================================================================
  8. Topology: the entity types treated by damsel relate together through a topology. A topology is defined as a set where if any two members of a set intersect, the intersection is also a member of the set. In the context of Damsel entity types, this means that entities of lower topological dimension bound entities of higher dimension. For prescribed-topology entities, only specific adjacency relationships are allowed, and are described by the canonical numbering. For example, tetrahedron entities are bounded by four triangles, 6 edges, and 4 vertices. If a tetrahedron has vertices numbered 0 to 3, its faces will be composed of vertices (0, 1, 2), (0, 1, 3), (1, 2, 3), (2, 0, 3). These numbering relationships are also described in [Tau09].
  9. Polygon, polyhedron: a Polygon has an ordering implied by its vertices, with local numbering 0..N-1. A Polyhedron is described only by its 2D facets, each of type Triangle, Quadrilateral, or Polygon. There is no canonical numbering of the vertices in a Polyhedron.

5. Entity Handle

  1. Def: Once created, individual entities are referenced using an entity handle.
  2. Data type: The data type used for entity handles is implementation-defined. Examples of handle types include pointer, integer index, or a combination of bitmask in high-order bits and id in remaining bits. An entity handle is an integral type that supports increment, decrement, and range operations. Specifically, a collection of contiguous entity handles can be specified as a start handle and end handle, or as a start handle and number of entities.
  3. Uniqueness: If two handles returned by a given Damsel instance are the same, they refer to the same entity.
  4. Connectivity (2): An entity of any type except Polyhedron is described by its connectivity, which is a list of vertex handles which form the entity. For example, a hexahedron entity is described by its 8 vertex handles.

6. High-order entities

  1. Def: In addition to its corner vertices, entities can also be bounded by non-corner vertices. These vertices are referred to as "high-order" vertices, and entities having them are referred to as "high-order entities". Each high-order vertex is associated with a single 1D, 2D, or 3D facet of an entity, and each of those facets may be resolved by one or more high-order vertices.
  2. Connectivity: The connectivity of an entity is described by listing its corner vertices first, followed by high-order vertices on its bounding 1-d facets, its bounding 2-d facets, and its 3-d facet.
  3. Connectivity vector disambiguity: Several schemes are required for representing the connectivity of the entity in terms of its (corner and high-order) vertices, distinguished by the degree of constraints placed on numbers of high-order vertices allowed on facets of an entity and the amount of extra data required to resolve connectivity of the entity's facets. Listed in order of decreasing constraints:
    1. 0-1-equal-facet: All facets of a given dimension have the same number of high-order vertices, and that number is either 0 or 1. In this case, the entity type and the total number of vertices in an entity is enough to determine which facet dimensions of the entity have 0 or 1 high-order vertices, without ambiguities. For example, if a hexahedron has a total of 20 vertices, that hexahedron has high-order vertices on its edges, but not on its faces or in the hexahedron.
    2. 2+-equal-allfacets: All facets have exactly n high-order vertices, n > 1. For all prescribed-topology entity types plus Polygons, given the number of vertices, and n, and the high-order scheme (in this case 2+-equal-allfacets), the connectivity of the entity can be described with a list of vertices, with no ambiguity of placement of the (corner or high-order) vertices in the entity. The ordering of vertices in the connectivity list is as before, with all corner vertices listed first, then high-order vertices for 1D facets next, and so on.
    3. general: For the fully general case, where each facet can have a different number of high-order vertices, the entity can be described by a) the high-order scheme, in this case "general"; b) a connectivity vector, with corner vertices appearing first, 1D facet high-order vertices appearing next, and so on; and c) a vector of integers listing the number of high-order vertices on each facet, listed in order of increasing dimension, with the vertex dimension skipped (since 0D facets are not resolved with high-order nodes). For example, this vector for a 21-node hexahedron (with mid-edge and mid-hexahedron vertices) would be (12*(1), 6*(0), 1).

7. Entity Set

  1. Def: An entity set is an arbitrary (i.e. application-defined) collection of handles, where handles refer to entities, sets, tags, dimensions, units, or the interface itself.
  2. Handle: Entity sets are referenced using handles; the handle type used to refer to entity sets is the same data type as that used for other handles (i.e. for entities, tags, dimensions, units, and interface).
  3. Set or List type: A Set-type entity set allows only a single instance of a handle in the container, with handles returned in sorted order. A List-type entity set allows duplicate handles in the container, with handles returned in the order they were added to the entity set.
  4. Parent/child relations with other sets: Entity sets can be linked to other sets by designating parent or child relations with those sets. Parent/child relations are distinct from contains relations; that is, if entity set A is a parent of entity set B, A does not contain B. Parent/child relations are useful for storing graph-type data with a mesh, e.g. the geometric topology of the CAD model used to generate a mesh, or a tree decomposition of a mesh.
  5. Root set: Damsel defines a special "root set", which by convention is the set containing all entities, entity sets, tags, dimensions, and units, defined in a given Damsel database or instance. By definition, handles cannot be removed from or added to the root set; instead, data objects are deleted or created.

8. Tag

  1. Def: A tag is a piece of data that can take on a distinct value for each entity, entity set, tag, dimension, unit, or the root set. A tag has specified name, size type, size (in bytes), optional data type, optional default value, and optional storage type.
  2. Handle: After a tag is created, it is referred to using a handle returned from the tag creation function. The tag handle is stored using the same data type as is used for other handles.
  3. Data type: Supported data types for tags are: Int32, Int64, float, double, handle, opaque.
  4. Storage type: Supported storage types are: sparse, dense. Sparse tags are implied to be stored as (handle, value) tuples, with API functions optimized for access on individual entities. Dense tags are implied to be stored as (tag value 1, tag value 2, ...), for blocks of entities, with API functions optimized for access for blocks of entities.
  5. Default value: If a tag has been created with a default value, all tag query functions for that tag on an entity/set/tag/dimension/units/root set not yet assigned a value for that tag will return the default value. The implementation has the option of optimizing out the storage for blocks of entities not yet assigned a value for such a tag.
  6. Size type: Allowed values are: fixed, variable. For a tag with variable size type, both the value and size of this tag can vary for each entity/set/tag/dimension/units/root set. Variable-size tags are useful for storing string data in tags.

9. Block

  1. Def: A collection of handles passed to/from the Damsel API as a unit.
  2. Specification: A block can be referenced as a sequence of individual handles, or as one or more ranges of contiguous handles, e.g. handles 1-6, 10-21.
  3. State: Blocks of handles have no guaranteed state that persists across different instantiations of Damsel. That is, they are not guaranteed to be stored with the data. Blocks are used only as a means of providing efficient (usually constant-time or constant-space) access to collections of entities/sets/tags/dimension/units referenced by the handles.

10. Structured mesh block

  1. Def: A collection of 0D, 2D or 3D entities, with type vertex, quadrilateral, or hexahedron, respectively, with specified I, J, and K parametric extents IMIN-IMAX, JMIN-JMAX, and KMIN-KMAX. A structured mesh block of vertex entities can have I/J/K parametric extents, while structured blocks of quadrilaterals and hexahedra can only have extents I/J and I/J/K, respectively.
  2. Column-major ordering: The vertices in a structured vertex block can be serialized into a 1D array of handles, and this ordering uses a colum-major ordering. That is, in this 1D array, the I indices vary fastest, J the next fastest, and K the slowest. Quadrilateral and hexahedron entities have a corresponding 1D ordering, again using column-major order.
  3. Handles: Individual entities in structured vertex, quadrilateral, and hexahedron blocks are allocated entity handles just like other entities; however, these handles may not be stored explicitly for every entity in a structured block. For example, a structured vertex block may be represented as IMIN, IMAX, JMIN, JMAX, KMIN, KMAX, HSTART, (coords), where HSTART is the starting handle, and the total number of vertices in the block is (IMAX-IMIN+1)(JMAX-JMIN+1)(KMAX-KMIN+1).
  4. Vertex coordinates: The vertex coordinates can be represented in one of three ways:
    1. cartesian-equal-spacing: Using (x0, y0, z0) and (dx, dy, dz), where dx, dy, and dz are the (equal) spacing in the x, y, and z directions, respectively.
    2. cartesian-unequal-spacing: Using x[], y[], and z[], where e.g. x[] is an array of length (IMAX-IMIN+1) and x[i] stores the coordinates of all vertices with parameter i, similarly for y and z.
    3. general-coordinates: Using coords(i,j,k), i.e. with a separate coordinate position for each vertex in the structured vertex block.
  5. Association between vertex and quadrilateral/hexahedron blocks: A structured block of vertices can be associated with a stuctured block of hexahedra or quadrilaterals. If this is the case, the minima in I/J/K of the structured vertex block must be equal to the minima of the quad or hex block, and the maxima equal to one greater than those of the quadrilateral or hexahedron block. A structured block of quadrilaterals or hexahedra must have an associated structured block of vertices.
  6. Connectivity implied: For quadrilateral and hexahedron structured mesh blocks, the connectivity of the individual quadrilateral and hexahedron entities is implied by the arrangement of vertices in the structured vertex block.


[iMesh] The iMesh Interface specification, http://itaps.org/software/iMesh_html/index.html.
[Tau09] T. J. Canonical numbering systems for finite-element Communications in Numerical Methods in Engineering, Mar. 2009.
[NIST] http://physics.nist.gov/cuu/Units/units.html

Northwestern University EECS Home | McCormick Home | Northwestern Home | Calendar: Plan-It Purple
© 2011 Robert R. McCormick School of Engineering and Applied Science, Northwestern University
"Tech": 2145 Sheridan Rd, Tech L359, Evanston IL 60208-3118  |  Phone: (847) 491-5410  |  Fax: (847) 491-4455
"Ford": 2133 Sheridan Rd, Ford Building, Rm 3-320, Evanston, IL 60208  |  Fax: (847) 491-5258
Email Director

Last Updated: $LastChangedDate: 2014-09-17 14:51:09 -0500 (Wed, 17 Sep 2014) $