6.2.6. The function definition element

Prev		Next

The function element connects breakpoint sets (for gridded tables), independent variables, and data tables (gridded or ungridded) to their respective output variable.

    function : name
        description? :
            {text description of the function}
        EITHER
            provenanceRef? : provID
        OR
            provenance? : [provID]
                author+ : name, org, [email]
                    contactInfo* : [contactInfoType, contactLocation]
                        {text describing contact information}
                creationDate : date {in YYYY-MM-DD format}
                documentRef* : [docID,] refID
                modificationRef* : modID
                description?
        EITHER 
        (
          independentVarPts+ : varID, [name, units, sign, extrapolate, interpolate]
              {input values as character data}
          dependentVarPts : varID, [name, units, sign]
              {output values as character data}
        ) 
        OR 
        (
          independentVarRef+ : varID, [min, max, extrapolate, interpolate]
          dependentVarRef : varID
          functionDefn : [name]
              CHOICE OF
              (
                  griddedTableRef : gtID
              OR
                  griddedTableDef : [name, gtID, units]
                    description?
                        {text description of table}
                    (provenance | provenanceRef)?   {as described earlier}
                    breakpointRefs
                        bpRef+ : bpID
                    uncertainty? : effect
                        (normalPDF : numSigmas) | (uniformPDF : bounds+)
                    dataTable
                        {gridded data table as character data}
              OR
                  ungriddedTableRef : utID
              OR
                  ungriddedTableDef : [name, utID, units]
                    description?
                        {text description of table}
                    (provenance | provenanceRef)?   {as described earlier}
                    uncertainty? : effect
                        (normalPDF : numSigmas) | (uniformPDF : bounds+)
                    dataPoint+
                        {coordinate/value sets as character data}
              )
        )

function attributes:

name: A UNICODE name for the function.

function sub-elements:

description

The optional description element allows the author to describe the data contained within this function.

provenance

The optional provenance element allows the author to describe the source and history of the data within this function. Alternatively, a provenanceRef reference can be made to a previously defined provenance.

independentVarPts

If the author chooses, she can express a linearly interpolated functions by specifying the independent (breakpoint) value sets as one or more independentVarPts which are comma- or white space-separated, monotonically increasing floating-point coordinate values corresponding to the dependentVarPts. In the case of multiple dimensions, more than one independentVarPts must be specified, one for each dimension. The mandatory varID attribute is used to connect each independentVarPts set with an input variable.

An optional interpolate attribute specifies the preference for using linear, quadratic, or cubic relaxed splines for calculating dependent values when the independent arguments are in between specified values. When not specified, the expectation would be to use a linear spline interpolation between points. The performance of interpolation of various orders is left up to the processing application. See Section 6.3.

dependentVarPts

This element goes along with the previous element to specify a function table. Only one dependentVarPts may be specified. If the function is multi-dimensional, the convention is the last breakpoint dimension changes most rapidly in this comma- or white space-separated list of floating-point output values. The mandatory varID attribute is used to connect this table's output to an output variable.

independentVarRef

One or more of these elements refers to separately defined variableDefs. The order of specification is important and must match the order in which breakpoint sets are specified or the order of coordinates in ungridded table coordinate/value sets.

An optional interpolate attribute specifies the preference for using discrete, linear, quadratic, or cubic splines for calculating dependent values when the independent arguments are in between specified values. When not specified, the default expectation would be a linear spline interpolation between points. The performance of interpolation of various orders is left up to the implementer. See Section 6.3.

dependentVarRef

A single dependentVarRef must be specified to connect the output of this function to a particular variableDef.

functionDefn

This element identifies either a separately specified data table definition or specifies a private table, either gridded or ungridded.

griddedTableRef

If not defining a simple function table, the author may use this element to point to a separately specified griddedTableDef element.

ungriddedTableRef

If not using a simple function table, the author may use this element to point to separately specified ungriddedTableDef element.

Example 11. An excerpt giving the example of a function which refers to a previously defined griddedTableDef

