Branch data Line data Source code
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 : 0 : 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
|
