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

   1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2
   3  Header:       FGPiston.h
   4  Author:       Jon S. Berndt
   5  Date started: 09/12/2000
   6
   7  ------------- Copyright (C) 2000  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 HISTORY
  27 --------------------------------------------------------------------------------
  28 09/12/2000  JSB  Created
  29 10/01/2001  DPM  Modified to use equations from Dave Luff's piston model.
  30 11/01/2008  RKJ  Modified piston engine model for more general use.
  31 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  32 SENTRY
  33 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  34
  35 #ifndef FGPISTON_H
  36 #define FGPISTON_H
  37
  38 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  39 INCLUDES
  40 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  41
  42 #include "FGEngine.h"
  43 #include <math/FGTable.h>
  44 #include <input_output/FGXMLElement.h>
  45
  46 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  47 DEFINITIONS
  48 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  49
  50 #define ID_PISTON "$Id$";
  51 #define FG_MAX_BOOST_SPEEDS 3
  52
  53 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  54 FORWARD DECLARATIONS
  55 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  56
  57 namespace JSBSim {
  58
  59 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  60 CLASS DOCUMENTATION
  61 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  62
  63 /** Models Dave Luff's Turbo/Supercharged Piston engine model.
  64
  65 <h3>Configuration File Format:</h3>
  66
  67 @code
  68 <piston_engine name="{string}">
  69   <minmp unit="{INHG | PA | ATM}"> {number} </minmp> <!-- Depricated -->
  70   <maxmp unit="{INHG | PA | ATM}"> {number} </maxmp> <!-- Depricated -->
  71   <displacement unit="{IN3 | LTR | CC}"> {number} </displacement>
  72   <sparkfaildrop> {number} </sparkfaildrop>
  73   <maxhp unit="{HP | WATTS}"> {number} </maxhp>
  74   <cycles> {number} </cycles>
  75   <idlerpm> {number} </idlerpm>
  76   <maxrpm> {number} </maxrpm>
  77   <maxthrottle> {number} </maxthrottle>
  78   <minthrottle> {number} </minthrottle>
  79   <numboostspeeds> {number} </numboostspeeds>
  80   <bsfc unit="{LBS/HP*HR | "KG/KW*HR"}"> {number} </bsft>
  81   <volumetric_efficiency> {number} </volumetric_efficiency>
  82   <boostoverride> {0 | 1} </boostoverride>
  83   <ratedboost1 unit="{INHG | PA | ATM}"> {number} </ratedboost1>
  84   <ratedpower1 unit="{HP | WATTS}"> {number} </ratedpower1>
  85   <ratedrpm1> {number} </ratedrpm1>
  86   <ratedaltitude1 unit="{FT | M}"> {number} </ratedaltitude1>
  87   <ratedboost2 unit="{INHG | PA | ATM}"> {number} </ratedboost2>
  88   <ratedpower2 unit="{HP | WATTS}"> {number} </ratedpower2>
  89   <ratedrpm2> {number} </ratedrpm2>
  90   <ratedaltitude2 unit="{FT | M}"> {number} </ratedaltitude2>
  91   <ratedboost3 unit="{INHG | PA | ATM}"> {number} </ratedboost3>
  92   <ratedpower3 unit="{HP | WATTS}"> {number} </ratedpower3>
  93   <ratedrpm3> {number} </ratedrpm3>
  94   <ratedaltitude3 unit="{FT | M}"> {number} </ratedaltitude3>
  95   <takeoffboost unit="{INHG | PA | ATM}"> {number} </takeoffboost>
  96 </piston_engine>
  97 @endcode
  98
  99 <pre>
 100     Additional elements are required for a supercharged engine.  These can be
 101     left off a non-supercharged engine, ie. the changes are all backward
 102     compatible at present.
 103
 104     - NUMBOOSTSPEEDS - zero (or not present) for a naturally-aspirated engine,
 105       either 1, 2 or 3 for a boosted engine.  This corresponds to the number of
 106       supercharger speeds.  Merlin XII had 1 speed, Merlin 61 had 2, a late
 107       Griffon engine apparently had 3.  No known engine more than 3, although
 108       some German engines apparently had a continuously variable-speed
 109       supercharger.
 110
 111     - BOOSTOVERRIDE - whether the boost pressure control system (either a boost
 112       control valve for superchargers or wastegate for turbochargers) can be
 113       overriden by the pilot.  During wartime this was commonly possible, and
 114       known as "War Emergency Power" by the Brits.  1 or 0 in the config file.
 115       This isn't implemented in the model yet though, there would need to be
 116       some way of getting the boost control cutout lever position (on or off)
 117       from FlightGear first.
 118
 119     - The next items are all appended with either 1, 2 or 3 depending on which
 120       boost speed they refer to, eg RATEDBOOST1.  The rated values seems to have
 121       been a common convention at the time to express the maximum continuously
 122       available power, and the conditions to attain that power.
 123
 124     - RATEDBOOST[123] - the absolute rated boost above sea level ambient for a
 125       given boost speed, in psi.  Eg the Merlin XII had a rated boost of 9psi,
 126       giving approximately 42inHg manifold pressure up to the rated altitude.
 127
 128     - RATEDALTITUDE[123] - The altitude up to which rated boost can be
 129       maintained.  Up to this altitude the boost is maintained constant for a
 130       given throttle position by the BCV or wastegate.  Beyond this altitude the
 131       manifold pressure must drop, since the supercharger is now at maximum
 132       unregulated output.  The actual pressure multiplier of the supercharger
 133       system is calculated at initialisation from this value.
 134
 135     - RATEDPOWER[123] - The power developed at rated boost at rated altitude at
 136       rated rpm.
 137
 138     - RATEDRPM[123] - The rpm at which rated power is developed.
 139
 140     - TAKEOFFBOOST - Takeoff boost in psi above ambient.  Many aircraft had an
 141       extra boost setting beyond rated boost, but not totally uncontrolled as in
 142       the already mentioned boost-control-cutout, typically attained by pushing
 143       the throttle past a mechanical 'gate' preventing its inadvertant use. This
 144       was typically used for takeoff, and emergency situations, generally for
 145       not more than five minutes.  This is a change in the boost control
 146       setting, not the actual supercharger speed, and so would only give extra
 147       power below the rated altitude.  When TAKEOFFBOOST is specified in the
 148       config file (and is above RATEDBOOST1), then the throttle position is
 149       interpreted as:
 150
 151     - 0 to 0.95 : idle manifold pressure to rated boost (where attainable)
 152     - 0.96, 0.97, 0.98 : rated boost (where attainable).
 153     - 0.99, 1.0 : takeoff boost (where attainable).
 154
 155     A typical takeoff boost for an earlyish Merlin was about 12psi, compared
 156     with a rated boost of 9psi.
 157
 158     It is quite possible that other boost control settings could have been used
 159     on some aircraft, or that takeoff/extra boost could have activated by other
 160     means than pushing the throttle full forward through a gate, but this will
 161     suffice for now.
 162
 163     Note that MAXMP is still the non-boosted max manifold pressure even for
 164     boosted engines - effectively this is simply a measure of the pressure drop
 165     through the fully open throttle.
 166 </pre>
 167
 168     @author Jon S. Berndt (Engine framework code and framework-related mods)
 169     @author Dave Luff (engine operational code)
 170     @author David Megginson (initial porting and additional code)
 171     @author Ron Jensen (additional engine code)
 172     @version $Id$
 173   */
 174
 175 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 176 CLASS DECLARATION
 177 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 178
 179 class FGPiston : public FGEngine
 180 {
 181 public:
 182   /// Constructor
 183   FGPiston(FGFDMExec* exec, Element* el, int engine_number);
 184   /// Destructor
 185   ~FGPiston();
 186
 187   string GetEngineLabels(string delimeter);
 188   string GetEngineValues(string delimeter);
 189
 190   double Calculate(void);
 191   double GetPowerAvailable(void) {return PowerAvailable;}
 192   double CalcFuelNeed(void);
 193
 194   void ResetToIC(void);
 195   void SetMagnetos(int magnetos) {Magnetos = magnetos;}
 196
 197   double  GetEGT(void) { return EGT_degC; }
 198   int     GetMagnetos(void) {return Magnetos;}
 199
 200   double getExhaustGasTemp_degF(void) {return KelvinToFahrenheit(ExhaustGasTemp_degK);}
 201   double getManifoldPressure_inHg(void) const {return ManifoldPressure_inHg;}
 202   double getCylinderHeadTemp_degF(void) {return KelvinToFahrenheit(CylinderHeadTemp_degK);}
 203   double getOilPressure_psi(void) const {return OilPressure_psi;}
 204   double getOilTemp_degF (void) {return KelvinToFahrenheit(OilTemp_degK);}
 205   double getRPM(void) {return RPM;}
 206
 207 protected:
 208   double ThrottleAngle;
 209
 210 private:
 211   int crank_counter;
 212
 213   double BrakeHorsePower;
 214   double SpeedSlope;
 215   double SpeedIntercept;
 216   double AltitudeSlope;
 217   double PowerAvailable;
 218
 219   // timestep
 220   double dt;
 221
 222   void doEngineStartup(void);
 223   void doBoostControl(void);
 224   void doMAP(void);
 225   void doAirFlow(void);
 226   void doFuelFlow(void);
 227   void doEnginePower(void);
 228   void doEGT(void);
 229   void doCHT(void);
 230   void doOilPressure(void);
 231   void doOilTemperature(void);
 232
 233   int InitRunning(void);
 234
 235   //
 236   // constants
 237   //
 238
 239   const double R_air;
 240   const double rho_fuel;    // kg/m^3
 241   const double calorific_value_fuel;  // W/Kg (approximate)
 242   const double Cp_air;      // J/KgK
 243   const double Cp_fuel;     // J/KgK
 244
 245   FGTable *Lookup_Combustion_Efficiency;
 246   FGTable *Power_Mixture_Correlation;
 247   FGTable *Mixture_Efficiency_Correlation;
 248
 249   //
 250   // Configuration
 251   //
 252   double MinManifoldPressure_inHg; // Inches Hg
 253   double MaxManifoldPressure_inHg; // Inches Hg
 254   double MaxManifoldPressure_Percent; // MaxManifoldPressure / 29.92
 255   double Displacement;             // cubic inches
 256   double MaxHP;                    // horsepower
 257   double SparkFailDrop;            // drop of power due to spark failure
 258   double Cycles;                   // cycles/power stroke
 259   double IdleRPM;                  // revolutions per minute
 260   double MaxRPM;                   // revolutions per minute
 261   double StarterHP;                // initial horsepower of starter motor
 262   int BoostSpeeds;      // Number of super/turbocharger boost speeds - zero implies no turbo/supercharging.
 263   int BoostSpeed;       // The current boost-speed (zero-based).
 264   bool Boosted;         // Set true for boosted engine.
 265   int BoostOverride;    // The raw value read in from the config file - should be 1 or 0 - see description below.
 266   bool bBoostOverride;  // Set true if pilot override of the boost regulator was fitted.
 267               // (Typically called 'war emergency power').
 268   bool bTakeoffBoost;   // Set true if extra takeoff / emergency boost above rated boost could be attained.
 269               // (Typically by extra throttle movement past a mechanical 'gate').
 270   double TakeoffBoost;  // Sea-level takeoff boost in psi. (if fitted).
 271   double RatedBoost[FG_MAX_BOOST_SPEEDS];       // Sea-level rated boost in psi.
 272   double RatedAltitude[FG_MAX_BOOST_SPEEDS];    // Altitude at which full boost is reached (boost regulation ends)
 273                           // and at which power starts to fall with altitude [ft].
 274   double RatedRPM[FG_MAX_BOOST_SPEEDS]; // Engine speed at which the rated power for each boost speed is delivered [rpm].
 275   double RatedPower[FG_MAX_BOOST_SPEEDS];       // Power at rated throttle position at rated altitude [HP].
 276   double BoostSwitchAltitude[FG_MAX_BOOST_SPEEDS - 1];  // Altitude at which switchover (currently assumed automatic)
 277                               // from one boost speed to next occurs [ft].
 278   double BoostSwitchPressure[FG_MAX_BOOST_SPEEDS - 1];  // Pressure at which boost speed switchover occurs [Pa]
 279   double BoostMul[FG_MAX_BOOST_SPEEDS]; // Pressure multipier of unregulated supercharger
 280   double RatedMAP[FG_MAX_BOOST_SPEEDS]; // Rated manifold absolute pressure [Pa] (BCV clamp)
 281   double TakeoffMAP[FG_MAX_BOOST_SPEEDS];       // Takeoff setting manifold absolute pressure [Pa] (BCV clamp)
 282   double BoostSwitchHysteresis; // Pa.
 283
 284   double minMAP;  // Pa
 285   double maxMAP;  // Pa
 286   double MAP;     // Pa
 287   double BSFC;    // brake specific fuel consumption [lbs/horsepower*hour
 288
 289   //
 290   // Inputs (in addition to those in FGEngine).
 291   //
 292   double p_amb;              // Pascals
 293   double p_amb_sea_level;    // Pascals
 294   double T_amb;              // degrees Kelvin
 295   double RPM;                // revolutions per minute
 296   double IAS;                // knots
 297   bool Magneto_Left;
 298   bool Magneto_Right;
 299   int Magnetos;
 300
 301
 302   //
 303   // Outputs (in addition to those in FGEngine).
 304   //
 305   double rho_air;
 306   double volumetric_efficiency;
 307   double map_coefficient;
 308   double m_dot_air;
 309   double equivalence_ratio;
 310   double m_dot_fuel;
 311   double Percentage_Power;
 312   double HP;
 313   double combustion_efficiency;
 314   double ExhaustGasTemp_degK;
 315   double EGT_degC;
 316   double ManifoldPressure_inHg;
 317   double CylinderHeadTemp_degK;
 318   double OilPressure_psi;
 319   double OilTemp_degK;
 320
 321   void Debug(int from);
 322 };
 323 }
 324 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 325 #endif