src/FDM/JSBSim/math/FGFunction.h

   1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2
   3 Header: FGFunction.h
   4 Author: Jon Berndt
   5 Date started: August 25 2004
   6
   7  ------------- Copyright (C) 2001  Jon S. Berndt (jon@jsbsim.org) -------------
   8
   9  This program is free software; you can redistribute it and/or modify it under
  10  the terms of the GNU Lesser General Public License as published by the Free Software
  11  Foundation; either version 2 of the License, or (at your option) any later
  12  version.
  13
  14  This program is distributed in the hope that it will be useful, but WITHOUT
  15  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  16  FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
  17  details.
  18
  19  You should have received a copy of the GNU Lesser General Public License along with
  20  this program; if not, write to the Free Software Foundation, Inc., 59 Temple
  21  Place - Suite 330, Boston, MA  02111-1307, USA.
  22
  23  Further information about the GNU Lesser General Public License can also be found on
  24  the world wide web at http://www.gnu.org.
  25
  26 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  27 SENTRY
  28 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  29
  30 #ifndef FGFUNCTION_H
  31 #define FGFUNCTION_H
  32
  33 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  34 INCLUDES
  35 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  36
  37 #include <vector>
  38 #include <string>
  39 #include "FGParameter.h"
  40 #include <input_output/FGXMLElement.h>
  41 #include <input_output/FGPropertyManager.h>
  42
  43 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  44 DEFINITIONS
  45 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  46
  47 #define ID_FUNCTION "$Id$"
  48
  49 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  50 FORWARD DECLARATIONS
  51 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  52
  53 namespace JSBSim {
  54
  55 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  56 CLASS DOCUMENTATION
  57 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  58
  59 /** Represents a mathematical function.
  60 The FGFunction class is a powerful and versatile resource that allows
  61 algebraic functions to be defined in a JSBSim configuration file. It is
  62 similar in concept to MathML (Mathematical Markup Language, www.w3.org/Math/),
  63 but simpler and more terse.
  64 A function definition consists of an operation, a value, a table, or a property
  65 (which evaluates to a value). The currently supported operations are:
  66 - sum (takes n args)
  67 - difference (takes n args)
  68 - product (takes n args)
  69 - quotient (takes 2 args)
  70 - pow (takes 2 args)
  71 - exp (takes 2 args)
  72 - abs (takes n args)
  73 - sin (takes 1 arg)
  74 - cos (takes 1 arg)
  75 - tan (takes 1 arg)
  76 - asin (takes 1 arg)
  77 - acos (takes 1 arg)
  78 - atan (takes 1 arg)
  79 - atan2 (takes 2 args)
  80 - min (takes n args)
  81 - max (takes n args)
  82 - avg (takes n args)
  83 - fraction
  84 - mod
  85 - random (Gaussian random number)
  86 - integer
  87
  88 An operation is defined in the configuration file as in the following example:
  89
  90 @code
  91   <sum>
  92     <value> 3.14159 </value>
  93     <property> velocities/qbar </property>
  94     <product>
  95       <value> 0.125 </value>
  96       <property> metrics/wingarea </property>
  97     </product>
  98   </sum>
  99 @endcode
 100
 101 A full function definition, such as is used in the aerodynamics section of a
 102 configuration file includes the function element, and other elements. It should
 103 be noted that there can be only one non-optional (non-documentation) element -
 104 that is, one operation element - in the top-level function definition.
 105 Multiple value and/or property elements cannot be immediate child
 106 members of the function element. Almost always, the first operation within the
 107 function element will be a product or sum. For example:
 108
 109 @code
 110 <function name="aero/coefficient/Clr">
 111     <description>Roll moment due to yaw rate</description>
 112     <product>
 113         <property>aero/qbar-area</property>
 114         <property>metrics/bw-ft</property>
 115         <property>aero/bi2vel</property>
 116         <property>velocities/r-aero-rad_sec</property>
 117         <table>
 118             <independentVar>aero/alpha-rad</independentVar>
 119             <tableData>
 120                  0.000  0.08
 121                  0.094  0.19
 122             </tableData>
 123         </table>
 124     </product>
 125 </function>
 126 @endcode
 127
 128 The "lowest level" in a function is always a value or a property, which cannot
 129 itself contain another element. As shown, operations can contain values,
 130 properties, tables, or other operations. In the first above example, the sum
 131 element contains all three. What is evaluated is written algebraically as:
 132
 133 @code 3.14159 + qbar + (0.125 * wingarea) @endcode
 134
 135 Some operations can take only a single argument. That argument, however, can be
 136 an operation (such as sum) which can contain other items. The point to keep in
 137 mind is that it evaluates to a single value - which is just what the trigonometric
 138 functions require (except atan2, which takes two arguments).
 139
 140 @author Jon Berndt
 141 */
 142
 143 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 144 DECLARATION: FGFunction
 145 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 146
 147 // Todo: Does this class need a copy constructor, like FGLGear?
 148
 149 class FGFunction : public FGParameter
 150 {
 151 public:
 152
 153 /** Constructor.
 154     When this constructor is called, the XML element pointed to in memory by the
 155     element argument is traversed. If other FGParameter-derived objects (values,
 156     functions, properties, or tables) are encountered, this instance of the
 157     FGFunction object will store a pointer to the found object and pass the relevant
 158     Element pointer to the constructor for the new object. In other words, each
 159     FGFunction object maintains a list of "child" FGParameter-derived objects which
 160     in turn may each contain its own list, and so on. At runtime, each object
 161     evaluates its child parameters, which each may have its own child parameters to
 162     evaluate.
 163     @param PropertyManager a pointer to the property manager instance.
 164     @param element a pointer to the Element object containing the function definition.
 165     @param prefix an optional prefix to prepend to the name given to the property
 166            that represents this function (if given).
 167 */
 168   FGFunction(FGPropertyManager* PropertyManager, Element* element, string prefix="");
 169   /// Destructor.
 170   virtual ~FGFunction();
 171
 172 /** Retrieves the value of the function object.
 173     @return the total value of the function. */
 174   double GetValue(void) const;
 175
 176 /** The value that the function evaluates to, as a string.
 177   @return the value of the function as a string. */
 178   string GetValueAsString(void) const;
 179
 180 /// Retrieves the name of the function.
 181   string GetName(void) const {return Name;}
 182
 183 /** Specifies whether to cache the value of the function, so it is calculated only
 184     once per frame.
 185     If shouldCache is true, then the value of the function is calculated, and
 186     a flag is set so further calculations done this frame will use the cached value.
 187     In order to turn off caching, cacheValue must be called with a false argument.
 188     @param shouldCache specifies whether the function should cache the computed value. */
 189   void cacheValue(bool shouldCache);
 190
 191 private:
 192   vector <FGParameter*> Parameters;
 193   FGPropertyManager* const PropertyManager;
 194   bool cached;
 195   string Prefix;
 196   string description_string;
 197   string property_string;
 198   string value_string;
 199   string table_string;
 200   string p_string;
 201   string v_string;
 202   string t_string;
 203   string function_string;
 204   string sum_string;
 205   string difference_string;
 206   string product_string;
 207   string quotient_string;
 208   string pow_string;
 209   string exp_string;
 210   string abs_string;
 211   string sin_string;
 212   string cos_string;
 213   string tan_string;
 214   string asin_string;
 215   string acos_string;
 216   string atan_string;
 217   string atan2_string;
 218   string min_string;
 219   string max_string;
 220   string avg_string;
 221   string fraction_string;
 222   string mod_string;
 223   string random_string;
 224   string integer_string;
 225   double cachedValue;
 226   enum functionType {eTopLevel=0, eProduct, eDifference, eSum, eQuotient, ePow,
 227                      eExp, eAbs, eSin, eCos, eTan, eASin, eACos, eATan, eATan2,
 228                      eMin, eMax, eAvg, eFrac, eInteger, eMod, eRandom} Type;
 229   string Name;
 230   void bind(void);
 231   void Debug(int from);
 232 };
 233
 234 } // namespace JSBSim
 235
 236 #endif