iRel Requirements

iRel Interface (v1_0)
EntArr Proposal (v1 1)
"None" Type Proposal
iRel Use Cases

iRel is ITAPS interface specification for managing the relationships among two or more of the core data types (see footnote1), resolving cross references between entities in different institutions, and provide additional functionality that depends on multiple core data types.


The ITAPS project is developing technology to improve interoperability in mesh-based scientific computing. Three primary activities are: designing common interfaces for mesh, geometry, and other data; developing and porting services involving those data to those interfaces; and building applications or higher-level services based on those services and interfaces. Current interfaces include iMesh (interface to discretized definition of spatial domain), iGeom (continuous definition of spatial domain), iField (mathematical field and operators, on continuous or discretized domain). Interfaces have been developed or imagined for other kinds of data, including: material models, ???

Interface design philosophy

There are several characteristics interfaces should have, regardless of how the interface is designed:

  • Scope: The types of data and functionality to be included in an interface. An interface should include data and functionality that are intrinsically related and would be difficult or awkward to separate in different interfaces, but no more. A more practical definition is that an interface include data and functions that most applications dealing with those types of data are likely to need. Separation of a collection of data and functions into multiple interfaces is appropriate when there are many applications which need one interface without needing other interfaces.
  • Level of abstraction: The level of abstraction used to expose data and functionality to applications strongly affects both the usability and versatility of an interface. The level of abstraction falls on a spectrum between concrete and abstract. If an interface is too concrete, it is large and unwieldy, and can have limited versatility for new applications. Too abstract, and the interface is difficult to use by practitioners only casually familiar with the data and functionality exposed by the interface.

The actual definition of an interface consists of two parts: a data model, which is the language and types used to define data exposed by an interface; and an API, which defines the data types and functions used in the specification of the interface. The design of a data model is guided by the level of abstraction desired in an interface.

ITAPS interface design

The separation of ITAPS interfaces into iMesh, iGeom, and iField follows from the definition of scope above. Speculation of other interfaces which may arise in the context of scientific computing, e.g. a materials interface, also follow from that principle. The data model exposed by iMesh and iGeom includes four fundamental types: entity, set, tag, and interface or root set.

Although it is desirable to have separate interfaces for various types of data, there is often a need to relate data in one interface to data in another. For example, mesh generation applications generate mesh, stored in iMesh, that discretizes geometric entities in iGeom. For this purpose, ITAPS also defines a relations interface, iRel, to accomplish this task.


