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, tCustom, tNone } 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> tGround: wdot with altitude, qdot with theta, and pdot with phi</li>
 105     The remaining modes include <b>tCustom</b>, which is completely user defined and
 106     <b>tNone</b>.
 107     </ul>
 108     Currently, this class cannot trim a non-1g condition and is limited to
 109     trimming for constant true airspeed in climbs and descents.
 110
 111     Note that trims can (and do) fail for reasons that are completely outside
 112     the control of the trimming routine itself. The most common problem is the
 113     initial conditions: is the model capable of steady state flight
 114     at those conditions?  Check the speed, altitude, configuration (flaps,
 115     gear, etc.), weight, cg, and anything else that may be relevant.
 116
 117     Example usage:
 118     FGFDMExec* FDMExec = new FGFDMExec();
 119     .
 120     .
 121     .
 122     FGInitialCondition* fgic = new FGInitialCondition(FDMExec);
 123     FGTrim *fgt(FDMExec,fgic,tFull);
 124     fgic->SetVcaibratedKtsIC(100);
 125     fgic->SetAltitudeFtIC(1000);
 126     fgic->SetClimbRate(500);
 127     if( !fgt->DoTrim() ) {
 128       cout << "Trim Failed" << endl;
 129     }
 130     fgt->ReportState();
 131     @author Tony Peden
 132     @version $Id$
 133 */
 134
 135 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 136 CLASS DECLARATION
 137 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 138
 139 class FGTrim : public FGJSBBase
 140 {
 141 private:
 142
 143   vector<FGTrimAxis*> TrimAxes;
 144   int current_axis;
 145   int N, Nsub;
 146   TrimMode mode;
 147   int Debug;
 148   float Tolerance, A_Tolerance;
 149   float wdot,udot,qdot;
 150   float dth;
 151   float *sub_iterations;
 152   float *successful;
 153   bool *solution;
 154   int max_sub_iterations;
 155   int max_iterations;
 156   int total_its;
 157   bool trimudot;
 158   bool gamma_fallback;
 159   bool trim_failed;
 160   int axis_count;
 161   int solutionDomain;
 162   float xlo,xhi,alo,ahi;
 163
 164   FGFDMExec* fdmex;
 165   FGInitialCondition* fgic;
 166
 167   bool solve(void);
 168
 169   /** @return false if there is no change in the current axis accel
 170       between accel(control_min) and accel(control_max). If there is a
 171       change, sets solutionDomain to:
 172       0 for no sign change,
 173      -1 if sign change between accel(control_min) and accel(0)
 174       1 if sign between accel(0) and accel(control_max)
 175   */
 176   bool findInterval(void);
 177
 178   bool checkLimits(void);
 179
 180 public:
 181   /** Initializes the trimming class
 182       @param FDMExec pointer to a JSBSim executive object.
 183       @param FGIC pointer to a FGInitialCondition object
 184       @param TrimMode the set of axes to trim. Can be:
 185              tLongitudinal, tFull, tGround, tCustom, or tNone
 186   */
 187   FGTrim(FGFDMExec *FDMExec, FGInitialCondition *FGIC, TrimMode tt);
 188
 189     ~FGTrim(void);
 190
 191   /** Execute the trim
 192   */
 193   bool DoTrim(void);
 194
 195   /** Print the results of the trim. For each axis trimmed, this
 196       includes the final state value, control value, and tolerance
 197       used.
 198       @return true if trim succeeds
 199   */
 200   void Report(void);
 201
 202   /** Prints a summary of simulator state (speed, altitude,
 203       configuration, etc.)
 204   */
 205   void ReportState(void);
 206
 207   /** Iteration statistics
 208   */
 209   void TrimStats();
 210
 211   /** Clear all state-control pairs from the current configuration.
 212       The trimming routine must have at least one state-control pair
 213       configured to be useful
 214   */
 215   void ClearStates(void);
 216
 217   /** Add a state-control pair to the current configuration. See the enums
 218       State and Control in FGTrimAxis.h for the available options.
 219       Will fail if the given state is already configured.
 220       @param state the accel or other condition to zero
 221       @param control the control used to zero the state
 222       @return true if add is successful
 223   */
 224   bool AddState( State state, Control control );
 225
 226   /** Remove a specific state-control pair from the current configuration
 227       @param state the state to remove
 228       @return true if removal is successful
 229   */
 230   bool RemoveState( State state );
 231
 232   /** Change the control used to zero a state previously configured
 233       @param state the accel or other condition to zero
 234       @param control the control used to zero the state
 235   */
 236   bool EditState( State state, Control new_control );
 237
 238   /** automatically switch to trimming longitudinal acceleration with
 239       flight path angle (gamma) once it becomes apparent that there
 240       is not enough/too much thrust.
 241       @param gamma_fallback true to enable fallback
 242   */
 243   inline void SetGammaFallback(bool bb) { gamma_fallback=true; }
 244
 245   /** query the fallback state
 246       @return true if fallback is enabled.
 247   */
 248   inline bool GetGammaFallback(void) { return gamma_fallback; }
 249
 250   /** Set the iteration limit. DoTrim() will return false if limit
 251       iterations are reached before trim is achieved.  The default
 252       is 60.  This does not ordinarily need to be changed.
 253       @param ii integer iteration limit
 254   */
 255   inline void SetMaxCycles(int ii) { max_iterations = ii; }
 256
 257   /** Set the per-axis iteration limit.  Attempt to zero each state
 258       by iterating limit times before moving on to the next. The
 259       default limit is 100 and also does not ordinarily need to
 260       be changed.
 261       @param ii integer iteration limit
 262   */
 263   inline void SetMaxCyclesPerAxis(int ii) { max_sub_iterations = ii; }
 264
 265   /** Set the tolerance for declaring a state trimmed. Angular accels are
 266       held to a tolerance of 1/10th of the given.  The default is
 267       0.001 for the recti-linear accelerations and 0.0001 for the angular.
 268   */
 269   inline void SetTolerance(float tt) {
 270     Tolerance = tt;
 271     A_Tolerance = tt / 10;
 272   }
 273
 274   //Debug level 1 shows results of each top-level iteration
 275   //Debug level 2 shows level 1 & results of each per-axis iteration
 276   inline void SetDebug(int level) { Debug = level; }
 277   inline void ClearDebug(void) { Debug = 0; }
 278
 279 };
 280
 281
 282 #endif
 283
 284
 285
 286
 287
 288
 289
 290
 291