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