JSBSim Engines

From FlightGear wiki
Jump to navigation Jump to search

JSBSim provides a framework for aerodynamics. This page will attempt to explain how to create engines for the JSBSim framework. Engines also require thrusters.


FGPiston

Piston engine model. You enter values based on commonly available data and this model creates reasonable output values.

Configuration File Format

<?xml version="1.0"?> 
 <piston_engine name="{string}">
  <minmp unit="{INHG | PA | ATM}"> {number} </minmp>
  <maxmp unit="{INHG | PA | ATM}"> {number} </maxmp>
  <displacement unit="{IN3 | LTR | CC}"> {number} </displacement>
  <bore unit="{IN | M}"> {number} </bore> <!-- Unused -->
  <stroke unit="{IN | M}"> {number} </stroke>
  <cylinders> {number} </cylinders><!-- Unused -->
  <cylinder-head-mass unit="{KG | LBS}"> {number} </cylinder-head-mass> 
  <compression-ratio> {number} </compression-ratio>
  <sparkfaildrop> {number} </sparkfaildrop>
  <maxhp unit="{HP | WATTS}"> {number} </maxhp>
  <cycles> {number} </cycles> 
  <idlerpm> {number} </idlerpm>
  <maxrpm> {number} </maxrpm>
  <numboostspeeds> {number} </numboostspeeds>
  <boostoverride> {0 | 1} </boostoverride>
  <boostmanual> {0 | 1} </boostmanual>
  <ratedboost1 unit="{INHG | PA | ATM}"> {number} </ratedboost1>
  <ratedpower1 unit="{HP | WATTS}"> {number} </ratedpower1>
  <ratedrpm1> {number} </ratedrpm1>
  <ratedaltitude1 unit="{FT | M}"> {number} </ratedaltitude1>
 (repeat for speeds 2 and 3)
  <takeoffboost unit="{INHG | PA | ATM}"> {number} </takeoffboost>
 <!-- advanced tags! -->
  <bsfc unit="{LBS/HP*HR | KG/KW*HR}"> {number} </bsfc>
  <volumetric-efficiency> {number} </volumetric-efficiency>
  <air-intake-impedance-factor> {number} </air-intake-impedance-factor>
  <ram-air-factor> {number} </ram-air-factor>
  <cooling-factor> {number} </cooling-factor> 
<!-- Added in FlightGear 2.8 -->
  <starter-torque> {number} </starter-torque>
  <starter-rpm> {number} </starter-rpm>
  <static-friction  unit="{HP | WATTS}"> {number} </static-friction>
  <man-press-lag> {number} </man-press-lag>
  <boost-loss-factor> {number} </boost-loss-factor>
<!-- Added in FlightGear 2017.2 -->
  <oil-pressure-relief-valve-psi> {number} </oil-pressure-relief-valve-psi>
  <design-oil-temp-degK> {number} </design-oil-temp-degK>
  <oil-pressure-rpm-max> {number} </oil-pressure-rpm-max>
  <oil-viscosity-index> {number} </oil-viscosity-index>
 </piston_engine>

Parameter definitions

