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