YASim's Piston-driven Propeller Engines
By Gary "Buckaroo" Neely
YASim's piston-driven propeller engines are easy to set up, but can be difficult to tune. It can give a pretty good result, but you're going to have to work for it through trial-and-error experimentation. Don't be discouraged though, because I'm going to show you what I've learned and how you might solve some problems.
A sample piston-driven propeller engine looks like this:
<propeller x="-2.429" y="1.905" z="1.549"
radius="1.2"
mass="731"
moment="33"
min-rpm="1200"
max-rpm="2300"
fine-stop="0.51"
coarse-stop="4"
cruise-rpm="2200"
cruise-power="300"
cruise-speed="143"
cruise-alt="5000">
<actionpt x="-2.260" y="1.905" z="1.563" />
<dir x="0.9986" y="0.0" z="0.05234" />
<control-input axis="/controls/engines/engine[0]/propeller-pitch" control="ADVANCE"/>
<piston-engine
eng-rpm="2300"
eng-power="440"
displacement="985"
compression="6"
supercharger="1"
turbo-mul="1.3"
wastegate-mp="36.5">
<control-input axis="/controls/engines/engine[0]/magnetos" control="MAGNETOS"/>
<control-input axis="/controls/engines/engine[0]/mixture" control="MIXTURE"/>
<control-input axis="/controls/engines/engine[0]/throttle" control="THROTTLE"/>
<control-input axis="/controls/engines/engine[0]/starter" control="STARTER"/>
<control-input axis="/controls/engines/engine[0]/boost" control="BOOST"/>
</piston-engine>
</propeller>
There's a fair amount there but not all of it is required for all cases. I'll break everything down and talk about each component in detail.
Each propeller-engine unit should have its own propeller definition. You'll have one definition for a single-engine plane, two for a twin, etc.
Propeller Basics
Setting up the fundamentals is easy. Before you start, you'll need to collect some information:
propeller radius in meters
propeller assembly mass in kilograms
propeller assembly + engine weight in pounds
maximum engine RPM
maximum engine power
engine displacement in cubic inches
engine compression ratio
the approximate location of the propeller + engine mass CG
the approximate location of the thrust bearing
the direction of thrust (optional)
Many of these things you can get from commonly available references or the aircraft model. Certification sheets often provide much of this information. Some information can be hard to find, like the weight of the propeller assembly. If you can't find exactly what you need, try to find information for similar components for other aircraft. A good estimate is better than a wild guess or numbers taken from another unrelated YASim FDM.
Any propeller engine definition is likely to have these elements:
<propeller ...>
<actionpt ... />
<piston-engine ...>
<control-input axis="/controls/engines/engine[0]/magnetos" control="MAGNETOS"/>
<control-input axis="/controls/engines/engine[0]/mixture" control="MIXTURE"/>
<control-input axis="/controls/engines/engine[0]/throttle" control="THROTTLE"/>
<control-input axis="/controls/engines/engine[0]/starter" control="STARTER"/>
</piston-engine>
</propeller>
There are other possible elements in addition to these, but you're sure to have these basic ones. Each element will also contain a number of possible attributes. Let's look at the elements and their possible attributes in detail.
Propeller Attributes
These are the settings that live inside the <propeller> tag. Some are optional, but most will have to be populated with values. Refer to the above complete example to see how each might be used.
The propeller element must contain the physical location (ie, center of mass) of the combined propeller and engine assembly expressed as x, y, and z coordinate attributes. Remember the YASim coordinate system: X axis is forward, Y is left, and Z is up. Probably you'll have to estimate this location, unless you have really good engineering data for the aircraft. Don't base your estimate on an engine nacelle as the engine assembly often takes up only a fraction of a nacelle. A cut-away diagram showing the actual engine position can be a useful guide.
For mass, enter the weight of the combined propeller and engine assembly in pounds. Again, mass represents the entire engine and propeller assembly, not just the engine. Engine dry weights are easy to find, but finding propeller weights can be take a lot of digging.
For radius, enter the radius of the propeller in meters. Yes, YASim is oddly inconsistent on units.
Once you know the propeller mass and its radius, you can calculate the propeller moment. Moment calculations are approximations, and there are numerous methods available. I recommend you consider these methods:
plain stick method: mass(kg) * radius(m)^2 / 3 rods method: mass(kg) * radius(m)^2 / 3 * (number of blades) disk method: mass(kg) * radius(m)^2 / 2
Choose one, or pick several and average the results. For smaller props I use the average of the rods and disk methods. For larger props I simply go with the plain stick. The reason is that large moments can greatly affect how long it takes a propeller to spin up or spin down, and can have too much roll influence. Not being a pilot of any of the aircraft I've modeled, I have no way to know what is realistic. Moment is very fuzzy, since accurate propeller weights are hard to find and even if you find it, the mass distribution is known only to the engineers. I recommend finding a reasonable number (on the smaller side for larger props) and adjusting the values after flight trials.
Positive moments indicate a clockwise rotation. Moment can be negative, which indicates a propeller moving in a counter-clockwise (when looking forward from the cockpit) rotation. Negative moments are particularly useful for pusher-type configurations. You can also set the contra attribute:
contra="1"
This indicates a paired contra-rotating usually coaxial propeller configuration for the engine, such as used by the Tu-95. Doing this eliminates the engine's contribution to the net gyroscopic moment, asymmetric torque on the aircraft body, and asymmetric slipstream effects.
Cruise Settings
Next you'll need some reference figures for typical cruise settings and power usage:
cruise-speed
cruise-rpm
cruise-power
cruise-alt
I believe these YASim settings are meant to determine where the engine delivers the most efficient use of power. For example, if your propeller has these settings:
cruise-power="235", cruise-rpm="2400", cruise-speed="175" and cruise-alt="8000"
you are saying that it requires 235 HP to make 2400 RPM at 8000' and 175 knots. Since this is establishing a power curve, cruise-rpm and cruise-power should not exceed engine-power and engine-rpm.
Think of these as power settings for long range flight. If you can find typical long-range cruise power settings in a pilot's handbook, try using those figures for your cruise values. Failing that, try power settings in the 60% range at 4000 or 5000 feet. Cruise settings have a great influence on the solver results, so don't get too fixated on the exact numbers because you'll likely tweak these values later based on flight testing.
When using a fixed-pitch propeller, cruise-speed has a lot of influence over the efficiency of that propeller. The higher you set it, the more the fixed-pitch propeller is optimized for high-end cruise speeds, requiring longer take-off runs and slower climb rates. The lower you set it, the propeller delivers great low-speed performance, but might have trouble reaching cruise speeds. I think.
Constant-Speed Propellers
YASim assumes a fixed-pitch propeller by default. If your engine is using a constant-speed propeller, you'll also need to provide these attributes:
max-rpm, the maximum RPM governor range (usually max RPM)
min-rpm, the minimum RPM governor range
fine-stop (optional, defaults to 0.25)
coarse-stop (optional, defaults to 4.0)
If max-rpm is present, YASim assumes you are defining a constant-speed prop. Make sure you also provide min-rpm.
The governor range specified by min and max RPM tells YASim what RPM values the propeller should try to seek. You can often find these in a pilot's handbook or related reference.
Fine-stop and coarse-stop are rather fuzzy YASim values that you can either omit or try to tune. Originally they were a hack to get around fixed internal YASim values. Leave these alone until you're happy with the rest of your engine settings. They won't affect the solver results and it's a waste of time messing with them until you've got good solver results.
Fine-stop defaults to 0.25. Increasing this value will give lower idle RPMs, but if you push it too far it will begin lowering the maximum power RPM, not a good thing. My suggestion is to set this value to 0.25 and note where the engine idles. If idle speed is higher than the desired idle range of the engine (which will likely be the case), begin increasing fine-stop. Observe the new idle results, and also the maximum-power RPM. Keep increasing fine-stop until one of two things occurs: idle speed enters the desired idle RPM range, or maximum power RPM begins to fall short of the maximum desired RPM. Course-stop defaults to 4. I've yet to find that playing with course-stop alters much-- it doesn't seem able to compensate for high-RPM issues with fine-stop, so I recommend leaving course-stop at 4 or simply omitting it.
If using a fixed-pitch propeller, omit the above four attributes.
Cruise settings become somewhat more difficult to tune for constant-speed propellers, since it's hard to know what the propeller pitch will be at any given time. I suggest trying to tune your settings as a fixed-pitch prop first, and then add settings for constant-speed after you have good fixed-pitch results.
Variable Pitch Propellers
In addition to fixed-pitch and constant-speed, YASim also lets you define a variable-pitch propeller. In this case pitch is set manually by the pilot. To specify a variable-pitch propeller, include the attribute:
manual-pitch="1"
Nothing else is required except a propeller control element. I cover control elements at the end of this tutorial.
Some fixed-pitch propellers may have their pitch altered on the ground but not in flight. Assigning the prop as a YASim variable-pitch propeller with special pre-flight only options to set the pitch may be an interesting solution.
Geared engines
If your engine output is geared, add the following attribute to the propeller element:
gear-ratio
This specifies the output multiplier. For example, if the gear ratio is 16:9, use gear-ratio="0.5625". The default value is 1.0.
If using a gear ratio other than the default, all propeller attributes referring to propeller RPM should be factored by the gear ratio. For example, if the governing range is 1200-2700 RPM and the engine uses a 16:9 gearing, set: min-rpm="675" and max-rpm="1519". Factor cruise-rpm by the gear-ratio values as well. Do not do this for the eng-rpm attribute of the <piston-engine> sub-element covered in the next section. That value should be the raw, ungeared maximum engine RPM.
Takeoff Power Settings
These are optional attributes:
takeoff-power
takeoff-rpm
These attributes provide a way to limit thrust at low propeller advance ratios. This is typical of takeoff conditions, where the propeller is spinning fast but the aircraft is moving slow. This could be used to represent a sharp drop in propeller efficiency at low advance ratios, where large portions of the propeller are essentially stalled. As the advance ratio increases, thrust will eventually match rated thrust, depending on conditions.
Though optional, I recommend setting these values, especially for fixed-pitch propellers. If the engine is capable of max-RPM, max-power when sitting at rest on the tarmac, then set these values to the same settings as the engine, or, if the propeller is geared, the same RPM as the maximum geared RPM value. If you have static thrust numbers, try using these for takeoff power and rpm. Lacking those, try values of about 85% engine power and rpm numbers.
If you provide an attribute for takeoff-power, be sure to provide takeoff-rpm. Providing takeoff-rpm alone will be ignored by YASim.
Action Point and Direction Subelements
The propeller element should contain an action point subelement with attributes of x, y, z. This is the point on the aircraft where the thrust is actually applied. I believe it defaults to the engine assembly location, but I am not certain. In any case, you should specify an action point as it will rarely if ever be the assembly's center of mass. What I do is find a diagram of the engine and locate the approximate position of the thrust bearings and use that location as my action point. In typical engines, this will be roughly at the end of the engine block immediately behind the propeller.
The direction subelement is optional. If used, this is a vector to offset the thrust from the usual forward, station-line vector. For example, if thrust were offset 3 degrees up from the station-line, you would include the following subelement in your propeller definition:
<dir x="0.9986" y="0.0" z="0.05234" />
Here, most of the thrust is forward in the x axis, but a small fraction is diverted upward along the z axis.
For most situations you will not need a direction element. It will default to x="1", y="0", z="0".
The Piston-Engine Subelement
The piston-engine subelement is placed within the propeller element. Most of this subelement is easy to populate. Dig out your reference information and fill in the blanks for:
eng-rpm
eng-power
displacement
compression
RPM and power are maximum-power settings. All of these are easy to find even from Wikipedia pages. (Which I normally would not recommend as a reference.) If the engine is normally-aspirated, you're done.
Supercharged and Turbocharged Engines
Many engines have a means for ingesting more air than normally-aspirated engines. This allows higher manifold pressures, enabling the engine to burn more fuel and deliver more power, particularly useful at higher altitudes where low air pressures would result in low fuel-air ratios and corresponding weak power. These engines require a few more attributes and a little tweaking. You'll need to set two more values:
wastegate-mp
turbo-mul
Wastegate-mp is easy. Simply set this to the maximum manifold pressure setting allowed by the engine. The MP result will be scaled up to this value and will never exceed it.
Turbo-mul (turbo-multiplier) is not so easy. The documentation says, "Static pressure will be multiplied by this value to get the manifold pressure." Somewhat informative, but not very helpful. To find this value, I look for a reference in a pilot handbook that indicates the altitude at which maximum MP can be sustained. Through flight trials I then try to find a turbo-mul value that yields that MP up to that altitude and no more. MP should start falling off above that altitude. For example, if a manual says the aircraft should be able to get 48" inHg up to 4000', then I try flights up to 4000' using different turbo-mul settings until I get MP values that maintain 48" and only begin to fall-off after 4000' is exceeded. Make sure you do this with the appropriate boost control settings. See the control section below.
Superchargers and turbochargers are mechanically different means to cram in more air. Superchargers rely on direct power from the engine via gears to drive a compressor. Turbochargers use exhaust gasses to drive a compressor. In YASim, turbocharging is the default method. If the engine is supercharged, supply the following attribute:
supercharger="1"
In YASim, a turbocharged engine experiences some lag in boost pressure but a supercharger responds instantly. A turbocharger effect also works only when the engine is running, possibly affecting engine re-starts. You can change the turbocharger lag with this attribute:
turbo-lag
The documentation reads, "Time lag, in seconds, for 90% of a power change to be reflected in the turbocharger boost pressure." The default is 2 seconds, so you can simply omit this attribute unless you're fooling with the value.
Tweaking Manifold Pressure
YASim's calculates a manifold pressure value that is usually too low for accurate engine MP reporting. You can alter this behavior by setting an optional piston-engine attribute:
min-throttle (defaults to 0.1)
This attribute is a YASim hack that prevents manifold pressure from indicating a total vacuum when the engine is idling. If you know where your manifold pressure typically sits when the engine is idling, then you can play with min-throttle until you get a result close to that value. A value of 0.3 works reasonably for common general aviation engines, typically giving a reading a little over 9" inHg. The min-throttle attribute should not be confused with throttle settings or effects.
Unfortunately, using min-throttle is problematic. If you use it to get an MP value that is reasonable at idle, you will likely find your engine has too much power at idle. The problem is that YASim power is linear with manifold pressure. A real engine has all sorts of friction and pressure effects that cause a non-linear power response. I've had better luck leaving min-throttle at the default (or even lowering it slightly to get better idle RPM numbers) and using my own scripted functions to correct the manifold pressure values seen by instruments.
Control Input Subelements
If you've gotten this far, you're almost done. The last, and perhaps easiest thing to do is map Flightgear properties to serve as control inputs for the engine and propeller. This consists of creating mappings between your selected properties and the desired YASim control axis.
Propeller Controls
The propeller itself needs no control subelements if it is a fixed-pitch propeller since you cannot change the propeller's pitch. If it is a constant-speed propeller, then provide a control input within the propeller element:
<control-input axis="/controls/engines/engine[0]/propeller-rpm" control="ADVANCE"/>
This creates a mapping between the property "/controls/engines/engine[0]/propeller-rpm" and the the YASim ADVANCE control axis, which regulates the propeller governor. The property can be anything you want. This property uses the index 0 for engine 0, identifying a single engine configuration, or the left-most engine for a multi-engine airplane if using the standard engine number convention. If a multi-engined airplane, the next engine to the right would be specified as "/controls/engines/engine[1]/propeller-rpm", etc.
Though "/controls/engines/engine[0]/propeller-pitch" is a commonly used convention for this control in Flightgear, in my opinion "/controls/engines/engine[0]/propeller-rpm" is be a better choice since ADVANCE actually controls the propeller governor. The choice is up to you. The value of this property should range from 0 to 1, with 0 being lowest RPM and 1 indicating highest RPM.
Note that PROP is mentioned in the YASim documentation in place of ADVANCE, but PROP does not appear to be recognized by the YASim parser. I believe this to be a legacy from the original YASim documentation post from 2001.
If the propeller is a variable-pitch (manual) propeller, then use the PROPPITCH control axis instead of ADVANCE:
<control-input axis="/controls/engines/engine[0]/propeller-pitch" control="PROPPITCH"/>
Like ADVANCE, this control expects a value of 0 to 1. Again, the name of the property is up to you to decide. Make sure your property names are correctly bound to the controls or animations that can change their settings.
There is another YASim propeller control axis called PROPFEATHER. Though it is recognized by the YASim parser and the value sets an internal propeller property, as far as I can tell from experience and looking at the YASim code, the control seems to be a stub with no current operational effect.
Engine Controls
Now let's look at the possible controls for the engine itself:
<control-input axis="/controls/engines/engine[0]/magnetos" control="MAGNETOS"/> <control-input axis="/controls/engines/engine[0]/mixture" control="MIXTURE"/> <control-input axis="/controls/engines/engine[0]/throttle" control="THROTTLE"/> <control-input axis="/controls/engines/engine[0]/starter" control="STARTER"/> <control-input axis="/controls/engines/engine[0]/boost" control="BOOST"/>
These controls should be placed within the piston-engine subelement. Make sure the engine index number matches the correct engine being defined.
MAGNETOS, MIXTURE, THROTTLE and STARTER should all be fairly obvious in function and will most likely always be present in any propeller piston-engine definition.
A BOOST control is required only if the engine is supercharged or turbocharged. Boost is essentially a multiplier for the manifold pressure benefits of supercharging or turbocharging. For a single-stage, always-engaged supercharger or turbocharger, boost should be set to 1 otherwise you will not get the full effects. For a two-stage supercharger or turbocharger, boost might be initially set to 0.5 or some other fractional value, and to 1 if the second stage is engaged. Remember to define and initialize a boost property for each engine.
A Word on Control Element XML Positioning
The YASim parser does not enforce the position of control elements. You could have an engine control element positioned outside of the piston-engine tags, or even outside of the propeller tags, and YASim will still map the axis to the control correctly. But this is not a good idea. YASim may eventually be revised to use a more strict XML parser, so it would be wise to position controls in their logical container elements. ADVANCE is a propeller control and should be placed within the propeller tags and not within the piston-engine tags. MAGNETOS, MIXTURE, THROTTLE, STARTER and BOOST are engine controls and should live inside the piston-engine tags.