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