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