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