JSBSim Engines

2012-12-31T12:45:56Z

Jentron: /* Parameter definitions */

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

== FGPiston ==
Piston engine model. You enter values based on commonly available data and this model creates reasonable output values.
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?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> 
<stroke unit="{IN | M}"> {number} </stroke>
<cylinders> {number} </cylinders>
<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>

<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>

<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>
</piston_engine>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|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.
|-
|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.
|-
|}

=== 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 ===
<syntaxhighlight lang="xml">
<?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>
<idlen1> {number} </idlen1>
<idlen2> {number} </idlen2>
<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>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|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
|-
|idlen1
|Fan rotor rpm (% of max) at idle
|-
|idlen2
|Core rotor rpm (% of max) at idle
|-
|maxn1
|Fan rotor rpm (% of max) at full throttle
|-
|maxn2
|Core rotor rpm (% of max) at full throttle
|-
|augmented
|0 = afterburner not installed<br />1 = afterburner installed
|-
|augmethod
|0 = afterburner activated by property /engines/engine[n]/augmentation<br />1 = afterburner activated by pushing throttle above 99% position<br />2 = throttle range is expanded in the FCS, and values above 1.0 are afterburner range
|-
|injected
|0 = Water injection not installed<br />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

== FGTurboprop ==
The turboprop engine

=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|milthrust
|[LBS]
|-
|idlen1
|[%]
|-
|maxn1
|[%]
|-
|betarangeend[%]
| if ThrottleCmd < betarangeend/100.0 then engine power=idle, propeller pitch is controled by ThrottleCmd (between MINPITCH and REVERSEPITCH).<br /> 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)
|-
|}

== FGRocket ==
The rocket engine
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?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>
</syntaxhighlight>

== 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 ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<electric_engine name="{string}">
<power unit="{HP | WATTS}"> {number} </power>
</electric_engine>
</syntaxhighlight>

=== 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 ==
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGPiston.html
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGTurbine.html
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGTurboProp.html

{{JSBSim}}

JSBSim Engines

2012-12-11T13:45:42Z

Jentron: remove duplicate and unused tags

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

== FGPiston ==
Piston engine model. You enter values based on commonly available data and this model creates reasonable output values.
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?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> 
<stroke unit="{IN | M}"> {number} </stroke>
<cylinders> {number} </cylinders>
<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>

<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>

<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>
</piston_engine>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|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]
|unused
|-
|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.
|-
|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.
|-
|}

=== 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 ===
<syntaxhighlight lang="xml">
<?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>
<idlen1> {number} </idlen1>
<idlen2> {number} </idlen2>
<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>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|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
|-
|idlen1
|Fan rotor rpm (% of max) at idle
|-
|idlen2
|Core rotor rpm (% of max) at idle
|-
|maxn1
|Fan rotor rpm (% of max) at full throttle
|-
|maxn2
|Core rotor rpm (% of max) at full throttle
|-
|augmented
|0 = afterburner not installed<br />1 = afterburner installed
|-
|augmethod
|0 = afterburner activated by property /engines/engine[n]/augmentation<br />1 = afterburner activated by pushing throttle above 99% position<br />2 = throttle range is expanded in the FCS, and values above 1.0 are afterburner range
|-
|injected
|0 = Water injection not installed<br />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

== FGTurboprop ==
The turboprop engine

=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|milthrust
|[LBS]
|-
|idlen1
|[%]
|-
|maxn1
|[%]
|-
|betarangeend[%]
| if ThrottleCmd < betarangeend/100.0 then engine power=idle, propeller pitch is controled by ThrottleCmd (between MINPITCH and REVERSEPITCH).<br /> 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)
|-
|}

== FGRocket ==
The rocket engine
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?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>
</syntaxhighlight>

== 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 ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<electric_engine name="{string}">
<power unit="{HP | WATTS}"> {number} </power>
</electric_engine>
</syntaxhighlight>

=== 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 ==
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGPiston.html
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGTurbine.html
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGTurboProp.html

{{JSBSim}}

Talk:YASim

2012-10-20T01:44:41Z

Jentron:

With all due respect to Gary Neeley, "Contrast this with JSBSim which relies on pre-generated tabular data to build up the flight model." is not an accurate statement of JSBSim's functionality. JSBSim can use any formula the designer wants to use to specify flight, there is no constraint to pre-generate any tabular data at all. While the commonly used Aeromatic model doesn't do much in the way of physically modeling the aircraft, the framework is in place to generate models based on data similar to the data commonly used in YASim, at least aerodynamically.
[[User:Jentron|Jentron]] 21:44, 19 October 2012 (EDT)

JSBSim Aerodynamics

2012-03-20T03:17:36Z

Jentron: /* Effects */

[[JSBSim]] provides a framework for aerodynamics. This page will attempt to explain how to translate traditional aerodynamics concepts into the [[JSBSim]] framework, and how to create [[FDM]]s that are sane for any flight value.

This page uses the term "coefficient" both the traditional sense of a constant multiplicative factor or in the [[JSBSim]] sense of the output of a function derived from a coefficient.

