Declare a subset relation

saf_declare_subset_relation is a function defined in rel.c.

Synopsis:

SAF_Rel * saf_declare_subset_relation(SAF_ParMode pmode, SAF_Db *db, SAF_Set *sup, SAF_Set *sub, SAF_Cat *sup_cat, SAF_Cat *sub_cat, SAF_BoundMode sbmode, SAF_BoundMode cbmode, SAF_RelRep *srtype, hid_t A_type, void *A_buf, hid_t B_type, void *B_buf, SAF_Rel *rel)

Formal Arguments:

  • pmode: The parallel mode.
  • db: The database in which to place the new relation.
  • sup: The superset. In SAF__ONE parallel mode, all processors except the one identified by the SAF__ONE argument should pass the null set of the database by using the SAF__NULL macro.
  • sub: The subset. In SAF__ONE parallel mode, all processors except the one identified by the SAF__ONE argument should pass the null set of the database by using the SAF__NULL macro.
  • sup_cat: The collection category on the sup set upon which the subset relation is being defined. Note that collections of this category must have already been defined on sup. Otherwise, an error is generated. Note, the four args, sup_cat, sub_cat, sbmode, cbmode, are typically passed using one of the macros described above, SAF__COMMON``(C), ``SAF__BOUNDARY``(``P,``B``), SAF__EMBEDBND``(``P,``B``) or SAF__GENERAL``(``BND)
  • sub_cat: The collection category on the sub set upon which the subset relation is being defined. Note that collections of this category must have already been defined on sub. Otherwise an error is generated.
  • sbmode: Indicates whether sub is the boundary of sup. Pass either SAF__BOUNDARY_TRUE or SAF__BOUNDARY_FALSE
  • cbmode: Indicates whether members of collection on sub are on the boundary of members of the collection on sup. Pass either SAF__BOUNDARY_TRUE or SAF__BOUNDARY_FALSE
  • srtype: Subset relation types. This argument describes how the data in ABUF represents the subset. Valid values are SAF__HSLAB meaning that ABUF points to a hyperslab specification and SAF__TUPLES meaning that ABUF points to a list of N-tuples.
  • A_type: The type of the data in A_buf
  • A_buf: This buffer contains references, one for each member of the domain collection (on sub), to members of the range collection (on sup). The client may pass NULL here meaning that the raw data will be bound to the object during write, rather than declaration.
  • B_type: The type of the data in B_buf
  • B_buf: This buffer is valid only when the members of the domain collection (on sub) are on the boundaries of the members of the range collection (on sup). In this case, the data contained in this buffer identifies “which piece” of the boundary each member of the domain collection is. Otherwise, the client should pass NULL here. As with ABUF, the client may pass also NULL here meaning the raw data will be bound to the object during write, rather than declaration.
  • rel: [OUT] Optional returned relation handle.

Description: This call is used to declare a subset relation between two sets. The relation is specified in terms of collections on both sets. The subset, sub, can be either a boundary of sup or not. Which case is indicated by the sbmode argument which can be either SAF__BOUNDARY_TRUE or SAF__BOUNDARY_FALSE.

In addition, The members of the collection on the sub set are either on the boundary of the members of the collection on the sup set or not (the only other acceptable case is one in which the members of the collection on the sub are equal to the members of the collection on sup). Which case is indicated by the value of the cbmode argument, can be either SAF__BOUNDARY_TRUE or SAF__BOUNDARY_FALSE.

Thus, there are two statements made about boundary information. One about the sets, sup and sub and one about the members of the collections on sup and sub. Furthermore, the statement about the sets, indicated by sbmode, is that sub is the boundary of sup or it is not. The statement about the collections, indicated by cbmode, is that the members of the sub collection are on the boundary of the members of the sup collection or not.

The values in ABUF enumerate the members of the collection on sub that are either on the boundaries of or equal to the members of the collection on sup. In the on the boundary of case (e.g. cbmode``==``SAF__BOUNDARY_TRUE) the values in BBUF, if non-NULL, indicate “which” piece of the sup collection member’s boundary each member of sub collection is. For example, if the sub collection is faces and the sup collection is a bunch of hexes, BBUF can be used to identify which of the 6 faces each member of sub collection is. This information is optional.

