6.2.2. The variable definition element

The variableDef element is used to define each constant, parameter, or variable used within or generated by the defined subsystem model. It contains attributes including the variable name (used for documentation), an XML-unique varID identifier (used for automatic code generation), the units of measure of the variable, and optional axis system, sign convention, alias, and symbol declarations. Optional sub-elements include a written text description and a mathematical description, in MathML-2 content markup, of the calculations needed to derive the variable from other variables or function table outputs. An optional sub-element, isOutput, serves to indicate an intermediate calculation that should be brought out to the rest of the simulation. Another optional sub-element, isStdAIAA, indicates the variable name is defined in the AIAA simulation standards document. A final sub-element, uncertainty, captures the statistical properties of a (normally constant) parameter.

There must be a single variableDef for each and every input, output or intermediate constant or variable within the DAVEfunc model.

    variableDef+ : name, varID, units, [axisSystem, sign, alias, symbol, initialValue]
        description? :
            (description character data)
        provenanceRef? : provID  OR
        provenance? :
            author : name, org, [email]
                address? :
                    (address character data)
            creationDate :
                (date in YYYY-MM-DD format, character data)
            documentRef* : docID
            modificationRef* : modID
        calculation? :
            math (defined in MathML2.0 DTD) :
        isOutput? :
        isStdAIAA? :
        isState? :
        isStateDeriv? :
        uncertainty? : effect
            (normalPDF : numSigmas | uniformPDF )
	

variableDef attributes:

name

A UNICODE name for the variable (may be the same string as the varID).

varID

An XML-legal name that is unique within the file.

units

The units-of-measure for the signal, using the AIAA standard units convention.

axisSystem

An optional indicator of the axis system (body, inertial, etc.) in which the signal is measured. See Section 6.5, “Additional DAVE-ML conventions” below for recommended practice for nomenclature.

sign

An optional indicator of which direction is considered positive (+RWD, +UP, etc.). See the section on Section 6.5, “Additional DAVE-ML conventions” below for recommended practice for abbreviations.

symbol

A UNICODE Greek symbol for the signal [to be superseded with more formal MathML or TeX element in a later release].

initialValue

An optional initial value for the parameter. This is normally specified for constant parameters only.

variableDef sub-elements:

description

An optional text description of the variable.

provenance

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

calculation

An optional container for the MathML content markup that describes how this variable is calculated from other variables or function table outputs. This element contains a single math element which is defined in the MathML-2 markup language.

isOutput

This optional element, if present, signifies that this variable needs to be passed as an output. How this is accomplished is up to the implementer. Unless specified by this element, a variable is considered an output only if it is the result of a calculation or function AND is not used elsewhere in the DAVEfunc.

isStdAIAA

This optional element, if present, signifies that this variable is one of the standard AIAA simulation variable names that are defined in the (draft) AIAA Simulation Standard Variable Names [AIAA01]. Such identification should make it easier for the importing process to connect this variable (probably an input or output of the model) to the appropriate variable to/from the user's simulation framework.

isState

This optional element, if present, signifies that this variable serves as a state of the model.

isStateDeriv

This optional element, if present, signifies that this variable serves as a state derivative of the model.

uncertainty

This optional element, if present, describes the uncertainty of this parameter. See the section on Statistics below for more information about this element. Note that the uncertainty sub-element makes sense only for constant parameters (e.g., those with no calculation element but with an initialValue specified.

Example 2. Two excerpts with examples of variableDef elements defining input signals

In the excerpts below, two input variables are defined: XMACH and DBFLL. These two variables are inputs to a table lookup function shown in Example 11, “An excerpt giving the example of a function which refers to a previously defined griddedTableDef below.

<!--                     ==========================                     -->
<!-- ====================   VARIABLE DEFINITIONS   ==================== -->
<!--                     ==========================                     -->


      <!-- ================== -->
      <!--  Input variables   -->
      <!-- ================== -->

  <variableDef name="MachNumber"1 varID="XMACH"2 units="" symbol="M">
    <description>
        Mach number (dimensionless) 
    </description>
    <isStdAIAA/>3
  </variableDef>

  <variableDef name="dbfll" varID="DBFLL" units="d"4 sign="+TED"5 
                symbol="&#x3B4;bfll"6>
    <description>
        Lower left body flap deflection, deg, +TED (so deflections are
        always zero or positive).
    </description>
  </variableDef>
	  
1

The name attribute is intended for humans to read, perhaps as the signal name in a wiring diagram. Note that "MachNumber" is one of the standard AIAA simulation parameter name.

2

The varID attribute is intended for the processing application to read. This must be an XML-valid identifier and must be unique within this model.

3

The optional isStdAIAA sub-element indicates this signal is one of the predefined standard variables that most simulation facilities define in their equations of motion code. The name attribute should correspond to the standard AIAA parameter name from [AIAA01] or subsequent standards document

4

The optional units attribute describes the units of measure of the variable. See Section 6.5.6, “Units of measure abbreviation” below for a recommended list of units-of-measure abbreviations.

5

The optional sign attribute describes the sign convention that applies to this variable. In this case, the lower-left body-flap is positive with trailing-edge-down deflection. See Section 6.5.5, “Common sign convention notation” below for a recommended list of sign abbreviations.

6

The optional symbol attribute allows a UNICODE character string that might be used for this variable in a symbols listing.


Example 3. A simple local variable

This DAVE-ML excerpt defines CRBFLLO which is the "independent variable" output from the table lookup function shown in Example 11, “An excerpt giving the example of a function which refers to a previously defined griddedTableDef below.

      <!-- ================== -->
      <!--  Local variables   -->
      <!-- ================== -->

<!-- PRELIMINARY BUILDUP EQUATIONS -->

<!--  LOWER LEFT BODY FLAP CONTRIBUTIONS -->

<!--    table output signal   -->
  <variableDef name="Cldbfll_0" varID="CRBFLL0" units="">
    <description>
        Output of CRBFLL0 function; rolling moment contribution of
        lower left body flap deflection due to alpha^0 (constant
        term).
    </description>
  </variableDef>
	  

Example 4. A more complete excerpt using a calculation element

Here the local variable CLBFLL is defined as a calculated quantity, based on several other input or local variables (not shown). Note the description element is used to describe the equation, in FORTRAN-ish human-readable text. The calculation element describes this same equation in MathML-2 content markup syntax; this portion should be used by parsing applications to create either source code, documentation, or run-time calculation structures.

<!--    lower left body flap lift buildup -->
  <variableDef name="CLdbfll" varID="CLBFLL" units="">
    <description>
        Lift contribution of lower left body flap deflection
        CLdbfll = CLdbfll_0 + alpha*(CLdbfll_1 + alpha*(CLdbfll_2 
                            + alpha*CLdbfll_3)) 1
    </description>
    <calculation>  2
      <math xmlns="http://www.w3.org/1998/Math/MathML">
        <apply>  3
        <plus/>
          <ci>CLBFLL0</ci>
          <apply>
            <times/>
            <ci>ALP</ci>
            <apply>
              <plus/>
              <ci>CLBFLL1</ci>
              <apply>
                <times/>
                <ci>ALP</ci>
                <apply>
                  <plus/>
                  <ci>CLBFLL2</ci>
                  <apply> 4
                    <times/>
                    <ci>ALP</ci>
                    <ci>CLBFLL3</ci>
                  </apply> <!--            a*c3   -->  5
                </apply> <!--        (c2 + a*c3)  -->
              </apply> <!--        a*(c2 + a*c3)  -->
            </apply> <!--    (c1 + a*(c2 + a*c3)) -->
          </apply> <!--    a*(c1 + a*(c2 + a*c3)) -->
        </apply> <!-- c0 + a*(c1 + a*(c2 + a*c3)) -->
      </math>
    </calculation>
  </variableDef>
	  
1

This FORTRAN-ish equation, located in the description element, is provided in this example for the benefit of human readers; it should not parsed by the processing application.

2

A calculation element always embeds a MathML-2 math element; note the definition of the MathML-2 namespace.

3

Each apply tag pair surrounds a math operation (in this example, a plus) operator) and the arguments to that operation (in this case, a variable CLBFLL defined elsewhere is added to the results of the nested apply operation).