JSBSim provides three [[#Forces|Forces]] and three [[#Moments|Moments]] (a moment is a twisting or turning force), therefore it is a 'six degree of freedom' simulation.

== Frames ==
JSBSim incorporates several frame of reference. The body frame and wind frame are the most important to the aerodynamic model.
* '''Body XYZ''' The body frame uses the X axis for forward and aft, with + to the front. The Y axis is side to side with + to the right. The Z axis is up and down, with + being up. The origin of this frame is the Center of Gravity (CG), about which the aircraft forces and moments are summed and the resulting accelerations are integrated to get velocities.

* '''Wind XYZ''' The wind frame X-axis points directly into the relative wind. The Z-axis is perpendicular to the X-axis, and remains within the aircraft body axis XZ plane (also called the reference plane). The Y-axis completes a right hand coordinate system. The origin of this frame is the AeroRP.

* '''Wind UVW''' This isn't really a frame, but it is the components of the wind velocity vector. The relative wind is imposed on the body frame using variables U,V, and W. U to represent the velocity of the wind flowing past the aircraft. U represents the wind blowing down the X or longitudinal axis of the aircraft. V represents the wind blowing down the body frame Y axis, that is, wind in your ear. W represents wind blowing down the body frame Z axis, or wind from above.

== Angles ==
These two angles define the direction the relative wind is blowing in regard to the body frame.
* '''Alpha''' Alpha is the angle between the X body axis and the X wind axis measured on the UV plane. In standard aerodynamics Alpha is often referenced to the main wing chord line, this is not the case in [[JSBSim]].
* '''Beta''' Beta is the angle between the X body axis and the X wind axis measured in the UW plane.

== QBar ==
QBar, or dynamic pressure, is the product of velocity^2*(air density)/2
* '''QBarUV''' Use this value for formula involving Alpha. It is the value of QBar restricted to the vertical plane.
* '''QBarUW''' Use this value for formula involving Beta. It is the value of QBar restricted to the horizontal plane.

== Metrics ==
The metrics section provides a standard place to record common aircraft dimensions. [[Aeromatic]] built [[FDM]]s only use three of the defined properties.
* Wing Area - metrics/Sw-sqft
* Wing Span - metrics/bw-ft
* Wing Chord - metrics/cbarw-ft

Other dimensions [[Aeromatic]] creates but does not use are: (tail arms are used by the JSBSim Turbulence code)
* Horizontal Tail Area - Sh-sqft
* Horizontal Tail Arm - lh-ft
* Vertical Tail Area - Sv-sqft
* Vertical Tail Arm - lv-ft

== Forces ==
For purposes of the Aerodynamics section the entire aircraft creates a single, unified aerodynamic force. This force is split into three component vectors. The most common way of splitting this force into vectors is the Lift Drag Side method. Another, potential better way from the perspective of generating a full 360 degree capable [[FDM]], is the Normal, Axial, Side method.
* '''Lift: CL''' Lift is the portion of the aerodynamic force that is at a right angle to the relative wind, and points up.
** Lift is a function of QBar * Wing Area * Cl<sub>lift</sub>. Cl<sub>lift</sub> is generally derived from a 2D table as a function of AoA. In the real world it is also a function of the Reynolds and Mach Numbers.
* '''Drag: CD''' Drag is the portion of the aerodynamic force that is parallel to the relative wind.
** It is important to ensure all coefficient functions in the drag section remain positive. When drag coefficient functions are negative, drag is effectively acting as thrust opposite the relative wind.
* '''Side: CY''' Side is the portion of the aerodynamic force that is at a right angle to the relative wind and points to the side.

This system was developed by and for people using wind tunnels. Lift is to the top of the wind tunnel, drag is out the back and side is to the side. As a real aircraft in free space yanks and banks it becomes somewhat ambiguous which direction the forces are applied. For example, an aircraft is diving straight at the ground, 90 degrees nose down pitch. Its angle of attack, and the relative wind, is almost 0. 'Lift' is supposed to be perpendicular to the relative wind and point to the heavens, but there is not a vector that satisfies that description in this case.

Enter the Axial, Normal, Side system.
* '''Axial: CA''' Axial force is the portion of the aerodynamic force that is parallel to the aircraft's longitudinal (X) axis. For very small angles of attack it is analogous to Drag.
* '''Normal: CN''' Normal force is the portion of the aerodynamic force that is parallel to the aircraft's vertical (Z) axis. For very small angles of attack it is analogous to Lift.
* '''Side: CY''' Side is the portion of the aerodynamic force that is parallel to the aircraft's lateral (Y) axis.

Which ever system is used, the forces are applied at the Aerodynamic Reference Point (AeroRP). If the AeroRP is not coincident to the model's center of gravity (CG), yaw, pitch and roll moments are created that do not appear in the moments sections.

== Moments ==
* '''Roll: Cl''' Aerodynamic rolling moment comes from multiple sources:
** One is the lift generated by the vertical tail. On most aircraft the center of pressure for the vertical tail is not on the X body axis. This sets up a moment arm creating a moment of (moment arm length)*(vertical tail lift force).
** Another roll moment source is main wing dihedral angle. FIXME: explain how dihedral contributes to roll moment.
* '''Pitch: Cm''' The primary contributor to the pitching moment is the lift generated by the horizontal tail. The pitching moment of the main wing airfoil is a secondary contributor. Because of this fact it makes sense that the value for Cm will resemble the CL curve for the horizontal tail airfoil. The standard CL curve does not take into account the changes in tail Angle of Attack (AoA) and QBar due to main wing down-wash and rotational velocity around the Y axis. Using QBarUV is more appropriate for Cm than the generic QBar.
* '''Yaw: Cn''' The primary contributor to the yawing moment is the lift generated by the vertical tail. The wind force on the fuselage is a secondary contributor. Because of this fact it makes sense that the value for Cn will resemble the CL curve for the vertical tail airfoil. Changes in QBar due to the vertical tail moving into the 'shadow' of a stalled main wing may need to be accounted for, as well. The source for vertical tail Angle of Attack (AoA) should be Beta and QBarUW is more appropriate for Cn than the generic QBar.

== Effects ==
* '''Stall''' - A 'stall' is generally regarded as a loss of lift due to flow separation over the top of a wing, however, examination of lift polar for an airfoil over a full 360 degrees shows that significant amounts of lift are NOT lost as the stall occurs. The biggest aerodynamic effect of a stall is a large and rapid increase in drag.
* '''Spin''' - Spins are caused loss of stability in the Yaw Moment axis. A stock [[Aeromatic]] [[FDM]] yaw section does not take alpha into account when calculating the yaw moment.
* '''Aerodynamic Reference Point''' - JSBSim provides a way to shift the aerodynamic reference point (AeroRP) forward (negative values) and aft (positive) in response to mach, pitch or other influences. Use the tag <aero_ref_pt_shift_x> in the <aerodynamics> section. The value this tag function returns is internally multiplied by the chord entered in the <metrics> section to get the final shift. You could use this by setting the AeroRP to the leading edge of the wing and use a 1D table indexed by mach starting at .25 chord and getting bigger as the mach number increases to simulate mach tuck.
*'''Lift Due To Elevator""" - There are two interrelated effects from elevator deflection, the Force change and the Moment. These have two different coefficients in two different sections of the FDM but should be considered together. The formula is:

CLde * lh-ft = Cmde * cbarw-ft

That is, the force (lift) created by the elevator times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the chord as the reference length.

A similar formula:

CYdr * lv-ft = Cndr * bw-ft

Is applicable the rudder's side force and yawing moment. The force (side) created by the rudder times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the wing span as the reference length.
{{JSBSim}}

JSBSim Aerodynamics

2012-03-20T03:16:53Z

Jentron: /* Effects */ Talk about forces and moments due to control surface deflections.

[[JSBSim]] provides a framework for aerodynamics. This page will attempt to explain how to translate traditional aerodynamics concepts into the [[JSBSim]] framework, and how to create [[FDM]]s that are sane for any flight value.

This page uses the term "coefficient" both the traditional sense of a constant multiplicative factor or in the [[JSBSim]] sense of the output of a function derived from a coefficient.

JSBSim provides three [[#Forces|Forces]] and three [[#Moments|Moments]] (a moment is a twisting or turning force), therefore it is a 'six degree of freedom' simulation.

== Frames ==
JSBSim incorporates several frame of reference. The body frame and wind frame are the most important to the aerodynamic model.
* '''Body XYZ''' The body frame uses the X axis for forward and aft, with + to the front. The Y axis is side to side with + to the right. The Z axis is up and down, with + being up. The origin of this frame is the Center of Gravity (CG), about which the aircraft forces and moments are summed and the resulting accelerations are integrated to get velocities.

* '''Wind XYZ''' The wind frame X-axis points directly into the relative wind. The Z-axis is perpendicular to the X-axis, and remains within the aircraft body axis XZ plane (also called the reference plane). The Y-axis completes a right hand coordinate system. The origin of this frame is the AeroRP.

* '''Wind UVW''' This isn't really a frame, but it is the components of the wind velocity vector. The relative wind is imposed on the body frame using variables U,V, and W. U to represent the velocity of the wind flowing past the aircraft. U represents the wind blowing down the X or longitudinal axis of the aircraft. V represents the wind blowing down the body frame Y axis, that is, wind in your ear. W represents wind blowing down the body frame Z axis, or wind from above.

== Angles ==
These two angles define the direction the relative wind is blowing in regard to the body frame.
* '''Alpha''' Alpha is the angle between the X body axis and the X wind axis measured on the UV plane. In standard aerodynamics Alpha is often referenced to the main wing chord line, this is not the case in [[JSBSim]].
* '''Beta''' Beta is the angle between the X body axis and the X wind axis measured in the UW plane.

== QBar ==
QBar, or dynamic pressure, is the product of velocity^2*(air density)/2
* '''QBarUV''' Use this value for formula involving Alpha. It is the value of QBar restricted to the vertical plane.
* '''QBarUW''' Use this value for formula involving Beta. It is the value of QBar restricted to the horizontal plane.

== Metrics ==
The metrics section provides a standard place to record common aircraft dimensions. [[Aeromatic]] built [[FDM]]s only use three of the defined properties.
* Wing Area - metrics/Sw-sqft
* Wing Span - metrics/bw-ft
* Wing Chord - metrics/cbarw-ft

Other dimensions [[Aeromatic]] creates but does not use are: (tail arms are used by the JSBSim Turbulence code)
* Horizontal Tail Area - Sh-sqft
* Horizontal Tail Arm - lh-ft
* Vertical Tail Area - Sv-sqft
* Vertical Tail Arm - lv-ft

== Forces ==
For purposes of the Aerodynamics section the entire aircraft creates a single, unified aerodynamic force. This force is split into three component vectors. The most common way of splitting this force into vectors is the Lift Drag Side method. Another, potential better way from the perspective of generating a full 360 degree capable [[FDM]], is the Normal, Axial, Side method.
* '''Lift: CL''' Lift is the portion of the aerodynamic force that is at a right angle to the relative wind, and points up.
** Lift is a function of QBar * Wing Area * Cl<sub>lift</sub>. Cl<sub>lift</sub> is generally derived from a 2D table as a function of AoA. In the real world it is also a function of the Reynolds and Mach Numbers.
* '''Drag: CD''' Drag is the portion of the aerodynamic force that is parallel to the relative wind.
** It is important to ensure all coefficient functions in the drag section remain positive. When drag coefficient functions are negative, drag is effectively acting as thrust opposite the relative wind.
* '''Side: CY''' Side is the portion of the aerodynamic force that is at a right angle to the relative wind and points to the side.

This system was developed by and for people using wind tunnels. Lift is to the top of the wind tunnel, drag is out the back and side is to the side. As a real aircraft in free space yanks and banks it becomes somewhat ambiguous which direction the forces are applied. For example, an aircraft is diving straight at the ground, 90 degrees nose down pitch. Its angle of attack, and the relative wind, is almost 0. 'Lift' is supposed to be perpendicular to the relative wind and point to the heavens, but there is not a vector that satisfies that description in this case.

Enter the Axial, Normal, Side system.
* '''Axial: CA''' Axial force is the portion of the aerodynamic force that is parallel to the aircraft's longitudinal (X) axis. For very small angles of attack it is analogous to Drag.
* '''Normal: CN''' Normal force is the portion of the aerodynamic force that is parallel to the aircraft's vertical (Z) axis. For very small angles of attack it is analogous to Lift.
* '''Side: CY''' Side is the portion of the aerodynamic force that is parallel to the aircraft's lateral (Y) axis.

Which ever system is used, the forces are applied at the Aerodynamic Reference Point (AeroRP). If the AeroRP is not coincident to the model's center of gravity (CG), yaw, pitch and roll moments are created that do not appear in the moments sections.

== Moments ==
* '''Roll: Cl''' Aerodynamic rolling moment comes from multiple sources:
** One is the lift generated by the vertical tail. On most aircraft the center of pressure for the vertical tail is not on the X body axis. This sets up a moment arm creating a moment of (moment arm length)*(vertical tail lift force).
** Another roll moment source is main wing dihedral angle. FIXME: explain how dihedral contributes to roll moment.
* '''Pitch: Cm''' The primary contributor to the pitching moment is the lift generated by the horizontal tail. The pitching moment of the main wing airfoil is a secondary contributor. Because of this fact it makes sense that the value for Cm will resemble the CL curve for the horizontal tail airfoil. The standard CL curve does not take into account the changes in tail Angle of Attack (AoA) and QBar due to main wing down-wash and rotational velocity around the Y axis. Using QBarUV is more appropriate for Cm than the generic QBar.
* '''Yaw: Cn''' The primary contributor to the yawing moment is the lift generated by the vertical tail. The wind force on the fuselage is a secondary contributor. Because of this fact it makes sense that the value for Cn will resemble the CL curve for the vertical tail airfoil. Changes in QBar due to the vertical tail moving into the 'shadow' of a stalled main wing may need to be accounted for, as well. The source for vertical tail Angle of Attack (AoA) should be Beta and QBarUW is more appropriate for Cn than the generic QBar.

== Effects ==
* '''Stall''' - A 'stall' is generally regarded as a loss of lift due to flow separation over the top of a wing, however, examination of lift polar for an airfoil over a full 360 degrees shows that significant amounts of lift are NOT lost as the stall occurs. The biggest aerodynamic effect of a stall is a large and rapid increase in drag.
* '''Spin''' - Spins are caused loss of stability in the Yaw Moment axis. A stock [[Aeromatic]] [[FDM]] yaw section does not take alpha into account when calculating the yaw moment.
* '''Aerodynamic Reference Point''' - JSBSim provides a way to shift the aerodynamic reference point (AeroRP) forward (negative values) and aft (positive) in response to mach, pitch or other influences. Use the tag <aero_ref_pt_shift_x> in the <aerodynamics> section. The value this tag function returns is internally multiplied by the chord entered in the <metrics> section to get the final shift. You could use this by setting the AeroRP to the leading edge of the wing and use a 1D table indexed by mach starting at .25 chord and getting bigger as the mach number increases to simulate mach tuck.
{{JSBSim}}
^'''Lift Due To Elevator""" - There are two interrelated effects from elevator deflection, the Force change and the Moment. These have two different coefficients in two different sections of the FDM but should be considered together. The formula is:

CLde * lh-ft = Cmde * cbarw-ft

That is, the force (lift) created by the elevator times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the chord as the reference length.

A similar formula:

CYdr * lv-ft = Cndr * bw-ft

Is applicable the rudder's side force and yawing moment. The force (side) created by the rudder times its length from the CG is equal to the moment. For some reason standard aerodynamics uses the wing span as the reference length.

JSBSim Mass and balance

2011-12-07T14:33:26Z

Jentron: /* Parameter definitions */

{{stub}}

=== Configuration File Format ===
<syntaxhighlight lang="xml">
<mass_balance>
<ixx unit="{SLUG*FT2 | KG*M2}"> {number} </ixx>
<iyy unit="{SLUG*FT2 | KG*M2}"> {number} </iyy>
<izz unit="{SLUG*FT2 | KG*M2}"> {number} </izz>
<ixy unit="{SLUG*FT2 | KG*M2}"> {number} </ixy>
<ixz unit="{SLUG*FT2 | KG*M2}"> {number} </ixz>
<iyz unit="{SLUG*FT2 | KG*M2}"> {number} </iyz>
<emptywt unit="{LBS | KG"> {number} </emptywt>
<location name="CG" unit="{IN | FT | M}">
<x> {number} </x>
<y> {number} </y>
<z> {number} </z>
</location>
[<pointmass name="{string}">
<form shape="{tube | cylinder | sphere | ball}">
<radius unit="{IN | FT | M}"> {number} </radius>
<length unit="{IN | FT | M}"> {number} </length>
</form>
<weight unit="{LBS | KG}"> {number} </weight>
<location name="{string}" unit="{IN | FT | M}">
<x> {number} </x>
<y> {number} </y>
<z> {number} </z>
</location>
</pointmass>
... other point masses ...]
</mass_balance>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
!i..
|Inertia. Higher values result in slower rolls than lower values. [http://www.eng.auburn.edu/~marghitu/MECH2110/C_4.pdf A technical summary of moments of inertia is here] or [http://en.wikipedia.org/wiki/Moment_of_inertia on Wikipedia here]. Generally the ixz, iyz, and ixy terms will be zero (because the x, y, and z axes are [http://en.wikipedia.org/wiki/Principal_axis_(mechanics)#Principal_axes_of_inertia principal axes]); the exception would be in the case of an extremely asymmetrical aircraft design or if your x, y, and z axes don't line up with any of the axes of symmetry of the aircraft.
|-
!emptywt
|The mass weight of the empty aircraft.
|-
!pointmass
|There can be any number of pointmasses. Each can also have a shape which - if present - causes an associated moment of inertia to be calculated based on the shape. Note that cylinders and balls are solid, while tubes and spheres are hollow.
|}

=== Notes ===
* <tt>emptywt + pointmasses + fuel = total weight</tt>
* Fuel weight is defined in the [[JSBSim Propulsion|propulsion section]].

You can add the pointmasses to the Equipment > Fuel and payload dialog, by adding the following code (for each single pointmass) to your aircraft's -set.xml file:
<syntaxhighlight lang="xml">
<payload>
<weight>
<name type="string">Passengers and crew</name>
<weight-lb alias="/fdm/jsbsim/inertia/pointmass-weight-lbs[0]"/>
<min-lb type="double">3000.0</min-lb>
<max-lb type="double">90000.0</max-lb>
</weight>
</payload>
</syntaxhighlight>

{{JSBSim}}

[[Category:JSBSim|Mass and balance]]

JSBSim

2011-11-26T00:46:06Z

Jentron: /* Overview */

'''JSBSim''' is an open source [[Flight Dynamics Model]] (FDM) software library that models the flight dynamics of an aerospace vehicle. The library has been incorporated into the flight simulation packages [[FlightGear]] and [http://www.openeaagles.org/ OpenEaagles]. It can also be called from a small standalone program to create a batch simulation tool. JSBSim has been in development and use since 1996, and has been built on all of the most popular platforms in use today including those running Linux, Macintosh, and Microsoft Windows operating systems. JSBSim is written in C++ and uses [[File Formats#|XML]] configuration files.

* JSBSim is also used by [[OpenEaagles]]
* [[JSBSim Commander]] is a software program for developing FDM for aircraft with JSBSim.

== Overview ==
JSBSim provides several different physics models which work together to calculate the overall vehicle dynamics.
* Mass Balance - This model uses weight (mass) to provide a force due to gravity and moments of inertia to damp changes in rotational velocity. Empty mass and inertia are specified, and point masses (which can have a shape and size) and fuel load are added in.

* Ground Reactions - JSBSim has a fairly simple system for ground reactions. You can have structural contacts which are uni-directional or bogeys which act only in a given direction. Both are modeled as spring and damper systems. Each bogey or structural contact provides a force on the vehicle when in contact with the ground. If the contact is not at the CG it also provides a rotating moment.

* Propulsion - JSBSim models a variety of engine types using different methods. All engines provide a force along their X axis, and create moments if this force in not applied at the CG. The propeller and rotor thrusters also create turning moments.

* Aerodynamics - JSBSim's aerodyamics are a blank slate. It is entirely up to the vehicle author to use valid formulas. The aerodynamic force is divided into Lift, Drag, and Side. You can also create Roll, Pitch and Yaw moments. In addition, if the aerodynamic force reference point is not coincident to the CoG the forces will create a hidden moment.

* Buoyant forces - Lighter than air craft, i.e., Balloons, dirigibles and rigid airships, can be simulated with this model.

* External forces - If the aerodynamic section is too limiting, or you want to simulate glider tow ropes, catapults or other things, you can add forces at arbitrary points.

* Atmosphere
* Gravity

== Aeromatic ==

{| style="margin-top:0.1em; margin-bottom:0.1em; margin-left:2em; padding:2px; font-size:95%; text-align:left; background: transparent;"
|-
| [[File:1rightarrow.png|15px]] ''See [http://jsbsim.sourceforge.net/readme-aeromatic.html Aeromatic Readme] for the main article about this subject.''
|}

[http://jsbsim.sourceforge.net/aeromatic2.html Aeromatic] can be used to create aircraft configuration files for use with the JSBSim Flight Dynamics Model. The configuration file format produced using this utility is version 2.0, and is incompatable with older formats because of an extensive overhaul of JSBSim's XML code that occured in December of 2004. Aeromatic is a online web tool, written in PHP, not a standalone program.

You will need at least three files for a complete configuration, an '''aircraft file''' containing information on the aircraft's mass properties, propulsion, flight control, aerodynamic properties, etc., an [http://wiki.flightgear.org/JSBSim_Engines engine file] describing the engine(s), and a [http://wiki.flightgear.org/JSBSim_Thrusters thruster file]. Thrusters can be rotors, propellers, nozzles or direct. All turbine engines use the default "direct" thruster. Piston, electric and turboprops need rotors or propellers. Rockets need nozzles. Aeromatic will generate plausible configuration files for your aircraft using some simplifying assumptions. Note that Aeromatic allows only one type of engine to be defined per aircraft. If you want to mix engine types you'll have to make the necessary changes by hand.

Be careful when tweaking the resulting configuration file, because it's easy to make changes that will result in an unflyable FDM. Common errors are: moving things around so they are not left/right symmetrical, and moving the CG too far away from the AeroRP.

== Related content ==
* [[JSBSim Aerodynamics|JSBSim Aerodynamics notes]]
* [[JSBSim GroundReactions]]
* [[JSBSim Engines|JSBSim Engine configuration]]
* [[JSBSim Thrusters|JSBSim Thruster configuration]]

== External links ==
* [http://www.jsbsim.org/ JSBSim web site]
* [http://www.jsbsim.org/JSBSimReferenceManual.pdf JSBSim Reference Manual] (in-work, PDF)
* [http://jsbsimcommander.sf.net/ JSBSim Commander] (beta)
* [http://jsbsim.sourceforge.net/aeromatic2.html Aeromatic]
* [http://www.holycows.net/datcom/ DATCOM+]

{{FDM}}

{{JSBSim}}

JSBSim

2011-11-26T00:32:20Z

Jentron:

JSBSim Aerodynamics

2011-10-22T17:46:51Z

Jentron: /* Effects */

[[JSBSim]] provides a framework for aerodynamics. This page will attempt to explain how to translate traditional aerodynamics concepts into the [[JSBSim]] framework, and how to create [[FDM]]s that are sane for any flight value.

This page uses the term "coefficient" both the traditional sense of a constant multiplicative factor or in the [[JSBSim]] sense of the output of a function derived from a coefficient.

JSBSim provides three [[#Forces|Forces]] and three [[#Moments|Moments]] (a moment is a twisting or turning force), therefore it is a 'six degree of freedom' simulation.

== Frames ==
JSBSim incorporates several frame of reference. The body frame and wind frame are the most important to the aerodynamic model.
* '''Body XYZ''' The body frame uses the X axis for forward and aft, with + to the front. The Y axis is side to side with + to the right. The Z axis is up and down, with + being up. The origin of this frame is the Center of Gravity (CG), about which the aircraft forces and moments are summed and the resulting accelerations are integrated to get velocities.

* '''Wind XYZ''' The wind frame X-axis points directly into the relative wind. The Z-axis is perpendicular to the X-axis, and remains within the aircraft body axis XZ plane (also called the reference plane). The Y-axis completes a right hand coordinate system. The origin of this frame is the AeroRP.

* '''Wind UVW''' This isn't really a frame, but it is the components of the wind velocity vector. The relative wind is imposed on the body frame using variables U,V, and W. U to represent the velocity of the wind flowing past the aircraft. U represents the wind blowing down the X or longitudinal axis of the aircraft. V represents the wind blowing down the body frame Y axis, that is, wind in your ear. W represents wind blowing down the body frame Z axis, or wind from above.

== Angles ==
These two angles define the direction the relative wind is blowing in regard to the body frame.
* '''Alpha''' Alpha is the angle between the X body axis and the X wind axis measured on the UV plane. In standard aerodynamics Alpha is often referenced to the main wing chord line, this is not the case in [[JSBSim]].
* '''Beta''' Beta is the angle between the X body axis and the X wind axis measured in the UW plane.

== QBar ==
QBar, or dynamic pressure, is the product of velocity^2*(air density)/2
* '''QBarUV''' Use this value for formula involving Alpha. It is the value of QBar restricted to the vertical plane.
* '''QBarUW''' Use this value for formula involving Beta. It is the value of QBar restricted to the horizontal plane.

== Metrics ==
The metrics section provides a standard place to record common aircraft dimensions. [[Aeromatic]] built [[FDM]]s only use three of the defined properties.
* Wing Area - metrics/Sw-sqft
* Wing Span - metrics/bw-ft
* Wing Chord - metrics/cbarw-ft

Other dimensions [[Aeromatic]] creates but does not use are: (tail arms are used by the JSBSim Turbulence code)
* Horizontal Tail Area - Sh-sqft
* Horizontal Tail Arm - lh-ft
* Vertical Tail Area - Sv-sqft
* Vertical Tail Arm - lv-ft

== Forces ==
For purposes of the Aerodynamics section the entire aircraft creates a single, unified aerodynamic force. This force is split into three component vectors. The most common way of splitting this force into vectors is the Lift Drag Side method. Another, potential better way from the perspective of generating a full 360 degree capable [[FDM]], is the Normal, Axial, Side method.
* '''Lift: CL''' Lift is the portion of the aerodynamic force that is at a right angle to the relative wind, and points up.
** Lift is a function of QBar * Wing Area * Cl<sub>lift</sub>. Cl<sub>lift</sub> is generally derived from a 2D table as a function of AoA. In the real world it is also a function of the Reynolds and Mach Numbers.
* '''Drag: CD''' Drag is the portion of the aerodynamic force that is parallel to the relative wind.
** It is important to ensure all coefficient functions in the drag section remain positive. When drag coefficient functions are negative, drag is effectively acting as thrust opposite the relative wind.
* '''Side: CY''' Side is the portion of the aerodynamic force that is at a right angle to the relative wind and points to the side.

This system was developed by and for people using wind tunnels. Lift is to the top of the wind tunnel, drag is out the back and side is to the side. As a real aircraft in free space yanks and banks it becomes somewhat ambiguous which direction the forces are applied. For example, an aircraft is diving straight at the ground, 90 degrees nose down pitch. Its angle of attack, and the relative wind, is almost 0. 'Lift' is supposed to be perpendicular to the relative wind and point to the heavens, but there is not a vector that satisfies that description in this case.

Enter the Axial, Normal, Side system.
* '''Axial: CA''' Axial force is the portion of the aerodynamic force that is parallel to the aircraft's longitudinal (X) axis. For very small angles of attack it is analogous to Drag.
* '''Normal: CN''' Normal force is the portion of the aerodynamic force that is parallel to the aircraft's vertical (Z) axis. For very small angles of attack it is analogous to Lift.
* '''Side: CY''' Side is the portion of the aerodynamic force that is parallel to the aircraft's lateral (Y) axis.

Which ever system is used, the forces are applied at the Aerodynamic Reference Point (AeroRP). If the AeroRP is not coincident to the model's center of gravity (CG), yaw, pitch and roll moments are created that do not appear in the moments sections.

== Moments ==
* '''Roll: Cl''' Aerodynamic rolling moment comes from multiple sources:
** One is the lift generated by the vertical tail. On most aircraft the center of pressure for the vertical tail is not on the X body axis. This sets up a moment arm creating a moment of (moment arm length)*(vertical tail lift force).
** Another roll moment source is main wing dihedral angle. FIXME: explain how dihedral contributes to roll moment.
* '''Pitch: Cm''' The primary contributor to the pitching moment is the lift generated by the horizontal tail. The pitching moment of the main wing airfoil is a secondary contributor. Because of this fact it makes sense that the value for Cm will resemble the CL curve for the horizontal tail airfoil. The standard CL curve does not take into account the changes in tail Angle of Attack (AoA) and QBar due to main wing down-wash and rotational velocity around the Y axis. Using QBarUV is more appropriate for Cm than the generic QBar.
* '''Yaw: Cn''' The primary contributor to the yawing moment is the lift generated by the vertical tail. The wind force on the fuselage is a secondary contributor. Because of this fact it makes sense that the value for Cn will resemble the CL curve for the vertical tail airfoil. Changes in QBar due to the vertical tail moving into the 'shadow' of a stalled main wing may need to be accounted for, as well. The source for vertical tail Angle of Attack (AoA) should be Beta and QBarUW is more appropriate for Cn than the generic QBar.

== Effects ==
* '''Stall''' - A 'stall' is generally regarded as a loss of lift due to flow separation over the top of a wing, however, examination of lift polar for an airfoil over a full 360 degrees shows that significant amounts of lift are NOT lost as the stall occurs. The biggest aerodynamic effect of a stall is a large and rapid increase in drag.
* '''Spin''' - Spins are caused loss of stability in the Yaw Moment axis. A stock [[Aeromatic]] [[FDM]] yaw section does not take alpha into account when calculating the yaw moment.
* '''Aerodynamic Reference Point''' - JSBSim provides a way to shift the aerodynamic reference point (AeroRP) forward (negative values) and aft (positive) in response to mach, pitch or other influences. Use the tag <aero_ref_pt_shift_x> in the <aerodynamics> section. The value this tag function returns is internally multiplied by the chord entered in the <metrics> section to get the final shift. You could use this by setting the AeroRP to the leading edge of the wing and use a 1D table indexed by mach starting at .25 chord and getting bigger as the mach number increases to simulate mach tuck.
{{JSBSim}}

JSBSim Aerodynamics

2011-10-22T17:42:33Z

Jentron: /* Effects */

[[JSBSim]] provides a framework for aerodynamics. This page will attempt to explain how to translate traditional aerodynamics concepts into the [[JSBSim]] framework, and how to create [[FDM]]s that are sane for any flight value.

This page uses the term "coefficient" both the traditional sense of a constant multiplicative factor or in the [[JSBSim]] sense of the output of a function derived from a coefficient.

JSBSim provides three [[#Forces|Forces]] and three [[#Moments|Moments]] (a moment is a twisting or turning force), therefore it is a 'six degree of freedom' simulation.

== Frames ==
JSBSim incorporates several frame of reference. The body frame and wind frame are the most important to the aerodynamic model.
* '''Body XYZ''' The body frame uses the X axis for forward and aft, with + to the front. The Y axis is side to side with + to the right. The Z axis is up and down, with + being up. The origin of this frame is the Center of Gravity (CG), about which the aircraft forces and moments are summed and the resulting accelerations are integrated to get velocities.

* '''Wind XYZ''' The wind frame X-axis points directly into the relative wind. The Z-axis is perpendicular to the X-axis, and remains within the aircraft body axis XZ plane (also called the reference plane). The Y-axis completes a right hand coordinate system. The origin of this frame is the AeroRP.

* '''Wind UVW''' This isn't really a frame, but it is the components of the wind velocity vector. The relative wind is imposed on the body frame using variables U,V, and W. U to represent the velocity of the wind flowing past the aircraft. U represents the wind blowing down the X or longitudinal axis of the aircraft. V represents the wind blowing down the body frame Y axis, that is, wind in your ear. W represents wind blowing down the body frame Z axis, or wind from above.

== Angles ==
These two angles define the direction the relative wind is blowing in regard to the body frame.
* '''Alpha''' Alpha is the angle between the X body axis and the X wind axis measured on the UV plane. In standard aerodynamics Alpha is often referenced to the main wing chord line, this is not the case in [[JSBSim]].
* '''Beta''' Beta is the angle between the X body axis and the X wind axis measured in the UW plane.

== QBar ==
QBar, or dynamic pressure, is the product of velocity^2*(air density)/2
* '''QBarUV''' Use this value for formula involving Alpha. It is the value of QBar restricted to the vertical plane.
* '''QBarUW''' Use this value for formula involving Beta. It is the value of QBar restricted to the horizontal plane.

== Metrics ==
The metrics section provides a standard place to record common aircraft dimensions. [[Aeromatic]] built [[FDM]]s only use three of the defined properties.
* Wing Area - metrics/Sw-sqft
* Wing Span - metrics/bw-ft
* Wing Chord - metrics/cbarw-ft

Other dimensions [[Aeromatic]] creates but does not use are: (tail arms are used by the JSBSim Turbulence code)
* Horizontal Tail Area - Sh-sqft
* Horizontal Tail Arm - lh-ft
* Vertical Tail Area - Sv-sqft
* Vertical Tail Arm - lv-ft

== Forces ==
For purposes of the Aerodynamics section the entire aircraft creates a single, unified aerodynamic force. This force is split into three component vectors. The most common way of splitting this force into vectors is the Lift Drag Side method. Another, potential better way from the perspective of generating a full 360 degree capable [[FDM]], is the Normal, Axial, Side method.
* '''Lift: CL''' Lift is the portion of the aerodynamic force that is at a right angle to the relative wind, and points up.
** Lift is a function of QBar * Wing Area * Cl<sub>lift</sub>. Cl<sub>lift</sub> is generally derived from a 2D table as a function of AoA. In the real world it is also a function of the Reynolds and Mach Numbers.
* '''Drag: CD''' Drag is the portion of the aerodynamic force that is parallel to the relative wind.
** It is important to ensure all coefficient functions in the drag section remain positive. When drag coefficient functions are negative, drag is effectively acting as thrust opposite the relative wind.
* '''Side: CY''' Side is the portion of the aerodynamic force that is at a right angle to the relative wind and points to the side.

This system was developed by and for people using wind tunnels. Lift is to the top of the wind tunnel, drag is out the back and side is to the side. As a real aircraft in free space yanks and banks it becomes somewhat ambiguous which direction the forces are applied. For example, an aircraft is diving straight at the ground, 90 degrees nose down pitch. Its angle of attack, and the relative wind, is almost 0. 'Lift' is supposed to be perpendicular to the relative wind and point to the heavens, but there is not a vector that satisfies that description in this case.

Enter the Axial, Normal, Side system.
* '''Axial: CA''' Axial force is the portion of the aerodynamic force that is parallel to the aircraft's longitudinal (X) axis. For very small angles of attack it is analogous to Drag.
* '''Normal: CN''' Normal force is the portion of the aerodynamic force that is parallel to the aircraft's vertical (Z) axis. For very small angles of attack it is analogous to Lift.
* '''Side: CY''' Side is the portion of the aerodynamic force that is parallel to the aircraft's lateral (Y) axis.

Which ever system is used, the forces are applied at the Aerodynamic Reference Point (AeroRP). If the AeroRP is not coincident to the model's center of gravity (CG), yaw, pitch and roll moments are created that do not appear in the moments sections.

== Moments ==
* '''Roll: Cl''' Aerodynamic rolling moment comes from multiple sources:
** One is the lift generated by the vertical tail. On most aircraft the center of pressure for the vertical tail is not on the X body axis. This sets up a moment arm creating a moment of (moment arm length)*(vertical tail lift force).
** Another roll moment source is main wing dihedral angle. FIXME: explain how dihedral contributes to roll moment.
* '''Pitch: Cm''' The primary contributor to the pitching moment is the lift generated by the horizontal tail. The pitching moment of the main wing airfoil is a secondary contributor. Because of this fact it makes sense that the value for Cm will resemble the CL curve for the horizontal tail airfoil. The standard CL curve does not take into account the changes in tail Angle of Attack (AoA) and QBar due to main wing down-wash and rotational velocity around the Y axis. Using QBarUV is more appropriate for Cm than the generic QBar.
* '''Yaw: Cn''' The primary contributor to the yawing moment is the lift generated by the vertical tail. The wind force on the fuselage is a secondary contributor. Because of this fact it makes sense that the value for Cn will resemble the CL curve for the vertical tail airfoil. Changes in QBar due to the vertical tail moving into the 'shadow' of a stalled main wing may need to be accounted for, as well. The source for vertical tail Angle of Attack (AoA) should be Beta and QBarUW is more appropriate for Cn than the generic QBar.

== Effects ==
* '''Stall''' - A 'stall' is generally regarded as a loss of lift due to flow separation over the top of a wing, however, examination of lift polar for an airfoil over a full 360 degrees shows that significant amounts of lift are NOT lost as the stall occurs. The biggest aerodynamic effect of a stall is a large and rapid increase in drag.
* '''Spin''' - Spins are caused loss of stability in the Yaw Moment axis. A stock [[Aeromatic]] [[FDM]] yaw section does not take alpha into account when calculating the yaw moment.
* '''Aerodynamic Reference Point''' - JSBSim provides a way to shift the aerodynamic reference point (AeroRP) forward and aft in response to mach, pitch or other influences. Create a function in the <aerodynamics> section called aero_ref_pt_shift_x or just use the tag <aero_ref_pt_shift_x>. The value this function returns is internally multiplied by the chord entered in the <metrics> section.
{{JSBSim}}

JSBSim

2011-10-21T14:24:07Z

Jentron: /* Aeromatic */

JSBSim

2011-10-21T14:11:28Z

Jentron: /* Aeromatic */

JSBSim Engines

2011-10-13T18:43:41Z

Jentron: /* Notes */

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

== FGPiston ==
Piston engine model. You enter values based on commonly available data and this model creates reasonable output values.
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?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> 
<stroke unit="{IN | M}"> {number} </stroke>
<cylinders> {number} </cylinders>
<cylinder-head-mass unit="{KG | LBS}"> {number} </cylinder-head-mass>
<compression-ratio> {number} </compression-ratio>
<sparkfaildrop> {number} </sparkfaildrop>
<maxhp unit="{HP | WATTS}"> {number} </maxhp>
<static-friction unit="{HP | WATTS}"> {number} </static-friction> 
<cycles> {number} </cycles>
<idlerpm> {number} </idlerpm>
<maxrpm> {number} </maxrpm>
<maxthrottle> {number} </maxthrottle> 
<minthrottle> {number} </minthrottle> 
<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>

<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>
</piston_engine>
</syntaxhighlight>
=== Parameter definitions ===
{| class="prettytable"
|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
|-
|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]
|unused
|-
|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.
|-
|}

=== 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 ===
<syntaxhighlight lang="xml">
<?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>
<idlen1> {number} </idlen1>
<idlen2> {number} </idlen2>
<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>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|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
|-
|idlen1
|Fan rotor rpm (% of max) at idle
|-
|idlen2
|Core rotor rpm (% of max) at idle
|-
|maxn1
|Fan rotor rpm (% of max) at full throttle
|-
|maxn2
|Core rotor rpm (% of max) at full throttle
|-
|augmented
|0 = afterburner not installed<br />1 = afterburner installed
|-
|augmethod
|0 = afterburner activated by property /engines/engine[n]/augmentation<br />1 = afterburner activated by pushing throttle above 99% position<br />2 = throttle range is expanded in the FCS, and values above 1.0 are afterburner range
|-
|injected
|0 = Water injection not installed<br />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

== FGTurboprop ==
The turboprop engine

=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|milthrust
|[LBS]
|-
|idlen1
|[%]
|-
|maxn1
|[%]
|-
|betarangeend[%]
| if ThrottleCmd < betarangeend/100.0 then engine power=idle, propeller pitch is controled by ThrottleCmd (between MINPITCH and REVERSEPITCH).<br /> 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)
|-
|}

== FGRocket ==
The rocket engine
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?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>
</syntaxhighlight>

== 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 ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<electric_engine name="{string}">
<power unit="{HP | WATTS}"> {number} </power>
</electric_engine>
</syntaxhighlight>

=== 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 ==
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGPiston.html
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGTurbine.html
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGTurboProp.html

{{JSBSim}}

JSBSim Engines

2011-09-22T15:38:55Z

Jentron: /* FGRocket */

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

== FGPiston ==
Piston engine model. You enter values based on commonly available data and this model creates reasonable output values.
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?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> 
<stroke unit="{IN | M}"> {number} </stroke>
<cylinders> {number} </cylinders>
<cylinder-head-mass unit="{KG | LBS}"> {number} </cylinder-head-mass>
<compression-ratio> {number} </compression-ratio>
<sparkfaildrop> {number} </sparkfaildrop>
<maxhp unit="{HP | WATTS}"> {number} </maxhp>
<static-friction unit="{HP | WATTS}"> {number} </static-friction> 
<cycles> {number} </cycles>
<idlerpm> {number} </idlerpm>
<maxrpm> {number} </maxrpm>
<maxthrottle> {number} </maxthrottle> 
<minthrottle> {number} </minthrottle> 
<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>

<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>
</piston_engine>
</syntaxhighlight>
=== Parameter definitions ===
{| class="prettytable"
|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
|-
|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]
|unused
|-
|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.
|-
|}

=== 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.
** <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 ===
<syntaxhighlight lang="xml">
<?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>
<idlen1> {number} </idlen1>
<idlen2> {number} </idlen2>
<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>
</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|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
|-
|idlen1
|Fan rotor rpm (% of max) at idle
|-
|idlen2
|Core rotor rpm (% of max) at idle
|-
|maxn1
|Fan rotor rpm (% of max) at full throttle
|-
|maxn2
|Core rotor rpm (% of max) at full throttle
|-
|augmented
|0 = afterburner not installed<br />1 = afterburner installed
|-
|augmethod
|0 = afterburner activated by property /engines/engine[n]/augmentation<br />1 = afterburner activated by pushing throttle above 99% position<br />2 = throttle range is expanded in the FCS, and values above 1.0 are afterburner range
|-
|injected
|0 = Water injection not installed<br />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

== FGTurboprop ==
The turboprop engine

=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

</syntaxhighlight>

=== Parameter definitions ===
{| class="prettytable"
|milthrust
|[LBS]
|-
|idlen1
|[%]
|-
|maxn1
|[%]
|-
|betarangeend[%]
| if ThrottleCmd < betarangeend/100.0 then engine power=idle, propeller pitch is controled by ThrottleCmd (between MINPITCH and REVERSEPITCH).<br /> 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)
|-
|}

== FGRocket ==
The rocket engine
=== Configuration File Format ===
<syntaxhighlight lang="xml">
<?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>
</syntaxhighlight>

== 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 ===
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<electric_engine name="{string}">
<power unit="{HP | WATTS}"> {number} </power>
</electric_engine>
</syntaxhighlight>

=== 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 ==
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGPiston.html
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGTurbine.html
* http://jsbsim.sourceforge.net/JSBSim/classJSBSim_1_1FGTurboProp.html

{{JSBSim}}