Defining requirements for a relations interface is straightforward, based on experience in mesh generation and mesh-based applications. Requirements are in two areas: representation, describing the type of relation that needs to be represented; and function, the functionality needed by various applications. These are indicated with (R) or (F) in the requirements below. While many of the requirements below are phrased in interface-specific terms (mesh, geometry, etc.), all of them have more abstract definitions and applications with other interface types.

  • Geometry entity to mesh entities (R): From the perspective of mesh generation and related fields, it is necessary to store the relation of a geometric entity (e.g. model face) with the mesh entities which discretize or are positioned on that model entity (e.g. mesh faces, along with nonboundary edges and vertices). Most commonly, these relations need to be symmetric; that is, they can be queried starting from either side of the relation.
  • Geometry entity to collection of mesh entities (R): There are several cases where it is desirable to relate geometry entities to collections of mesh entities, i.e. to a collection of mesh entities represented as an object in the mesh state. The accepted mechanism for doing this is to use entity sets. First, it may be more efficient to handle sets of mesh than individual entities. This may be due to the implementation of iMesh, for example when storing a relation in this way is more memory efficient; or it may be due to the application, for example mesh generation on non-manifold models or manifold models with boundaries, where the container for the collection may exist before the actual mesh entities do. Second, relating a geometry entity to a mesh set may be desirable for the actual mesh generation process, where a mesh set is created for each geometry entity first, then the mesh generation application is coordinated using mesh sets. Relations of this type (geometry entity to mesh set) are also usually symmetric.
  • Mesh entity to geometry entity (R): In some cases it is more compute-efficient to access mesh to geometry relations individually, without first going through a mesh set. Two straightforward examples are adaptive mesh refinement and mesh smoothing, where mesh vertices must be projected to the owning geometry entity. These relations are usually not symmetric; that is, a geometry entity is usually not related to a single mesh entity.
  • Field data to tag on mesh (R): The iField interface is being designed to handle both generalized tensor fields and operators on those fields. The scope of this interface, as currently targeted, includes both discrete and continuous fields, with discrete fields including both those defined on a mesh as well as those from external sources, e.g. measured experimental data. In the case of mesh-based discrete fields, where the actual field data may be stored in iMesh (see footnote2), there will need to be a relation to the field meta-data, which describes the semantics of the field. iRel could be used to store that relation. Because iField is in an early stage of development, it is difficult to speculate how best to represent that meta-data in the data model. These types of relations could be symmetric or asymmetric, depending on whether multiple entities on one side of the relation would be related to single entities on the other side.
  • Material mixture to geometry entity or set (R): Consistent with the principle of scope, it is logical to separate the definition of material properties from that of the spatial domain. However, at the application level, the two are often specified at the same time. For example, CAD systems often have the ability to specify material properties as the geometric model is developed. A material interface is likely to have application-defined materials, for example to define material or isotopic mixtures. If the geometry and material interfaces are independent, then the relations interface must be able to relate things between those interfaces. Both entities and sets are needed on the geometry side, since material identifiers on CAD models are often specified on collections of these entities.
  • Assignment (F): Since iMesh and iGeom are usable independent of the other, the data in each is not automatically related to the data in the other. Relations must be assigned before they can be used by applications. Assignment of relations happens at a lower level; that is, individual entities or sets in one interface are related to those in another interface. The most obvious use of this functionality is in mesh generation, where mesh-geometry relations are assigned as the mesh is constructed. A relation should be available for query at any time after it has been assigned.
  • Infer (F): Because the interfaces related by iRel are independent, the data in each is often saved and restored independently. Applications using relations may be run separate from the application creating the relations in the first place, after a save and restore of the data in each interface. These querying applications may not know how to re-assign relations either; in this case, relations must be inferred. Specific approaches to inferring relations between interfaces are discussed later in this document; here, we assume only that iRel provides the functionality to bootstrap relations data based on data in the interfaces being related. For example, in a physics application using an adaptive mesh refinement service, that service tells iRel to restore relations between mesh and geometry, on individual entities or for the entire model, before starting the refinement process.
  • Save/restore (F): There are many times where the application creating the relations is different from the application which later uses those relations. For example, mesh is created in a mesh generation application, and adaptively refined in a physics application. It may be desirable tospecify that relations be saved and restored explicitly, rather than being inferred by later applications.
  • Change type (F): The actual representation of a relation between an entity in one interface and a collection of entities in another interface has characteristic memory and cpu time costs. In many cases, application requirements may vary, even during the same run. For example, an application may want the AMR service to minimize memory usage when it is not actively refining mesh while also allowing that service to use more memory during refinement. Another example of this is mesh generation on non-manifold models, where the mesh entity to geometry entity relation evaluation is needed only for the geometric region and boundary being meshed at a given time. To accommodate the varying needs of applications, the relations interface must allow the application to request different forms of representations and changes to those representations during a given run.

Relationship of iRel to other ITAPS Interfaces and Requirements Implications (aka Carl's email of Feb 2, 2011)

It certainly is true that there's a relationship between iField and iMesh/iGeom, at two levels.
  1. At the high level, a tensor field (in iField) is defined over some collection of iMesh or iGeom entities.
  2. At the low level, DOFs for a tensor field are associated with particular mesh entities.
    Those statements are, I think, both true in the general sense as well as in the data model that we've defined.

What's less clear is how these relationships should be expressed through an API, and that may be especially true if we want to have both of those kinds of relationships.

What iField currently does is this: the relationship between tensor field and a collection of entities is managed by the Domain data object, which may (especially for mesh domains specified in terms of geometric entities) choose to use iRel under the hood. This relationship is one way, from iField to iMesh, with no connection back from the iMesh side. That may or may not be sufficient, but that's what we've currently got.)

The relationship between dofs and entities is also currently an under-the-hood thing, in part because we at least can't identify an alternative that we find particularly attractive.

Speaking first specifically to iRel, setting up an efficient entity-to-dof map using iRel would require two things. First, the dofs associated with an entity would (in the current iRel API) have to be wrapped in something that was of type iBase_EntityHandle; while such a definition is possible, it distorts the notion of entity handle beyond common recognition. Second, we'd need to add an explicit performance requirement on iRel that these one-to-one relationships be retrievable in O(1) time. Given those two things, it's possible to avoid memory overhead on the iField side if you're willing to forego retrieving the entity that a set of dofs is associated with. In this case, your handle on the dof side in iRel is just a pointer / index to data.

We can also easily imagine scenarios in which an iField implementation would choose to maintain its own internal entity-to-dof map (again with O(1) access time).

If we wanted to have in addition a tensor field level connection through iRel, the only mechanism we see (with the current iRel spec) is to pretend that a tensor field is an entity set, which it most certainly is not, semantically. (Or have two different things in iField that are both entities, which is worse.)

Yes, if we had the notion of inheritance, we could say that a tensor field or dof cluster is Relatable and Taggable, just as an entity or set is. Not sure how to do that in a C interface...

And the 800 pound gorilla in the room is mesh modification.