4

Inner-most apply multiplies variables ALP and CLBFLL3.

5

The comments here are useful for humans to understand how the equation is being built up; the processing application ignores all comments.


Example 5. An output variable based on another calculation element

This excerpt is an example of how an output variable (CL) might be defined from previously calculated local variables (in this case, CL0, CLBFL, etc.).


      <!-- ================== -->
      <!--  Output variables  -->
      <!-- ================== -->

  <variableDef name="CL" varID="CL" units="" sign="+UP" symbol="CL">
    <description>
        Coefficient of lift
        CL = CL0 + CLBFUL + CLBFUR + CLBFLL + CLBFLR + 
                   CLWFL + CLWFR + CLRUD + CLGE + CLLG
    </description>
    <calculation>
      <math>
        <apply> 1
          <plus/>
          <ci>CL0</ci>
          <ci>CLBFUL</ci>
          <ci>CLBFUR</ci>
          <ci>CLBFLL</ci>
          <ci>CLBFLR</ci>
          <ci>CLWFL</ci>
          <ci>CLWFR</ci>
          <ci>CLRUD</ci>
          <ci>CLGE</ci>
          <ci>CLLG</ci>
        </apply>
      </math>
    </calculation>
    <isOutput/> 2
  </variableDef>
	  
1

Here <apply> simply sums the value of these variables, referenced by their varIDs.

2

The isOutput element signifies to the processing application that this variable should be made visible to models external to this DAVEfunc.


Example 6. An intermediate variable with a calculation element that uses a DAVE-ML extension (atan2) to the standard MathML function set

In this excerpt, we demonstrate a means to encode a non-standard MathML-2 math function, atan2. The atan2 function is used often in C, C++, Java and other modeling languages and has been added to the DAVE-ML standard by use of the MathML csymbol element, specifically provided to allow extension of MathML for cases such as this.


      <!-- ================== -->
      <!--    ATAN2 example   --> 1
      <!-- ================== -->

  <variableDef name="Wind vector roll angle" varID="PHI" units="r">
    <description>
      This encodes the equation PHI = atan2( tan(BETA), sin(ALPHA) ) where atan2
      is the two-argument arc tangent function from the ANSI C standard math
      library; the first argument represents the sine component and the second
      argument is the cosine component.
    </description>
    <calculation>
      <math>
        <apply>
          <csymbol definitionURL="http://daveml.nasa.gov/function_spaces.html#atan2"
                   encoding="text">  2
            atan2
          </csymbol>
          <apply>
            <tan/>
            <ci>BETA</ci>   3
          </apply>
          <apply>
            <sin/>
            <ci>ALPHA</ci>  4
          </apply>
        </apply> 
      </math>
    </calculation>

  </variableDef>
	  
1

This excerpt shows how to calculate wind roll angle, phi, from angle of attack and angle of sideslip; it comes from the Apollo aero data book [NAA64].

2

The csymbol element is provided by MathML-2 as a means to extend the function set of MathML. Only a limited set of extensions given in this Standard are supported but others may be added to the standard in later versions. Note the specific URL that uniquely identifies this function; it is also the address of the documentation of the interpretation of the atan2 function.

3

BETA is the varID of a previously defined variable.

4

ALPHA is the varID of a previously defined variable.


$Revision: 348 $