1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
7 ------------- Copyright (C) 1999 Jon S. Berndt (jon@jsbsim.org) -------------
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
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
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.
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.
26 FUNCTIONAL DESCRIPTION
27 --------------------------------------------------------------------------------
29 Based on Flightgear code, which is based on LaRCSim. This class simulates
33 --------------------------------------------------------------------------------
36 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
38 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
43 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
45 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
47 #include "FGJSBBase.h"
48 #include "math/FGColumnVector3.h"
51 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
53 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
55 #define ID_TANK "$Id$"
57 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
59 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
64 class FGPropertyManager;
67 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
69 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
71 /** Models a fuel tank.
73 <h3>Fuel Temperature:</h3>
75 Fuel temperature is calculated using the following assumptions:
77 Fuel temperature will only be calculated for tanks which have an initial fuel
78 temperature specified in the configuration file.
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.
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.
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.
96 <h3>Fuel Transfer:</h3>
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.
105 <h3>Configuration File Format:</h3>
108 <tank type="{FUEL | OXIDIZER}">
109 <grain_config type="{CYLINDRICAL | ENDBURNING}">
110 <length unit="{IN | FT | M}"> {number} </radius>
112 <location unit="{FT | M | IN}">
117 <drain_location unit="{FT | M | IN}">
122 <radius unit="{IN | 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 <priority> {integer} </priority>
128 <density unit="{KG/L | LBS/GAL}"> {number} </density>
129 <type> {string} </type> <!-- will override previous density setting -->
133 <h3>Definition of the tank configuration file parameters:</h3>
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 - \b priority - Establishes feed sequence of tank. "1" is the highest priority.
144 - \b density - Density of liquid tank contents.
145 - \b type - Named fuel type. One of AVGAS, JET-A, JET-A1, JET-B, JP-1, JP-2, JP-3,
146 - \b JP-4, JP-5, JP-6, JP-7, JP-8, JP-8+100, RP-1, T-1, ETHANOL, HYDRAZINE,
147 - \b F-34, F-35, F-40, F-44, AVTAG, AVCAT
150 - \b x - Location of tank on aircraft's x-axis, defaults to inches.
151 - \b y - Location of tank on aircraft's y-axis, defaults to inches.
152 - \b z - Location of tank on aircraft's z-axis, defaults to inches.
155 - \b x - Location of tank drain on aircraft's x-axis, defaults to inches.
156 - \b y - Location of tank drain on aircraft's y-axis, defaults to inches.
157 - \b z - Location of tank drain on aircraft's z-axis, defaults to inches.
159 <h3>Default values of the tank configuration file parameters:</h3>
161 - \b type - ttUNKNOWN (causes a load error in the propulsion configuration)
162 - \b location, \b drain_location - both optional, but a warning message will
163 be printed to the console if the location is not given
164 - \b x - 0.0 (both full and drained CG locations)
165 - \b y - 0.0 (both full and drained CG locations)
166 - \b z - 0.0 (both full and drained CG locations)
168 - \b capacity - 0.00001 (tank capacity must not be zero)
170 - \b temperature - -9999.0 (flag which indicates no temperature is set)
171 - \b standpipe - 0.0 (all contents may be dumped)
172 - \b priority - 1 (highest feed sequence priority)
175 @author Jon Berndt, Dave Culp
176 @see Akbar, Raza et al. "A Simple Analysis of Fuel Addition to the CWT of
177 747", California Institute of Technology, 1998,
178 http://www.galcit.caltech.edu/EDL/projects/JetA/reports/lumped.pdf
181 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
183 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
185 class FGTank : public FGJSBBase
189 The constructor reads in the defining parameters from a configuration file.
190 @param exec a pointer to the base FGFDMExec instance.
191 @param el a pointer to the Tank element.
192 @param tank_number the tank number (zero based).
194 FGTank(FGFDMExec* exec, Element* el, int tank_number);
198 /** Removes fuel from the tank.
199 This function removes fuel from a tank. If the tank empties, it is
201 @param used the amount of fuel used in lbs.
202 @return the remaining contents of the tank in lbs.
204 double Drain(double used);
206 /** Performs local, tanks-specific calculations, such as fuel temperature.
207 This function calculates the temperature of the fuel in the tank.
208 @param dt the time step for this model.
209 @return the current temperature in degrees Celsius.
211 double Calculate(double dt);
213 /** Retrieves the type of tank: Fuel or Oxidizer.
214 @return the tank type, 0 for undefined, 1 for fuel, and 2 for oxidizer.
216 int GetType(void) {return Type;}
218 /** Resets the tank parameters to the initial conditions */
219 void ResetToIC(void);
221 /** If the tank is set to supply fuel, this function returns true.
222 @return true if this tank is set to a non-zero priority.*/
223 bool GetSelected(void) {return Selected;}
225 /** Gets the tank fill level.
226 @return the fill level in percent, from 0 to 100.*/
227 double GetPctFull(void) {return PctFull;}
229 /** Gets the capacity of the tank.
230 @return the capacity of the tank in pounds. */
231 double GetCapacity(void) {return Capacity;}
233 /** Gets the capacity of the tank.
234 @return the capacity of the tank in gallons. */
235 double GetCapacityGallons(void) {return Capacity/Density;}
237 /** Gets the contents of the tank.
238 @return the contents of the tank in pounds. */
239 double GetContents(void) const {return Contents;}
241 /** Gets the contents of the tank.
242 @return the contents of the tank in gallons. */
243 double GetContentsGallons(void) const {return Contents/Density;}
245 /** Gets the temperature of the fuel.
246 The temperature of the fuel is calculated if an initial tempearture is
247 given in the configuration file.
248 @return the temperature of the fuel in degrees C IF an initial temperature
249 is given, otherwise 0.0 C is returned. */
250 double GetTemperature_degC(void) {return Temperature;}
252 /** Gets the temperature of the fuel.
253 The temperature of the fuel is calculated if an initial tempearture is
254 given in the configuration file.
255 @return the temperature of the fuel in degrees F IF an initial temperature
256 is given, otherwise 32 degrees F is returned. */
257 double GetTemperature(void) {return CelsiusToFahrenheit(Temperature);}
259 /** Returns the density of a named fuel type.
260 @return the density, in lbs/gal, or 6.6 if name cannot be resolved. */
261 double ProcessFuelName(std::string const& name);
263 double GetIxx(void) {return Ixx;}
264 double GetIyy(void) {return Iyy;}
265 double GetIzz(void) {return Izz;}
267 double GetStandpipe(void) {return Standpipe;}
269 int GetPriority(void) const {return Priority;}
270 void SetPriority(int p) { Priority = p; Selected = p>0 ? true:false; }
272 double GetDensity(void) const {return Density;}
273 void SetDensity(double d) { Density = d; }
275 const FGColumnVector3 GetXYZ(void);
276 const double GetXYZ(int idx);
278 double Fill(double amount);
279 void SetContents(double amount);
280 void SetContentsGallons(double gallons);
281 void SetTemperature(double temp) { Temperature = temp; }
282 void SetStandpipe(double amount) { Standpipe = amount; }
283 void SetSelected(bool sel) { sel==true ? SetPriority(1):SetPriority(0); }
285 enum TankType {ttUNKNOWN, ttFUEL, ttOXIDIZER};
286 enum GrainType {gtUNKNOWN, gtCYLINDRICAL, gtENDBURNING};
293 std::string strGType;
294 FGColumnVector3 vXYZ;
295 FGColumnVector3 vXYZ_drain;
306 double Contents, InitialContents;
308 double Temperature, InitialTemperature;
309 double Standpipe, InitialStandpipe;
311 int Priority, InitialPriority;
313 FGPropertyManager* PropertyManager;
314 void CalculateInertias(void);
315 void Debug(int from);
318 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%