minmp this value is the nominal idle manifold pressure at sea-level without boost. Along with idlerpm, it determines the throttle response slope.
maxmp this value is the nomial maximum manifold pressure at sea-level without boost. Along with maxrpm it determines the resistance of the aircraft's intake system. See air-intake-impedance-factor
displacement this value is used to determine mass air and fuel flow which impacts engine power and cooling.
bore cylinder bore is currently unused.
stroke piston stroke is used to determine the mean piston speed. A longer stroke results in an engine that does not work as well at higher speeds.
cylinders number of cylinders scales the cylinder head mass.
cylinder-head-mass the nominal mass of a cylinder head. A larger value slows changes in engine temperature
compression-ratio the compression ratio affects the change in volumetric efficiency with altitude.
sparkfaildrop this is the percentage drop in horsepower for single magneto operation.
maxhp this value is the nominal power the engine creates at maxrpm. It will determine bsfc if that tag is not input. It also determines the starter motor power.
static-friction this value is the power required to turn an engine that is not running. Used to control and slow a windmilling propeller.
cycles Designate a 2 or 4 stroke engine. Currently only the 4 stroke engine is supported.
idlerpm this value affects the throttle fall off and the engine stops running if it is slowed below 80% of this value. The engine starts running when it reaches 80% of this value.
maxrpm this value is used to calculate air-box resistance and BSFC. It also affects oil pressure among other things.
maxthrottle Deprecated / unused
minthrottle Deprecated / unused
numboostspeed zero (or not present) for a naturally-aspirated engine, either 1, 2 or 3 for a boosted engine. This corresponds to the number of supercharger speeds. Merlin XII had 1 speed, Merlin 61 had 2, a late Griffon engine apparently had 3. No known engine more than 3, although some German engines apparently had a continuously variable-speed supercharger.
boostoverride unused
boost-loss-factor (fgfs 2.8) boost-loss-factor - zero (or not present) for 'free' supercharging. A value entered will be used as a multiplier to the power required to compress the input air. Typical value should be 1.15 to 1.20.
boostmanual whether a multispeed supercharger will manually or automatically shift boost speeds. On manual shifting the boost speeds is accomplished by controlling propulsion/engine/boostspeed
takeoffboost boost in psi above sea level ambient.
ratedboost[123] the absolute rated boost above sea level ambient (14.7 PSI, 29.92 inHg) for a given boost speed, in psi
ratedpower[123] required by the parser but ignored
ratedrpm[123] The rpm at which rated boost is developed
ratedaltitude[123] The altitude up to which rated boost can be maintained. Up to this altitude the boost is maintained constant for a given throttle position by the BCV or wastegate. Beyond this altitude the manifold pressure must drop, since the supercharger is now at maximum unregulated output. The actual pressure multiplier of the supercharger system is calculated at initialisation from this value.
bsfc (Advanced) Indicated Specific Fuel Consumption. The power produced per unit of fuel. Higher numbers give worse fuel economy. This number may need to be lowered slightly from actual BSFC numbers because some internal engine losses are modeled separately.
volumetric-efficiency (Advanced) the nominal volumetric efficiency of the engine. Boosted engines require values above 1.
air-intake-impedance-factor (Advanced) this number is the pressure drop across the intake system. Increasing it reduces available manifold pressure.
ram-air-factor (Advanced) this number creates a pressure increase with an increase in dynamic pressure (aircraft speed).
cooling-factor (Advanced) this number models how efficient the aircraft cooling system is.
starter-torque (fgfs 2.8) A value specifying the zero RPM torque in lb*ft the starter motor provides. Current default value is 40% of the maximum horsepower value.
starter-rpm (fgfs 2.8) A value specifying the maximum RPM the unloaded starter motor can achieve. Loads placed on the engine by the propeller and throttle will further limit RPM achieved in practice. The actual RPM needs to be more than idlerpm * 0.8 for the engine to start running.
static-friction (fgfs 2.8) this value is the power required to turn an engine that is not running. Used to control and slow a windmilling propeller. Choose a small percentage of maxhp. It can also be adjusted at run-time to simulate accessory or other non-thruster engine load.
man-press-lag (fgfs 2.8) Delay in seconds for manifold pressure changes to take effect after the throttle is moved or the RPM changes. Default is 1 second.
oil-pressure-relief-valve-psi (fgfs 2017.2) the basic max value reached by oil pressure at engine RPM >= [oil-pressure-rpm-max]. Default = 60 psi. This basic value is later corrected for oil temperature and viscosity, to give the final oil pressure.
oil-pressure-rpm-max (fgfs 2017.2) the engine RPM value above which the basic oil pressure stabilizes at [oil-pressure-relief-valve-psi]. Default = maxrpm * 0.75. Below this regime, the oil pressure increases linearly with RPM as (oil-pressure-relief-valve-psi) * RPM / (oil-pressure-rpm-max).
design-oil-temp-degK (fgfs 2017.2) A characteristic oil temperature at which the final oil pressure = [oil-pressure-relief-valve-psi] if RPM are >= [oil-pressure-rpm-max]. Default = 358 K. Otherwise, the final oil pressure depends on oil temperature and viscosity index (and RPM at low regime).
oil-viscosity-index (fgfs 2017.2) A coefficient for oil viscosity dependence on oil temperature. Default = 0.25 psi / K regarding the effect on oil pressure.

