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.32 2011/10/11 16:16:16 jentron 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 a Supercharged Piston engine. Based on Dave Luff's 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   <idlerpm> {number} </idlerpm>
  71   <maxrpm> {number} </maxrpm>
  72   <maxhp unit="{HP | WATTS}"> {number} </maxhp>
  73   <displacement unit="{IN3 | LTR | CC}"> {number} </displacement>
  74   <cycles> {number} </cycles>
  75   <bore unit="{IN | M}"> {number} </bore>
  76   <stroke unit="{IN | M}"> {number} </stroke>
  77   <cylinders> {number} </cylinders>
  78   <compression-ratio> {number} </compression-ratio>
  79   <sparkfaildrop> {number} </sparkfaildrop>
  80   <static-friction unit="{HP | WATTS}"> {number} </static-friction>
  81   <air-intake-impedance-factor> {number} </air-intake-impedance-factor>
  82   <ram-air-factor> {number} </ram-air-factor>
  83   <cooling-factor> {number} </cooling-factor>
  84   <cylinder-head-mass unit="{KG | LBS}"> {number} </cylinder-head-mass>
  85   <bsfc unit="{LBS/HP*HR | "KG/KW*HR"}"> {number} </bsfc>
  86   <volumetric-efficiency> {number} </volumetric-efficiency>
  87   <dynamic-fmep unit="{INHG | PA | ATM}"> {number} </dynamic-fmep>
  88   <static-fmep unit="{INHG | PA | ATM}"> {number} </static-fmep>
  89   <numboostspeeds> {number} </numboostspeeds>
  90   <boostoverride> {0 | 1} </boostoverride>
  91   <boostmanual> {0 | 1} </boostmanual>
  92   <ratedboost1 unit="{INHG | PA | ATM}"> {number} </ratedboost1>
  93   <ratedpower1 unit="{HP | WATTS}"> {number} </ratedpower1>
  94   <ratedrpm1> {number} </ratedrpm1>
  95   <ratedaltitude1 unit="{FT | M}"> {number} </ratedaltitude1>
  96   <ratedboost2 unit="{INHG | PA | ATM}"> {number} </ratedboost2>
  97   <ratedpower2 unit="{HP | WATTS}"> {number} </ratedpower2>
  98   <ratedrpm2> {number} </ratedrpm2>
  99   <ratedaltitude2 unit="{FT | M}"> {number} </ratedaltitude2>
 100   <ratedboost3 unit="{INHG | PA | ATM}"> {number} </ratedboost3>
 101   <ratedpower3 unit="{HP | WATTS}"> {number} </ratedpower3>
 102   <ratedrpm3> {number} </ratedrpm3>
 103   <ratedaltitude3 unit="{FT | M}"> {number} </ratedaltitude3>
 104   <takeoffboost unit="{INHG | PA | ATM}"> {number} </takeoffboost>
 105 </piston_engine>
 106 @endcode
 107
 108 <h3>Definition of the piston engine configuration file parameters:</h3>
 109 Basic parameters:
 110 - \b minmp - this value is the nominal idle manifold pressure at sea-level
 111       without boost. Along with idlerpm, it determines throttle response slope.
 112 - \b maxmp - this value is the nominal maximum manifold pressure at sea-level
 113       without boost. Along with maxrpm it determines the resistance of the
 114       aircraft intake system. Overridden by air-intake-impedance-factor
 115 - \b idlerpm - this value affects the throttle fall off and the engine stops
 116       running if it is slowed below 80% of this value. The engine starts
 117       running when it reaches 80% of this value.
 118 - \b maxrpm - this value is used to calculate air-box resistance and BSFC. It
 119       also affects oil pressure among other things.
 120 - \b maxhp - this value is the nominal power the engine creates at maxrpm. It
 121       will determine bsfc if that tag is not input. It also determines the
 122       starter motor power.
 123 - \b displacement - this value is used to determine mass air and fuel flow
 124       which impacts engine power and cooling.
 125 - \b cycles - Designate a 2 or 4 stroke engine. Currently only the 4 stroke
 126       engine is supported.
 127 - \b bore - cylinder bore is currently unused.
 128 - \b stroke - piston stroke is used to determine the mean piston speed. Longer
 129       strokes result in an engine that does not work as well at higher RPMs.
 130 - \b compression-ratio - the compression ratio affects the change in volumetric
 131       efficiency with altitude.
 132 - \b sparkfaildrop - this is the percentage drop in horsepower for single
 133       magneto operation.
 134 - \b static-friction - this value is the power required to turn an engine that
 135       is not running. Used to control and slow a windmilling propeller. Choose
 136       a small percentage of maxhp.
 137
 138 Advanced parameters
 139 - \b bsfc - Indicated Specific Fuel Consumption. The power produced per unit of
 140       fuel. Higher numbers give worse fuel economy. This number may need to be
 141       lowered slightly from actual BSFC numbers because some internal engine
 142       losses are modeled separately. Typically between 0.3 and 0.5
 143 - \b volumetric-efficiency - the nominal volumetric efficiency of the engine.
 144       This is the primary way to control fuel flow  Boosted engines may require
 145       values above 1. Typical engines are 0.80 to 0.82
 146 - \b air-intake-impedance-factor - this number is the pressure drop across the
 147       intake system. Increasing it reduces available manifold pressure. Also a
 148       property for run-time adjustment.
 149 - \b ram-air-factor - this number creates increases manifold pressure with an
 150       increase in dynamic pressure (aircraft speed).
 151       Also a property for run-time adjustment.
 152
 153 Cooling control:
 154 - \b cylinders  - number of cylinders scales the cylinder head mass.
 155 - \b cylinder-head-mass - the nominal mass of a cylinder head. A larger value
 156       slows changes in engine temperature
 157 - \b cooling-factor - this number models the efficiency of the aircraft cooling
 158       system. Also a property for run-time adjustment.
 159
 160 Supercharge parameters:
 161 - \b numboostspeed -  zero (or not present) for a naturally-aspirated engine,
 162       either 1, 2 or 3 for a boosted engine.  This corresponds to the number of
 163       supercharger speeds.  Merlin XII had 1 speed, Merlin 61 had 2, a late
 164       Griffon engine apparently had 3.  No known engine more than 3, although
 165       some German engines had continuously variable-speed superchargers.
 166 - \b boostoverride - unused
 167 - \b boostmanual - whether a multispeed supercharger will manually or
 168       automatically shift boost speeds. On manual shifting the boost speeds is
 169       accomplished by controlling the property propulsion/engine/boostspeed.
 170 - \b takeoffboost - boost in psi above sea level ambient. Typically used for
 171       takeoff, and emergency situations, generally for not more than five
 172       minutes.  This is a change in the boost control setting, not the actual
 173       supercharger speed, and so would only give extra power below the rated altitude.
 174       A typical takeoff boost for an early Merlin was about 12psi, compared
 175       with a rated boost of 9psi.
 176
 177       When TAKEOFFBOOST is specified in the config file (and is above RATEDBOOST1),
 178       the throttle position is interpreted as:
 179      - 0 to 0.98 : idle manifold pressure to rated boost (where attainable)
 180      - 0.99, 1.0 : takeoff boost (where attainable).
 181
 182 The next items are all appended with either 1, 2 or 3 depending on which
 183 boostspeed they refer to:
 184 - \b ratedboost[123] - the absolute rated boost above sea level ambient
 185       (14.7 PSI, 29.92 inHg) for a given boost speed.
 186
 187 - \b ratedpower[123] - unused
 188 - \b ratedrpm[123] - The rpm at which rated boost is developed
 189 - \b ratedaltitude[123] - The altitude up to which the rated boost can be
 190       maintained. Up to this altitude the boost is clipped to rated boost or
 191       takeoffboost. Beyond this altitude the manifold pressure must drop,
 192       since the supercharger is now at maximum unregulated output. The actual
 193       pressure multiplier of the supercharger system is calculated at
 194       initialization from this value.
 195
 196     @author Jon S. Berndt (Engine framework code and framework-related mods)
 197     @author Dave Luff (engine operational code)
 198     @author David Megginson (initial porting and additional code)
 199     @author Ron Jensen (additional engine code)
 200     @see Taylor, Charles Fayette, "The Internal Combustion Engine in Theory and Practice"
 201     @version $Id: FGPiston.h,v 1.32 2011/10/11 16:16:16 jentron Exp $
 202   */
 203
 204 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 205 CLASS DECLARATION
 206 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 207
 208 class FGPiston : public FGEngine
 209 {
 210 public:
 211   /// Constructor
 212   FGPiston(FGFDMExec* exec, Element* el, int engine_number, struct Inputs& input);
 213   /// Destructor
 214   ~FGPiston();
 215
 216   std::string GetEngineLabels(const std::string& delimiter);
 217   std::string GetEngineValues(const std::string& delimiter);
 218
 219   void Calculate(void);
 220   double GetPowerAvailable(void) const {return (HP * hptoftlbssec);}
 221   double CalcFuelNeed(void);
 222
 223   void ResetToIC(void);
 224   void SetMagnetos(int magnetos) {Magnetos = magnetos;}
 225
 226   double  GetEGT(void) const { return EGT_degC; }
 227   int     GetMagnetos(void) const {return Magnetos;}
 228
 229   double getExhaustGasTemp_degF(void) const {return KelvinToFahrenheit(ExhaustGasTemp_degK);}
 230   double getManifoldPressure_inHg(void) const {return ManifoldPressure_inHg;}
 231   double getCylinderHeadTemp_degF(void) const {return KelvinToFahrenheit(CylinderHeadTemp_degK);}
 232   double getOilPressure_psi(void) const {return OilPressure_psi;}
 233   double getOilTemp_degF (void) const {return KelvinToFahrenheit(OilTemp_degK);}
 234   double getRPM(void) const {return RPM;}
 235
 236 protected:
 237
 238 private:
 239   int crank_counter;
 240
 241   double IndicatedHorsePower;
 242   double PMEP;
 243   double FMEP;
 244   double FMEPDynamic;
 245   double FMEPStatic;
 246
 247   void doEngineStartup(void);
 248   void doBoostControl(void);
 249   void doMAP(void);
 250   void doAirFlow(void);
 251   void doFuelFlow(void);
 252   void doEnginePower(void);
 253   void doEGT(void);
 254   void doCHT(void);
 255   void doOilPressure(void);
 256   void doOilTemperature(void);
 257   double GetStdPressure100K(double altitude) const;
 258
 259   int InitRunning(void);
 260
 261   //
 262   // constants
 263   //
 264
 265   const double R_air;
 266   const double rho_fuel;    // kg/m^3
 267   const double calorific_value_fuel;  // J/Kg (approximate)
 268   const double Cp_air;      // J/KgK
 269   const double Cp_fuel;     // J/KgK
 270   const double standard_pressure; //Pa
 271
 272
 273   FGTable *Lookup_Combustion_Efficiency;
 274   FGTable *Mixture_Efficiency_Correlation;
 275
 276   //
 277   // Configuration
 278   //
 279   double MinManifoldPressure_inHg; // Inches Hg
 280   double MaxManifoldPressure_inHg; // Inches Hg
 281   double MaxManifoldPressure_Percent; // MaxManifoldPressure / 29.92
 282   double Displacement;             // cubic inches
 283   double displacement_SI;          // cubic meters
 284   double MaxHP;                    // horsepower
 285   double StaticFriction_HP;        // horsepower: amount subtracted from final engine power
 286   double SparkFailDrop;            // drop of power due to spark failure
 287   double Cycles;                   // cycles/power stroke
 288   double IdleRPM;                  // revolutions per minute
 289   double MaxRPM;                   // revolutions per minute
 290   double Bore;                     // inches
 291   double Stroke;                   // inches
 292   double Cylinders;                // number
 293   double CylinderHeadMass;         // kilograms
 294   double CompressionRatio;         // number
 295   double Z_airbox; // number representing intake impediance before the throttle
 296   double Z_throttle; // number representing slope of throttle impediance
 297   double PeakMeanPistonSpeed_fps; // ft/sec speed where intake valves begin to choke. Typically 33-50 fps
 298   double RatedMeanPistonSpeed_fps; // ft/sec derived from MaxRPM and stroke.
 299   double Ram_Air_Factor;           // number
 300
 301   double StarterHP;                // initial horsepower of starter motor
 302   int BoostSpeeds;  // Number of super/turbocharger boost speeds - zero implies no turbo/supercharging.
 303   int BoostSpeed;   // The current boost-speed (zero-based).
 304   bool Boosted;     // Set true for boosted engine.
 305   int BoostManual;  // The raw value read in from the config file - should be 1 or 0 - see description below.
 306   bool bBoostManual;    // Set true if pilot must manually control the boost speed.
 307   int BoostOverride;    // The raw value read in from the config file - should be 1 or 0 - see description below.
 308   bool bBoostOverride;  // Set true if pilot override of the boost regulator was fitted.
 309               // (Typically called 'war emergency power').
 310   bool bTakeoffBoost;   // Set true if extra takeoff / emergency boost above rated boost could be attained.
 311               // (Typically by extra throttle movement past a mechanical 'gate').
 312   double TakeoffBoost;  // Sea-level takeoff boost in psi. (if fitted).
 313   double RatedBoost[FG_MAX_BOOST_SPEEDS];   // Sea-level rated boost in psi.
 314   double RatedAltitude[FG_MAX_BOOST_SPEEDS];    // Altitude at which full boost is reached (boost regulation ends)
 315                           // and at which power starts to fall with altitude [ft].
 316   double RatedRPM[FG_MAX_BOOST_SPEEDS]; // Engine speed at which the rated power for each boost speed is delivered [rpm].
 317   double RatedPower[FG_MAX_BOOST_SPEEDS];   // Power at rated throttle position at rated altitude [HP].
 318   double BoostSwitchAltitude[FG_MAX_BOOST_SPEEDS - 1];  // Altitude at which switchover (currently assumed automatic)
 319                               // from one boost speed to next occurs [ft].
 320   double BoostSwitchPressure[FG_MAX_BOOST_SPEEDS - 1];  // Pressure at which boost speed switchover occurs [Pa]
 321   double BoostMul[FG_MAX_BOOST_SPEEDS]; // Pressure multipier of unregulated supercharger
 322   double RatedMAP[FG_MAX_BOOST_SPEEDS]; // Rated manifold absolute pressure [Pa] (BCV clamp)
 323   double TakeoffMAP[FG_MAX_BOOST_SPEEDS];   // Takeoff setting manifold absolute pressure [Pa] (BCV clamp)
 324   double BoostSwitchHysteresis; // Pa.
 325
 326   double minMAP;  // Pa
 327   double maxMAP;  // Pa
 328   double MAP;     // Pa
 329   double TMAP;    // Pa - throttle manifold pressure e.g. before the supercharger boost
 330   double ISFC;    // Indicated specific fuel consumption [lbs/horsepower*hour
 331
 332   //
 333   // Inputs (in addition to those in FGEngine).
 334   //
 335   double TotalDeltaT;        // Time in seconds between calls.
 336   double p_amb;              // Pascals
 337   double p_ram;              // Pascals
 338   double T_amb;              // degrees Kelvin
 339   double RPM;                // revolutions per minute
 340   double IAS;                // knots
 341   double Cooling_Factor;     // normal
 342   bool Magneto_Left;
 343   bool Magneto_Right;
 344   int Magnetos;
 345
 346   //
 347   // Outputs (in addition to those in FGEngine).
 348   //
 349   double rho_air;
 350   double volumetric_efficiency;
 351   double map_coefficient;
 352   double m_dot_air;
 353   double equivalence_ratio;
 354   double m_dot_fuel;
 355   double HP;
 356   double combustion_efficiency;
 357   double ExhaustGasTemp_degK;
 358   double EGT_degC;
 359   double ManifoldPressure_inHg;
 360   double CylinderHeadTemp_degK;
 361   double OilPressure_psi;
 362   double OilTemp_degK;
 363   double MeanPistonSpeed_fps;
 364
 365   void Debug(int from);
 366 };
 367 }
 368 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 369 #endif