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