Notes

  • Intake & Throttle
    • The intake is modeled by <ram-air-factor>,<minmp>, <maxmp>, and <air-intake-impedance-factor>.
    • <ram-air-factor> is the efficiency of the air scoop intake. 0 turns ram air off. Default is 1. This value is exposed on the property tree so it may be altered at runtime to simulate alternate air, etc. The value can be calculated by (ambient pressure)/(desired pressure)-1 where desired pressure is full throttle at rated RPM.
    • <maxmp> is the maximum manifold pressure achievable. It is used for determining <BSFC> and <air-intake-impedance-factor> if a values are not supplied for those items.
    • <minmp> is used along with <idlerpm> to determine the slope of the throttle response
    • <air-intake-impedance-factor> is the fixed impedance in the air intake system. It is determined by <maxmp> if not supplied. This value is exposed on the property tree so it may be altered at runtime to simulate intake icing, alternate air, etc.
  • Boost
    • <boostmanual> whether a multispeed supercharger will manually or automatically shift boost speeds. On manual shifting the boost speeds is accomplished by controlling propulsion/engine/boostspeed
    • <takeoffboost> - Many aircraft had an extra boost setting beyond rated boost, but not totally uncontrolled as in the already mentioned boost-control-cutout, typically attained by pushing the throttle past a mechanical 'gate' preventing its inadvertant use. This was typically used for takeoff, and emergency situations, generally for not more than five minutes. This is a change in the boost control setting, not the actual supercharger speed, and so would only give extra power below the rated altitude. When TAKEOFFBOOST is specified in the config file (and is above RATEDBOOST1), then the throttle position is interpreted as:
      • 0 to 0.98 : idle manifold pressure to rated boost (where attainable)
      • 0.99, 1.0 : takeoff boost (where attainable).
      • A typical takeoff boost for an earlyish Merlin was about 12psi, compared with a rated boost of 9psi.
      • It is quite possible that other boost control settings could have been used on some aircraft, or that takeoff/extra boost could have activated by other means than pushing the throttle full forward through a gate, but this will suffice for now.
    • <ratedboost[123]> - the absolute rated boost above sea level ambient (14.7 PSI, 29.92 inHg) for a given boost speed, in psi. Eg the Merlin XII had a rated boost of 9psi, giving approximately 39inHg manifold pressure up to the rated altitude.
      • Note that <maxmp> is still the non-boosted max manifold pressure even for boosted engines - effectively this is simply a measure of the pressure drop through the fully open throttle.
    • <ratedaltitude[123]> - The altitude up to which rated boost can be maintained. Up to this altitude the boost is maintained constant for a given throttle position by the BCV or wastegate. Beyond this altitude the manifold pressure must drop, since the supercharger is now at maximum unregulated output. The actual pressure multiplier of the supercharger system is calculated at initialisation from this value.
    • <ratedpower[123]> - The power developed at rated boost at rated altitude at rated rpm.
    • <ratedrpm[123]> - The rpm at which rated power is developed.
  • Power production
    • <sparkfaildrop> is the amount of power you get for single magneto operation, try a value of 0.8 or so.
    • <volumetric-efficiency> controls how much air goes through the engine at a given RPM. Values below 1 for unboosted engines and values over 1 for boosted engines. This value is exposed on the property tree so it may be altered at runtime.
    • <bsfc> is the amount of power the engine produces per unit of fuel consumed. Use it to tune the power produced. This value is exposed on the property tree so it may be altered at runtime.
  • Cooling
    • <cylinder-head-mass> controls how fast the engine heats up and cools off. So if you have a '5-minute' limit on a power setting you can adjust this value so the engine just starts to overheat at the end of the given time frame.
    • <cooling-factor> controls how much 'air' flows over the engine to cool it. Raising the value makes the engine run cooler. This value is exposed on the property tree so it may be altered at runtime to simulate cowl flaps, for example.
  • Tuning
    • Using a constant speed load, set the engine model to full throttle and rated RPM.
    • Set <ram-air-factor> to zero.
    • Adjust <air-intake-impedance-factor> to achieve the proper static full throttle manifold pressure.
    • Increase airspeed to cruise and adjust <ram-air-factor> to achieve the proper dynamic full throttle manifold pressure.
    • Adjust <volumetric-efficiency> first to achieve desired fuel flow rate, leaning engine as required.
    • Adjust <bsfc> to achieve desired power.
    • Some piston engines will have power curves that will need to be altered from default depending on operating conditions. For example engines with multi-speed superchargers will produce less horse power on high speed at the same manifold pressure compared to low speed. Functions can be setup to alter <volumetric-efficiency> and <bsfc> at run time to get the power and fuel consumption curves correct by using different values for high and low supercharger speeds.

