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