This example ties the input variables DBFLL and XMACH into output variable CLBFLLO through a function called CLBFLO_fn, which is represented by the linear interpolation of the gridded table previously defined by the CLBFL0_table griddedTableDef (see the griddedTableDef example above).

      <!-- ============================== -->
      <!-- Lower left body flap functions -->
      <!-- ============================== -->

  <function name="CLBFLL0">
    <description>
      Lower left body flap lookup function for lift, polynomial constant term.
    </description>
    <independentVarRef varID="DBFLL"  min="0.0" max="60." extrapolate="neither"/> 
    <independentVarRef varID="XMACH" min="0.3" max="4.0" extrapolate="neither"/>
    <dependentVarRef varID="CLBFLL0"/> 
    <functionDefn name="CLBFL0_fn">
      <griddedTableRef gtID="CLBFL0_table"/> 
    </functionDefn>
  </function>

	The independent variables must be given in the order of least-rapidly changing to most-rapidly changing values in the previously defined function table. The processing application needs to pay attention to the `extrapolate` attribute, which specifies how to treat a variable whose value exceeds the stated limits on input. See Section 6.3.
	The dependent variable (identified as `CLBFLL0`) is the output variable for this function. `CLBFLL0` must have been declared previously with a `variableDef` element.
	This is a reference to the previously declared `griddedTableDef`.

Example 12. A function with an internal table

In this example , the function CLRUD0 returns, in the variable CLRUD0, the value of function CLRUD0_fn represented by gridded CLRUD0_table. The inputs to the function are abs_rud and XMACH which are used to normalize breakpoint sets DRUD_PTS and XMACH1_PTS respectively. The input variables are limited between 0.0 to 30.0 and 0.3 to 4.0, respectively.

      <!-- ================ -->
      <!-- Rudder functions -->
      <!-- ================ -->

<!-- The rudder functions are only used once, so their table
     definitions are internal to the function definition.
--> 

  <function name="CLRUD0_fn"> 
    <description>
        Rudder contribution to lift coefficient,
        polynomial multiplier for constant term.
    </description>
    <provenance> 
      <author name="Bruce Jackson" org="NASA Langley Research Center" email="[email protected]"/>
      <creationDate date="2003-01-31"/>
      <documentRef docID="REF01"/>
    </provenance>
    <independentVarRef varID="abs_rud"  min="0.0" max="30." extrapolate="neither"/>
    <independentVarRef varID="XMACH" min="0.3" max="4.0" extrapolate="neither"/>
    <dependentVarRef varID="CLRUD0"/> 

    <functionDefn name="CLRUD0_fn_defn">
      <griddedTableDef name="CLRUD0_table"> 
        <breakpointRefs>
          <bpRef bpID="DRUD_PTS"/>
          <bpRef bpID="XMACH1_PTS"/>
        </breakpointRefs>
        <dataTable> <!-- last breakpoint changes most rapidly -->
<!-- CLRUD0  POINTS  -->
<!-- RUD =    0.0    -->
 0.00000E+00 , 0.00000E+00 , 0.00000E+00 , 0.00000E+00 , 0.00000E+00 ,
 0.00000E+00 , 0.00000E+00 , 0.00000E+00 , 0.00000E+00 , 0.00000E+00 ,
 0.00000E+00 , 0.00000E+00 , 0.00000E+00 ,
<!-- RUD =   15.0    -->
-0.13646E-01 , 0.26486E-01 , 0.16977E-01 ,-0.16891E-01 , 0.10682E-01 ,
 0.75071E-02 , 0.53891E-02 ,-0.30802E-02 ,-0.59013E-02 ,-0.95733E-02 ,
 0.00000E+00 , 0.00000E+00 , 0.00000E+00 ,
<!-- RUD =   30.0    -->
-0.12709E-02 , 0.52971E-01 , 0.33953E-01 ,-0.33782E-01 , 0.21364E-01 ,
 0.15014E-01 , 0.10778E-01 ,-0.61604E-02 ,-0.11803E-01 ,-0.19147E-01 ,
 0.00000E+00 , 0.00000E+00 , 0.00000E+00 
        </dataTable>
      </griddedTable>
    </functionDefn>
  </function>

	This comment helps humans understand the reason for an embedded table.
	The `name` attribute is used for documentation purposes, not for internal variable linkage.
	The `provenance` element is required by the AIAA standard [AIAA11].
	The `varID` attribute is used to link the output of this function with a previously defined variable as given in Example 3.
	This example has an embedded gridded table.

Example 13. A simple 1D function

At the other end of the spectrum, a simple 1D nonlinear function can be defined with no reuse, as shown below; however, multiple-dimension functions are supported by adding additional independentVarPts definitions.

<function name="CL">
  <independentVarPts varID="alpdeg"> 
   -4.0, 0., 4.0, 8.0, 12.0, 16.0
  </independentVarPts>
  <dependentVarPts varID="cl"> 
    0.0, 0.2, 0.4, 0.8, 1.0, 1.2
  </dependentVarPts>
</function>

	Breakpoints in angle-of-attack are listed here.
	Values of `cl` are given, corresponding to the angle-of-attack breakpoints given previously.