FGTurbine

The jet turbine engine

Configuration File Format

<?xml version="1.0"?> 
 <turbine_engine name="{string}">
  <milthrust unit="{LBS | N}"> {number} </milthrust>
  <maxthrust unit="{LBS | N}"> {number} </maxthrust>
  <bypassratio> {number} </bypassratio>
  <bleed> {number} </bleed>
  <tsfc> {number} </tsfc>
  <atsfc> {number} </atsfc>
  <ignitionn1> {number} </ignitionn1>
  <ignitionn2> {number} </ignitionn2>
  <idlen1> {number} </idlen1>
  <idlen2> {number} </idlen2>
  <n1spinup> {number} </n1spinup>
  <n2spinup> {number} </n2spinup>
  <n1startrate> {number} </n1startrate>
  <n2startrate> {number} </n2startrate>
  <maxn1> {number} </maxn1>
  <maxn2> {number} </maxn2>
  <augmented> {0 | 1} </augmented>
  <augmethod> {0 | 1 | 2} </augmethod>
  <injected> {0 | 1} </injected>
  <injection-time> {number} </injection-time>
  <function name="IdleThrust"> </function>
  <function name="MilThrust">  </function>
  <function name="AugThrust">  </function>
  <function name="Injection">  </function>
 </turbine_engine>

Parameter definitions

milthrust Maximum thrust, static, at sea level.
maxthrust Afterburning thrust, static, at sea level.
bypassratio Ratio of bypass air flow to core air flow.
bleed Thrust reduction factor due to losses (0.0 to 1.0).
tsfc Thrust-specific fuel consumption at cruise, lbm/hr/lbf
atsfc Afterburning TSFC, lbm/hr/lbf
ignitionn1 Fan rotor rpm (% of max) while starting
ignitionn2 Core rotor rpm (% of max) while starting
idlen1 Fan rotor rpm (% of max) at idle
idlen2 Core rotor rpm (% of max) at idle
n1spinup Fan rotor rpm starter acceleration (default 1.0%/sec)
n2spinup Core rotor rpm starter acceleration (default 3.0%/sec)
n1startrate Fan rotor rpm time taken to accelerate from ignitionn1 to idlen1 value (default 1.4%/sec)
n2startrate Core rotor rpm time taken to accelerate from ignitionn2 to idlen2 value (default 2.0%/sec)
maxn1 Fan rotor rpm (% of max) at full throttle
maxn2 Core rotor rpm (% of max) at full throttle
augmented 0 = afterburner not installed
1 = afterburner installed
augmethod 0 = afterburner activated by property /engines/engine[n]/augmentation
1 = afterburner activated by pushing throttle above 99% position
2 = throttle range is expanded in the FCS, and values above 1.0 are afterburner range
injected 0 = Water injection not installed
1 = Water injection installed
injection-time Time, in seconds, of water injection duration
function Two functions, IdleThrust and MilThrust must always be defined. AugThrust is required for afterburning (reheated) engines. Injection is for water injected engines. These functions return a multiplier that is applied to the supplied static thrust values. In aeromatic configurations these functions are tables based on sonic velocity and air density

