Declare a topological relation

saf_declare_topo_relation is a function defined in rel.c.

Synopsis:

SAF_Rel * saf_declare_topo_relation(SAF_ParMode pmode, SAF_Db *db, SAF_Set *set, SAF_Cat *pieces, SAF_Set *range_set, SAF_Cat *range_cat, SAF_Cat *storage_decomp, SAF_Set *my_piece, SAF_RelRep *trtype, 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 dataset where the new relation will be created.
  • set: The containing set of the collection whose members are being sewn together by the relation.
  • pieces: The collection of members that are being sewn together.
  • range_cat: Together, range_set and range_cat identify the range of the relation (e.g., collection used to glue the pieces together). There are really only two valid values for RANGES_S: the set set or the set my_piece.
  • storage_decomp: The decomposition of set upon which the relation is stored.
  • my_piece: The piece of the decomposition being declared here.
  • trtype: The relation types. One of SAF__STRUCTURED, SAF__UNSTRUCTURED, or SAF__ARBITRARY.
  • A_type: The type of the data in A_buf.
  • A_buf: The buffer. Pass NULL if you would rather provide this in the write call.
  • B_type: The type of the data in B_buf.
  • B_buf: The buffer. Pass NULL if you would rather provide this in the write call.
  • rel: [OUT] Optional memory that will be initialized (and returned) to point to the new relation.

Description: A topology relation describes how the individual members of a collection are sewn together to form a mesh. A topology relation is composed of one or more steps. Each step in the relation represents a portion of the dimensional cascade in representing an N dimensional set in terms of a bunch of N-1 dimensional sets that form its boundary, which are, in turn, represented by a bunch of N-2 dimensional sets, etc. The last step is always on zero dimensional sets (e.g., SAF__CELLTYPE_POINT cells). Typically, there is only ever one step from a primitive decomposition to SAF__CELLTYPE_POINT cells (nodes). In this case, the topology relation is a list describing the nodal connectivity for each element in the decomposition.

In the case of SAF__STRUCTURED, all other arguments are currently ignored and rectangular structure is assumed. Later, different types of structure will be supported. In the case of SAF__UNSTRUCTURED, ABUF is a pointer to one value of type DATA_TYPE representing the number of range references for each member of the domain collection and BBUF is an array of type DATA_TYPE containing that number of range references for each member of the domain. In the case of SAF__ARBITRARY, ABUF is a pointer to an array of values of type DATA_TYPE equal to the size of the domain collection. Each value in the ABUF array represents the number of range references for the corresponding number of the domain collection. BBUF is a pointer to the range references.

By convention, a topology relation should be declared on the maximal set in the subset inclusion lattice (e.g., the top-most set in the subset inclusion lattice) for which it makes sense to define the topology. If the topology relation is, in fact, stored in non-contiguous chunks, then the client should use the storage_decomp argument of the topology relation to declare that the relation data is stored in pieces on the given decomposition.

Preconditions:

  • pmode must be valid. (low-cost)
  • set must be a valid set handle. (low-cost)
  • pieces must be a valid category. (low-cost)
  • range_set must be a valid set. (low-cost)
  • range_cat must be a valid category. (low-cost)
  • MY_PIECES must be a valid handle. (low-cost)
  • storage_decomp must be either the self decomposition or a valid cat handle. (low-cost)
  • trtype must be a consistent relation representation handle. (low-cost)
  • trtype must be a valid topology representation. (low-cost)
  • If supplied, A_type must be an integer type (or SAF__HANDLE if decomposed). (low-cost)
  • A_type must be supplied if A_buf is supplied. (low-cost)
  • B_type must be an integer type or handle type. (low-cost)
  • B_type must be supplied if B_buf if supplied. (low-cost)
  • A_type must be handle if storage decomposition is not self. (low-cost)

Return Value: On success, returns a pointer to the new relation: either the rel argument or an allocated relation. Returns the null pointer on failure.

See Also: