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 "FGFDMExec.h"
  48 #include <FGJSBBase.h>
  49 #include <input_output/FGXMLElement.h>
  50 #include <math/FGColumnVector3.h>
  51 #include <string>
  52
  53 using std::string;
  54 using std::cerr;
  55 using std::endl;
  56 using std::cout;
  57
  58 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  59 DEFINITIONS
  60 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  61
  62 #define ID_TANK "$Id$"
  63
  64 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  65 FORWARD DECLARATIONS
  66 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  67
  68 namespace JSBSim {
  69
  70 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  71 CLASS DOCUMENTATION
  72 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  73
  74 /** Models a fuel tank.
  75
  76 <h3>Fuel Temperature:</h3>
  77
  78     Fuel temperature is calculated using the following assumptions:
  79
  80     Fuel temperature will only be calculated for tanks which have an initial fuel
  81     temperature specified in the configuration file.
  82
  83     The surface area of the tank is estimated from the capacity in pounds.  It
  84     is assumed that the tank is a wing tank with dimensions h by 4h by 10h. The
  85     volume of the tank is then 40(h)(h)(h). The area of the upper or lower
  86     surface is then 40(h)(h).  The volume is also equal to the capacity divided
  87     by 49.368 lbs/cu-ft, for jet fuel.  The surface area of one side can then be
  88     derived from the tank's capacity.
  89
  90     The heat capacity of jet fuel is assumed to be 900 Joules/lbm/K, and the
  91     heat transfer factor of the tank is 1.115 Watts/sq-ft/K.
  92
  93 <h3>Fuel Dump:</h3>
  94
  95     Fuel dumping is handled by the FGPropulsion class.  A standpipe can be defined
  96     here for each tank which sets the level of contents (in pounds) which is not dumpable.
  97     Default standpipe level is zero, making all contents dumpable.
  98
  99 <h3>Fuel Transfer:</h3>
 100
 101     Fuel transfer is handled by the FGPropulsion class, however the contents of tanks
 102     may be manipulated directly using the SetContents() function here, or via the property
 103     tree at <tt>propulsion/tank[i]/contents-lbs</tt>, where i is the tank number (Tanks
 104     are automatically numbered, starting at zero, in the order in which they are read in
 105     the aircraft configuration file).  The latter method allows one to use a system of FCS
 106     components to control tank contents.
 107
 108 <h3>Configuration File Format:</h3>
 109
 110 @code
 111 <tank type="{FUEL | OXIDIZER}">
 112   <grain_config type="{CYLINDRICAL | ENDBURNING}">
 113     <length unit="{IN | FT | M}"> {number} </radius>
 114   </grain_config>
 115   <location unit="{FT | M | IN}">
 116     <x> {number} </x>
 117     <y> {number} </y>
 118     <z> {number} </z>
 119   </location>
 120   <drain_location unit="{FT | M | IN}">
 121     <x> {number} </x>
 122     <y> {number} </y>
 123     <z> {number} </z>
 124   </drain_location>
 125   <radius unit="{IN | FT | M}"> {number} </radius>
 126   <capacity unit="{LBS | KG}"> {number} </capacity>
 127   <contents unit="{LBS | KG}"> {number} </contents>
 128   <temperature> {number} </temperature> <!-- must be degrees fahrenheit -->
 129   <standpipe unit="{LBS | KG"}> {number} </standpipe>
 130 </tank>
 131 @endcode
 132
 133 <h3>Definition of the tank configuration file parameters:</h3>
 134
 135 - \b type - One of FUEL or OXIDIZER.  This is required.
 136 - \b radius - Equivalent radius of tank for modeling slosh, defaults to inches.
 137 - \b grain_config type - One of CYLINDRICAL or ENDBURNING.
 138 - \b length - length of tank for modeling solid fuel propellant grain, defaults to inches.
 139 - \b capacity - Capacity, defaults to pounds.
 140 - \b contents - Initial contents, defaults to pounds.
 141 - \b temperature - Initial temperature, defaults to degrees Fahrenheit.
 142 - \b standpipe - Minimum contents to which tank can dump, defaults to pounds.
 143
 144 location:
 145 - \b x - Location of tank on aircraft's x-axis, defaults to inches.
 146 - \b y - Location of tank on aircraft's y-axis, defaults to inches.
 147 - \b z - Location of tank on aircraft's z-axis, defaults to inches.
 148
 149 drain_location:
 150 - \b x - Location of tank drain on aircraft's x-axis, defaults to inches.
 151 - \b y - Location of tank drain on aircraft's y-axis, defaults to inches.
 152 - \b z - Location of tank drain on aircraft's z-axis, defaults to inches.
 153
 154 <h3>Default values of the tank configuration file parameters:</h3>
 155
 156 - \b type - ttUNKNOWN  (causes a load error in the propulsion configuration)
 157 - \b location, \b drain_location - both optional, but a warning message will
 158 be printed to the console if the location is not given
 159 - \b x - 0.0  (both full and drained CG locations)
 160 - \b y - 0.0  (both full and drained CG locations)
 161 - \b z - 0.0  (both full and drained CG locations)
 162 - \b radius - 0.0
 163 - \b capacity - 0.0
 164 - \b contents - 0.0
 165 - \b temperature - -9999.0
 166 - \b standpipe - 0.0
 167
 168     @author Jon Berndt, Dave Culp
 169     @see Akbar, Raza et al. "A Simple Analysis of Fuel Addition to the CWT of
 170     747", California Institute of Technology, 1998,
 171     http://www.galcit.caltech.edu/EDL/projects/JetA/reports/lumped.pdf
 172 */
 173
 174 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 175 CLASS DECLARATION
 176 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 177
 178 class FGTank : public FGJSBBase
 179 {
 180 public:
 181   /** Constructor.
 182       The constructor reads in the defining parameters from a configuration file.
 183       @param exec a pointer to the base FGFDMExec instance.
 184       @param el a pointer to the Tank element.
 185       @param tank_number the tank number (zero based).
 186   */
 187   FGTank(FGFDMExec* exec, Element* el, int tank_number);
 188   /// Destructor
 189   ~FGTank();
 190
 191   /** Removes fuel from the tank.
 192       This function removes fuel from a tank. If the tank empties, it is
 193       deselected.
 194       @param used the amount of fuel used in lbs.
 195       @return the remaining contents of the tank in lbs.
 196   */
 197   double Drain(double used);
 198
 199   /** Performs local, tanks-specific calculations, such as fuel temperature.
 200       This function calculates the temperature of the fuel in the tank.
 201       @param dt the time step for this model.
 202       @return the current temperature in degrees Celsius.
 203   */
 204   double Calculate(double dt);
 205
 206   /** Retrieves the type of tank: Fuel or Oxidizer.
 207       @return the tank type, 0 for undefined, 1 for fuel, and 2 for oxidizer.
 208   */
 209   int GetType(void) {return Type;}
 210
 211   /** Resets the tank parameters to the initial conditions */
 212   void ResetToIC(void);
 213
 214   /** If the tank is supplying fuel, this function returns true.
 215       @return true if this tank is feeding an engine.*/
 216   bool GetSelected(void) {return Selected;}
 217
 218   /** Gets the tank fill level.
 219       @return the fill level in percent, from 0 to 100.*/
 220   double GetPctFull(void) {return PctFull;}
 221
 222   /** Gets the capacity of the tank.
 223       @return the capacity of the tank in pounds. */
 224   double GetCapacity(void) {return Capacity;}
 225
 226   /** Gets the contents of the tank.
 227       @return the contents of the tank in pounds. */
 228   double GetContents(void) const {return Contents;}
 229
 230   /** Gets the temperature of the fuel.
 231       The temperature of the fuel is calculated if an initial tempearture is
 232       given in the configuration file.
 233       @return the temperature of the fuel in degrees C IF an initial temperature
 234       is given, otherwise 0.0 C is returned. */
 235   double GetTemperature_degC(void) {return Temperature;}
 236
 237   /** Gets the temperature of the fuel.
 238       The temperature of the fuel is calculated if an initial tempearture is
 239       given in the configuration file.
 240       @return the temperature of the fuel in degrees F IF an initial temperature
 241       is given, otherwise 32 degrees F is returned. */
 242   double GetTemperature(void) {return CelsiusToFahrenheit(Temperature);}
 243
 244   double GetIxx(void) {return Ixx;}
 245   double GetIyy(void) {return Iyy;}
 246   double GetIzz(void) {return Izz;}
 247
 248   double GetStandpipe(void) {return Standpipe;}
 249
 250   const FGColumnVector3 GetXYZ(void);
 251   const double GetXYZ(int idx);
 252
 253   double Fill(double amount);
 254   void SetContents(double amount);
 255   void SetTemperature(double temp) { Temperature = temp; }
 256   void SetStandpipe(double amount) { Standpipe = amount; }
 257
 258   enum TankType {ttUNKNOWN, ttFUEL, ttOXIDIZER};
 259   enum GrainType {gtUNKNOWN, gtCYLINDRICAL, gtENDBURNING};
 260
 261 private:
 262   TankType Type;
 263   GrainType grainType;
 264   int TankNumber;
 265   string type;
 266   string strGType;
 267   FGColumnVector3 vXYZ;
 268   FGColumnVector3 vXYZ_drain;
 269   double Capacity;
 270   double Radius;
 271   double InnerRadius;
 272   double Length;
 273   double Volume;
 274   double Density;
 275   double Ixx;
 276   double Iyy;
 277   double Izz;
 278   double PctFull;
 279   double Contents, InitialContents;
 280   double Area;
 281   double Temperature, InitialTemperature;
 282   double Standpipe, InitialStandpipe;
 283   bool  Selected;
 284   FGFDMExec* Exec;
 285   FGPropertyManager* PropertyManager;
 286   void CalculateInertias(void);
 287   void Debug(int from);
 288 };
 289 }
 290 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 291 #endif
 292