Declare a field template

saf_declare_field_tmpl is a function defined in ftempl.c.

Synopsis:

SAF_FieldTmpl * saf_declare_field_tmpl(SAF_ParMode pmode, SAF_Db *db, const char *name, SAF_Algebraic *atype, SAF_Basis *basis, SAF_Quantity *quantity, int num_comp, SAF_FieldTmpl *ctmpl, SAF_FieldTmpl *ftmpl)

Formal Arguments:

  • pmode: The parallel mode.
  • db: The database handle in which to create the template.
  • name: The name of the field template.
  • atype: The algebraic type: SAF__ALGTYPE_SCALAR, SAF__ALGTYPE_VECTOR, SAF__ALGTYPE_TENSOR, SAF__ALGTYPE_SYMTENSOR, SAF__ALGTYPE_FIELD. If the algebraic type is SAF__ALGTYPE_FIELD, then all we know about the field is that it references other fields (i.e., an indirect field). Therefore, the next four arguments are not applicable. More generalized user defined type definitions will be available in later implementations.
  • basis: The basis. Not implemented yet. Pass null
  • quantity: The quantity. See saf_declare_quantity for quantity definitions and how to define new quantities.
  • num_comp: Number of components. Although this may often be inferred from atype, SAF currently does no work to infer it. Pass SAF__NOT_APPLICABLE_INT if this template will be used in the declaration of an inhomogeneous field. Otherwise, pass the number of components. For a simple scalar field, the number of components is 1. See Fields for further discussion of inhomogeneous fields.
  • ctmpl: This is an array of NUM_COMPS field template handles that comprise the composite field template or NULL if there are no component field templates. Pass NULL if this field template will be used in the declaration of an INhomogeneous field.
  • ftmpl: Returned field template handle for composite fields. If the algebraic type (atype) is SAF__ALGTYPE_FIELD, then the returned field template may be used as a state template (see *State Templates*).

Description: This function declares a field template. A field template defines the implementation independent features of a field such as its algebraic type, the quantity it represents, etc.

Preconditions:

  • pmode must be valid. (low-cost)
  • ftmpl must be non-null. (low-cost)
  • name must be non-null. (low-cost)
  • num_comp >= 1. (low-cost)
  • ctmpl must be non-NULL if num_comp > 1. (low-cost)
  • atype must be a valid algebraic type handle. (low-cost)
  • ctmpl may be NULL only if num_comp == 1 and atype must be direct. (low-cost)
  • ctmpl must be NULL if components are not appropriate. (low-cost)
  • basis must be a valid basis handle or NULL. (low-cost)
  • quantity must be a valid quantity handle if supplied. (low-cost)

Return Value: A pointer to the new field template handle is returned on success, either the ftmpl argument if non-null or a freshly allocated handle. A null pointer is returned on failure.

Issues: It would be better if we could create new field types (templates) from old ones, or alternatively, construct new algebriac types from old ones. This is most apparent when the alg-type is SAF__FIELD. This is the C-language equivalent of a void . It tells us only that it is a reference to a field (in fact, the lib doesn’t care if you pass ``SAF__Rel`` objects here) but does not say what kind of fields (e.g. field templates) it should reference. One might be inclined to think that the component fields templates can serve to define the type of references of a ``SAF__FIELD`` entity. However, this is not so. The component field templates define the *component fields. We can illustrate by an example.

Suppose we have a time series of the coordinate field of an airplane. Each instant in time of the coordinate field is a field on SPACE. To create the coordinates as a function of time, we create a field on TIME whose alg-type is SAF__FIELD. What are its component fields? If we want somehow to use the component fields to define the kinds of field this SAF__FIELD entity refers to, we’d specify the field template for coordinate fields on SPACE as the component field template here. However, if we do that, how do we then specify the components of coordinates as a function of time, namely x(t), y(t), and z(t) whose field template is on TIME. We can’t! In essence, we need to be able to say what kind of SAF__FIELD this entity is by passing a list of field templates as the algebraic type. Or, more specifically, we need to generalize the notion of algebraic type and allow the client to build new types from old ones. That will be deferred to a later release. For now, the best we can do with this is equivalent to a void* field reference.

We could extend the API and allow a list of field templates for the atype argument. Alternatively, would could allow the member field types to come in via the component fields of the component fields of a SAF__FIELD template. However, that is rather convoluted.

See Also: