Declare a field

saf_declare_field is a function defined in field.c.

Synopsis:

SAF_Field * saf_declare_field(SAF_ParMode pmode, SAF_Db *db, SAF_FieldTmpl *ftmpl, const char *name, SAF_Set *base_space, SAF_Unit *unit, SAF_Cat *homog_decomp, SAF_Cat *coeff_assoc, int assoc_ratio, SAF_Cat *eval_cat, SAF_Eval *eval_func, hid_t data_type, SAF_Field *comp_flds, SAF_Interleave comp_intlv, int *comp_order, void **bufs, SAF_Field *fld)

Formal Arguments:

  • pmode: The parallel mode.
  • db: The database where the new field will be created.
  • ftmpl: The field template handle for this field. Recall that the field template describes the abstract features of the field, including the quantity the field represents, and the algebraic type. The field being created in this saf_declare_field call is simply an instance of the abstract field characterized by the field template passed as this argument.
  • name: The name of this field. If a writer client declares different fields with the same name, a reader client that searches for fields by name will find multiple matches. However, it is ok to declare different fields with the same name.
  • base_space: The base_space of this field
  • unit: The specific units of measure. If in the field template, the quantity was not specified, then the only valid value that can be passed for units is SAF__NOT_APPLICABLE_UNIT. Otherwise, pass SAF__NOT_SET_UNIT if you do not want to specify units for the field or pass one of the valid units of measure.
  • homog_decomp: If the field is homogeneous, enter SAF__SELF here. Otherwise, the field is inhomogenous and this argument must indicate a decomposing collection of the field’s base-space upon which it is presumably homogeneous. We say presumably because it is not a requirement that the field be homogeneous on each of the members of the collection indentified here. The field pieces defined on any one or all of those members can, in turn, also be inhomogeneous. The only requirement is that the collection identified here be a decomposition of the associated set and that, ultimately, the recursion of defining inhomogeneous fields in terms of other inhomogeneous fields terminates on a bunch of homogeneous pieces. A common use of this argument is to indicate that the field is broken into independent chunks of storage (either within a single processor or distributed across other processors). In fact, prior to SAF-1.2.1, that was all this argument was used for and documented as supporting. Any collections contained in the base space set for which the IS_DECOMP argument in the saf_declare_collection call was SAF__DECOMP_TRUE, can be passed here. See the chapter introduction for fields for further information (see *Fields*).
  • coeff_assoc: This argument identifies the category of a collection in the base space set which the field’s coefficients are n:1 associated with. For example, for a field whose coefficients are 1:1 with a collection of a category representing the nodes, you would identify that collection category with this argument. Likewise, for a field whose coefficients are 4:1 with a collection of a category representing the elements in the problem, you would identify that collection with this argument. Note, if the coefficients are associated with the base space itself, and not the members of a collection in the base-space set, you would pass SAF__SELF for this argument.
  • assoc_ratio: This argument specifies the n in the n:1 association described above. For example, if for every member of the collection representing the elements, you have 1 coefficient, then this value would be 1. This value is always non-negative.
  • eval_cat: This argument specifies the collection whose members represent the pieces in the piecewise evaluation of the field. If there is only a single piece (e.g. the whole base space), then pass SAF__SELF. For example, a collection category identifying the nodes for the coeff_assoc argument and an assoc_ratio of 1 indicates only that we have 1 coefficient for each member of the collection of nodes. It does not indicate which collection in the base space (for example the elements), the field is actually piecewise evaluated on.
  • eval_func: This argument identifies one of several evaluation functions currently known to SAF. Again, SAF does not yet actually evaluate a field. It only stores the descriptive information to support its evaluation. See definition of SAF__EvalFunc enum for the possible values. Also, we have provided some convenience macros for this and coeff_assoc, assoc_ratio, and eval_cat arguments for common cases; node centered and zone centered fields. Pass SAF__NODAL for a node centered field, SAF__ZONAL for a zone centered field, SAF__DECOMP for a field that is piecewise constant over some decomposing collection (e.g. domains) or SAF__CONSTANT for a constant field.
  • data_type: The type of data in bufs if bufs are provided.
  • comp_flds: Array of component field handles. Pass null only if there are no components to this field (the field is a scalar field).
  • comp_intlv: The particular fashion in which components are interleaved. Currently there are really only two: SAF__INTERLEAVE_VECTOR and SAF__INTERLEAVE_COMPONENT. These represent the XYZXYZ…``XYZ`` and the XXX…``XYYY``…``YZZZ``…``Z`` cases. Note that interleave really only deals within a single blob of storage. In the case of a composite field whose coefficients are stored independently on the component fields, interleave really has no meaning (use SAF__INTERLEAVE_INDEPENDENT). Interleave only has meaning on fields with storage. In the case of a scalar field interleave is also meaningless, both cases degenerate to the same layout: XXX…``X`` (use SAF__INTERLEAVE_NONE).
  • comp_order: Only relevant for fields with component fields. This value indicates the order of the fields in the comp_flds relative to the registered order. Pass NULL if the permutation is the identity.
  • bufs: The field data buffers. Pass NULL if you would rather provide this on the write call. Note that the number and size of buffers (if any) is specified by the interleave and number of components. If the field has vector interleave then there may only be 1 buffer, if the field has component interleave then there must be num_components buffers. The number of components is defined in the field template specified by ftmpl.
  • fld: [OUT] The optional returned field handle. If NULL is passed here then this function allocates the field handle before returning it.

