The variable definition element
Prev Schematic overview of DAVEfunc Next

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)
        calculation? :
            math (defined in MathML2.0 DTD) :
        isOutput? :
        isStdAIAA? :
        uncertainty? : effect
            (normalPDF : numSigmas | uniformPDF : symmetry )

variableDef attributes:

name

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

varID

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

units

The units-of-measure for the signal.

axisSystem

An optional indicator of the axis system (body, inertial, etc.) in which the signal is measured. See Conventions below for best recommended practice for nomenclature.

sign

An optional indicator of which direction is considered positive (+RWD, +UP, etc.). See the section on Conventions below, for best 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.

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, identifies 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 this DAVEfunc model.

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 application to hook up this variable (probably an input or output of the model) to the appropriate importing facility's signal.

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 examples of variableDef elements defining input signals

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


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

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

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

The name attribute is intended for humans to read, perhaps as the signal name in an automated wiring diagram. Note that "MachNumber" is a standard 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 description element may be used in an automated data dictionary entry associated with the name attribute.

4

The optional units attribute describes the units of measure of the variable. See the section on Conventions 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 the section on Conventions 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.

7

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

In the example above, two input variables are defined: XMACH and DBFLL. These two variables are inputs to a table lookup function shown in example 10 below.


Example 3. A simple local variable

      <!-- ================== -->
      <!--  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>

This example defines CRBFLLO which is the "independent variable" output from the table lookup function shown in example 10 below.


Example 4. A more complete example using a calculation element

<!--    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>
        <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 FORTRANish equation is simply for human readers and is not parsed by the processing application.

2

A calculation element always embeds a MATHML-2 math element.

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 doesn't use these comments.

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 FORTRANish 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.


Example 5. An output variable based on another calculation element


      <!-- ================== -->
      <!--  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.

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


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


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

  <variableDef name="Wind vector roll angle" varID="PHI" units="rad">
    <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 example shows how to calculate wind roll angle, phi, from angle of attack and angle of sideslip; it comes from the Apollo aero databook [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 would be the varID of a previously defined variable.

4

ALPHA would be the varID of a previously defined variable.

In this example, 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.


Prev Up Next
The header element Home | ToC The breakpoint set definition element