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.26 2011/03/10 01:35:25 dpculp 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.26 2011/03/10 01:35:25 dpculp 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 (HP * hptoftlbssec);}
 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
 231   // timestep
 232   double dt;
 233
 234   void doEngineStartup(void);
 235   void doBoostControl(void);
 236   void doMAP(void);
 237   void doAirFlow(void);
 238   void doFuelFlow(void);
 239   void doEnginePower(void);
 240   void doEGT(void);
 241   void doCHT(void);
 242   void doOilPressure(void);
 243   void doOilTemperature(void);
 244
 245   int InitRunning(void);
 246
 247   //
 248   // constants
 249   //
 250
 251   const double R_air;
 252   const double rho_fuel;    // kg/m^3
 253   const double calorific_value_fuel;  // W/Kg (approximate)
 254   const double Cp_air;      // J/KgK
 255   const double Cp_fuel;     // J/KgK
 256   const double standard_pressure; //Pa
 257
 258
 259   FGTable *Lookup_Combustion_Efficiency;
 260   FGTable *Mixture_Efficiency_Correlation;
 261
 262   //
 263   // Configuration
 264   //
 265   double MinManifoldPressure_inHg; // Inches Hg
 266   double MaxManifoldPressure_inHg; // Inches Hg
 267   double MaxManifoldPressure_Percent; // MaxManifoldPressure / 29.92
 268   double Displacement;             // cubic inches
 269   double displacement_SI;          // cubic meters
 270   double MaxHP;                    // horsepower
 271   double SparkFailDrop;            // drop of power due to spark failure
 272   double Cycles;                   // cycles/power stroke
 273   double IdleRPM;                  // revolutions per minute
 274   double MaxRPM;                   // revolutions per minute
 275   double Bore;                     // inches
 276   double Stroke;                   // inches
 277   double Cylinders;                // number
 278   double CylinderHeadMass;         // kilograms
 279   double CompressionRatio;         // number
 280   double Z_airbox; // number representing intake impediance before the throttle
 281   double Z_throttle; // number representing slope of throttle impediance
 282   double PeakMeanPistonSpeed_fps; // ft/sec speed where intake valves begin to choke. Typically 33-50 fps
 283   double RatedMeanPistonSpeed_fps; // ft/sec derived from MaxRPM and stroke.
 284   double Ram_Air_Factor;           // number
 285
 286   double StarterHP;                // initial horsepower of starter motor
 287   int BoostSpeeds;      // Number of super/turbocharger boost speeds - zero implies no turbo/supercharging.
 288   int BoostSpeed;       // The current boost-speed (zero-based).
 289   bool Boosted;         // Set true for boosted engine.
 290   int BoostManual;      // The raw value read in from the config file - should be 1 or 0 - see description below.
 291   bool bBoostManual;    // Set true if pilot must manually control the boost speed.
 292   int BoostOverride;    // The raw value read in from the config file - should be 1 or 0 - see description below.
 293   bool bBoostOverride;  // Set true if pilot override of the boost regulator was fitted.
 294               // (Typically called 'war emergency power').
 295   bool bTakeoffBoost;   // Set true if extra takeoff / emergency boost above rated boost could be attained.
 296               // (Typically by extra throttle movement past a mechanical 'gate').
 297   double TakeoffBoost;  // Sea-level takeoff boost in psi. (if fitted).
 298   double RatedBoost[FG_MAX_BOOST_SPEEDS];       // Sea-level rated boost in psi.
 299   double RatedAltitude[FG_MAX_BOOST_SPEEDS];    // Altitude at which full boost is reached (boost regulation ends)
 300                           // and at which power starts to fall with altitude [ft].
 301   double RatedRPM[FG_MAX_BOOST_SPEEDS]; // Engine speed at which the rated power for each boost speed is delivered [rpm].
 302   double RatedPower[FG_MAX_BOOST_SPEEDS];       // Power at rated throttle position at rated altitude [HP].
 303   double BoostSwitchAltitude[FG_MAX_BOOST_SPEEDS - 1];  // Altitude at which switchover (currently assumed automatic)
 304                               // from one boost speed to next occurs [ft].
 305   double BoostSwitchPressure[FG_MAX_BOOST_SPEEDS - 1];  // Pressure at which boost speed switchover occurs [Pa]
 306   double BoostMul[FG_MAX_BOOST_SPEEDS]; // Pressure multipier of unregulated supercharger
 307   double RatedMAP[FG_MAX_BOOST_SPEEDS]; // Rated manifold absolute pressure [Pa] (BCV clamp)
 308   double TakeoffMAP[FG_MAX_BOOST_SPEEDS];       // Takeoff setting manifold absolute pressure [Pa] (BCV clamp)
 309   double BoostSwitchHysteresis; // Pa.
 310
 311   double minMAP;  // Pa
 312   double maxMAP;  // Pa
 313   double MAP;     // Pa
 314   double TMAP;    // Pa - throttle manifold pressure e.g. before the supercharger boost
 315   double ISFC;    // Indicated specific fuel consumption [lbs/horsepower*hour
 316
 317   //
 318   // Inputs (in addition to those in FGEngine).
 319   //
 320   double p_amb;              // Pascals
 321   double p_ram;              // Pascals
 322   double T_amb;              // degrees Kelvin
 323   double RPM;                // revolutions per minute
 324   double IAS;                // knots
 325   double Cooling_Factor;     // normal
 326   bool Magneto_Left;
 327   bool Magneto_Right;
 328   int Magnetos;
 329
 330   //
 331   // Outputs (in addition to those in FGEngine).
 332   //
 333   double rho_air;
 334   double volumetric_efficiency;
 335   double map_coefficient;
 336   double m_dot_air;
 337   double equivalence_ratio;
 338   double m_dot_fuel;
 339   double HP;
 340   double combustion_efficiency;
 341   double ExhaustGasTemp_degK;
 342   double EGT_degC;
 343   double ManifoldPressure_inHg;
 344   double CylinderHeadTemp_degK;
 345   double OilPressure_psi;
 346   double OilTemp_degK;
 347   double MeanPistonSpeed_fps;
 348
 349   void Debug(int from);
 350 };
 351 }
 352 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 353 #endif