The group of four formal arguments sup_cat, sub_cat, sbmode, cbmode select from the various cases described above. For convenience, we provide a number of macros for these four arguments for the common cases…

:ref:`SAF_COMMON <SAF_COMMON>`(C) : a subset relationship in which the subset is specified by enumerating those members of the superset that are in the subset. This is the most common case. Argument C is the collection category both sets have in common.

SAF_BOUNDARY <SAF_BOUNDARY>`(``P`,``B``) : a subset relationship in which sub is the boundary of sup and the members of B on sub are on the boundaries of the members of P on sup.

SAF_EMBEDBND <SAF_EMBEDBND>`(``P`,``B``) : a subset relationship in which sub is some embedded boundary in sup and members of the collection B on sub are on the boundaries of the members of collection P on sup.

SAF_GENERAL <SAF_GENERAL>`(``BND`) : a subset relationship in which all that is known is that sub is indeed a subset of sup The details of the relationships are not known. In this case, the BND is a boolean indicating if sub is the boundary of sup.

Finally, there is the subset relation representation type, srtype…

By and large, the details of the relation data can be derived from knowledge of the indexing schemes used in the domain and range collections of the relation. For example, if the range is indexed using some N dimensional indexing scheme, then the relation will either be an N dimensional hyperslab or a list of N-tuples.

In the case of SAF__HSLAB, it is assumed the memory pointed to by ABUF contains 3 N-tuples of the form (starts, counts, strides) where starts, counts, and strides indicate the starting point of the hyperslab in N dimensions, the number of items in each dimension and the stride (through the range collection) in each dimension respectively. The order of dimensional axes in each of these arrays is assumed to match the terms in which the range collection’s indexing is specified.

In the case of SAF__TUPLES, it is assumed the memory pointed to by ABUF contains a list of N-tuples where each N tuple identifies one member of the range collection. The offsets argument to SAF__TUPLES, if present, indicates a fixed N-tuple offset to be associated with each N-tuple in ABUF.

There are two ways the client may pass the data buffer holding the relation data; either here as the ABUF argument of the declare call or later as the ABUF argument of the write call. The client cannot do both. It must choose. This flexibility was provided to aim the API for in-memory communications as well as persistent file writes. By and large, the client should pass NULL for the ABUF arg here and pass the buffer in the write call whenever it is writing persistent data to the file. However, whenever the client is planning to do in-memory communication, it should specify ABUF here.

Preconditions:

  • pmode must be valid. (low-cost)
  • sup must be a valid set handle. (low-cost)
  • sub must be a valid set handle. (low-cost)
  • sbmode must be either SAF__BOUNDARY_TRUE or SAF__BOUNDARY_FALSE. (low-cost)
  • cbmode must be either SAF__BOUNDARY_TRUE or SAF__BOUNDARY_FALSE. (low-cost)
  • cbmode must be SAF__BOUNDARY_TRUE if sbmode is SAF__BOUNDARY_TRUE for all participating processes. (low-cost)
  • Either A_buf is null and both sup_cat and sub_cat are not valid cat handles or. (low-cost)
  • B_buf can be non-NULL only when cbmode is SAF__BOUNDARY_TRUE. (low-cost)
  • On the reserved, “self” collection, cbmode and sbmode must be SAF__BOUNDARY_FALSE. (low-cost)
  • srtype must be a valid relation representation handle. (low-cost)
  • srtype must be either SAF__HSLAB or SAF__TUPLES. (low-cost)
  • rel must be non-NULL. (low-cost)
  • A_type must be an integer type if supplied. (low-cost)
  • B_type must be an integer type if supplied. (low-cost)

Return Value: On success returns either the supplied rel argument or a pointer to a newly allocated relation link. Returns the null pointer on failure.

Issues: We may want to have separate datatypes for ABUF and BBUF as BBUF’s values are likely to always fit in a byte though I don’t know any clients that actually store them that way.

At present, we assert that for any boundary case, the range collection (on sup) must be of a primitive type (e.g. not SAF__CELLTYPE_SET). However, this really need not be the case. Any set which has a boundary set can then have “pieces” of that boundary that could be referred to use the local address space of that boundary. It just so happens that the most common case for this is when we are referring to cell-types.

If we could guarantee all processors’ is_top member were identical, we could wrap this call so that we don’t try to put the set record if its already NOT a top set.

See Also: