src/FDM/JSBSim/models/propulsion/FGTank.h

   1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2
   3  Header:       FGTank.h
   4  Author:       Jon S. Berndt
   5  Date started: 01/21/99
   6
   7  ------------- Copyright (C) 1999  Jon S. Berndt (jon@jsbsim.org) -------------
   8
   9  This program is free software; you can redistribute it and/or modify it under
  10  the terms of the GNU Lesser 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 Lesser General Public License for more
  17  details.
  18
  19  You should have received a copy of the GNU Lesser 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 Lesser General Public License can also be found on
  24  the world wide web at http://www.gnu.org.
  25
  26 FUNCTIONAL DESCRIPTION
  27 --------------------------------------------------------------------------------
  28
  29 Based on Flightgear code, which is based on LaRCSim. This class simulates
  30 a generic Tank.
  31
  32 HISTORY
  33 --------------------------------------------------------------------------------
  34 01/21/99   JSB   Created
  35
  36 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  37 SENTRY
  38 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  39
  40 #ifndef FGTank_H
  41 #define FGTank_H
  42
  43 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  44 INCLUDES
  45 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  46
  47 #include "FGJSBBase.h"
  48 #include "math/FGColumnVector3.h"
  49 #include <string>
  50
  51 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  52 DEFINITIONS
  53 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  54
  55 #define ID_TANK "$Id: FGTank.h,v 1.26 2011/10/31 14:54:41 bcoconni Exp $"
  56
  57 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  58 FORWARD DECLARATIONS
  59 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  60
  61 namespace JSBSim {
  62
  63 class Element;
  64 class FGPropertyManager;
  65 class FGFDMExec;
  66
  67 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  68 CLASS DOCUMENTATION
  69 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  70
  71 /** Models a fuel tank.
  72
  73 <h3>Fuel Temperature:</h3>
  74
  75     Fuel temperature is calculated using the following assumptions:
  76
  77     Fuel temperature will only be calculated for tanks which have an initial fuel
  78     temperature specified in the configuration file.
  79
  80     The surface area of the tank is estimated from the capacity in pounds.  It
  81     is assumed that the tank is a wing tank with dimensions h by 4h by 10h. The
  82     volume of the tank is then 40(h)(h)(h). The area of the upper or lower
  83     surface is then 40(h)(h).  The volume is also equal to the capacity divided
  84     by 49.368 lbs/cu-ft, for jet fuel.  The surface area of one side can then be
  85     derived from the tank's capacity.
  86
  87     The heat capacity of jet fuel is assumed to be 900 Joules/lbm/K, and the
  88     heat transfer factor of the tank is 1.115 Watts/sq-ft/K.
  89
  90 <h3>Fuel Dump:</h3>
  91
  92     Fuel dumping is handled by the FGPropulsion class.  A standpipe can be defined
  93     here for each tank which sets the level of contents (in pounds) which is not dumpable.
  94     Default standpipe level is zero, making all contents dumpable.
  95
  96 <h3>Fuel Transfer:</h3>
  97
  98     Fuel transfer is handled by the FGPropulsion class, however the contents of tanks
  99     may be manipulated directly using the SetContents() function here, or via the property
 100     tree at <tt>propulsion/tank[i]/contents-lbs</tt>, where i is the tank number (Tanks
 101     are automatically numbered, starting at zero, in the order in which they are read in
 102     the aircraft configuration file).  The latter method allows one to use a system of FCS
 103     components to control tank contents.
 104
 105     There is also a property <tt>propulsion/tank[i]/external-flow-rate-pps</tt>. Setting
 106     this property to a positive value causes the tank to fill at the rate specified.
 107     Setting a negative number causes the tank to drain. The value is the rate in pounds
 108     of fuel per second. The tank will not fill past 100% full and will not drain below 0%.
 109     Fuel may be transfered between two tanks by setting the source tank's external flow rate
 110     to a negative value and the destination's external flow rate to the same positive value.
 111     Care must be taken to stop fuel flow before the source tank becomes empty to prevent
 112     phantom fuel being created.
 113
 114 <h3>Configuration File Format:</h3>
 115
 116 @code
 117 <tank type="{FUEL | OXIDIZER}">
 118   <grain_config type="{CYLINDRICAL | ENDBURNING}">
 119     <length unit="{IN | FT | M}"> {number} </radius>
 120   </grain_config>
 121   <location unit="{FT | M | IN}">
 122     <x> {number} </x>
 123     <y> {number} </y>
 124     <z> {number} </z>
 125   </location>
 126   <drain_location unit="{FT | M | IN}">
 127     <x> {number} </x>
 128     <y> {number} </y>
 129     <z> {number} </z>
 130   </drain_location>
 131   <radius unit="{IN | FT | M}"> {number} </radius>
 132   <capacity unit="{LBS | KG}"> {number} </capacity>
 133   <contents unit="{LBS | KG}"> {number} </contents>
 134   <temperature> {number} </temperature> <!-- must be degrees fahrenheit -->
 135   <standpipe unit="{LBS | KG"}> {number} </standpipe>
 136   <priority> {integer} </priority>
 137   <density unit="{KG/L | LBS/GAL}"> {number} </density>
 138   <type> {string} </type> <!-- will override previous density setting -->
 139 </tank>
 140 @endcode
 141
 142 <h3>Definition of the tank configuration file parameters:</h3>
 143
 144 - \b type - One of FUEL or OXIDIZER.  This is required.
 145 - \b radius - Equivalent radius of tank for modeling slosh, defaults to inches.
 146 - \b grain_config type - One of CYLINDRICAL or ENDBURNING.
 147 - \b length - length of tank for modeling solid fuel propellant grain, defaults to inches.
 148 - \b capacity - Capacity, defaults to pounds.
 149 - \b contents - Initial contents, defaults to pounds.
 150 - \b temperature - Initial temperature, defaults to degrees Fahrenheit.
 151 - \b standpipe - Minimum contents to which tank can dump, defaults to pounds.
 152 - \b priority - Establishes feed sequence of tank. "1" is the highest priority.
 153 - \b density - Density of liquid tank contents.
 154 - \b type - Named fuel type. One of AVGAS, JET-A, JET-A1, JET-B, JP-1, JP-2, JP-3,
 155 - \b        JP-4, JP-5, JP-6, JP-7, JP-8, JP-8+100, RP-1, T-1, ETHANOL, HYDRAZINE,
 156 - \b        F-34, F-35, F-40, F-44, AVTAG, AVCAT
 157
 158 location:
 159 - \b x - Location of tank on aircraft's x-axis, defaults to inches.
 160 - \b y - Location of tank on aircraft's y-axis, defaults to inches.
 161 - \b z - Location of tank on aircraft's z-axis, defaults to inches.
 162
 163 drain_location:
 164 - \b x - Location of tank drain on aircraft's x-axis, defaults to inches.
 165 - \b y - Location of tank drain on aircraft's y-axis, defaults to inches.
 166 - \b z - Location of tank drain on aircraft's z-axis, defaults to inches.
 167
 168 <h3>Default values of the tank configuration file parameters:</h3>
 169
 170 - \b type - ttUNKNOWN  (causes a load error in the propulsion configuration)
 171 - \b location, \b drain_location - both optional, but a warning message will
 172 be printed to the console if the location is not given
 173 - \b x - 0.0  (both full and drained CG locations)
 174 - \b y - 0.0  (both full and drained CG locations)
 175 - \b z - 0.0  (both full and drained CG locations)
 176 - \b radius - 0.0
 177 - \b capacity - 0.00001 (tank capacity must not be zero)
 178 - \b contents - 0.0
 179 - \b temperature - -9999.0 (flag which indicates no temperature is set)
 180 - \b standpipe - 0.0 (all contents may be dumped)
 181 - \b priority - 1 (highest feed sequence priority)
 182 - \b density - 6.6
 183
 184     @author Jon Berndt, Dave Culp
 185     @see Akbar, Raza et al. "A Simple Analysis of Fuel Addition to the CWT of
 186     747", California Institute of Technology, 1998,
 187     http://www.galcit.caltech.edu/EDL/projects/JetA/reports/lumped.pdf
 188 */
 189
 190 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 191 CLASS DECLARATION
 192 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 193
 194 class FGTank : public FGJSBBase
 195 {
 196 public:
 197   /** Constructor.
 198       The constructor reads in the defining parameters from a configuration file.
 199       @param exec a pointer to the base FGFDMExec instance.
 200       @param el a pointer to the Tank element.
 201       @param tank_number the tank number (zero based).
 202   */
 203   FGTank(FGFDMExec* exec, Element* el, int tank_number);
 204   /// Destructor
 205   ~FGTank();
 206
 207   enum TankType {ttUNKNOWN, ttFUEL, ttOXIDIZER};
 208   enum GrainType {gtUNKNOWN, gtCYLINDRICAL, gtENDBURNING};
 209
 210   /** Removes fuel from the tank.
 211       This function removes fuel from a tank. If the tank empties, it is
 212       deselected.
 213       @param used the amount of fuel used in lbs.
 214       @return the remaining contents of the tank in lbs.
 215   */
 216   double Drain(double used);
 217
 218   /** Performs local, tanks-specific calculations, such as fuel temperature.
 219       This function calculates the temperature of the fuel in the tank.
 220       @param dt the time step for this model.
 221       @param TempC the Total Air Temperature in degrees Celsius.
 222       @return the current temperature in degrees Celsius.
 223   */
 224   double Calculate(double dt, double TempC);
 225
 226   /** Retrieves the type of tank: Fuel or Oxidizer.
 227       @return the tank type, 0 for undefined, 1 for fuel, and 2 for oxidizer.
 228   */
 229   int GetType(void) const {return Type;}
 230
 231   /** Resets the tank parameters to the initial conditions */
 232   void ResetToIC(void);
 233
 234   /** If the tank is set to supply fuel, this function returns true.
 235       @return true if this tank is set to a non-zero priority.*/
 236   bool GetSelected(void) const {return Selected;}
 237
 238   /** Gets the tank fill level.
 239       @return the fill level in percent, from 0 to 100.*/
 240   double GetPctFull(void) const {return PctFull;}
 241
 242   /** Gets the capacity of the tank.
 243       @return the capacity of the tank in pounds. */
 244   double GetCapacity(void) const {return Capacity;}
 245
 246   /** Gets the capacity of the tank.
 247       @return the capacity of the tank in gallons. */
 248   double GetCapacityGallons(void) const {return Capacity/Density;}
 249
 250   /** Gets the contents of the tank.
 251       @return the contents of the tank in pounds. */
 252   double GetContents(void) const {return Contents;}
 253
 254   /** Gets the contents of the tank.
 255       @return the contents of the tank in gallons. */
 256   double GetContentsGallons(void) const {return Contents/Density;}
 257
 258   /** Gets the temperature of the fuel.
 259       The temperature of the fuel is calculated if an initial tempearture is
 260       given in the configuration file.
 261       @return the temperature of the fuel in degrees C IF an initial temperature
 262       is given, otherwise 0.0 C is returned. */
 263   double GetTemperature_degC(void) const {return Temperature;}
 264
 265   /** Gets the temperature of the fuel.
 266       The temperature of the fuel is calculated if an initial tempearture is
 267       given in the configuration file.
 268       @return the temperature of the fuel in degrees F IF an initial temperature
 269       is given, otherwise 32 degrees F is returned. */
 270   double GetTemperature(void) const {return CelsiusToFahrenheit(Temperature);}
 271
 272   /** Returns the density of a named fuel type.
 273       @return the density, in lbs/gal, or 6.6 if name cannot be resolved. */
 274   double ProcessFuelName(const std::string& name);
 275
 276   double GetIxx(void) const {return Ixx;}
 277   double GetIyy(void) const {return Iyy;}
 278   double GetIzz(void) const {return Izz;}
 279
 280   double GetStandpipe(void) const {return Standpipe;}
 281
 282   int  GetPriority(void) const {return Priority;}
 283   void SetPriority(int p) { Priority = p; Selected = p>0 ? true:false; }
 284
 285   double GetDensity(void) const {return Density;}
 286   void   SetDensity(double d) { Density = d; }
 287
 288   double GetExternalFlow(void) const {return ExternalFlow;}
 289   void   SetExternalFlow(double f) { ExternalFlow = f; }
 290
 291   FGColumnVector3 GetXYZ(void) const;
 292   double GetXYZ(int idx) const;
 293
 294   const GrainType GetGrainType(void) const {return grainType;}
 295
 296   double Fill(double amount);
 297   void SetContents(double amount);
 298   void SetContentsGallons(double gallons);
 299   void SetTemperature(double temp) { Temperature = temp; }
 300   void SetStandpipe(double amount) { Standpipe = amount; }
 301   void SetSelected(bool sel) { sel==true ? SetPriority(1):SetPriority(0); }
 302
 303 private:
 304   TankType Type;
 305   GrainType grainType;
 306   int TankNumber;
 307   std::string type;
 308   std::string strGType;
 309   FGColumnVector3 vXYZ;
 310   FGColumnVector3 vXYZ_drain;
 311   double Capacity;
 312   double Radius;
 313   double InnerRadius;
 314   double Length;
 315   double Volume;
 316   double Density;
 317   double Ixx;
 318   double Iyy;
 319   double Izz;
 320   double PctFull;
 321   double Contents, InitialContents;
 322   double PreviousUsed;
 323   double Area;
 324   double Temperature, InitialTemperature;
 325   double Standpipe, InitialStandpipe;
 326   double ExternalFlow;
 327   bool  Selected;
 328   int Priority, InitialPriority;
 329   FGFDMExec* Exec;
 330   FGPropertyManager* PropertyManager;
 331
 332   void CalculateInertias(void);
 333   void Debug(int from);
 334 };
 335 }
 336 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 337 #endif
 338