Description: This function is used to declare a field. A field is some physical quantity known to have value at every point in the infinite set of points that serves as the field’s base space. That is, a field is some continuous (as opposed to discrete) quantity that exists and has value everywhere over the base space the field is defined on - that is, at every point in the infinite set of points that is the field’s base space.

We apologize for the large number of arguments in this function call. We have developed prototype interfaces that reduce this complexity significantly but introduce other issues. As more experience is gained with this software and data model, we’ll have a better idea how to proceed.

In SAF, the description of a field is done in two parts; a field template (see saf_declare_field_tmpl) and an instance of a field. The field template object describes all the abstract information about a field. The field object itself describes the implementation details of an instance of a field. For example, the field template object describes the abstract quantity of measure the field represents, such as length (see *Quantities*) while the field object describes specific units of measure for that quantity such as meters (see *Units*).

You will notice that the base space upon which the field is defined is not part of the field object. Instead it is part of the field template object. This allows the field template object to classify fields according to which pieces of the base space they are defined on.

In the hierarchy of sets that serve as candidate base spaces for fields, the idea is to declare a field on the top-most set in the hierarchy which contains all points the field is defined on but contains no points the field is not defined on. Such a set is also called the maximal set of the field. It could also be thought of as the region of support of the field.

There is a big difference between declaring a field that is identically zero over portions of a set and declaring the field only over the subset(s) for which it is non-zero. The former indicates that the field is known everywhere on the set and is zero in some places. The latter indicates that the field is known on the subset(s) and undefined (e.g. does not exist) anywhere else.

At present, SAF really does not do much to interpret the data or descriptive information for a field. Currently, SAF simply allows a writer client to describe the salient features of a field and a reader client to discover them. As SAF evolves, SAF will be able to interpret more and more about the field itself.

Preconditions:

  • pmode must be valid. (low-cost)
  • base_space must be a valid set handle. (low-cost)
  • name must be non-null. (low-cost)
  • ftmpl must be a valid field template. (low-cost)
  • STORAGE_DECOMP must be either SELF_DECOMP or a valid cat handle. (low-cost)
  • coeff_assoc must be a valid cat handle. (low-cost)
  • eval_cat must be a valid cat handle. (low-cost)
  • unit must be a valid unit handle if supplied. (low-cost)
  • unit must agree with quantity defined on field template. (low-cost)
  • assoc_ratio must be non-negative. (low-cost)
  • eval_func must be a valid evaluation type handle if supplied. (low-cost)
  • Units of component fields must match units of composite field. (low-cost)

Return Value: Returns a handle to the set on success (either the one passed in by the fld argument or one allocated herein); returns NULL on failure.

See Also: