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 #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>
  71   <displacement unit="{IN3 | LTR | CC}"> {number} </displacement>
  72   <bore unit="{IN | M}"> {number} </bore>
  73   <stroke unit="{IN | M}"> {number} </stroke>
  74   <cylinders> {number} </cylinders>
  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   <numboostspeeds> {number} </numboostspeeds>
  86   <boostoverride> {0 | 1} </boostoverride>
  87   <boostmanual> {0 | 1} </boostmanual>
  88   <ratedboost1 unit="{INHG | PA | ATM}"> {number} </ratedboost1>
  89   <ratedpower1 unit="{HP | WATTS}"> {number} </ratedpower1>
  90   <ratedrpm1> {number} </ratedrpm1>
  91   <ratedaltitude1 unit="{FT | M}"> {number} </ratedaltitude1>
  92   <ratedboost2 unit="{INHG | PA | ATM}"> {number} </ratedboost2>
  93   <ratedpower2 unit="{HP | WATTS}"> {number} </ratedpower2>
  94   <ratedrpm2> {number} </ratedrpm2>
  95   <ratedaltitude2 unit="{FT | M}"> {number} </ratedaltitude2>
  96   <ratedboost3 unit="{INHG | PA | ATM}"> {number} </ratedboost3>
  97   <ratedpower3 unit="{HP | WATTS}"> {number} </ratedpower3>
  98   <ratedrpm3> {number} </ratedrpm3>
  99   <ratedaltitude3 unit="{FT | M}"> {number} </ratedaltitude3>
 100   <takeoffboost unit="{INHG | PA | ATM}"> {number} </takeoffboost>
 101   <air-intake-impedance-factor> {number} </air-intake-impedance-factor>
 102   <ram-air-factor> {number} </ram-air-factor>
 103 </piston_engine>
 104 @endcode
 105
 106 <pre>
 107     Additional elements are required for a supercharged engine.  These can be
 108     left off a non-supercharged engine, ie. the changes are all backward
 109     compatible at present.
 110
 111     - NUMBOOSTSPEEDS - zero (or not present) for a naturally-aspirated engine,
 112       either 1, 2 or 3 for a boosted engine.  This corresponds to the number of
 113       supercharger speeds.  Merlin XII had 1 speed, Merlin 61 had 2, a late
 114       Griffon engine apparently had 3.  No known engine more than 3, although
 115       some German engines apparently had a continuously variable-speed
 116       supercharger.
 117
 118     - BOOSTOVERRIDE - whether the boost pressure control system (either a boost
 119       control valve for superchargers or wastegate for turbochargers) can be
 120       overriden by the pilot.  During wartime this was commonly possible, and
 121       known as "War Emergency Power" by the Brits.  1 or 0 in the config file.
 122       This isn't implemented in the model yet though, there would need to be
 123       some way of getting the boost control cutout lever position (on or off)
 124       from FlightGear first.
 125
 126     - BOOSTMANUAL - whether a multispeed supercharger will manually or
 127       automatically shift boost speeds.  On manual shifting the boost speeds
 128       is accomplished by controling propulsion/engine/boostspeed
 129
 130     - The next items are all appended with either 1, 2 or 3 depending on which
 131       boost speed they refer to, eg RATEDBOOST1.  The rated values seems to have
 132       been a common convention at the time to express the maximum continuously
 133       available power, and the conditions to attain that power.
 134
 135     - RATEDBOOST[123] - the absolute rated boost above sea level ambient for a
 136       given boost speed, in psi.  Eg the Merlin XII had a rated boost of 9psi,
 137       giving approximately 42inHg manifold pressure up to the rated altitude.
 138
 139     - RATEDALTITUDE[123] - The altitude up to which rated boost can be
 140       maintained.  Up to this altitude the boost is maintained constant for a
 141       given throttle position by the BCV or wastegate.  Beyond this altitude the
 142       manifold pressure must drop, since the supercharger is now at maximum
 143       unregulated output.  The actual pressure multiplier of the supercharger
 144       system is calculated at initialisation from this value.
 145
 146     - RATEDPOWER[123] - The power developed at rated boost at rated altitude at
 147       rated rpm.
 148
 149     - RATEDRPM[123] - The rpm at which rated power is developed.
 150
 151     - TAKEOFFBOOST - Takeoff boost in psi above ambient.  Many aircraft had an
 152       extra boost setting beyond rated boost, but not totally uncontrolled as in
 153       the already mentioned boost-control-cutout, typically attained by pushing
 154       the throttle past a mechanical 'gate' preventing its inadvertant use. This
 155       was typically used for takeoff, and emergency situations, generally for
 156       not more than five minutes.  This is a change in the boost control
 157       setting, not the actual supercharger speed, and so would only give extra
 158       power below the rated altitude.  When TAKEOFFBOOST is specified in the
 159       config file (and is above RATEDBOOST1), then the throttle position is
 160       interpreted as:
 161
 162     - 0 to 0.95 : idle manifold pressure to rated boost (where attainable)
 163     - 0.96, 0.97, 0.98 : rated boost (where attainable).
 164     - 0.99, 1.0 : takeoff boost (where attainable).
 165
 166     A typical takeoff boost for an earlyish Merlin was about 12psi, compared
 167     with a rated boost of 9psi.
 168
 169     It is quite possible that other boost control settings could have been used
 170     on some aircraft, or that takeoff/extra boost could have activated by other
 171     means than pushing the throttle full forward through a gate, but this will
 172     suffice for now.
 173
 174     Note that MAXMP is still the non-boosted max manifold pressure even for
 175     boosted engines - effectively this is simply a measure of the pressure drop
 176     through the fully open throttle.
 177 </pre>
 178
 179     @author Jon S. Berndt (Engine framework code and framework-related mods)
 180     @author Dave Luff (engine operational code)
 181     @author David Megginson (initial porting and additional code)
 182     @author Ron Jensen (additional engine code)
 183     @version $Id$
 184   */
 185
 186 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 187 CLASS DECLARATION
 188 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 189
 190 class FGPiston : public FGEngine
 191 {
 192 public:
 193   /// Constructor
 194   FGPiston(FGFDMExec* exec, Element* el, int engine_number);
 195   /// Destructor
 196   ~FGPiston();
 197
 198   std::string GetEngineLabels(const std::string& delimiter);
 199   std::string GetEngineValues(const std::string& delimiter);
 200
 201   double Calculate(void);
 202   double GetPowerAvailable(void) {return PowerAvailable;}
 203   double CalcFuelNeed(void);
 204
 205   void ResetToIC(void);
 206   void SetMagnetos(int magnetos) {Magnetos = magnetos;}
 207
 208   double  GetEGT(void) { return EGT_degC; }
 209   int     GetMagnetos(void) {return Magnetos;}
 210
 211   double getExhaustGasTemp_degF(void) {return KelvinToFahrenheit(ExhaustGasTemp_degK);}
 212   double getManifoldPressure_inHg(void) const {return ManifoldPressure_inHg;}
 213   double getCylinderHeadTemp_degF(void) {return KelvinToFahrenheit(CylinderHeadTemp_degK);}
 214   double getOilPressure_psi(void) const {return OilPressure_psi;}
 215   double getOilTemp_degF (void) {return KelvinToFahrenheit(OilTemp_degK);}
 216   double getRPM(void) {return RPM;}
 217
 218 protected:
 219   double ThrottleAngle;
 220
 221 private:
 222   int crank_counter;
 223
 224   double IndicatedHorsePower;
 225   double PMEP;
 226   double FMEP;
 227   double SpeedSlope;
 228   double SpeedIntercept;
 229   double AltitudeSlope;
 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 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   bool Magneto_Left;
 326   bool Magneto_Right;
 327   int Magnetos;
 328
 329   //
 330   // Outputs (in addition to those in FGEngine).
 331   //
 332   double rho_air;
 333   double volumetric_efficiency;
 334   double map_coefficient;
 335   double m_dot_air;
 336   double equivalence_ratio;
 337   double m_dot_fuel;
 338   double HP;
 339   double combustion_efficiency;
 340   double ExhaustGasTemp_degK;
 341   double EGT_degC;
 342   double ManifoldPressure_inHg;
 343   double CylinderHeadTemp_degK;
 344   double OilPressure_psi;
 345   double OilTemp_degK;
 346   double MeanPistonSpeed_fps;
 347
 348   void Debug(int from);
 349 };
 350 }
 351 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 352 #endif