]> git.mxchange.org Git - flightgear.git/blob - src/FDM/JSBSim/FGForce.h
Added FGTurbine.[ch]*
[flightgear.git] / src / FDM / JSBSim / FGForce.h
1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2
3  Header:       FGForce.h
4  Author:       Tony Peden
5  Date started: 5/20/00
6
7  ------------- Copyright (C) 1999  Anthony K. Peden (apeden@earthlink.net) -------------
8
9  This program is free software; you can redistribute it and/or modify it under
10  the terms of the GNU 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 General Public License for more
17  details.
18
19  You should have received a copy of the GNU 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 General Public License can also be found on
24  the world wide web at http://www.gnu.org.
25
26
27  HISTORY
28 --------------------------------------------------------------------------------
29 5/20/00  TP   Created
30
31
32 FUNCTIONAL DESCRIPTION
33 --------------------------------------------------------------------------------
34
35 The purpose of this class is to provide storage for computed forces and
36 encapsulate all the functionality associated with transforming those
37 forces from their native coord system to the body system.  This includes
38 computing the moments due to the difference between the point of application
39 and the cg.
40
41 CAVEAT:  if the custom transform is used for wind-to-body transforms then the
42          user *must* always pass this class the negative of beta. This is true
43          because sideslip angle does not follow the right hand rule i.e. it is
44          positive for aircraft nose left sideslip.  Note that use of the custom
45          transform for this purpose shouldn't be necessary as it is already
46          provided by SetTransform(tWindBody) and is not subject to the same
47          restriction.
48
49 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
50 SENTRY
51 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
52
53 #ifndef FGFORCE_H
54 #define FGFORCE_H
55
56 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
57 INCLUDES
58 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
59
60 #define ID_FORCE "$Id$"
61
62 #include "FGFDMExec.h"
63 #include "FGJSBBase.h"
64 #include "FGMatrix33.h"
65 #include "FGColumnVector3.h"
66 #include "FGColumnVector4.h"
67
68 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
69 COMMENTS, REFERENCES, and NOTES [use "class documentation" below for API docs]
70 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
71
72 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
73 CLASS DOCUMENTATION
74 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
75
76 /** Utility class that aids in the conversion of forces between coordinate systems
77     and calculation of moments.
78 <br><h3>Resolution of Applied Forces into Moments and Body Axes Components</h3>
79 <br><p>
80 All forces acting on the aircraft that cannot be considered a change in weight
81 need to be resolved into body axis components so that the aircraft acceleration
82 vectors, both translational and rotational, can be computed. Furthermore, the
83 moments produced by each force that does not act at a location corresponding to
84 the center of gravity also need to be computed. Unfortunately, the math required
85 to do this can be a bit messy and errors are easily introduced so the class
86 FGForce was created to provide these services in a consistent and reusable
87 manner.<br><br></p>
88
89 <h4>Basic usage</h4>
90
91 <p>FGForce requires that its users supply it with the location of the applied
92 force vector in JSBSim structural coordinates, the sense of each axis in that
93 coordinate system relative to the body system, the orientation of the vector
94 also relative to body coordinates and, of course, the force vector itself. With
95 this information it will compute both the body axis force components and the
96 resulting moments. Any moments inherently produced by the native system can be
97 supplied as well and they will be summed with those computed.</p>
98
99 <p>A good example for demonstrating the use of this class are the aerodynamic
100 forces: lift, drag, and side force and the aerodynamic moments about the pitch,
101 roll and yaw axes. These "native" forces and moments are computed and stored
102 in the FGColumnVector objects vFs and vMoments. Their native coordinate system
103 is often referred to as the wind system and is defined as a right-handed system
104 having its x-axis aligned with the relative velocity vector and pointing towards
105 the rear of the aircraft , the y-axis extending out the right wing, and the
106 z-axis directed upwards. This is different than body axes; they are defined such
107 that the x-axis is lies on the aircraft's roll axis and positive forward, the
108 y-axis is positive out the right wing, and the z-axis is positive downwards. In
109 this instance, JSBSim already provides the needed transform and FGForce can make
110 use of it by calling SetTransformType() once an object is created:</p>
111
112 <p><tt>FGForce fgf(FDMExec);</tt><br>
113 <tt>fgf.SetTransformType(tWindBody);</tt><br><br>
114
115 This call need only be made once for each object. The available transforms are
116 defined in the enumerated type TransformType and are tWindBody, tLocalBody,
117 tCustom, and tNone. The local-to-body transform, like the wind-to-body, also
118 makes use of that already available in JSBSim. tNone sets FGForce to do no
119 angular transform at all, and tCustom allows for modeling force vectors at
120 arbitrary angles relative to the body system such as that produced by propulsion
121 systems. Setting up and using a custom transform is covered in more detail below.
122 Continuing with the example, the point of application of the aerodynamic forces,
123 the aerodynamic reference point in JSBSim, also needs to be set:</p>
124 <p><tt>
125 fgf.SetLocation(x, y, z)</tt></p>
126
127 <p>where x, y, and z are in JSBSim structural coordinates.</p>
128
129 <p>Initialization is complete and the FGForce object is ready to do its job. As
130 stated above, the lift, drag, and side force are computed and stored in the
131 vector vFs and need to be passed to FGForce:</p>
132
133 <p><tt>fgf.SetNativeForces(vFs);</tt> </p>
134
135 <p>The same applies to the aerodynamic pitching, rolling and yawing moments:</p>
136
137 <p><tt>fgf.SetNativeMoments(vMoments);</tt></p>
138
139 <p>Note that storing the native forces and moments outside of this class is not
140 strictly necessary, overloaded SetNativeForces() and SetNativeMoments() methods
141 which each accept three doubles (rather than a vector) are provided and can be
142 repeatedly called without incurring undue overhead. The body axes force vector
143 can now be retrieved by calling:</p>
144
145 <p><tt>vFb=fgf.GetBodyForces();</tt></p>
146
147 <p>This method is where the bulk of the work gets done so calling it more than
148 once for the same set of native forces and moments should probably be avoided.
149 Note that the moment calculations are done here as well so they should not be
150 retrieved after calling the GetBodyForces() method:</p>
151
152 <p><tt>vM=fgf.GetMoments();</tt> </p>
153
154 <p>As an aside, the native moments are not needed to perform the computations
155 correctly so, if the FGForce object is not being used to store them then an
156 alternate approach is to avoid the SetNativeMoments call and perform the sum</p>
157
158 <p><tt>vMoments+=fgf.GetMoments();</tt> <br><br>
159
160 after the forces have been retrieved. </p>
161
162 <h4>Use of the Custom Transform Type</h4>
163
164 <p>In cases where the native force vector is not aligned with the body, wind, or
165 local coordinate systems a custom transform type is provided. A vectorable engine
166 nozzle will be used to demonstrate its usage. Initialization is much the same:</p>
167
168 <p><tt>FGForce fgf(FDMExec);</tt> <br>
169 <tt>fgf.SetTransformType(tCustom);</tt> <br>
170 <tt>fgf.SetLocation(x,y,z);</tt> </p>
171
172 <p>Except that here the tCustom transform type is specified and the location of
173 the thrust vector is used rather than the aerodynamic reference point. Thrust is
174 typically considered to be positive when directed aft while the body x-axis is
175 positive forward and, if the native system is right handed, the z-axis will be
176 reversed as well. These differences in sense need to be specified using by the
177 call: </p>
178
179 <p><tt>fgf.SetSense(-1,1,-1);</tt></p>
180
181 <p>The angles are specified by calling the method: </p>
182
183 <p><tt>fgf.SetAnglesToBody(pitch, roll, yaw);</tt> </p>
184
185 <p>in which the transform matrix is computed. Note that these angles should be
186 taken relative to the body system and not the local as the names might suggest.
187 For an aircraft with vectorable thrust, this method will need to be called
188 every time the nozzle angle changes, a fixed engine/nozzle installation, on the
189 other hand, will require it to be be called only once.</p>
190
191 <p>Retrieval of the computed forces and moments is done as detailed above.</p>
192 <br>
193 <blockquote>
194     <p><i>CAVEAT: If the custom system is used to compute
195     the wind-to-body transform, then the sign of the sideslip
196     angle must be reversed when calling SetAnglesToBody().
197     This is true because sideslip angle does not follow the right
198     hand rule. Using the custom transform type this way
199     should not be necessary, as it is already provided as a built
200     in type (and the sign differences are correctly accounted for).</i>
201     <br></p>
202 </blockquote>
203
204 <h4>Use as a Base Type</h4>
205
206 <p>For use as a base type, the native force and moment vector data members are
207 defined as protected. In this case the SetNativeForces() and SetNativeMoments()
208 methods need not be used and, instead, the assignments to vFn, the force vector,
209 and vMn, the moments, can be made directly. Otherwise, the usage is similar.<br>
210 <br><br></p>
211
212     @author Tony Peden
213     @version $Id$
214 */
215
216 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
217 CLASS DECLARATION
218 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
219
220 class FGForce : public FGJSBBase
221 {
222 public:
223   /// Constructor
224   FGForce(FGFDMExec *FDMExec);
225   /// Destructor
226   ~FGForce();
227
228   enum TransformType { tNone, tWindBody, tLocalBody, tCustom } ttype;
229
230   inline void SetNativeForces(double Fnx, double Fny, double Fnz) {
231     vFn(1)=Fnx;
232     vFn(2)=Fny;
233     vFn(3)=Fnz;
234   }
235   inline void SetNativeForces(FGColumnVector3 vv) { vFn = vv; };
236
237   inline void SetNativeMoments(double Ln,double Mn, double Nn) {
238     vMn(1)=Ln;
239     vMn(2)=Mn;
240     vMn(3)=Nn;
241   }
242   inline void SetNativeMoments(FGColumnVector3 vv) { vMn = vv; }
243
244   inline FGColumnVector3& GetNativeForces(void) { return vFn; }
245   inline FGColumnVector3& GetNativeMoments(void) { return vMn; }
246
247   FGColumnVector3& GetBodyForces(void);
248
249   inline FGColumnVector3& GetMoments(void) { return vM; }
250
251   // Normal point of application, JSBsim structural coords
252   // (inches, x +back, y +right, z +up)
253   inline void SetLocation(double x, double y, double z) {
254     vXYZn(eX) = x;
255     vXYZn(eY) = y;
256     vXYZn(eZ) = z;
257     SetActingLocation(x, y, z);
258   }
259   
260   /** Acting point of application.
261       JSBsim structural coords used (inches, x +back, y +right, z +up).
262       This function sets the point at which the force acts - this may
263       not be the same as where the object resides. One area where this
264       is true is P-Factor modeling.
265       @param x acting location of force
266       @param y acting location of force
267       @param z acting location of force    */
268   inline void SetActingLocation(double x, double y, double z) {
269     vActingXYZn(eX) = x;
270     vActingXYZn(eY) = y;
271     vActingXYZn(eZ) = z;
272   }
273   inline void SetLocationX(double x) {vXYZn(eX) = x; vActingXYZn(eX) = x;}
274   inline void SetLocationY(double y) {vXYZn(eY) = y; vActingXYZn(eY) = y;}
275   inline void SetLocationZ(double z) {vXYZn(eZ) = z; vActingXYZn(eZ) = z;}
276   inline double SetActingLocationX(double x) {vActingXYZn(eX) = x; return x;}
277   inline double SetActingLocationY(double y) {vActingXYZn(eY) = y; return y;}
278   inline double SetActingLocationZ(double z) {vActingXYZn(eZ) = z; return z;}
279   inline void SetLocation(FGColumnVector3 vv) { vXYZn = vv; SetActingLocation(vv);}
280   inline void SetActingLocation(FGColumnVector3 vv) { vActingXYZn = vv; }
281   
282   inline double GetLocationX( void ) { return vXYZn(eX);}
283   inline double GetLocationY( void ) { return vXYZn(eY);}
284   inline double GetLocationZ( void ) { return vXYZn(eZ);}
285   inline double GetActingLocationX( void ) { return vActingXYZn(eX);}
286   inline double GetActingLocationY( void ) { return vActingXYZn(eY);}
287   inline double GetActingLocationZ( void ) { return vActingXYZn(eZ);}
288   FGColumnVector3& GetLocation(void) { return vXYZn; }
289   FGColumnVector3& GetActingLocation(void) { return vActingXYZn; }
290
291   //these angles are relative to body axes, not earth!!!!!
292   //I'm using these because pitch, roll, and yaw are easy to visualize,
293   //there's no equivalent to roll in wind axes i.e. alpha, ? , beta
294   //making up new names or using these is a toss-up: either way people
295   //are going to get confused.
296   //They are in radians.
297
298   void SetAnglesToBody(double broll, double bpitch, double byaw);
299   inline void  SetAnglesToBody(FGColumnVector3 vv) {
300     SetAnglesToBody(vv(eRoll), vv(ePitch), vv(eYaw));
301   }
302
303   inline void SetSense(double x, double y, double z) { vSense(eX)=x, vSense(eY)=y, vSense(eZ)=z; }
304   inline void SetSense(FGColumnVector3 vv) { vSense=vv; }
305
306   inline FGColumnVector3& GetSense(void) { return vSense; }
307
308   inline void SetTransformType(TransformType ii) { ttype=ii; }
309   inline TransformType GetTransformType(void) { return ttype; }
310
311   FGMatrix33 Transform(void);
312
313 protected:
314   FGFDMExec *fdmex;
315   FGColumnVector3 vFn;
316   FGColumnVector3 vMn;
317   FGColumnVector3 vH;
318   
319 private:
320   FGColumnVector3 vFb;
321   FGColumnVector3 vM;
322   FGColumnVector3 vXYZn;
323   FGColumnVector3 vActingXYZn;
324   FGColumnVector3 vDXYZ;
325   FGColumnVector3 vSense;
326
327   FGMatrix33 mT;
328
329   virtual void Debug(int from);
330 };
331
332 #endif
333