Let's say that we define a domain in iField as all the entities that are related to a geometric region. When we adapt the mesh, we have to add dofs for the new mesh entities (and the adaptation scheme knows this, and also knows how to calculate the values for those dofs). So far, so good. But unless we're actually storing the dofs as tags on the entities (which is always possible, though not necessarily simply in cases where different entities have different numbers of dofs), iField as to (at best, from the programmer's point of view) identify that this is a new entity for which dof storage isn't currently associated to a particular location in memory and automagically make that happen.

All this would be a great argument for just using tags to store dof data except for a couple of not-so-minor efficiency things:
  1. Without the notion of dense tags, there's almost certain to be both memory and CPU overhead for using tags here. At least, we can't think of an implementation that avoids those overheads. And with dense tags, you buy the problem of resizing that data (presumably stored as an array) when you adapt the mesh.
  2. Solver apps are going to want to have access to the raw field dof data in an array. (In fact, it's possible to attach a field to external array data in the current iField API, just as you can attach one to tag data.)

So tag data certainly isn't the whole answer. At this point, the best solution may be to switch from some array-based storage scheme to an entity-by-entity storage scheme (whether internal to the iField impl or external array/tags) for mesh modification and then back again for the solver.

Whether iRel is used for entity-to-dof mapping, or some internal iField thing is used, that map still has to be updated regularly, which suggests that we may also want to require O(1) update of entity-to-entity relation data in iRel (in addition to O(1) access).

To conclude, here are a couple of thoughts about things that iRel needs to be able to do to make using it for the iField relationships palatable.

  1. One-way relationships. We want to be able to forego the memory overhead associated with maintaining a mapping from dofs back to their entity (at least until someone can show me a compelling use case).
  2. Relate iBase_Relatable (or equivalent), not entities and sets. Otherwise, we get an explosion of functions to relate mesh entities to dofs, or geom entities to fields, or mesh sets to fields, with each of those functions serving a single specific purpose. Yes, this implies that apps have to know what kind of iBase_Relatable they just got back so they can cast it properly, but they had to know that already. Yes, implementations have to cast internally, too. But isn't the smaller, easier to understand interface prefered? And yes, one-to-many relationships are still needed, and no, we're not entirely sure how both relations would work here.
  3. Impose performance restrictions, which would amount to O(1) time for both update and retrieval. This is a big restriction on possible ways to implement iRel, but it's probably necessary for good solver and adaptation performance.

Discussion Notes

1 Note 1:
MCM: In the design of the iField interface, we have a need to maintain a relationship between degrees of freedom (DOFs) of the fields defined on a mesh and the entities comprising the mesh itself. For this reason, I know some are considering an implementation of iField that employs iRel to handle the DOF<->entity relations. At the same time, the iField interface specification, as currently posed, does not require the use of iRel to maintain the DOF<->entity relation. Is this a contradiction to the above statement regarding the intent of iRel?

Tim: I don't believe so. Interactions between interfaces can be pretty nuanced sometimes, dependent on the implementation (see my note below for a CGM-MOAB example). iRel is intended to make it possible to maintain independence between other interfaces, but at the same time that is not required. RPI chooses to bind iGeom and iMesh together, at least sometimes, and so do I.

2 Note 2:
: As currently designed, iField allows different modes of storage of DOFs. One such mode of storage is as an iMesh tag. However, storing DOFs as tags is not the only means of storage of DOFs in iField. It is simply one of a few options. iField is required to support the situation when users so choose to store DOFs as iMesh tags. However, users of iField are NOT required to store DOFs in this way in all cases. Furthermore, the mapping of DOFs to mesh entities, which is known either implicitly due to the DOFs storage as iMesh tags (and the tags subsequent relationship to iMesh entities) or explicitly due to iField maintaining the mapping itself is not necessarily an object in an of itself that iField exposes or supports. In other words, iField knows about the relationship between DOFs and tags but is not designed to expose that above its API as an iRel-like object that can be manipulated independently. Its concieveable we could add methods to iField to gather up and return that mapping as an iRel object. But, in some sense I think it would have to be a read-only object and not one where changes to the iRel object can/should result to changes in how iField is storing/mapping its DOFs.

Mark Beall: Doesn't that kind of mean that this paragraph doesn't really belong here as one of the requirements for iRel? Would seem to be kind of important to resolve one way or the other.

Tim: I had the same reaction. However, this is one of those complicated situations where either might be appropriate at different times. This'll probably make others wince, but I see similar things in building MOAB on top of CGM. That is, you can enable MOAB to pick up a geometric model, and represent it as facets plus parent/child-related entity sets. To MOAB, it just looks like another reader. So in this situation, MOAB is linked to CGM through one of its readers, but may also eventually be related through iRel, e.g. as we generate meshes for the model. Though, I haven't convinced myself that that's the right way to view it. These issues also come up when doing the reverse, i.e. building an iGeom interface on top of MOAB data (exposing groups of facets as model faces for remeshing).