Notes

  • Bypass ratio is used only to estimate engine acceleration time. The effect of bypass ratio on engine efficiency is already included in the TSFC value. Feel free to set this parameter (even for turbojets) to whatever value gives a desired spool-up rate. Default value is 0.
  • The bleed factor is multiplied by thrust to give a resulting thrust after losses. This can represent losses due to bleed, or any other cause. Default value is 0. A common value would be 0.04.
  • Nozzle position, for variable area exhaust nozzles, is provided for users needing to drive a nozzle gauge or animate a virtual nozzle.
  • This model can only be used with the "direct" thruster. See the file: /engine/direct.xml
  • TSFC=fuel consumption per hour/thrust
  • There is a Java program here to calculate thrust vs airspeed and altitude. http://adg.stanford.edu/aa241/propulsion/engmodel.html[dead link]
  • n1spinup and n2spinup are the rate (in %/sec) of increase below 25.8% N2, or until 15% if cutoff is false. These N% values can be manipulated by ignitionn1 and ignitionn2.
  • acceleration between 25.8% N2 and Idle is at a preset rate of 2.0/%sec for M2, 1.4%/sec for N1. Can now be manipulated by n1startrate / n2startrate
  • once running the acceleration is (90.0 / (BypassRatio + 3.0) ) per second
  • ignitionn1 / ignitionn2 and n1startrate / n2startrate available from 2018.4+

FGTurboprop

The turboprop engine

Configuration File Format

<?xml version="1.0"?> 
<milthrust unit="{LBS | N}"> {number} </milthrust>
<idlen1> {number} </idlen1>
<idlen2> {number} </idlen2>
<maxn1> {number} </maxn1>
<maxn2> {number} </maxn2>

<betarangeend> {number} </betarangeend>
<reversemaxpower> {number} </reversemaxpower>
<maxpower> {number} </maxpower>
<psfc> {number} </psfc>
<n1idle_max_delay> {number} </n1idle_max_delay>
<maxstartingtime> {number} </maxstartingtime>
<startern1> {number} </startern1>
<ielumaxtorque> {number} </ielumaxtorque>
<itt_delay> {number} </itt_delay>

  <table name="EnginePowerVC">
    <description> Engine power, function of airspeed and pressure </description>
    <independentVar lookup="row">atmosphere/P-sl-psf</independentVar>
    <independentVar lookup="column">velocities/ve-kts</independentVar>
    <tableData>
                 0     50    100    150    200    250
       503   0.357  0.380  0.400  0.425  0.457  0.486
      1048   0.586  0.589  0.600  0.621  0.650  0.686
      1328   0.707  0.721  0.731  0.757  0.786  0.821
      1496   0.779  0.786  0.808  0.821  0.857  0.900
      1684   0.850  0.857  0.874  0.900  0.943  0.979
      1896   0.914  0.929  0.946  0.971  1      1.057
      2135   1      1.011  1.029  1.043  1.083  1.150
      2213   1.029  1.043  1.057  1.079  1.114  1.171
    </tableData>
  </table> 

  <table name="EnginePowerRPM_N1" type="internal">
    <description> Engine Power, function of RPM and N1 </description>
    <tableData>
            0   5   60    86   94   95   96   97   98   99  100  101
         0  0   0.5  0.5   0.5  0.5  0.5  0.5  0.5  0.5  0.5  0.5  0.5
       800  0   0.5 35   200  350  380  420  460  500  530  580  620
      1200  0   0.5 30   230  400  430  470  505  550  590  640  680
      1600  0   0.5  5   240  440  475  510  550  595  630  680  720
      2000  0   0.1  0.1 225  450  495  525  565  610  650  700  745
      2200  0   0.1  0.1 205  440  480  515  560  605  645  695  743
    </tableData>
  </table>

  <table name="ITT_N1" type="internal">
    <description> Inter-Turbine Temperature ITT [deg C] depending on N1 and engine run (0=off / 1=running) </description>
    <tableData>
              0     1
      {n1 value} {number} {number}
       ...
      {n1 value} {number} {number}
      </tableData>
  </table> 
  
  <table name="CombustionEfficiency_N1" type="internal">
    <tableData>
      {n1 value} {number}
       ...
      {n1 value} {number}
      </tableData>
  </table>

