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
  41 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  42 DEFINITIONS
  43 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  44
  45 #define ID_FUNCTION "$Id: FGFunction.h,v 1.21 2009/11/18 04:49:02 jberndt Exp $"
  46
  47 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  48 FORWARD DECLARATIONS
  49 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  50
  51 namespace JSBSim {
  52
  53 class FGPropertyManager;
  54 class Element;
  55
  56 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  57 CLASS DOCUMENTATION
  58 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  59
  60 /** Represents a mathematical function.
  61 The FGFunction class is a powerful and versatile resource that allows
  62 algebraic functions to be defined in a JSBSim configuration file. It is
  63 similar in concept to MathML (Mathematical Markup Language, www.w3.org/Math/),
  64 but simpler and more terse.
  65 A function definition consists of an operation, a value, a table, or a property
  66 (which evaluates to a value). The currently supported operations are:
  67 - sum (takes n args)
  68 - difference (takes n args)
  69 - product (takes n args)
  70 - quotient (takes 2 args)
  71 - pow (takes 2 args)
  72 - exp (takes 2 args)
  73 - log2 (takes 1 arg)
  74 - ln (takes 1 arg)
  75 - log10 (takes 1 arg)
  76 - abs (takes n args)
  77 - sin (takes 1 arg)
  78 - cos (takes 1 arg)
  79 - tan (takes 1 arg)
  80 - asin (takes 1 arg)
  81 - acos (takes 1 arg)
  82 - atan (takes 1 arg)
  83 - atan2 (takes 2 args)
  84 - min (takes n args)
  85 - max (takes n args)
  86 - avg (takes n args)
  87 - fraction
  88 - mod
  89 - random (Gaussian random number)
  90 - integer
  91
  92 An operation is defined in the configuration file as in the following example:
  93
  94 @code
  95   <sum>
  96     <value> 3.14159 </value>
  97     <property> velocities/qbar </property>
  98     <product>
  99       <value> 0.125 </value>
 100       <property> metrics/wingarea </property>
 101     </product>
 102   </sum>
 103 @endcode
 104
 105 A full function definition, such as is used in the aerodynamics section of a
 106 configuration file includes the function element, and other elements. It should
 107 be noted that there can be only one non-optional (non-documentation) element -
 108 that is, one operation element - in the top-level function definition.
 109 Multiple value and/or property elements cannot be immediate child
 110 members of the function element. Almost always, the first operation within the
 111 function element will be a product or sum. For example:
 112
 113 @code
 114 <function name="aero/coefficient/Clr">
 115     <description>Roll moment due to yaw rate</description>
 116     <product>
 117         <property>aero/qbar-area</property>
 118         <property>metrics/bw-ft</property>
 119         <property>aero/bi2vel</property>
 120         <property>velocities/r-aero-rad_sec</property>
 121         <table>
 122             <independentVar>aero/alpha-rad</independentVar>
 123             <tableData>
 124                  0.000  0.08
 125                  0.094  0.19
 126             </tableData>
 127         </table>
 128     </product>
 129 </function>
 130 @endcode
 131
 132 The "lowest level" in a function is always a value or a property, which cannot
 133 itself contain another element. As shown, operations can contain values,
 134 properties, tables, or other operations. In the first above example, the sum
 135 element contains all three. What is evaluated is written algebraically as:
 136
 137 @code 3.14159 + qbar + (0.125 * wingarea) @endcode
 138
 139 Some operations can take only a single argument. That argument, however, can be
 140 an operation (such as sum) which can contain other items. The point to keep in
 141 mind is that it evaluates to a single value - which is just what the trigonometric
 142 functions require (except atan2, which takes two arguments).
 143
 144 @author Jon Berndt
 145 */
 146
 147 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 148 DECLARATION: FGFunction
 149 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 150
 151 // Todo: Does this class need a copy constructor, like FGLGear?
 152
 153 class FGFunction : public FGParameter
 154 {
 155 public:
 156
 157 /** Constructor.
 158     When this constructor is called, the XML element pointed to in memory by the
 159     element argument is traversed. If other FGParameter-derived objects (values,
 160     functions, properties, or tables) are encountered, this instance of the
 161     FGFunction object will store a pointer to the found object and pass the relevant
 162     Element pointer to the constructor for the new object. In other words, each
 163     FGFunction object maintains a list of "child" FGParameter-derived objects which
 164     in turn may each contain its own list, and so on. At runtime, each object
 165     evaluates its child parameters, which each may have its own child parameters to
 166     evaluate.
 167     @param PropertyManager a pointer to the property manager instance.
 168     @param element a pointer to the Element object containing the function definition.
 169     @param prefix an optional prefix to prepend to the name given to the property
 170            that represents this function (if given).
 171 */
 172   FGFunction(FGPropertyManager* PropertyManager, Element* element, const std::string& prefix="");
 173   /// Destructor.
 174   virtual ~FGFunction();
 175
 176 /** Retrieves the value of the function object.
 177     @return the total value of the function. */
 178   double GetValue(void) const;
 179
 180 /** The value that the function evaluates to, as a string.
 181   @return the value of the function as a string. */
 182   std::string GetValueAsString(void) const;
 183
 184 /// Retrieves the name of the function.
 185   std::string GetName(void) const {return Name;}
 186
 187 /** Specifies whether to cache the value of the function, so it is calculated only
 188     once per frame.
 189     If shouldCache is true, then the value of the function is calculated, and
 190     a flag is set so further calculations done this frame will use the cached value.
 191     In order to turn off caching, cacheValue must be called with a false argument.
 192     @param shouldCache specifies whether the function should cache the computed value. */
 193   void cacheValue(bool shouldCache);
 194
 195 private:
 196   std::vector <FGParameter*> Parameters;
 197   FGPropertyManager* const PropertyManager;
 198   bool cached;
 199   double invlog2val;
 200   std::string Prefix;
 201   std::string description_string;
 202   std::string property_string;
 203   std::string value_string;
 204   std::string table_string;
 205   std::string p_string;
 206   std::string v_string;
 207   std::string t_string;
 208   std::string function_string;
 209   std::string sum_string;
 210   std::string difference_string;
 211   std::string product_string;
 212   std::string quotient_string;
 213   std::string pow_string;
 214   std::string exp_string;
 215   std::string log2_string;
 216   std::string ln_string;
 217   std::string log10_string;
 218   std::string abs_string;
 219   std::string sin_string;
 220   std::string cos_string;
 221   std::string tan_string;
 222   std::string asin_string;
 223   std::string acos_string;
 224   std::string atan_string;
 225   std::string atan2_string;
 226   std::string min_string;
 227   std::string max_string;
 228   std::string avg_string;
 229   std::string fraction_string;
 230   std::string mod_string;
 231   std::string random_string;
 232   std::string integer_string;
 233   double cachedValue;
 234   enum functionType {eTopLevel=0, eProduct, eDifference, eSum, eQuotient, ePow,
 235                      eExp, eAbs, eSin, eCos, eTan, eASin, eACos, eATan, eATan2,
 236                      eMin, eMax, eAvg, eFrac, eInteger, eMod, eRandom, eLog2, eLn, eLog10} Type;
 237   std::string Name;
 238   void bind(void);
 239   void Debug(int from);
 240 };
 241
 242 } // namespace JSBSim
 243
 244 #endif