1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
5 Date started: August 25 2004
7 ------------- Copyright (C) 2001 Jon S. Berndt (jon@jsbsim.org) -------------
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
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
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.
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.
26 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
28 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
33 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
35 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
39 #include "FGParameter.h"
41 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
43 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
45 #define ID_FUNCTION "$Id: FGFunction.h,v 1.21 2009/11/18 04:49:02 jberndt Exp $"
47 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
49 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
53 class FGPropertyManager;
56 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
58 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
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:
68 - difference (takes n args)
69 - product (takes n args)
70 - quotient (takes 2 args)
83 - atan2 (takes 2 args)
89 - random (Gaussian random number)
92 An operation is defined in the configuration file as in the following example:
96 <value> 3.14159 </value>
97 <property> velocities/qbar </property>
99 <value> 0.125 </value>
100 <property> metrics/wingarea </property>
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:
114 <function name="aero/coefficient/Clr">
115 <description>Roll moment due to yaw rate</description>
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>
122 <independentVar>aero/alpha-rad</independentVar>
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:
137 @code 3.14159 + qbar + (0.125 * wingarea) @endcode
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).
147 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
148 DECLARATION: FGFunction
149 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
151 // Todo: Does this class need a copy constructor, like FGLGear?
153 class FGFunction : public FGParameter
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
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).
172 FGFunction(FGPropertyManager* PropertyManager, Element* element, const std::string& prefix="");
174 virtual ~FGFunction();
176 /** Retrieves the value of the function object.
177 @return the total value of the function. */
178 double GetValue(void) const;
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;
184 /// Retrieves the name of the function.
185 std::string GetName(void) const {return Name;}
187 /** Specifies whether to cache the value of the function, so it is calculated only
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);
196 std::vector <FGParameter*> Parameters;
197 FGPropertyManager* const PropertyManager;
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;
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;
239 void Debug(int from);
242 } // namespace JSBSim