]> git.mxchange.org Git - flightgear.git/blob - src/FDM/JSBSim/FGTrim.h
Adds a basic FDM model for LaRCsim debugging purposes.
[flightgear.git] / src / FDM / JSBSim / FGTrim.h
1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2  
3  Header:       FGTrim.h
4  Author:       Tony Peden
5  Date started: 7/1/99
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 9/8/99   TP   Created
30  
31  
32 FUNCTIONAL DESCRIPTION
33 --------------------------------------------------------------------------------
34  
35 This class takes the given set of IC's and finds the aircraft state required to
36 maintain a specified flight condition.  This flight condition can be 
37 steady-level with non-zero sideslip, a steady turn, a pull-up or pushover.
38 On-ground conditions can be trimmed as well, but this is currently limited to
39 adjusting altitude and pitch angle only. It is implemented using an iterative,
40 one-axis-at-a-time scheme.  
41  
42 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
43 SENTRY
44 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
45
46 #ifndef FGTRIM_H
47 #define FGTRIM_H
48
49 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
50 INCLUDES
51 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
52
53 #include "FGFDMExec.h"
54 #include "FGJSBBase.h"
55 #include "FGTrimAxis.h"
56
57 #include <vector>
58
59 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
60 DEFINITIONS
61 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
62
63 #define ID_TRIM "$Id$"
64
65 #if defined(_WIN32) && !defined(__CYGWIN__)
66   #define snprintf _snprintf
67 #endif
68
69 namespace JSBSim {
70
71 typedef enum { tLongitudinal, tFull, tGround, tPullup, 
72                tCustom, tNone, tTurn 
73              } TrimMode;
74
75 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
76 FORWARD DECLARATIONS
77 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
78
79 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
80 COMMENTS, REFERENCES, and NOTES [use "class documentation" below for API docs]
81 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
82
83 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
84 CLASS DOCUMENTATION
85 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
86
87 /** FGTrim -- the trimming routine for JSBSim.
88     FGTrim finds the aircraft attitude and control settings needed to maintain
89     the steady state described by the FGInitialCondition object .  It does this
90     iteratively by assigning a control to each state and adjusting that control
91     until the state is within a specified tolerance of zero. States include the
92     recti-linear accelerations udot, vdot, and wdot, the angular accelerations 
93     qdot, pdot, and rdot, and the difference between heading and ground track.
94     Controls include the usual flight deck controls available to the pilot plus
95     angle of attack (alpha), sideslip angle(beta), flight path angle (gamma), 
96     pitch attitude(theta), roll attitude(phi), and altitude above ground.  The
97     last three are used for on-ground trimming. The state-control pairs used in
98     a given trim are completely user configurable and several pre-defined modes
99     are provided as well. They are:
100     <ul>
101     <li> tLongitudinal: Trim wdot with alpha, udot with thrust, qdot with elevator</li>
102     <li> tFull: tLongitudinal + vdot with phi, pdot with aileron, rdot with rudder
103                 and heading minus ground track (hmgt) with beta</li>
104     <li> tPullup: tLongitudinal but adjust alpha to achieve load factor input
105          with SetTargetNlf()
106
107     <li> tGround: wdot with altitude, qdot with theta, and pdot with phi</li>
108     
109     The remaining modes include <b>tCustom</b>, which is completely user defined and
110     <b>tNone</b>.
111     </ul>
112     
113     Note that trims can (and do) fail for reasons that are completely outside
114     the control of the trimming routine itself. The most common problem is the 
115     initial conditions: is the model capable of steady state flight
116     at those conditions?  Check the speed, altitude, configuration (flaps,
117     gear, etc.), weight, cg, and anything else that may be relevant.
118     
119     Example usage:
120     FGFDMExec* FDMExec = new FGFDMExec();
121     .
122     .
123     .
124     FGInitialCondition* fgic = new FGInitialCondition(FDMExec);
125     FGTrim *fgt(FDMExec,fgic,tFull);
126     fgic->SetVcaibratedKtsIC(100);
127     fgic->SetAltitudeFtIC(1000);
128     fgic->SetClimbRate(500);
129     if( !fgt->DoTrim() ) {
130       cout << "Trim Failed" << endl;
131     }
132     fgt->ReportState();  
133     @author Tony Peden
134     @version $Id$
135     @see <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/jsbsim/JSBSim/FGTrim.h?rev=HEAD&content-type=text/vnd.viewcvs-markup">
136          Header File </a>
137     @see <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/jsbsim/JSBSim/FGTrim.cpp?rev=HEAD&content-type=text/vnd.viewcvs-markup">
138          Source File </a>
139 */       
140   
141 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
142 CLASS DECLARATION
143 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
144
145 class FGTrim : public FGJSBBase
146 {
147 private:
148
149   vector<FGTrimAxis*> TrimAxes;
150   unsigned int current_axis;
151   int N, Nsub;
152   TrimMode mode;
153   int DebugLevel, Debug;
154   double Tolerance, A_Tolerance;
155   double wdot,udot,qdot;
156   double dth;
157   double *sub_iterations;
158   double *successful;
159   bool *solution;
160   int max_sub_iterations;
161   int max_iterations;
162   int total_its;
163   bool trimudot;
164   bool gamma_fallback;
165   bool trim_failed;
166   unsigned int axis_count;
167   int solutionDomain;
168   double xlo,xhi,alo,ahi;
169   double targetNlf;
170   int debug_axis;
171   
172   double psidot,thetadot;
173
174   FGFDMExec* fdmex;
175   FGInitialCondition* fgic;
176    
177   bool solve(void);
178   
179   /** @return false if there is no change in the current axis accel
180       between accel(control_min) and accel(control_max). If there is a
181       change, sets solutionDomain to:
182       0 for no sign change,
183      -1 if sign change between accel(control_min) and accel(0)
184       1 if sign between accel(0) and accel(control_max)
185   */
186   bool findInterval(void);
187
188   bool checkLimits(void);
189   
190   void setupPullup(void);
191   void setupTurn(void);
192   
193   void updateRates(void);
194
195   void setDebug(void);
196
197 public:
198   /** Initializes the trimming class
199       @param FDMExec pointer to a JSBSim executive object.
200       @param FGIC pointer to a FGInitialCondition object
201   */
202   FGTrim(FGFDMExec *FDMExec, TrimMode tt=tGround );
203
204     ~FGTrim(void);
205
206   /** Execute the trim
207   */
208   bool DoTrim(void);
209
210   /** Print the results of the trim. For each axis trimmed, this 
211       includes the final state value, control value, and tolerance
212       used.
213       @return true if trim succeeds
214   */     
215   void Report(void);
216   
217   /** Iteration statistics
218   */
219   void TrimStats();
220   
221   /** Clear all state-control pairs and set a predefined trim mode
222       @param TrimMode the set of axes to trim. Can be:
223              tLongitudinal, tFull, tGround, tCustom, or tNone
224   */
225   void SetMode(TrimMode tt);
226
227   /** Clear all state-control pairs from the current configuration.
228       The trimming routine must have at least one state-control pair
229       configured to be useful
230   */    
231   void ClearStates(void);
232
233   /** Add a state-control pair to the current configuration. See the enums
234       State and Control in FGTrimAxis.h for the available options.
235       Will fail if the given state is already configured.
236       @param state the accel or other condition to zero 
237       @param control the control used to zero the state
238       @return true if add is successful
239   */    
240   bool AddState( State state, Control control );
241   
242   /** Remove a specific state-control pair from the current configuration
243       @param state the state to remove
244       @return true if removal is successful
245   */    
246   bool RemoveState( State state );
247   
248   /** Change the control used to zero a state previously configured
249       @param state the accel or other condition to zero 
250       @param control the control used to zero the state
251   */
252   bool EditState( State state, Control new_control );
253
254   /** automatically switch to trimming longitudinal acceleration with
255       flight path angle (gamma) once it becomes apparent that there
256       is not enough/too much thrust.
257       @param gamma_fallback true to enable fallback
258   */     
259   inline void SetGammaFallback(bool bb) { gamma_fallback=bb; }
260   
261   /** query the fallback state
262       @return true if fallback is enabled.
263   */
264   inline bool GetGammaFallback(void) { return gamma_fallback; }
265
266   /** Set the iteration limit. DoTrim() will return false if limit
267       iterations are reached before trim is achieved.  The default
268       is 60.  This does not ordinarily need to be changed.
269       @param ii integer iteration limit 
270   */
271   inline void SetMaxCycles(int ii) { max_iterations = ii; }
272   
273   /** Set the per-axis iteration limit.  Attempt to zero each state
274       by iterating limit times before moving on to the next. The
275       default limit is 100 and also does not ordinarily need to
276       be changed.
277       @param ii integer iteration limit 
278   */    
279   inline void SetMaxCyclesPerAxis(int ii) { max_sub_iterations = ii; }
280   
281   /** Set the tolerance for declaring a state trimmed. Angular accels are
282       held to a tolerance of 1/10th of the given.  The default is 
283       0.001 for the recti-linear accelerations and 0.0001 for the angular.
284   */         
285   inline void SetTolerance(double tt) {
286     Tolerance = tt;
287     A_Tolerance = tt / 10;
288   }
289   
290   /** 
291     Debug level 1 shows results of each top-level iteration
292     Debug level 2 shows level 1 & results of each per-axis iteration
293   */  
294   inline void SetDebug(int level) { DebugLevel = level; }
295   inline void ClearDebug(void) { DebugLevel = 0; }
296   
297   /**
298     Output debug data for one of the axes
299     The State enum is defined in FGTrimAxis.h
300   */  
301   inline void DebugState(State state) { debug_axis=state; }
302   
303   inline void SetTargetNlf(float nlf) { targetNlf=nlf; }
304   inline double GetTargetNlf(void) { return targetNlf; }
305
306 };
307 }
308
309 #endif