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 (jsb@hal-pc.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 <input_output/FGXMLElement.h>
  49 #include <math/FGColumnVector3.h>
  50 #include <models/FGAuxiliary.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   <location unit="{FT | M | IN}">
 113     <x> {number} </x>
 114     <y> {number} </y>
 115     <z> {number} </z>
 116   </location>
 117   <drain_location unit="{FT | M | IN}">
 118     <x> {number} </x>
 119     <y> {number} </y>
 120     <z> {number} </z>
 121   </drain_location>
 122   <radius unit="{FT | M}"> {number} </radius>
 123   <capacity unit="{LBS | KG}"> {number} </capacity>
 124   <contents unit="{LBS | KG}"> {number} </contents>
 125   <temperature> {number} </temperature> <!-- must be degrees fahrenheit -->
 126   <standpipe unit="{LBS | KG"}> {number} </standpipe>
 127 </tank>
 128 @endcode
 129
 130 <h3>Definition of the tank configuration file parameters:</h3>
 131
 132 - \b type - One of FUEL or OXIDIZER.  This is required.
 133 - \b radius - Equivalent radius of tank for modeling slosh, defaults to inches.
 134 - \b capacity - Capacity, defaults to pounds.
 135 - \b contents - Initial contents, defaults to pounds.
 136 - \b temperature - Initial temperature, defaults to degrees Fahrenheit.
 137 - \b standpipe - Minimum contents to which tank can dump, defaults to pounds.
 138
 139 location:
 140 - \b x - Location of tank on aircraft's x-axis, defaults to inches.
 141 - \b y - Location of tank on aircraft's y-axis, defaults to inches.
 142 - \b z - Location of tank on aircraft's z-axis, defaults to inches.
 143
 144 drain_location:
 145 - \b x - Location of tank drain on aircraft's x-axis, defaults to inches.
 146 - \b y - Location of tank drain on aircraft's y-axis, defaults to inches.
 147 - \b z - Location of tank drain on aircraft's z-axis, defaults to inches.
 148
 149 <h3>Default values of the tank configuration file parameters:</h3>
 150
 151 - \b type - ttUNKNOWN  (causes a load error in the propulsion configuration)
 152 - \b location, \b drain_location - both optional, but a warning message will
 153 be printed to the console if the location is not given
 154 - \b x - 0.0  (both full and drained CG locations)
 155 - \b y - 0.0  (both full and drained CG locations)
 156 - \b z - 0.0  (both full and drained CG locations)
 157 - \b radius - 0.0
 158 - \b capacity - 0.0
 159 - \b contents - 0.0
 160 - \b temperature - -9999.0
 161 - \b standpipe - 0.0
 162
 163     @author Jon Berndt, Dave Culp
 164     @see Akbar, Raza et al. "A Simple Analysis of Fuel Addition to the CWT of
 165     747", California Institute of Technology, 1998,
 166     http://www.galcit.caltech.edu/EDL/projects/JetA/reports/lumped.pdf
 167 */
 168
 169 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 170 CLASS DECLARATION
 171 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 172
 173 class FGTank : public FGJSBBase
 174 {
 175 public:
 176   /** Constructor.
 177       The constructor reads in the defining parameters from a configuration file.
 178       @param exec a pointer to the base FGFDMExec instance.
 179       @param el a pointer to the Tank element.
 180       @param tank_number the tank number (zero based).
 181   */
 182   FGTank(FGFDMExec* exec, Element* el, int tank_number);
 183   /// Destructor
 184   ~FGTank();
 185
 186   /** Removes fuel from the tank.
 187       This function removes fuel from a tank. If the tank empties, it is
 188       deselected.
 189       @param used the amount of fuel used in lbs.
 190       @return the remaining contents of the tank in lbs.
 191   */
 192   double Drain(double used);
 193
 194   /** Performs local, tanks-specific calculations, such as fuel temperature.
 195       This function calculates the temperature of the fuel in the tank.
 196       @param dt the time step for this model.
 197       @return the current temperature in degrees Celsius.
 198   */
 199   double Calculate(double dt);
 200
 201   /** Retrieves the type of tank: Fuel or Oxidizer.
 202       @return the tank type, 0 for undefined, 1 for fuel, and 2 for oxidizer.
 203   */
 204   int GetType(void) {return Type;}
 205
 206   /** Resets the tank parameters to the initial conditions */
 207   void ResetToIC(void);
 208
 209   /** If the tank is supplying fuel, this function returns true.
 210       @return true if this tank is feeding an engine.*/
 211   bool GetSelected(void) {return Selected;}
 212
 213   /** Gets the tank fill level.
 214       @return the fill level in percent, from 0 to 100.*/
 215   double GetPctFull(void) {return PctFull;}
 216
 217   /** Gets the capacity of the tank.
 218       @return the capacity of the tank in pounds. */
 219   double GetCapacity(void) {return Capacity;}
 220
 221   /** Gets the contents of the tank.
 222       @return the contents of the tank in pounds. */
 223   double GetContents(void) const {return Contents;}
 224
 225   /** Gets the temperature of the fuel.
 226       The temperature of the fuel is calculated if an initial tempearture is
 227       given in the configuration file.
 228       @return the temperature of the fuel in degrees C IF an initial temperature
 229       is given, otherwise 0.0 C is returned. */
 230   double GetTemperature_degC(void) {return Temperature;}
 231
 232   /** Gets the temperature of the fuel.
 233       The temperature of the fuel is calculated if an initial tempearture is
 234       given in the configuration file.
 235       @return the temperature of the fuel in degrees F IF an initial temperature
 236       is given, otherwise 32 degrees F is returned. */
 237   double GetTemperature(void) {return CelsiusToFahrenheit(Temperature);}
 238
 239   double GetStandpipe(void) {return Standpipe;}
 240
 241   const FGColumnVector3 GetXYZ(void);
 242   const double GetXYZ(int idx);
 243
 244   double Fill(double amount);
 245   void SetContents(double amount);
 246   void SetTemperature(double temp) { Temperature = temp; }
 247   void SetStandpipe(double amount) { Standpipe = amount; }
 248
 249   enum TankType {ttUNKNOWN, ttFUEL, ttOXIDIZER};
 250
 251 private:
 252   TankType Type;
 253   int TankNumber;
 254   string type;
 255   FGColumnVector3 vXYZ;
 256   FGColumnVector3 vXYZ_drain;
 257   double Capacity;
 258   double Radius;
 259   double PctFull;
 260   double Contents, InitialContents;
 261   double Area;
 262   double Temperature, InitialTemperature;
 263   double Standpipe, InitialStandpipe;
 264   bool  Selected;
 265   FGAuxiliary* Auxiliary;
 266   FGPropertyManager* PropertyManager;
 267   void Debug(int from);
 268 };
 269 }
 270 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 271 #endif
 272