Parameter definitions

milthrust [LBS]
idlen1 [%]
maxn1 [%]
betarangeend[%] if ThrottleCmd < betarangeend/100.0 then engine power=idle, propeller pitch is controled by ThrottleCmd (between MINPITCH and REVERSEPITCH).
if ThrottleCmd > betarangeend/100.0 then engine power increases up to max reverse power reversemaxpower [%] max engine power in reverse mode
maxpower [HP]
psfc power specific fuel consumption [pph/HP] for N1=100%
n1idle_max_delay [-] time constant for N1 change
maxstartenginetime [sec] after this time the automatic starting cycle is interrupted when the engine doesn't start (0=automatic starting not present)
startern1 [%] when starting starter spin up engine to this spin
ielumaxtorque [lb.ft] if torque>ielumaxtorque limiters decrease the throttle (ielu = Integrated Electronic Limiter Unit)
itt_delay [-] time constant for ITT change (ITT = Inter Turbine Temperature)

Starting the engine

Unlike YASim, JSBSim simulates the startup of Turbine engines.

  1. Set the property /controls/engines/engine[~n~]/starter to true.
  2. JSBsim will begin to crank the engine spinning it up to around 5% N1, and about 25% N2.
  3. You can set the property /engines/engine[~n~]/cutoff to true at any point.
  4. If the engine is above 15% N2, and the cutoff property is set to true, JSBsim will introduce fuel to the engine, and the engine will spin up.
  5. /engines/engine[~n~]/n1 will increase further until it stabilizes at the value which is defined in idlen1 in the engine definition file.
  6. Nasal can be used to automate this process, allowing any number of engine start simulations. Various JSBsim aircraft will do this differently, depending on how the real plane functions, and how the author implemented it.

FGRocket

The rocket engine

Configuration File Format

<?xml version="1.0"?> 
<rocket_engine name="{string}">
  <isp> {number} </isp>
  <builduptime> {number} </builduptime>
  <maxthrottle> {number} </maxthrottle>
  <minthrottle> {number} </minthrottle>
  <slfuelflowmax> {number} </slfuelflowmax>
  <sloxiflowmax>  {number} </sloxiflowmax>
  <variation>
    <thrust> {number} </thrust>
    <total_isp> {number} </total_isp>
  </variation> 
  <thrust_table name="propulsion/thrust_prop_remain" type="internal">
    <tableData>
      {number} {number}
	...
      {number} {number}
    </tableData>
  </thrust_table>
</rocket_engine>

FGElectric

Simple thrust producer. You enter the max power as <power unit="WATTS"> and the engine model produces throttle_setting*power watts of output.

  • Enter the max power as <power unit="WATTS"> and the engine model produces throttle_setting*power watts of output.

Configuration File Format

<?xml version="1.0"?> 
<electric_engine name="{string}">
 <power unit="{HP | WATTS}"> {number} </power>
</electric_engine>

Notes

FGElectric models an electric motor based on the configuration file <power> parameter. The throttle controls motor output linearly from zero to <power>. This power value (converted internally to horsepower) is then used by FGPropeller to apply torque to the propeller. At present there is no battery model available, so this motor does not consume any energy. There is no internal friction.

Sources

Retrieved from "https://wiki.flightgear.org/w/index.php?title=JSBSim_Engines&oldid=139566"