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.24 2011/08/06 13:10:00 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 - lt (less than, takes 2 args)
  90 - le (less equal, takes 2 args)
  91 - gt (greater than, takes 2 args)
  92 - ge (greater than, takes 2 args)
  93 - eq (equal, takes 2 args)
  94 - nq (not equal, takes 2 args)
  95 - and (takes n args)
  96 - or (takes n args)
  97 - not (takes 1 args)
  98 - if-then (takes 2-3 args)
  99 - switch (takes 2 or more args)
 100 - random (Gaussian random number)
 101 - integer
 102
 103 An operation is defined in the configuration file as in the following example:
 104
 105 @code
 106   <sum>
 107     <value> 3.14159 </value>
 108     <property> velocities/qbar </property>
 109     <product>
 110       <value> 0.125 </value>
 111       <property> metrics/wingarea </property>
 112     </product>
 113   </sum>
 114 @endcode
 115
 116 A full function definition, such as is used in the aerodynamics section of a
 117 configuration file includes the function element, and other elements. It should
 118 be noted that there can be only one non-optional (non-documentation) element -
 119 that is, one operation element - in the top-level function definition.
 120 Multiple value and/or property elements cannot be immediate child
 121 members of the function element. Almost always, the first operation within the
 122 function element will be a product or sum. For example:
 123
 124 @code
 125 <function name="aero/coefficient/Clr">
 126     <description>Roll moment due to yaw rate</description>
 127     <product>
 128         <property>aero/qbar-area</property>
 129         <property>metrics/bw-ft</property>
 130         <property>aero/bi2vel</property>
 131         <property>velocities/r-aero-rad_sec</property>
 132         <table>
 133             <independentVar>aero/alpha-rad</independentVar>
 134             <tableData>
 135                  0.000  0.08
 136                  0.094  0.19
 137             </tableData>
 138         </table>
 139     </product>
 140 </function>
 141 @endcode
 142
 143 The "lowest level" in a function is always a value or a property, which cannot
 144 itself contain another element. As shown, operations can contain values,
 145 properties, tables, or other operations. In the first above example, the sum
 146 element contains all three. What is evaluated is written algebraically as:
 147
 148 @code 3.14159 + qbar + (0.125 * wingarea) @endcode
 149
 150 Some operations can take only a single argument. That argument, however, can be
 151 an operation (such as sum) which can contain other items. The point to keep in
 152 mind is that it evaluates to a single value - which is just what the trigonometric
 153 functions require (except atan2, which takes two arguments).
 154
 155 @author Jon Berndt
 156 */
 157
 158 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 159 DECLARATION: FGFunction
 160 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 161
 162 // Todo: Does this class need a copy constructor, like FGLGear?
 163
 164 class FGFunction : public FGParameter
 165 {
 166 public:
 167
 168 /** Constructor.
 169     When this constructor is called, the XML element pointed to in memory by the
 170     element argument is traversed. If other FGParameter-derived objects (values,
 171     functions, properties, or tables) are encountered, this instance of the
 172     FGFunction object will store a pointer to the found object and pass the relevant
 173     Element pointer to the constructor for the new object. In other words, each
 174     FGFunction object maintains a list of "child" FGParameter-derived objects which
 175     in turn may each contain its own list, and so on. At runtime, each object
 176     evaluates its child parameters, which each may have its own child parameters to
 177     evaluate.
 178     @param PropertyManager a pointer to the property manager instance.
 179     @param element a pointer to the Element object containing the function definition.
 180     @param prefix an optional prefix to prepend to the name given to the property
 181            that represents this function (if given).
 182 */
 183   FGFunction(FGPropertyManager* PropertyManager, Element* element, const std::string& prefix="");
 184   /// Destructor.
 185   virtual ~FGFunction();
 186
 187 /** Retrieves the value of the function object.
 188     @return the total value of the function. */
 189   double GetValue(void) const;
 190
 191 /** The value that the function evaluates to, as a string.
 192   @return the value of the function as a string. */
 193   std::string GetValueAsString(void) const;
 194
 195 /// Retrieves the name of the function.
 196   std::string GetName(void) const {return Name;}
 197
 198 /** Specifies whether to cache the value of the function, so it is calculated only
 199     once per frame.
 200     If shouldCache is true, then the value of the function is calculated, and
 201     a flag is set so further calculations done this frame will use the cached value.
 202     In order to turn off caching, cacheValue must be called with a false argument.
 203     @param shouldCache specifies whether the function should cache the computed value. */
 204   void cacheValue(bool shouldCache);
 205
 206 private:
 207   std::vector <FGParameter*> Parameters;
 208   FGPropertyManager* const PropertyManager;
 209   bool cached;
 210   double invlog2val;
 211   std::string Prefix;
 212   static const std::string description_string;
 213   static const std::string property_string;
 214   static const std::string value_string;
 215   static const std::string table_string;
 216   static const std::string p_string;
 217   static const std::string v_string;
 218   static const std::string t_string;
 219   static const std::string function_string;
 220   static const std::string sum_string;
 221   static const std::string difference_string;
 222   static const std::string product_string;
 223   static const std::string quotient_string;
 224   static const std::string pow_string;
 225   static const std::string exp_string;
 226   static const std::string log2_string;
 227   static const std::string ln_string;
 228   static const std::string log10_string;
 229   static const std::string abs_string;
 230   static const std::string sign_string;
 231   static const std::string sin_string;
 232   static const std::string cos_string;
 233   static const std::string tan_string;
 234   static const std::string asin_string;
 235   static const std::string acos_string;
 236   static const std::string atan_string;
 237   static const std::string atan2_string;
 238   static const std::string min_string;
 239   static const std::string max_string;
 240   static const std::string avg_string;
 241   static const std::string fraction_string;
 242   static const std::string mod_string;
 243   static const std::string random_string;
 244   static const std::string integer_string;
 245   static const std::string rotation_alpha_local_string;
 246   static const std::string rotation_beta_local_string;
 247   static const std::string rotation_gamma_local_string;
 248   static const std::string rotation_bf_to_wf_string;
 249   static const std::string rotation_wf_to_bf_string;
 250   static const std::string lessthan_string;
 251   static const std::string lessequal_string;
 252   static const std::string greatthan_string;
 253   static const std::string greatequal_string;
 254   static const std::string equal_string;
 255   static const std::string notequal_string;
 256   static const std::string and_string;
 257   static const std::string or_string;
 258   static const std::string not_string;
 259   static const std::string ifthen_string;
 260   static const std::string switch_string;
 261   double cachedValue;
 262   enum functionType {eTopLevel=0, eProduct, eDifference, eSum, eQuotient, ePow,
 263                      eExp, eAbs, eSign, eSin, eCos, eTan, eASin, eACos, eATan, eATan2,
 264                      eMin, eMax, eAvg, eFrac, eInteger, eMod, eRandom, eLog2, eLn,
 265                      eLog10, eLT, eLE, eGE, eGT, eEQ, eNE,  eAND, eOR, eNOT,
 266                      eIfThen, eSwitch, eRotation_alpha_local, eRotation_beta_local,
 267                      eRotation_gamma_local, eRotation_bf_to_wf, eRotation_wf_to_bf} Type;
 268   std::string Name;
 269
 270   unsigned int GetBinary(double) const;
 271   void bind(void);
 272   void Debug(int from);
 273 };
 274
 275 } // namespace JSBSim
 276
 277 #endif