JSBSim Thrusters
JSBSim uses thruster models to convert engine power into aerodynamic forces. The following table shows which engine-thruster combinations work.
Direct | Nozzle | Propeller | Rotor | |
Electric | ||||
Piston | ||||
Rocket | ||||
Turbine | ||||
TurboProp |
FGDirect
Thrust is computed directly by the engine, the direct thruster file is a stub. Currently only the FGTurbine engine uses this thruster.
Configuration File Format
This is the complete configuration file. Copy and paste into your 'direct.xml' file.
<?xml version="1.0"?>
<direct name="Direct">
</direct>
Notes
- The direct thruster creates a property called propulsion/engine[#]/reverser-angle-rad
- "Reverser angle" as used here is a way to manipulate the thrust vector, along the thrust axis ONLY, during run time. This should not be confused with a thrust vectoring nozzle. The angle is defined in radians, and is used thus: Final_thrust = cosine( reverser_angle ) * unmodified_thrust. Therefore a reverser angle of 0 results in no change, and a reverser angle of 3.14 (pi) results in a completely reversed thrust vector. An angle of 1.57 (pi/2) results in no thrust at all
FGNozzle
FGNozzle is for the FGRocket engine.
Configuration File Format
<?xml version="1.0"?>
<nozzle name="{string}">
<area unit="{FT2 | M2 | IN2}"> {number} </area>
</nozzle>
Parameter definitions
area | Nozzle area at the exit plane. |
Notes
- All parameters MUST be specified.
FGPropeller
FGPropeller models a propeller given the tabular data for Ct and Cp, indexed by the advance ratio "J".
Configuration File Format
<!-- Sense goes in the parent tag -->
<sense> {1 | -1} </sense>
<?xml version="1.0"?>
<propeller name="{string}">
<ixx> {number} </ixx>
<diameter unit="IN"> {number} </diameter>
<numblades> {number} </numblades>
<gearratio> {number} </gearratio>
<minpitch> {number} </minpitch>
<maxpitch> {number} </maxpitch>
<minrpm> {number} </minrpm>
<maxrpm> {number} </maxrpm>
<constspeed> {number} </constspeed>
<reversepitch> {number} </reversepitch>
<p_factor> {number} </p_factor>
<ct_factor> {number} </ct_factor>
<cp_factor> {number} </cp_factor>
<table name="C_THRUST" type="internal">
<tableData>
{numbers}
</tableData>
</table>
<table name="C_POWER" type="internal">
<tableData>
{numbers}
</tableData>
</table>
<table name="CT_MACH" type="internal">
<tableData>
{numbers}
</tableData>
</table>
<table name="CP_MACH" type="internal">
<tableData>
{numbers}
</tableData>
</table>
</propeller>
Parameter definitions
ixx | Propeller rotational inertia. (Note: This appears to be in metric units, kg * meters^2, for a thin rod of mass m (kg) and diameter D (meters) spinning about its center, formula is m*D^2/12. See the Moments of inertia reference page and list of conversion factors for different units for moment of inertia.) |
diameter | Propeller disk diameter. |
numblades | Number of blades. |
gearratio | Ratio of (engine rpm) / (prop rpm). |
minpitch | Minimum blade pitch angle. |
maxpitch | Maximum blade pitch angle. |
minrpm | Minimum rpm target for constant speed propeller. |
maxrpm | Maximum rpm target for constant speed propeller. |
constspeed | 1 = constant speed mode, 0 = manual pitch mode. |
reversepitch | Blade pitch angle for reverse. |
sense | Direction of rotation (1=clockwise as viewed from cockpit, -1=anti-clockwise as viewed from cockpit). Sense is specified in the parent tag of the propeller. |
p_factor | P factor. |
ct_factor | A multiplier for the coefficients of thrust (multiplies the dependent variable in the C_THRUST table by this factor). |
cp_factor | A multiplier for the coefficients of power (multiplies the dependent variable in the C_POWER table by this factor). |
C_THRUST and C_POWER tables
The C_THRUST and C_POWER tables are required.
The independent variable for both tables is Advance Ratio (J). The dependent variable is the coefficient of thrust (Ct) for the C_THRUST and the coefficient of power (Cp) for C_POWER.
Propellors for F3D Models explains the theory and has formulas and many graphs showing the relationship between J, Ct, and Cp.
Relevant formulas relating the variables in the tables:
- Thrust: T = Ct/(rho * n^2 * D^4)
- Power: P = Cp/(rho * n^3 * D^5)
- Advance Ratio: J = v/(n*D)
- Efficiency: eta = Ct/Cp or, equivalently eta = v/(n*D)
In the formulas
- Ct = coefficient of thrust
- Cp = coefficient of power
- v = velocity of aircraft (m/s)
- D = diameter of propeller disk (m)
- n = rotations per second (1/s) (note RPS, not RPM)
- rho = density of air (kg/m^3)
- P = power (W)
- T = thrust (N)
For a typical propeller, both Cp and Ct are downward sloping curves that reach 0 near J=1. Typically Ct is slightly greater than than Cp for small J, crosses (is equal to) Cp at some point (typically, when J is between 0.6 and 0.8), and then remains smaller than Cp for larger J. Cp and Ct can be negative (typically for J > 1, approximately); this indicates the drag induced by the prop when the airspeed is relatively fast compared with prop RPM.
Ct/Cp gives the efficiency (eta), and propeller shape and general design give each propeller a distinctive efficiency curve. For fixed-pitch propellers, the propeller is generally designed to reach peak efficiency either at climb velocity & RPM, cruise velocity and RPM, or some compromise between the two. Variable pitch propellers and constant speed propellers bring different factors into play.
Sample C_THRUST and C_POWER tables
These example tables are from FlightGear's C172P aircraft:
<tableData> 0.0 0.068 0.1 0.068 0.2 0.067 0.3 0.066 0.4 0.064 0.5 0.062 0.6 0.059 0.7 0.054 0.8 0.043 0.9 0.031 1.0 0.019 1.1 0.008 1.2 -0.001 1.3 -0.008 1.4 -0.019 1.5 -0.029 1.6 -0.040 1.7 -0.050 1.8 -0.057 1.9 -0.061 2.0 -0.064 2.1 -0.066 2.2 -0.067 2.3 -0.068 5.0 -0.068 </tableData>CT_MACH and CP_MACH
The CT_MACH and CP_MACH tables are optional. They apply a factor to Ct and Cp based on the helical tip Mach.
Sense
Sense is the direction of rotation. 1=clockwise (typically as seen from rear of aircraft or the cockpit of a typical front-propeller aircraft, but this may vary depending on how you have set up the coordinate system for your aircraft) and -1 is counter-clockwise.
The sense tag goes in the parent tag of the thruster, in the <propulsion><thruster> section which is typically in the main JSBSim XML file. Example:
<propulsion> <engine file="Clerget9B"> <location unit="IN"> <x> 12 </x> <y> 0 </y> <z> 0 </z> </location> <orient unit="DEG"> <roll> 0 </roll> <pitch> 0 </pitch> <yaw> 0 </yaw> </orient> <feed>0</feed> <thruster file="CamelProp"> <sense>1</sense> <location unit="IN"> <x> 0 </x> <y> 0 </y> <z> 0 </z> </location> <orient unit="DEG"> <roll> 0 </roll> <pitch> 0 </pitch> <yaw> 0 </yaw> </orient> </thruster> </engine> <tank type="FUEL"> <location unit="IN"> <x> 60 </x> <y> 0 </y> <z> -5.62 </z> </location> <capacity unit="LBS">133.6</capacity> <contents unit="LBS">133.6</contents> </tank> </propulsion>
Notes
- Several references were helpful, here:
- Barnes W. McCormick, "Aerodynamics, Aeronautics, and Flight Mechanics", Wiley & Sons, 1979 ISBN 0-471-03032-5
- Edwin Hartman, David Biermann, "The Aerodynamic Characteristics of Full Scale Propellers Having 2, 3, and 4 Blades of Clark Y and R.A.F. 6 Airfoil Sections", NACA Report TN-640, 1938 (?)
- Various NACA Technical Notes and Reports
FGRotor
FGRotor moodels a helicopter rotor.
Configuration File Format
<!-- Sense goes in the parent tag -->
<sense> {1 | 0 | -1} </sense>
<?xml version="1.0"?>
<rotor name="{string}">
<diameter unit="{LENGTH}"> {number} </diameter>
<numblades> {number} </numblades>
<gearratio> {number} </gearratio>
<nominalrpm> {number} </nominalrpm>
<minrpm> {number} </minrpm>
<maxrpm> {number} </maxrpm>
<chord unit="{LENGTH}"> {number} </chord>
<liftcurveslope Xunit="1/RAD"> {number} </liftcurveslope>
<twist unit="{ANGLE}"> {number} </twist>
<hingeoffset unit="{LENGTH}"> {number} </hingeoffset>
<flappingmoment unit="{MOMENT}"> {number} </flappingmoment>
<massmoment Xunit="SLUG*FT"> {number} </massmoment>
<polarmoment unit="{MOMENT}"> {number} </polarmoment>
<inflowlag> {number} </inflowlag>
<tiplossfactor> {number} </tiplossfactor>
<maxbrakepower unit="{POWER}"> {number} </maxbrakepower>
<controlmap> {MAIN|TAIL|TANDEM} </controlmap>
<ExternalRPM> {number} </ExternalRPM>
<groundeffectexp> {number} </groundeffectexp>
<groundeffectshift unit="{LENGTH}"> {number} </groundeffectshift>
<freewheelthresh> {number} </freewheelthresh>
</rotor>
- LENGTH means any of the supported units, same for ANGLE and MOMENT.X unit-attributes are a hint for currently unsupported units, so values must be provided accordingly.
Parameter definitions
diameter | Rotor disk diameter (2x R). |
numblades | Number of blades (b). |
gearratio | Ratio of (engine rpm) / (rotor rpm), usually > 1. |
nominalrpm | RPM at which the rotor usally operates. |
minrpm | Lowest RPM used in the model, optional and defaults to 1. |
maxrpm | Largest RPM used in the model, optional and defaults to 2 x nominalrpm. |
chord | Blade chord, (c). |
liftcurveslope | Slope of curve of section lift against section angle of attack, per rad (a). |
twist | Blade twist from root to tip, (theta_1). |
hingeoffset | Rotor flapping-hinge offset (e). |
flappingmoment | Flapping moment of inertia (I_b). |
massmoment | Blade mass moment. Mass of a single blade times the blade's cg-distance from the hub, optional. |
polarmoment | Moment of inertia for the whole rotor disk, optional. |
inflowlag | Rotor inflow time constant, sec. Smaller values yield to quicker responses (typical values for main rotor: 0.1 - 0.2 s). |
tiplossfactor | Tip-loss factor. The Blade fraction that produces lift. Value usually ranges between 0.95 - 1.0, optional (B). |
maxbrakepower | Rotor brake, 20-30 hp should work for a mid size helicopter. |
controlmap | Defines the control inputs used (see notes). |
ExternalRPM | Links the rotor to another rotor, or an user controllable property.
Experimental properties |
groundeffectexp | Exponent for ground effect approximation. Values usually range from 0.04 for large rotors to 0.1 for smaller ones. As a rule of thumb the effect vanishes at a height 2-3 times the rotor diameter. formula used: exp ( - groundeffectexp * (height+groundeffectshift) ) Omitting or setting to 0.0 disables the effect calculation. |
groundeffectshift | Further adjustment of ground effect, approx. hub height or slightly above. |
freewheelthresh | Ratio of thruster power to engine power. The FWU will release when above the threshold. The value shouldn't be too close to 1.0, 1.5 seems ok. 0 disables this feature, which is also the default. |
Notes
Controls
- The behavior of the rotor is controlled/influenced by following inputs.
- The power provided by the engine. This is handled by the regular engine controls.
- The collective control input. This is read from the fdm property propulsion/engine[x]/collective-ctrl-rad. See below for tail rotor
- The lateral cyclic input. Read from propulsion/engine[x]/lateral-ctrl-rad.
- The longitudinal cyclic input. Read from propulsion/engine[x]/longitudinal-ctrl-rad.
- The tail collective (aka antitorque, aka pedal) control input. Read from propulsion/engine[x]/antitorque-ctrl-rad or propulsion/engine[x]/tail-collective-ctrl-rad.
Tail/tandem rotor
Providing <ExternalRPM> 0 </ExternalRPM> the tail rotor's RPM is linked to to the main (=first, =0) rotor, and specifying <controlmap> TAIL </controlmap> tells this rotor to read the collective input from propulsion/engine[1]/antitorque-ctrl-rad (The TAIL-map ignores lateral and longitudinal input). The rotor needs to be attached to a dummy engine, e.g. an 1HP electrical engine. A tandem rotor is setup analogous.
Sense
The 'sense' parameter from the thruster is interpreted as follows, sense=1 means counter clockwise rotation of the main rotor, as viewed from above. This is as a far as I know more popular than clockwise rotation, which is defined by setting sense to -1. Concerning coaxial designs - by setting 'sense' to zero, a Kamov-style rotor is modeled (i.e. the rotor produces no torque).
Engine issues
In order to keep the rotor speed constant, use of a RPM-Governor system is encouraged (see examples).
Development hints
Setting <ExternalRPM> -1 </ExternalRPM> the rotor's RPM is controlled by the propulsion/engine[x]/x-rpm-dict property. This feature can be useful when developing a FDM.
References:
SH79 | Shaugnessy, J. D., Deaux, Thomas N., and Yenni, Kenneth R., "Development and Validation of a Piloted Simulation of a Helicopter and External Sling Load", NASA TP-1285, 1979. |
BA41 | Bailey,F.J.,Jr., "A Simplified Theoretical Method of Determining the Characteristics of a Lifting Rotor in Forward Flight", NACA Rep.716, 1941 |
AM50 | Amer, Kenneth B.,"Theory of Helicopter Damping in Pitch or Roll and a Comparison With Flight Measurements", NACA TN-2136, 1950. |
TA77 | Talbot, Peter D., Corliss, Lloyd D., "A Mathematical Force and Moment Model of a UH-1H Helicopter for Flight Dynamics Simulations", NASA TM-73,254, 1977. |
GE49 | Gessow, Alfred, Amer, Kenneth B. "An Introduction to the Physical Aspects of Helicopter Stability", NACA TN-1982, 1949. |