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 thissaf_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
: Thebase_space
of this fieldunit
: 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 isSAF__NOT_APPLICABLE_UNIT
. Otherwise, passSAF__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, enterSAF__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 theIS_DECOMP
argument in the saf_declare_collection call wasSAF__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 aren:1
associated with. For example, for a field whose coefficients are1: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 are4: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 passSAF__SELF
for this argument.assoc_ratio
: This argument specifies the n in then: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 passSAF__SELF
. For example, a collection category identifying the nodes for thecoeff_assoc
argument and anassoc_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 ofSAF__EvalFunc
enum for the possible values. Also, we have provided some convenience macros for this andcoeff_assoc
,assoc_ratio
, andeval_cat
arguments for common cases; node centered and zone centered fields. PassSAF__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) orSAF__CONSTANT
for a constant field.data_type
: The type of data inbufs
ifbufs
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
andSAF__INTERLEAVE_COMPONENT
. These represent theXYZXYZ
…``XYZ`` and theXXX
…``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 (useSAF__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`` (useSAF__INTERLEAVE_NONE
).comp_order
: Only relevant for fields with component fields. This value indicates the order of the fields in thecomp_flds
relative to the registered order. PassNULL
if the permutation is the identity.bufs
: The field data buffers. PassNULL
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 benum_components
buffers. The number of components is defined in the field template specified byftmpl
.fld
: [OUT
] The optional returned field handle. IfNULL
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 eitherSELF_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:
- saf_declare_collection: 11.1: Declare a collection
- saf_declare_field_tmpl: 15.2: Declare a field template
- Fields: Introduction for current chapter