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 isSAF__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 nullquantity
: 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 fromatype
, SAF currently does no work to infer it. PassSAF__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 ofNUM_COMPS
field template handles that comprise the composite field template orNULL
if there are no component field templates. PassNULL
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
) isSAF__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
ifnum_comp
> 1. (low-cost)atype
must be a valid algebraic type handle. (low-cost)ctmpl
may beNULL
only ifnum_comp
== 1 andatype
must be direct. (low-cost)ctmpl
must beNULL
if components are not appropriate. (low-cost)basis
must be a valid basis handle orNULL
. (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:
- saf_declare_quantity: 20.9: Declare a new quantity
- Field Templates: Introduction for current chapter